Agentic Workspaces: Submodules, Skills, Knowledge, and Spec-Driven Delivery

In our experience, most teams do not have a monorepo problem — they have a coordination problem: several repositories, one product surface, and agents that forget context between sessions.

An agentic workspace is a meta-repository that does not replace your app repos. It wraps them. You keep independent git histories for each service, but you give agents a single place to land: synced code under apps/, workspace-level skills, a .knowledge/ layer for how-to docs and ADRs, and spec-driven tooling (OpenSpec or GitHub Spec Kit) for planned change. Think of the workspace as the platform layer: shared conventions, skills, and specs that the apps/* repos depend on without merging their histories.

On July 8, 2026, I reviewed official Git submodule documentation, the OpenSpec and GitHub Spec Kit repos and docs, the Agent Skills open format at agentskills.io, and Cursor and Claude Code guidance on skills and cloud agents. Workflow patterns and directory layouts below combine those primary sources with editorial synthesis from multi-repo agent setups — labeled where inference applies.

Audience: This article targets engineers and architects implementing the pattern, with a secondary lens for PMs and scrum masters who need to understand delivery cadence, risks, and what “done” means in a spec-driven agent loop.

TL;DR

• An agentic workspace is a root repo that holds submodules (typically under apps/), skills (.cursor/skills/ or .claude/skills/), durable knowledge (.knowledge/ or docs/), and spec tooling (openspec/ or .specify/ + specs/).
• The daily loop is predictable: sync submodules → ground in knowledge → propose/apply a spec → work inside a submodule → review the PR → triage feedback → update knowledge → retrospective.
• Git submodules give you audit-friendly dependency pinning (every bump is a reviewed commit), but they require discipline: recurse on pull, push submodule commits before the parent, and automate --remote updates with guardrails.
• Knowledge refresh works best as a PR-triggered or scheduled audit — not manual copy-paste after every merge.
• OpenSpec fits fluid, brownfield, delta-spec iteration; GitHub Spec Kit fits constitution-guided, phase-rich delivery. Many teams use OpenSpec inside the workspace and Spec Kit inside individual app repos — or pick one.
• The payoff (editorial judgment): clone the workspace, run the loop, locally or on Cursor Cloud Agents / Claude Code on the web, without rebuilding context from scratch each time.

What You Will Learn Here

• What belongs in an agentic workspace vs. what stays in app repos
• A reference directory layout and a seven-step daily loop you can automate
• How to keep submodule pointers fresh without breaking detached-HEAD workflows
• How .knowledge/ and ADRs give agents (and humans) shared grounding
• Where OpenSpec and Spec Kit sit in the loop, and how to choose
• Common failure modes — drift, stale docs, review loops — and practical fixes
• Why this pattern scales to multiple cloud-agent copies and cross-repo features

The Problem: Polyrepo Reality, Monorepo Expectations

Product teams rarely get to collapse everything into one repository. You might have a frontend, an API, a data pipeline, shared Terraform, and internal libraries — each with its own release cadence and ownership.

Agents amplify the pain:

• Context scattered across repos, tickets, and chat history
• No stable “how we work here” unless someone re-pastes it every session
• Cross-repo features planned in a doc that never updates after the PRs land

An agentic workspace does not merge git histories. It orients the agent the way a good platform team orients a new hire: here are the repos, here is how we specify work, here is what we already decided, here are the skills for routine tasks.

Without workspace                    With agentic workspace
─────────────────                    ──────────────────────
Agent opens repo A                   Agent opens workspace root
  → misses repo B context              → syncs apps/* submodules
  → reinvents conventions              → reads .knowledge/conventions.md
  → specs live in chat                 → /opsx:propose or /speckit.specify
  → PR review is ad hoc                → pr-reviewer skill + triage loop

Reference Layout

Treat the root as a thin table of contents. Keep CLAUDE.md or AGENTS.md under ~100 lines; point into skills and knowledge files agents load on demand (progressive disclosure).

agentic-workspace/
├── AGENTS.md / CLAUDE.md       # Entry point: where to look next (see example below)
├── .gitmodules                 # Submodule manifest
│
├── apps/                       # Submodule mount points
│   ├── web/                    # → github.com/org/web-app
│   ├── api/                    # → github.com/org/api-service
│   └── infra/                  # → github.com/org/terraform
│
├── .cursor/  (or .claude/)
│   ├── skills/
│   │   ├── workspace-sync-submodules/
│   │   ├── get-knowledge/
│   │   ├── update-knowledge/
│   │   ├── audit-knowledge/
│   │   ├── openspec-propose/          # if using OpenSpec
│   │   ├── pr-triage-fix-loop/
│   │   └── session-retrospective/
│   ├── commands/               # Slash aliases for spec workflows
│   └── subagents/              # Focused reviewers (read-only)
│
├── .knowledge/                 # Durable how-to + decisions
│   ├── README.md               # Index for agents
│   ├── conventions.md
│   ├── runbooks/
│   └── adr/
│       └── 001-segment-id-format.md
│
├── openspec/                   # OpenSpec (optional)
│   ├── config.yaml
│   ├── specs/                  # Canonical capability specs
│   └── changes/                # In-flight deltas
│
│   — or —
│
├── .specify/ + specs/          # GitHub Spec Kit (optional)
│
└── llms.txt                    # Optional machine-readable nav index (llmstxt.org)

Minimal workspace entry point — keep it a table of contents, not a dump of every rule:

# AGENTS.md

## Repos (submodules under apps/)
- apps/web — customer-facing UI
- apps/api — REST + event handlers
- apps/infra — Terraform modules

## Before planning
1. Run workspace-sync-submodules skill
2. Read @.knowledge/README.md and relevant ADRs

## Spec workflow
- Cross-repo changes: /opsx:propose at workspace root (OpenSpec)
- Single-service work: follow skills in the target apps/* repo

## Skills catalog
See .cursor/skills/*/SKILL.md — load on demand, not all at once.

