/map-codebase

/soloflow:map-codebase

Generates the three "shared-context" docs every SoloFlow agent expects to load on entry to a new session: a project CLAUDE.md, an ARCHITECTURE.md, and a CODE-PATTERNS.md. Additive and idempotent — only missing artifacts are created; existing files are never overwritten or rewritten by this command.

This is the bootstrap counterpart to /soloflow:compound's C-bucket: compound extends these files with sprint-derived learnings, but it assumes they already exist. Run this once at project setup (init prompts you), and re-run any time a missing artifact is added back to the project (e.g., a new subdirectory that deserves its own scoped CLAUDE.md).

The command is read-mostly: it surveys the codebase via Glob/Grep/Read, asks the user to confirm what to generate, and writes the chosen artifacts.

---

Step 0: Sanity check

1. Run pwd via Bash to capture the project root (used in commit messages and reported paths).
2. Run git rev-parse --is-inside-work-tree via Bash. Capture whether the project is in a git repo (is_git). Not being in a repo is fine — the command still writes the artifacts, just skips Step 5's commit.

Step 0.4: Parse flags

Scan $ARGUMENTS for the three skip flags and build a skip_set (a set of artifact names this run will not generate, even if missing):

• --skip-claudemd → add "CLAUDE.md" to skip_set.
• --skip-architecture → add "ARCHITECTURE.md" to skip_set.
• --skip-codepatterns → add "CODE-PATTERNS.md" to skip_set.

Match flags by exact string; treat any token in $ARGUMENTS that begins with --skip- but is not one of the three above as an error: print map-codebase: unknown flag "{token}". Recognized flags: --skip-claudemd, --skip-architecture, --skip-codepatterns. and stop. Order is irrelevant; duplicates are tolerated.

If skip_set contains all three names, print map-codebase: all three artifacts skipped via flags — nothing to do. and stop.

If skip_set is non-empty, print one line summarizing what was excluded: Skipping (via flag): {comma-joined names from skip_set}. This makes the suppression visible in the run log.

Carry skip_set forward to Steps 1 and 2.

Step 1: Detect existing artifacts

Glob for each artifact in its conventional locations. Treat any match as "present" — never propose to overwrite. Conventions surveyed:

• Root CLAUDE.md — CLAUDE.md at project root.
• Nested CLAUDE.md — **/CLAUDE.md excluding root. Reported as informational context but never generated by this command (subdirectory CLAUDE.md files are earned by recurring scope, not bootstrapped).
• ARCHITECTURE.md — first match wins among: ARCHITECTURE.md, docs/ARCHITECTURE.md, docs/architecture.md, ARCHITECTURE/README.md.
• CODE-PATTERNS.md — first match wins among: CODE-PATTERNS.md, docs/CODE-PATTERNS.md, docs/code-patterns.md.

Build a status map: each artifact is present (with its absolute path), missing (with its proposed default path — see Step 4), or skipped (in skip_set from Step 0.4 — even if the file is missing, this run will not generate it). skipped takes precedence over missing in the status display; present always wins (a skip flag never alters an existing file).

Report the table:

Existing project context:
  CLAUDE.md            {present at <path> | missing — would create at ./CLAUDE.md | skipped via --skip-claudemd}
  ARCHITECTURE.md      {present at <path> | missing — would create at ./docs/ARCHITECTURE.md (or ./ARCHITECTURE.md if no docs/) | skipped via --skip-architecture}
  CODE-PATTERNS.md     {present at <path> | missing — would create at ./docs/CODE-PATTERNS.md (or ./CODE-PATTERNS.md if no docs/) | skipped via --skip-codepatterns}

Nested CLAUDE.md files:
  {one line per nested file, or "(none)"}

If every top-level artifact is either present or skipped (i.e., no artifact has status missing), print:

✓ Nothing to generate — all unskipped context files are already in place.
  (Use /soloflow:compound to add learnings; use /soloflow:prune to consolidate or trim.)

and stop.

Step 2: Confirm what to generate

Use a single AskUserQuestion:

• Question: "Generate the missing context files? You can drop any of them — only the selected ones will be written."
• Header: "Generate"
• multiSelect: true
• Options: one per artifact whose status is missing in Step 1, e.g. "CLAUDE.md", "ARCHITECTURE.md", "CODE-PATTERNS.md". Pre-label each option as (missing). Do not include present artifacts (off limits — never overwritten) or skipped artifacts (already excluded by flag in Step 0.4).
• Always include a final option "Cancel".

