/specd.codebase.map

Spawn 4 parallel agents that analyze your codebase and write documentation designed for Claude to consume during feature planning and execution.

/specd.codebase.map

What it does

Each agent explores a focused area of your codebase and writes directly to .specd/codebase/. The orchestrator collects confirmations only — keeping token usage minimal.

Document	Question it answers
`MAP.md`	Where is X? What functions, types, and modules exist?
`PATTERNS.md`	How do I write code that fits here? What are the conventions?
`STRUCTURE.md`	Where do I put new code? What’s the directory convention?
`CONCERNS.md`	What will bite me? What’s the tech debt and the gotchas?

How agents work

/specd.codebase.map
        │
        ├── Map Agent     → MAP.md
        ├── Patterns Agent → PATTERNS.md
        ├── Structure Agent → STRUCTURE.md
        └── Concerns Agent  → CONCERNS.md

All four agents run in parallel. Each gets a fresh 200k context window — no token pollution between them. They write directly to files; you see a completion summary when all four finish.

When to run it

Run codebase.map when:

Starting with an unfamiliar codebase
Before planning your first feature in a project
After significant refactoring that changes architecture
Onboarding Claude to a repo it hasn’t seen

Skip codebase.map when:

The project has fewer than ~10 files
You already have recent codebase docs and nothing major has changed

Refresh behavior

If .specd/codebase/ already exists, the command asks whether to refresh or skip. Refreshing re-runs all four agents and overwrites the existing documents.

For section-by-section review and editing of existing codebase docs, use /specd.codebase.review.

Multi-project support

When specdacular detects multiple projects (via package.json, go.mod, Cargo.toml, etc.) in the repository, it offers to enable multi-project mode. In that mode:

4 mapper agents run per sub-project (in parallel across projects)
An orchestrator mapper runs after all sub-project maps complete
System-level documents are written to the root .specd/codebase/:

Document	What it answers
`PROJECTS.md`	What projects exist? What are their tech stacks and purposes?
`TOPOLOGY.md`	How do projects communicate? What’s the data flow?
`CONTRACTS.md`	What are the cross-project relationships and shared domains?
`CONCERNS.md`	What are the system-level gotchas?

Output structure

.specd/
└── codebase/
    ├── MAP.md
    ├── PATTERNS.md
    ├── STRUCTURE.md
    └── CONCERNS.md

All documents are committed to git automatically after generation.

/specd.new — Start planning a feature (loads codebase docs automatically)
/specd.codebase.map — This page