R-seed-docs

Seed Docs

Let: σ := .dev/stack.yml config DOCS := docs.path from σ (default: docs) FMT := md (write always Markdown; legacy .mdx stubs still eligible for fill) θ := stub threshold (< 30 non-blank, non-frontmatter lines OR ∃ TODO: markers) K := knowledge extracted from CLAUDE.md + codebase scan

Goal: fill every stub doc so agents find actionable guidance, not placeholder text.

Idempotent — skip files with ≥ 30 lines of real content (∄ TODOs). Safe to re-run.

/R-seed-docs                   → auto-discover DOCS from stack.yml
/R-seed-docs --docs-path docs  → explicit path
/R-seed-docs --no-scan         → skip codebase scan, use CLAUDE.md only

Phase 1 — Load Config

Read σ (cat .dev/stack.yml 2>/dev/null). Record DOCS, runtime, backend.framework, frontend.framework, backend.orm.

¬σ → DOCS=docs. --docs-path <p> ∈ $ARGUMENTS → DOCS=p. --no-scan ∈ $ARGUMENTS → skip Phase 3.

DOCS dir ∄ → present choice Run /init first | Create docs dir and seed | Cancel

• "Run /init" → explain /R-env-setup Phase 3 (scaffold-docs) or /R-dev-init creates stubs, exit.
• "Create" → mkdir -p {DOCS}/{architecture,standards,guides,processes}, continue.

Phase 2 — Read CLAUDE.md

Read CLAUDE.md (∃) + any @-imported files it references.

Extract into K:

• Purpose — one-paragraph project summary
• Architecture style — monolith | monorepo | microservices | plugin-based | other
• Module/folder structure — src/ layout, package names, plugin dirs
• Naming conventions — file, class, function, DB naming rules
• Stack — framework, ORM, UI lib, test runner, deploy target
• Key commands — dev, build, test, lint (from commands.* in σ or CLAUDE.md)
• Domain terms — glossary items, entity names, bounded contexts
• Patterns — "always X", "never Y", "use X for Y" rules
• Data flow — request lifecycle, event patterns, module boundaries
• Error handling — exception hierarchy, boundary rules
• Design principles — numbered/bulleted principles from CLAUDE.md

Display: Extracted {|K topics|} topics from CLAUDE.md.

Phase 3 — Codebase Scan (skip if --no-scan)

3a. Entry points — Glob: {src,app,lib,packages,plugins}/index.{ts,js,py,go,rb}, main.{ts,js,py,go,rb}, server.{ts,js}, app.{ts,js,py}

3b. Module structure — Glob {src,app,lib,packages,plugins}/** (head_limit: 40) + Bash(ls):

• Glob **/*.{service,controller,repository,handler,resolver}.ts (TS/JS)
• Python: Glob **/*.py, **/routers/**, **/models/**, **/schemas/**, **/services/**
• Go: Glob cmd/**, internal/**, pkg/**

3c. Naming patterns — Glob 10 files per type. Infer: file naming style, class/function naming (read first 30 lines of 3 files).

3d. Dependencies — read package.json | pyproject.toml / requirements.txt | go.mod. Identify major deps + versions if relevant.

3e. Test conventions — sample 2 test files: check describe/it/test naming, fixture patterns, co-location vs __tests__/.

Merge scan results into K. Display: Codebase scan: {N} source files sampled, {M} patterns extracted.

Phase 4 — Identify Stubs

Glob: {DOCS}/**/*.{md,mdx}. ∀ file — count non-blank, non-frontmatter, non-comment lines. File matches θ → stub.

Display:

Stub files to populate ({N}):
  docs/architecture/index.md         3 lines, 2 TODOs
  docs/architecture/patterns.md      5 lines, 4 TODOs
  docs/standards/backend-patterns.md 8 lines, 5 TODOs
  docs/standards/testing.md          4 lines, 3 TODOs
  ...

Already populated ({M} files) — will skip.

N=0 → "All docs appear populated. Use --force to re-seed (not implemented). Exiting." → exit.

→ present choice Populate {N} stub files | Select files | Cancel

• "Select" → list files numbered, present multi-select: which to include (comma-separated indices).

Phase 5 — Populate Stubs

∀ file ∈ selected stubs (order: architecture/index → architecture/patterns → architecture/ubiquitous-language → standards/* → guides/* → processes/* → rest):

Read file → identify TODO sections → fill each using K.

Section filling rules:

Writing rules:

• Replace TODO: <placeholder> with real content; remove the TODO line.
• Remove <!-- comment blocks --> covered by real content; keep only if they add context.
• Standards docs → write for developers; AI Quick Reference → write for agents.
• K has no data for section → keep TODO + add hint: TODO: (seed-docs found no data — check CLAUDE.md or run /R-seed-docs after adding more project context).
• ¬fabricate — if genuinely unknown, say so with a note.
• CI / quality-gate docs (AGENTS.md, standards.testing, lefthook comments): point at the package script ({package_manager} run validate:full or {commands.*}). Ban enumerating validate:full steps — the script is the SSoT; a copied list drifts (parallel-path-drift).
• Write/fill as plain Markdown. Prefer fenced Mermaid code blocks. If filling a legacy .mdx file, keep its existing component conventions; never convert .md → .mdx.

After each file: display ✅ {relative path} — {N} TODOs filled, {M} sections updated.

Phase 6 — AI Quick Reference Audit

After populating, verify ∀ ## AI Quick Reference section across all standards docs has ≥ 3 imperative rules. < 3 rules → add from K.patterns or infer from framework conventions.

Phase 7 — Summary

Seed Docs Complete
==================

  Source:      CLAUDE.md{+ codebase scan}
  Topics:      {|K|} knowledge items extracted
  Populated:   {N} files
  Skipped:     {M} already-populated files
  TODOs filled: {total}

  Files updated:
    docs/architecture/index.md          ✅ 2 TODOs filled
    docs/architecture/patterns.md       ✅ 4 TODOs filled
    docs/standards/backend-patterns.md  ✅ 5 TODOs filled
    ...

→ present choice Commit seeded docs | Review first, commit manually | Skip

"Commit" → git add {DOCS} + commit:

docs: seed architecture and standards docs from CLAUDE.md

Edge Cases

$ARGUMENTS