If the user picks "Cancel" (or selects nothing): print Aborted — no files written. and stop.

Carry the selected list forward as to_generate.

Step 3: Survey the codebase

Skip this step if to_generate is empty after the user's choice.

Survey only what the chosen artifacts need. Run the relevant probes via Bash (prefer one combined invocation per category) and Glob; cache the results in memory for Step 4.

3a. Always-on probes (used by every artifact)

• Project name + version. Try, in order, package.json (name, version), pyproject.toml ([project] name, version), Cargo.toml, go.mod, composer.json, Gemfile. Fall back to the basename of the project root.
• Language mix. find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.rb" -o -name "*.java" -o -name "*.kt" -o -name "*.swift" -o -name "*.php" \) -not -path "./node_modules/*" -not -path "./.git/*" -not -path "./dist/*" -not -path "./build/*" -not -path "./.next/*" -not -path "./target/*" -not -path "./vendor/*" 2>/dev/null | awk -F. '{print $NF}' | sort | uniq -c | sort -rn | head -8
• Top-level directory map. ls -1 -d */ 2>/dev/null | head -40. For each non-hidden directory, do a one-line peek (ls -1 <dir> | head -3) so the generator can describe what each holds without inventing.
• README.md — Read the first ~80 lines if it exists. Often the cleanest source of "what is this".
• .gitignore — Read in full (small file). Helps the generator avoid hallucinating tooling that isn't actually used.

3b. CLAUDE.md probes (only if generating CLAUDE.md)

