From soloflow
Surveys project and generates missing CLAUDE.md, ARCHITECTURE.md, CODE-PATTERNS.md for SoloFlow agent shared context. Idempotent; supports skip flags.
npx claudepluginhub kesteva/soloflow --plugin soloflow-dev# /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 ad...
/map-codebaseAnalyzes codebase with parallel mapper agents to produce 7 structured documents in .planning/codebase/: STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md.
/map-codebaseAnalyzes codebase with parallel mapper agents, optionally targeting a specific area, to produce .planning/codebase/ documents.
/map-codebasePerforms deep codebase analysis with parallel agents, producing 7 structured documents on tech stack, architecture, structure, conventions, testing, integrations, and concerns.
/map-codebaseAnalyzes existing repository and creates persistent codebase map in docs/project/codebase-map.md plus current status in docs/project/current.md. Optional focus area.
/map-codebaseBootstraps LID in existing codebase: reads files in scope, proposes lens-based clusterings, reconciles with user, generates LLD/HLD/EARS skeletons and arrow overlay, prompts to flesh out. Token-intensive.
/map-codebaseAnalyzes an existing codebase and produces structured reference documentation for starting new projects on top of it.
Share bugs, ideas, or general feedback.
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.
pwd via Bash to capture the project root (used in commit messages and
reported paths).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.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.
Glob for each artifact in its conventional locations. Treat any match as "present" — never propose to overwrite. Conventions surveyed:
CLAUDE.md at project root.**/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,
docs/ARCHITECTURE.md, docs/architecture.md, ARCHITECTURE/README.md.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.
Use a single AskUserQuestion:
"Generate the missing context files? You can drop any of them — only the selected ones will be written.""Generate"truemissing 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)."Cancel".If the user picks "Cancel" (or selects nothing): print Aborted — no files written. and stop.
Carry the selected list forward as to_generate.
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.
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.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 -8ls -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..gitignore — Read in full (small file). Helps the generator avoid
hallucinating tooling that isn't actually used.package.json scripts.test, pytest.ini /
pyproject.toml [tool.pytest], cargo test, go test, Makefile test
target, .github/workflows/*.yml for CI test commands.tsconfig.json, mypy.ini, ruff.toml,
eslintrc*, biome.json, Cargo.toml, clippy.toml.package.json scripts.{dev,build,start},
Makefile targets, Justfile, Taskfile.yml.pnpm-lock.yaml, yarn.lock,
package-lock.json, bun.lockb, poetry.lock, uv.lock, Cargo.lock,
go.sum.package.json main / bin, pyproject.toml [project.scripts],
Cargo.toml [[bin]], top-level src/index.*, src/main.*, cmd/**,
app/main.py.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.prisma/schema.prisma, drizzle.config.*,
migrations/, alembic.ini, schema.rb, mongoose, sqlx, sea-orm.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.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.PascalCase.tsx, kebab-case.ts,
snake_case.py), test colocation (*.test.*, __tests__/), and barrel
exports (index.ts).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)..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.
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".
For each entry in to_generate:
./CLAUDE.md (always project root)../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.docs/ if applicable).test -e <path>). If the file now
exists (race or user added it between steps), skip it and report "skipped
(file appeared during run)".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.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._
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._
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
Skip this step entirely if is_git from Step 0 is false, or if every selected
artifact was skipped in Step 4.
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).git add CLAUDE.md docs/ARCHITECTURE.md docs/CODE-PATTERNS.md). Never
git add . or git add -A.git diff --cached --quiet reports no staged changes, skip the commit
silently.docs: bootstrap {comma-joined names} —
e.g., docs: bootstrap CLAUDE.md, ARCHITECTURE.md, CODE-PATTERNS.md.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.
This command only writes the three top-level context files at the conventional paths. It does not:
.soloflow/ state. SoloFlow scaffolding is /soloflow:init's job./soloflow:prune to consolidate.