llms.txt is optional: it is a small navigation file that helps agents discover durable docs without scanning the whole tree.

What stays in app submodules: application code, service-specific tests, service CI, and repo-local agent rules when a team owns them outright.

What lives at workspace root: cross-repo specs, shared skills, knowledge that spans services, and automation that touches multiple apps/* paths.

The Seven-Step Daily Loop

This is the workflow teams converge on once skills exist for each step. Names are illustrative; align them to your skill registry.

        ┌───────────────────────────────────────────────┐
        │  1. workspace-sync-submodules                 │
        │     keep apps/* on agreed branches/commits    │
        │                                               │
        │  2. get-knowledge                             │
        │     ground in .knowledge before planning      │
        │                                               │
        │  3. /opsx:propose → /opsx:apply               │
        │     (or /speckit.specify → … → implement)     │
        │     ── implement inside the target submodule ─│
        │                                               │
        │  4. custom pr-reviewer-agent                  │
        │     audit diff against spec + conventions     │
        │                                               │
        │  5. custom pr-triage-fix-loop                 │
        │     resolve review comments until green       │
        │                                               │
        │  6. update-knowledge                          │
        │     capture ADRs, runbook deltas, spec sync   │
        │                                               │
        │  7. session-retrospective                     │
        │     reflect: what skill/knowledge gap appeared│
        └───────────────────────────────────────────────┘

Step 1 — Sync submodules

Goal: Every agent session starts from the same apps/* SHAs your team expects.

A workspace skill wraps the official Git commands:

# Pull parent and recurse into submodules (team-wide default)
git config submodule.recurse true
git pull --recurse-submodules

# Advance submodules to latest on their tracking branch
git submodule update --remote --merge --recursive

# Stage pointer updates in the parent
git add apps/
git commit -m "chore(workspace): bump submodule pointers"

Editorial note: Pin to tags when you need stability; track branch tips when you need daily freshness. That tradeoff is organizational, not technical — see Keeping Submodules Fresh below.

Architect note: Cloud agents (Cursor Cloud, Claude Code on the web) need credentials for private submodule repos — the parent checkout token is not always enough. CI runners must set submodules: recursive in checkout steps; default clones leave apps/* empty.

Step 2 — Ground in knowledge

Before /opsx:propose or /speckit.specify, the agent runs get-knowledge: read .knowledge/README.md, relevant ADRs, and any runbook tied to the capability. This step is cheap compared to re-deriving architecture from source on every task.

For PMs and scrum masters: treat this as the definition-of-ready check for agent work — if knowledge is missing, the agent should stop and file a knowledge gap, not invent policy.

Step 3 — Spec and implement in the right submodule

Cross-repo features get one workspace-level spec with tasks tagged by repo:

## tasks.md (workspace root)

- [ ] apps/api: add UUID column migration
- [ ] apps/api: expose segment lookup endpoint
- [ ] apps/web: map CDP UUID to segment in settings UI
- [ ] .knowledge: document segment ID format in adr/002-...

OpenSpec stores deltas under openspec/changes/<feature-id>/; Spec Kit uses feature folders under specs/<feature-id>/. For toolkit differences, see OpenSpec vs GitHub Spec Kit.

Implementation commits happen inside the submodule working tree; the workspace records the updated pointer when the submodule PR merges.

Steps 4–5 — Review and triage

This is a pattern you can build as workspace skills, not a claim that every tool ships these names out of the box. A pr-reviewer-agent skill (or subagent) checks:

• Implementation vs. spec scenarios
• Conventions from .knowledge/conventions.md
• Cross-repo task completion

pr-triage-fix-loop maps review comments to follow-up tasks, re-runs tests, and pushes until CI is green. This is where MCP tools help: GitHub API for review threads, Jira for linked tickets, internal observability for trace IDs mentioned in the spec. The MCP section below shows the server shape for those integrations.

Steps 6–7 — Knowledge capture and retrospective

update-knowledge promotes durable facts out of the change folder:

• New ADR if the decision will be referenced again
• Runbook edit if on-call steps changed
• /opsx:archive or the equivalent Spec Kit completion/archive step to merge specs into canonical truth

These two steps are paired because knowledge capture should happen before retrospective. session-retrospective is lightweight: one markdown note per week — which skill failed, which doc was stale, which automation to add. Feeds the next sprint’s platform work.

# session-retrospective/2026-07-08.md

- **Goal:** CDP UUID → segment mapping (cross-repo)
- **Worked:** get-knowledge + /opsx:propose at workspace root
- **Failed:** pr-triage-fix-loop — agent pushed parent before submodule commit
- **Automate next:** pre-push hook for push.recurseSubmodules=check

Delivery Cadence for PMs and Scrum Masters

You do not need to run the agent loop yourself to benefit from it. Map it to familiar ceremony:

Merge order for cross-repo features: API/backend PRs before UI; workspace pointer-bump PR last. Track one workspace spec ID across Jira/Linear epics so boards stay aligned.

Workspace Skills You Will Want

Skills follow the emerging Agent Skills open format: a folder with SKILL.md, optional scripts, and a description agents match before loading full instructions.

For engineers, the first useful skill is usually a guarded submodule sync wrapper:

---
name: workspace-sync-submodules
description: Keep apps/* submodules current and report drift before agent work starts.
---

1. Run `git submodule sync --recursive`.
2. Run `git submodule update --init --recursive`.
3. If asked to refresh pointers, run `git submodule update --remote --merge --recursive`.
4. Report `git submodule status` prefixes (`+`, `-`, `U`) before editing.
5. Never commit inside a submodule unless it is on a named branch.

Workspace skills differ from repo skills inside apps/api/.cursor/skills/. Workspace skills orchestrate; repo skills implement service-specific patterns (migrations, API style, etc.). Editorial inference: when skills live inside a submodule, checking out a newer submodule SHA may change available skills — pin SHAs if you need reproducible agent behavior across sessions.

For the skills maturity model (prompt → skill → MCP → plugin), see The Evolution of AI Agent Orchestration.

Keeping Submodules Fresh Without Surprises

This is the most common operational complaint about submodule-based workspaces.

Official mechanics (source-backed)

Git stores submodule references as gitlinks — commit SHAs in the parent repo (git-submodule documentation). Updating upstream code is a two-step process: move the submodule working tree, then commit the new pointer in the parent.

Common team defaults, based on documented Git options and reinforced by community submodule guides:

git config --global submodule.recurse true
git config --global push.recurseSubmodules on-demand
git config --global status.submodulesummary 1

Always prefer --merge or --rebase with --remote in automation — bare --remote can discard uncommitted submodule work.

Automation patterns

A mature variant bumps one submodule per PR so CI attributes failures correctly — as of July 2026, the aerospike-ce-ecosystem/workspace workflow provides one example.

Detached HEAD guardrail

git submodule update checks out a detached HEAD. Agents (and humans) must create a branch before committing:

cd apps/api
git checkout -b feat/segment-lookup
# ... work ...
git push origin feat/segment-lookup
cd ../..
git add apps/api
git commit -m "chore: point api at feat/segment-lookup"

Encode this in workspace-sync-submodules and in .knowledge/conventions.md so cloud agents do not orphan commits.

Keeping Knowledge and ADRs Fresh

Static .knowledge/ files drift quickly unless refresh is part of the delivery loop.

What to store

Use a consistent ADR template: Status, Context, Decision, Consequences.

Refresh triggers

1. On archive — When OpenSpec archives a change or Spec Kit completes implement, update-knowledge extracts decisions worth keeping.
2. Scheduled audit — Weekly audit-knowledge subagent compares .knowledge/ claims to main in apps/* (sample files, configuration variables, public routes). Output is a PR, not a chat summary.
3. Teammate PR hook — Optional GitHub Action on app repos: if PR touches areas mapped in .knowledge/index.yaml, comment with a checklist to update workspace knowledge. Editorial inference: few teams automate this fully on day one; start manual, automate once mappings stabilize.

Anti-pattern

Do not paste entire PR descriptions into ADRs. Link the PR, capture the decision and invariant the next agent needs.

OpenSpec vs Spec Kit in the Workspace

Both toolkits address spec drift in AI-assisted delivery; they sit at the workspace root or at individual apps/* repos depending on governance needs.

Practical split (editorial recommendation): In a workspace the choice gains a third dimension — git layout. Where a feature crosses submodule boundaries, OpenSpec’s root-level delta model avoids Spec Kit’s branch-per-feature pattern fighting the workspace’s submodule pointers.

• Workspace root + OpenSpec for cross-repo changes that touch multiple apps/* paths and iterate quickly.
• App repo + Spec Kit when a single service needs strict TDD, compliance, or phase gates.

See the sibling comparison for the full head-to-head: OpenSpec vs GitHub Spec Kit.

Cursor skills are discovered from .cursor/skills/ per Cursor skills docs; applying that to Cursor Cloud Agents is an inference from the same workspace checkout model. OpenSpec’s init flow can generate tool-specific skill files for Cursor and Claude Code — see the OpenSpec supported-tools documentation. Spec Kit uses specify init --here --ai cursor-agent per the Spec Kit README.

Deep comparison: OpenSpec vs GitHub Spec Kit. Polyrepo Spec Kit patterns: Integrate Spec Kit into existing repos.

Local and Cloud: Same Loop, Different Harness

The workspace pattern is harness-agnostic. The loop stays; only invocation changes.

Cloud scale advantage (editorial judgment): you can spin up multiple workspace clones — one per feature branch or per repo in a cross-cutting initiative — without manually re-seeding context. Each clone inherits skills and knowledge from the same root commit.

For subagent design in cloud contexts, see Designing Subagents in the Cloud and Cursor Subagents and Claude Code.

Cross-Repo Features: Spec at the Root, Code in Submodules

Cross-repo work fails when the spec lives in one app’s README and the other team never sees it.

Pattern:

1. Create openspec/changes/001-cdp-uuid-to-segment/ (or specs/001-cdp-uuid-to-segment/ for Spec Kit) at workspace root.
2. Delta specs name capabilities that map to submodules (cdp-ingestion, segment-identity, settings-ui).
3. Tasks explicitly prefix paths: apps/api/..., apps/web/....
4. Open one PR per submodule; merge order follows dependency (API before UI).
5. After all PRs merge, bump submodule pointers in the workspace and archive the change.

Workspace spec (single source of truth)
        │
        ├──► apps/api PR #142  (migration + endpoint)
        │
        └──► apps/web PR #89   (UI mapping)
                │
                └──► workspace PR #12 (pointer bumps + archive)

PMs: the workspace spec is your single feature brief; sprint planning can trace tasks to repo PRs without splitting narrative across boards.

MCP Tools for Trace, Triage, and Debug

Skills tell the agent what to do; MCP tools let it reach systems without bespoke scripts.

Typical workspace MCP config (.mcp.json for Claude Code; .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "your-org/mcp-jira-server"]
    }
  }
}

For GitHub, GitHub’s own github/github-mcp-server is the current first-party option; the @modelcontextprotocol/server-github reference implementation shown above is the simplest to illustrate. The Jira entry is a placeholder; replace it with your organization’s actual MCP server package or command. Configure credentials on the host (for example GITHUB_TOKEN, JIRA_TOKEN) per each MCP server’s documentation — do not commit tokens to the workspace repo.

• GitHub — PRs, reviews, checks, submodule repos
• Issue tracker — Jira/Linear for triage loops
• Observability — trace lookup when specs reference request IDs
• Internal docs — Confluence or equivalent for legacy context not yet in .knowledge/

Custom skills compose MCP calls:

• Triage — search duplicates, attach logs, propose fix branch
• Debug — read-only trace fetch, compare to runbook steps in .knowledge/runbooks/
• Report — weekly digest of merged PRs vs. open knowledge gaps

Keep MCP scopes minimal. A read-only triage server beats a full-production admin token on every cloud agent.

For PMs and scrum masters: these connections are what make the review-and-triage loop visible on delivery boards — the GitHub server surfaces PR and check status, the issue-tracker server surfaces ticket state — so progress is auditable without a manual status meeting. For MCP server construction and the full prompt → skill → MCP maturity arc, see The Evolution of AI Agent Orchestration.

Advantages and When Not to Bother

Advantages

1. Scale agent sessions — Clone the workspace; skills and knowledge travel with the repo SHA.
2. Share team workflows — Skills are versioned like code; a git submodule update on the workspace distributes improvements.
3. Plan cross-repo work once — Root-level specs with per-submodule tasks reduce coordination tax.
4. Audit trail — Submodule pointer bumps and ADRs document what changed and why, not just chat logs.

When a simpler setup wins

• Single repo, single team — A well-written AGENTS.md and one spec toolkit may suffice.
• Tight coupling, shared releases — A true monorepo with Nx/Turborepo/Bazel may be cheaper operationally.
• Submodule-averse culture — Subtrees or a package registry for shared libs avoids gitlink ceremony; you lose per-pointer PR audit unless you replicate it elsewhere.

Workspace vs. coordination repo (lighter polyrepo pattern)

If submodule ceremony is too heavy, a coordination repo without apps/* checkouts can still hold the canonical spec and shared skills while agents work one repo at a time. That pattern is documented in Integrate Spec Kit into existing repos (polyrepo). Choose the full workspace when agents must edit multiple repos in one session and pointer audit matters; choose coordination-only when specs are shared but implementation stays strictly per-repo.

Should I adopt an agentic workspace?
│
├─ One repo, one team?
│   └─ No workspace needed → AGENTS.md + one spec toolkit in-repo
│
├─ Multiple repos, always released together?
│   └─ Consider true monorepo (Nx/Bazel) instead of submodules
│
├─ Multiple repos, independent cadence, submodule-tolerant team?
│   ├─ Agents must touch 2+ repos per feature?
│   │   └─ Full workspace (apps/* submodules + root spec + skills)
│   └─ One agent / one repo per task?
│       └─ Coordination repo only (spec home, no apps/* checkout)
│
└─ Submodule-averse culture?
    └─ Package registry or subtrees + coordination repo for specs

Common Issues and Troubleshooting

Getting Started Checklist

1. Create an empty workspace repo with AGENTS.md pointing to .knowledge/README.md.
2. Add one app submodule: git submodule add <url> apps/<name>.
3. Install OpenSpec at workspace root (for cross-repo specs), or Spec Kit at workspace root or an app repo (for constitution-guided per-service phases); run init for your agent (cursor, claude).
4. Add four skills first: workspace-sync-submodules, get-knowledge, update-knowledge, plus your spec propose skill.
5. Write two knowledge files: conventions.md and one ADR for a decision newcomers always get wrong.
6. Run the seven-step loop on a small cross-cutting chore before a production feature.
7. Add automation for submodule bump PRs once manual sync becomes tedious.
8. After two or three loops, add the session-retrospective step to capture skill and knowledge gaps.

Conclusion

An agentic workspace is not a new git primitive. It is an operating model: submodules for multi-repo code, skills for repeatable agent actions, knowledge for decisions that outlive chat, and spec tooling for planned change. The seven-step loop turns ad hoc agent sessions into something scrum masters can reason about — sync, ground, specify, implement, review, triage, learn.

Start narrow: one workspace, two submodules, four skills, one spec. Automate submodule and knowledge refresh only after the manual loop works. In our view, teams that sustain this pattern treat the workspace as platform product, not a one-off dotfiles repo.

Sources

Primary sources consulted July 8, 2026:

• Git submodule reference — git-scm.com/docs/git-submodule
• Pro Git: Submodules — git-scm.com/book/en/v2/Git-Tools-Submodules
• OpenSpec — github.com/Fission-AI/OpenSpec, openspec.dev
• GitHub Spec Kit — github.com/github/spec-kit, github.github.com/spec-kit
• Agent Skills emerging open format — agentskills.io (accessed July 8, 2026)
• Renovate git submodule manager — docs.renovatebot.com
• llms.txt navigation format — llmstxt.org
• Cursor skills documentation — cursor.com/docs/context/skills
• Community guide: git submodules for platform engineering — tenthirtyam.org, April 16, 2026
• Community example: submodule bump automation — aerospike-ce-ecosystem/workspace workflow

Editorial inference (not independently verified): optimal split of OpenSpec at workspace root vs. Spec Kit in app repos; cloud-agent clone scaling claims; PR-triggered knowledge audit maturity path; weekly retrospective as platform feedback. Treat these as patterns to validate on your team, not vendor guarantees.

Related articles in this devlog:

• OpenSpec vs GitHub Spec Kit
• Integrate Spec Kit into existing repos (polyrepo)
• AI orchestration: prompts, skills, MCP, plugins
• Cursor subagents and Claude Code