• Test runner. Look for: package.json scripts.test, pytest.ini / pyproject.toml [tool.pytest], cargo test, go test, Makefile test target, .github/workflows/*.yml for CI test commands.
• Type-check / lint commands. tsconfig.json, mypy.ini, ruff.toml, eslintrc*, biome.json, Cargo.toml, clippy.toml.
• Dev / build commands. package.json scripts.{dev,build,start}, Makefile targets, Justfile, Taskfile.yml.
• Package manager. Presence of pnpm-lock.yaml, yarn.lock, package-lock.json, bun.lockb, poetry.lock, uv.lock, Cargo.lock, go.sum.
• Existing nested CLAUDE.md files (already collected in Step 1) — used to cross-reference scope so the root file doesn't duplicate them.

3c. ARCHITECTURE.md probes (only if generating ARCHITECTURE.md)

• Entry points. package.json main / bin, pyproject.toml [project.scripts], Cargo.toml [[bin]], top-level src/index.*, src/main.*, cmd/**, app/main.py.
• Framework signals. Grep package.json and lockfiles for: react, next, nuxt, vue, svelte, solid, expo, react-native, electron, tauri, fastapi, django, flask, rails, actix, axum, gin, nest, express, koa, hono. Also probe requirements.txt and pyproject.toml.
• Database / ORM signals. prisma/schema.prisma, drizzle.config.*, migrations/, alembic.ini, schema.rb, mongoose, sqlx, sea-orm.
• Layered structure. Glob for canonical layer dirs: src/{components,pages,routes,api,lib,utils,services,models,db,hooks,store,server,client}, app/, cmd/, internal/, pkg/, internal/handler/. Whichever exist define the project's natural layering.

3d. CODE-PATTERNS.md probes (only if generating CODE-PATTERNS.md)

• Recurring imports. grep -rh "^import" src/ app/ lib/ 2>/dev/null | sort | uniq -c | sort -rn | head -20. Identifies most-used internal modules — these are the high-leverage patterns to document.
• Component / module conventions. Sample 2–3 files from each major layer identified in 3c. Note naming (PascalCase.tsx, kebab-case.ts, snake_case.py), test colocation (*.test.*, __tests__/), and barrel exports (index.ts).
• Shared utilities. Look for an obvious lib/ or utils/ directory and list its top files via ls. Read the index file or the largest 1–2 files for signature shape (don't summarize bodies).
• Style / formatting. .prettierrc*, .editorconfig, biome.json, rustfmt.toml, pyproject.toml [tool.black]. Just record what's present.

Stop probing when you have enough. This is a survey, not an audit. If a probe returns nothing, leave the corresponding section in the generated file as a single-line placeholder (e.g., _No conventional test runner detected — fill in._) rather than guessing.

3e. Optional: delegate exploration

For very large repos (>2000 source files, or where Step 3a–3d would burn through the orchestrator's context), delegate exploration to the built-in Explore subagent instead. Spawn it via the Agent tool with subagent_type: "Explore" and a thoroughness of "medium", asking for the same probe outputs as bullets. Keep the delegation prompt concrete — list the exact questions, not "explore the codebase".

Step 4: Generate the chosen artifacts

For each entry in to_generate:

1. Resolve the target path:
   • CLAUDE.md → ./CLAUDE.md (always project root).
   • ARCHITECTURE.md → ./docs/ARCHITECTURE.md if a docs/ directory exists OR if the project has 5+ source directories at the top level; otherwise ./ARCHITECTURE.md. If docs/ does not exist and the chosen path uses it, create the directory with mkdir -p docs first.
   • CODE-PATTERNS.md → same rule as ARCHITECTURE.md (docs/ if applicable).
2. Re-check existence right before writing (test -e <path>). If the file now exists (race or user added it between steps), skip it and report "skipped (file appeared during run)".
3. Write the file with the templates below. Use Write — these are new files. Keep the content lean: the goal is a useful starting skeleton that the user fills in, not a comprehensive auto-doc.

Template — CLAUDE.md

Aim for ~30–60 lines total. Every line must be useful to every future agent invocation. If a section has no content from Step 3's survey, write the single-line placeholder verbatim — do not invent.

# CLAUDE.md

Guidance for Claude Code (claude.ai/code) working in this repo.

## Project Overview

{1–3 sentences from README + survey: what this project is, who uses it, the
single most important architectural choice. If README was empty, write:
"_Project overview pending — describe what this project is and who uses it._"}

## Stack & Tooling

- **Language(s):** {top 1–3 from 3a language mix}
- **Package manager:** {detected lockfile family, or "_unknown_"}
- **Test:** `{detected test command or "_no test command detected_"}`
- **Type-check:** `{detected typecheck command or "_n/a_"}`
- **Lint:** `{detected lint command or "_n/a_"}`
- **Dev / build:** `{detected dev or build command or "_n/a_"}`

## Layout

{One bullet per top-level non-hidden directory, ≤1 line each, derived from 3a's
peek. Skip `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `target/`.}

## Reference

{One bullet per sibling reference doc that exists OR that this run is creating:}
- **Architecture & system design** → [`{relative path to ARCHITECTURE.md}`]({relative path}) {include only if present or being generated this run}
- **Code patterns & conventions** → [`{relative path to CODE-PATTERNS.md}`]({relative path}) {include only if present or being generated this run}

## Conventions

_Add project-wide rules here as they emerge. `/soloflow:compound` will append
sprint-derived learnings to this section over time. Keep entries terse —
detailed implementation patterns belong in `CODE-PATTERNS.md`, not here._

Template — ARCHITECTURE.md

Aim for ~50–100 lines. Sections that have nothing concrete from the survey should carry a single-line placeholder rather than fabricated content.

# Architecture

## Purpose

{1–2 sentences. What this system does. Pull from README if available.}

## Entry Points

{Bullet each detected entry point with its file path. If none detected, write
"_No conventional entry point detected — list the file(s) a new contributor
should open first._"}

## Top-Level Layout

{For each major top-level directory found in 3a, write one ≤2-line entry
explaining its role. Use the language mix and 3c probes to make the description
concrete. Example:
- **`src/components/`** — React components. Functional, TypeScript, colocated tests.
- **`src/server/`** — Express handlers, organized by route prefix.
}

## Major Components / Layers

{Use 3c's layered-structure probe. One subsection per layer that actually
exists. Each subsection: 2–4 sentences on responsibility + the dirs/files that
implement it. If only one layer exists, fold this into "Top-Level Layout"
above and remove this section.}

## Frameworks & External Dependencies

{Bullet each framework signal detected in 3c. Include the version if pulled
from package.json/pyproject.toml. Example:
- **Next.js {version}** — App Router; server components by default.
- **Prisma {version}** — Postgres; schema in `prisma/schema.prisma`.
}

## Data Model

{If 3c found schema/migration files, summarize: where the schema lives, what
migration tool runs it, and the 3–6 most central models/tables (names only).
If no schema found, write "_No persistent data layer detected — update if this
is wrong._"}

## Build & Run

{Detected dev command, e.g. pnpm dev} {Detected build command} {Detected test command}

## Decisions & Trade-offs

_Add architectural decisions here as they're made. ADRs (one file per decision
under `docs/decisions/`) are encouraged for non-trivial trade-offs._

Template — CODE-PATTERNS.md

Aim for ~40–80 lines. Each pattern entry is a name + a 1–3 line description + a file-path pointer. Don't paste code blocks — point to canonical examples in the repo so they stay current.

# Code Patterns

Reusable conventions and shared utilities in this codebase. Each entry points
to a canonical example — read those for the actual implementation.

## File / Directory Conventions

- **Naming:** {detected — e.g. "Components: `PascalCase.tsx`. Utilities: `kebab-case.ts`."}
- **Test colocation:** {detected — e.g. "Tests live next to source as `*.test.ts`." or `__tests__/` subdirectories.}
- **Barrels:** {detected — e.g. "`index.ts` re-exports the public surface of each module folder." or "_no barrel pattern in use_"}
- **Formatting:** {detected formatter and config file, or "_no formatter config detected_"}

## Shared Utilities

{For each significant util/helper module identified in 3d, a one-block entry:}

### {module name, e.g. `lib/result`}

- **Path:** `{relative path}`
- **Use it for:** {one-sentence purpose, derived from imports + signature}
- **Canonical example:** `{path/to/file/that/uses/it.ts}`

## Recurring Patterns

_Document patterns here as they recur. Examples of patterns worth capturing:_

- _Data-fetching shape (e.g. "All server fetches go through `lib/api.ts` which retries on 5xx.")_
- _State management (e.g. "Global state lives in Zustand stores under `src/store/`; component-local state uses `useState`.")_
- _Error handling (e.g. "Errors thrown inside route handlers are caught by `withErrorBoundary`; never throw raw.")_
- _Form handling, validation, auth, logging — anything a future agent would otherwise re-discover._

`/soloflow:compound` will append patterns extracted from completed sprints to
this file over time.

After writing each file, print one line per file:

✓ Wrote {relative path} ({line count} lines)

If a file was skipped at the existence re-check, print:

⊘ Skipped {relative path} — file appeared during run

Step 5: Commit

Skip this step entirely if is_git from Step 0 is false, or if every selected artifact was skipped in Step 4.

1. For each newly written file, run git check-ignore -q <path>. Skip from the commit any path that is gitignored, but still keep the file on disk and warn the user (one line: ⚠ {path} is gitignored — written but not staged).
2. Stage only the explicit list of created files (e.g., git add CLAUDE.md docs/ARCHITECTURE.md docs/CODE-PATTERNS.md). Never git add . or git add -A.
3. If git diff --cached --quiet reports no staged changes, skip the commit silently.
4. Otherwise commit per the global atomic-commit rule:
   • Commit message: docs: bootstrap {comma-joined names} — e.g., docs: bootstrap CLAUDE.md, ARCHITECTURE.md, CODE-PATTERNS.md.
   • Single commit covering all newly written files (this is one logical task: "scaffold project context"; splitting into three commits is noise).
5. Do not push. (Global rule: commits stay local until the user asks.)

Step 6: Report and next steps

Print:

## /soloflow:map-codebase — complete

Generated:
{one line per file: ✓ <relative path>}

{If any were skipped: list them with the skip reason.}

Already present (left untouched):
{one line per pre-existing artifact, or "(none)"}

Next steps:
  - Open the generated files and replace placeholder lines with real content.
    The survey-driven defaults are starting points, not finished docs.
  - /soloflow:init        — if you haven't already, scaffold .soloflow/ state.
  - /soloflow:idea-extractor "<description>"  — start your first feature.
  - /soloflow:compound    — adds sprint-derived learnings to these files later.

If to_generate was empty (user cancelled in Step 2), the Step 6 report collapses to a single line: Cancelled — no files written.

---

Scope

This command only writes the three top-level context files at the conventional paths. It does not:

• Generate or modify nested CLAUDE.md files (those are earned through recurring scope, not bootstrapped — Claude or the user creates them when a directory develops its own conventions).
• Touch .soloflow/ state. SoloFlow scaffolding is /soloflow:init's job.
• Run linters, tests, or any code-mutating tooling.
• Re-survey or re-write existing artifacts. To refresh, delete the file (or rename it) and re-run this command, OR use /soloflow:prune to consolidate.