foundation

name

foundation

description

Generate the DevFlow foundation for a repo without committing to a full plan — as-is docs/SPEC skeleton (architecture, contracts, glossary, decision log), the core Mermaid diagram set, a one-command verification gate runner, a codebase guide, and the diagram-led / SPEC-assisted workflow conventions. Use when the user wants just the documentation and diagram foundation, a SPEC skeleton, or architecture docs — no sprints, no execution plan. Triggers: foundation, bootstrap docs, SPEC skeleton, architecture diagrams, 基座, 地基, 文檔基座.

request-devflow-plan:foundation

Build the DevFlow foundation (diagram-led, SPEC-assisted) as a standalone product — everything a plan's Sprint 0 would build, without a plan folder, sprints, or iron rules. Write all generated documents in the user's conversation language. Documentation is strictly as-is: it records what exists, never aspirations.

Flow

Step 1 — Recon

Read the repo: CLAUDE.md, README.md, package manifests, source layout, tests, CI, existing docs/SPEC/ and docs/diagrams/. Inventory what already exists — existing pieces are never rebuilt, only gap-filled.

Step 2 — Confirm scope

One AskUserQuestion, only when recon leaves it genuinely ambiguous: which diagrams apply (per the selection table in ../plan/references/devflow-distilled.md — UI flow for frontends, state machines where stateful entities exist) and where the docs live (default docs/SPEC/ and docs/diagrams/).

Step 3 — Generate (gap-fill only)

1. SPEC skeleton: docs/SPEC/ARCHITECTURE.md (module boundaries + allowed dependency directions), docs/SPEC/specs/API_CONTRACT.md (sole wire-contract authority; no API → a domain behavior contract instead), GLOSSARY.md, DECISIONS_AND_CHANGELOG.md.
2. Core as-is diagrams: the required set from the selection table (C4 container, package/dependency, ER, one sequence per core write path, state machines for stateful entities, deployment; UI flow for frontends). Mermaid in Markdown, zero toolchain; each file pinned to: purpose / diagram / contracts the picture can't carry → SPEC link / last-calibrated commit.
3. Verification gates: a one-command runner wrapping the repo's existing type check / lint / test tooling, in the repo's native shell (exit codes never read through a pipe; skipped ≠ green). Missing harness → record it as a gap with a recommendation; do not build one here.
4. Codebase guide: a module map + conventions document (CODEBASE_GUIDE.md, or the repo's existing equivalent extended).
5. Workflow conventions: docs/SPEC/WORKFLOW.md — the five SPEC rules (SPEC before code; report mismatches, never self-adjudicate; never edit SPEC to fit code; never delete a SPEC file; behavior changes sync SPEC in the same commit) plus the diagram-first loop and anti-drift habits, stated as standing repo conventions.

Step 4 — Self-check and deliver

• Every structural claim in a generated document (module, dependency direction, table, endpoint, state) carries file:line evidence gathered during recon — a claim without evidence may not be written. Run every gate command once and show the output.
• Deliver the inventory: created / extended / already existed / gaps noted.
• End with the Next steps block — full copy-paste command (never shorthand), preceded by the advisory "Run /clear (or open a new session) first": /request-devflow-plan:plan — plan real work; its recon finds this foundation and skips Sprint 0 basework (noted gaps, e.g. a missing test harness, become Sprint 0 items there) Docs were all you wanted → done; keep the diagrams calibrated per WORKFLOW.md.

Never

• Document aspirations as reality (as-is only)
• Rebuild anything that already exists
• Introduce new tooling — the gate runner wraps what the repo already has