agentic-workspace @ part 1 · jul 2026

Agentic
Workspaces

Submodules · Skills · Knowledge · Spec-Driven Delivery
Luis Mori Guerra — Engineering Manager / Technical Lead
the problem // why this exists

Not a monorepo problem.
A coordination problem.

Most teams live in polyrepo reality — frontend, API, pipelines, infra — each with its own cadence and owner.
Agents amplify the pain: context is scattered, conventions get reinvented every session, cross-repo specs go stale after PRs land.
The intention: give agents one place to land without merging git histories.
without workspace with workspace ───────────────── ────────────── opens repo A opens root - misses repo B + syncs apps/* - reinvents rules + reads .knowledge - specs in chat + /opsx:propose - ad-hoc review + pr-triage loop
what it is // the platform layer

A meta-repo that wraps your app repos

agentic-workspace / · thin table of contents
apps/SubmodulesIndependent git histories, pinned by SHA. Every bump is a reviewed commit.
.claude/skills/SkillsRepeatable agent actions, versioned like code and shared across the team.
.knowledge/KnowledgeDurable ADRs, runbooks & conventions that outlive any chat session.
openspec/Spec ToolingOpenSpec or Spec Kit for planned, cross-repo change — not chat-only specs.
root pins each apps/* to an external repo by SHA ⟶ app repos keep independent histories
goals // what it delivers

What the pattern buys you

  • 01A single landing zone — clone the workspace, run the loop, skip rebuilding context every session.
  • 02Shared grounding — .knowledge/ & ADRs give humans and agents the same source of truth.
  • 03Fresh dependencies, on purpose — submodule pointers stay current without breaking detached-HEAD workflows.
  • 04Cross-repo work, planned once — one root spec with per-submodule tasks.
  • 05Same loop everywhere — local, cloud agents, or scheduled automation.
the loop // what "done" looks like

The seven-step daily loop

cross-repo features // spec at root, code in submodules

One spec, many PRs, ordered merges

Workspace spec single source of truth openspec/changes/001-… merge order → API before UI 1 apps/api · PR #142 migration + endpoint 2 apps/web · PR #89 UI mapping 3 workspace PR #12 pointer bumps + archive
spec tooling // how to choose

OpenSpec vs GitHub Spec Kit

OpenSpec

propose → apply → archive
  • Fluid, brownfield, delta-spec iteration
  • Lightweight, change-folder oriented
  • Best at the workspace root for cross-repo deltas

Spec Kit

constitution → specify → plan → tasks
  • Constitution-guided, phase-rich delivery
  • Strict TDD, compliance, phase gates
  • Best inside a single app repo
Practical split: OpenSpec at the root for work that crosses submodules; Spec Kit in the service that needs strict phases. Or pick one.
runtime // harness-agnostic

Same loop, different harness

The workflow stays fixed; only the way you invoke it changes.
localCursor / Claude CodeDeveloper triggers skills; subagents audit in parallel.
cloudCursor Cloud · Claude on the webBranch checkout ships the workspace; mind private-submodule credentials.
cronScheduled automationBounded scope — sync + audit only, no free-form edits.
scaleMany clones at onceOne per feature branch, each inheriting skills & knowledge from the same root SHA.
advantages // & when not to bother

Why it pays off

Scale agent sessionsSkills & knowledge travel with the repo SHA.
Share team workflowsA single submodule update distributes improvements.
Plan cross-repo onceRoot specs + per-submodule tasks cut coordination tax.
Real audit trailPointer bumps & ADRs record what changed and why.
Skip it when: one repo + one team (an AGENTS.md is enough), tightly-coupled shared releases (use a true monorepo), or a submodule-averse culture (subtrees / a coordination repo).
should i adopt one? // decision tree

Pick the lightest thing that works

One repo, one team? Always released together? Submodule-averse culture? Agents edit 2+ reposper feature? no no no yes yes yes yes no AGENTS.md + one spec toolkit True monorepo · Nx / Bazel Registry / subtrees + coord repo ★ Full workspace Coordination repo only
conclusion
An agentic workspace isn't a new git primitive — it's an operating model: submodules for code, skills for actions, knowledge for decisions, specs for planned change.
Start narrow → one workspace · two submodules · four skills · one spec.
Automate refresh only after the manual loop works.
what's next // getting started

Your first loop

[ ]Create an empty workspace repo; AGENTS.md points to .knowledge/README.md.
[ ]Add one app: git submodule add <url> apps/<name>.
[ ]Install OpenSpec at root (or Spec Kit in a service); run init.
[ ]Add four skills: sync, get-knowledge, update-knowledge, propose.
[ ]Write two docs: conventions.md + one ADR newcomers always get wrong.
[ ]Run the seven-step loop on a small chore first.
[ ]Add submodule-bump automation once manual sync gets tedious.
[ ]After 2–3 loops, add retrospective to catch gaps.
Treat the workspace as a platform product — not a one-off dotfiles repo.
the roadmap // prove, then automate

Prove the manual loop before automating it

LOOP 1 Pilot narrow One workspace Two submodules Four skills + one spec LOOPS 2–3 Stabilize Fix sync discipline Capture one useful ADR Add session retrospective AFTER PROOF Automate Submodule bump PRs Scheduled knowledge audits Guarded cloud-agent runs
sources // further reading

Read the full write-ups

Agentic Workspaces: Submodules, Skills, Knowledge, and Spec-Driven Delivery The full source-backed guide behind this deck — reference layout, the seven-step daily loop, keeping submodules and knowledge fresh, and a loop that runs locally or in cloud agents. luismori.dev › agentic-workspace ↗ OpenSpec vs GitHub Spec Kit: A Side-by-Side Review The head-to-head comparison behind slide 6 — workflows, skills vs commands, generated artifacts, extensibility, and inferred token trade-offs for engineers and PMs choosing a toolkit. luismori.dev › openspec-vs-github-spec-kit ↗
01 / 12
← → or swipe · space to advance