@ngocsangairvds/vsaf 3.0.12 → 3.1.1

package/README.md

@@ -1,42 +1,37 @@
 # VSAF — SDLC Agentic Framework
 
-A development framework for Claude Code built on 4 integrated tools. Plan with
-AI agents, understand impact before coding, execute with TDD guardrails, track
-every decision. $20/month total.
+A development framework for Claude Code. Plan with AI agents, understand impact
+before coding, execute with TDD guardrails. $20/month total.
 
 ---
 
 ## Architecture
 
+3 tools, 5 workflow phases:
+
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│  DISCOVERY         BMAD (agents)                                     │
-│                    PM · Analyst · domain/market/tech research        │
-├──────────────────────────────────────────────────────────────────────┤
-│  PLANNING          BMAD (agents)                                     │
-│                    Analyst · Architect · Brainstorming · QA          │
-├──────────────────────────────────────────────────────────────────────┤
-│  CODE INTEL        GitNexus (MCP backbone)                           │
-│                    call-graph, impact analysis, blast radius         │
-├──────────────────────────────────────────────────────────────────────┤
-│  MEMORY            MemPalace (knowledge base)                        │
-│                    architecture decisions, temporal KG               │
-├──────────────────────────────────────────────────────────────────────┤
-│  IMPLEMENTATION    Claude Code + Superpowers                         │
-│                    TDD execution, code review                        │
-├──────────────────────────────────────────────────────────────────────┤
-│  KNOWLEDGE         Graphify + BMAD (tech writer, editors)            │
-│                    wiki, docs sync, distillation                     │
-└──────────────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────┐
+│  Phase           Tools used                            │
+├────────────────────────────────────────────────────────┤
+│  DISCOVERY       BMAD — domain, market, tech research  │
+│  PLANNING        BMAD — analyst, architect, QA         │
+│  CODE INTEL      GitNexus — impact, call-graph         │
+│  IMPLEMENTATION  Claude Code + Superpowers — TDD       │
+│  KNOWLEDGE       BMAD — tech writer, docs sync         │
+└────────────────────────────────────────────────────────┘
 ```
 
-See [1-setup-guide.md](docs/onboarding/1-setup-guide.md#2-how-the-tools-fit-together) for what each layer does and how the tools relate.
+| Tool | Role |
+|------|------|
+| **BMAD** | AI agents for planning, review, docs (PM, Analyst, Architect, QA, Tech Writer) |
+| **GitNexus** | Code knowledge graph via MCP — blast radius before every code change |
+| **Superpowers** | Claude Code plugin — TDD execution, code review, debugging discipline |
+
+---
 
 ## Quickstart
 
-Requires **Node.js ≥ 18**, **Python ≥ 3.10**, **Git**, and a
-**Claude Code subscription** ($20/mo). Full prerequisites in
-[1-setup-guide.md](docs/onboarding/1-setup-guide.md#3-prerequisites).
+Requires **Node.js ≥ 18**, **Git**, and a **Claude Code subscription** ($20/mo).
 
 ```bash
 git clone <this-repo> && cd vsaf
@@ -44,7 +39,7 @@ npx @ngocsangairvds/vsaf@latest init
 npx @ngocsangairvds/vsaf@latest status
 ```
 
-One manual post-setup step (requires an interactive Claude Code session):
+One manual step inside Claude Code:
 
 ```
 /plugin install superpowers@claude-plugins-official
@@ -52,9 +47,9 @@ One manual post-setup step (requires an interactive Claude Code session):
 
 Restart Claude Code after installing Superpowers.
 
-## Documentation
+---
 
-All onboarding docs live in [`docs/onboarding/`](docs/onboarding/).
+## Documentation
 
 | # | Doc | Covers |
 |---|-----|--------|
@@ -63,10 +58,11 @@ All onboarding docs live in [`docs/onboarding/`](docs/onboarding/).
 | 3 | [3-cheatsheet.md](docs/onboarding/3-cheatsheet.md) | 1-page command reference — print and pin |
 | 4 | [4-milestones.md](docs/onboarding/4-milestones.md) | Day 1 / Week 1 / Month 1 ramp-up path |
 | 5 | [5-faq.md](docs/onboarding/5-faq.md) | Mindset questions every new dev asks |
-| — | [2-workflow-guide.vi.md](docs/onboarding/2-workflow-guide.vi.md) | Bản tiếng Việt của workflow guide |
+| — | [2-workflow-guide.vi.md](docs/onboarding/2-workflow-guide.vi.md) | Vietnamese version of the workflow guide |
 
-**New here?** Start with **1-setup-guide** → then **4-milestones** for your
-first 30 days.
+**New here?** Start with **1-setup-guide** → then **4-milestones**.
+
+---
 
 ## Directory Layout
 
@@ -76,10 +72,10 @@ first 30 days.
 │   ├── settings.json       # Local AI settings
 │   └── skills/             # VSAF + BMAD + GitNexus skills
 ├── _bmad/                  # BMAD agent workspace
-├── docs/project/           # Generated project artifacts (SRS, testcases, plans)
+├── docs/project/           # Generated artifacts (PRD, SRS, testcases, plans)
 ├── docs/
 │   ├── architecture/       # Architecture documents (from BMAD Architect)
-│   └── onboarding/         # Developer onboarding (see table above)
+│   └── onboarding/         # Developer onboarding docs
 ├── assets/templates/       # Project scaffold templates
 ├── scripts/
 │   └── setup-vsaf.sh       # Full setup automation (used by `vsaf init`)
@@ -87,9 +83,9 @@ first 30 days.
 └── AGENTS.md               # GitNexus rules for AI agents
 ```
 
-## Daily Operations
+---
 
-Run `npx @ngocsangairvds/vsaf@latest --help` for the full list. Highlights:
+## Daily Operations
 
 | Command | What It Does |
 |---|---|
@@ -97,177 +93,328 @@ Run `npx @ngocsangairvds/vsaf@latest --help` for the full list. Highlights:
 | `vsaf index` | Re-index codebase (GitNexus) — run after every merge |
 | `vsaf review` | 2-layer review coordinator |
 | `vsaf status` | Show status of all installed tools |
-| `vsaf mine` | Extract decisions into MemPalace (weekly + after major decisions) |
 
 Main skill commands inside Claude Code:
 
-- `/vsaf-discover <product/domain>` — product discovery *(new)*
-- `/vsaf-sprint plan|status|story` — sprint management *(new)*
-- `/vsaf-onboard`
-- `/vsaf-plan <feature>`
-- `/vsaf-doc`
-- `/vsaf-test <path/to/srs>`
-- `/vsaf-build <path/to/srs> <path/to/testcases>`
-- `/vsaf-ship`
-- `/vsaf-docs` — documentation sync *(new)*
+| Command | When |
+|---------|------|
+| `/vsaf-discover <product>` | Starting a new product |
+| `/vsaf-sprint plan\|status\|story` | Sprint management |
+| `/vsaf-onboard` | First time on a codebase |
+| `/vsaf-plan <feature>` | Scope + impact + approach |
+| `/vsaf-doc-prd` | Write PRD from approved plan |
+| `/vsaf-doc-srs` | Write SRS from PRD |
+| `/vsaf-test <path/to/srs>` | Generate testcases from SRS |
+| `/vsaf-build <prd> <srs> <testcases>` | Implement with TDD (reads all 3 docs first) |
+| `/vsaf-test run <path/to/testcases>` | Run tests, write results to file |
+| `/vsaf-ship` | Review + ship |
+| `/vsaf-docs` | Documentation sync |
+| `/vsaf-retro` | Sprint/epic retrospective |
+
+---
 
 ## Workflow
 
-Full product lifecycle:
+### Standard Flow (features)
+
+```
+[Product level — once per product]
+/vsaf-discover → /vsaf-sprint plan
+
+[Per feature in sprint]
+/vsaf-onboard
+  → /vsaf-plan <feature>
+  → /vsaf-doc-prd
+  → /vsaf-doc-srs
+  → /vsaf-test <path/to/srs>          # generate testcases
+  → /vsaf-build <prd> <srs> <testcases>  # reads all 3 docs before writing code
+  → /vsaf-test run <path/to/testcases>   # run tests, write results to file
+  → /vsaf-ship
+
+[End of sprint]
+/vsaf-docs → /vsaf-sprint status → /vsaf-retro → next sprint
+```
+
+### Quick Flow (bug fixes / small changes)
 
 ```
-/vsaf-discover → /vsaf-sprint plan → [per feature in sprint]:
-  /vsaf-onboard → /vsaf-plan → /vsaf-doc → /vsaf-test → /vsaf-build → /vsaf-ship
-→ /vsaf-docs → /vsaf-sprint status → next sprint
+gitnexus_impact on symbol(s) you'll touch
+/vsaf-doc-srs (mini-SRS)
+/vsaf-test <mini-srs>
+/vsaf-build <mini-srs> <mini-testcases>   # reads docs before coding
+/vsaf-test run <mini-testcases>
+/vsaf-ship
 ```
 
-Every feature follows an **SRS-first cycle**. Bug fixes (Quick Flow) may use
-mini-SRS + mini-testcases, but still require `gitnexus_impact` before editing
-symbols and `gitnexus_detect_changes` before commit.
+### Hotfix Flow (production incidents — bypass, then backfill)
+
+```
+gitnexus_impact on target symbol         # mandatory, even under pressure
+[minimal fix — 1 commit]
+/superpowers:code-review (Layer 1)
+vsaf index (Layer 2)
+git push --hotfix-branch
+↓ after incident resolved:
+/vsaf-doc-srs (retroactive mini-SRS)
+/vsaf-test <mini-srs> + /vsaf-test run
+/vsaf-ship (close the loop)
+```
+
+> **Hotfix rule:** Impact analysis is never skipped. Gates are minimised, not removed.
+> Retroactive SRS + testcases must be completed before the next sprint starts.
+
+---
 
-### Flow breakdown
+## Flow breakdown
+
+### `/vsaf-discover <product/domain>` — Product discovery
+
+> Run once when starting a new product. Skip for features inside an existing product.
 
-#### `/vsaf-discover <product/domain>` — Product discovery *(new)*
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **MemPalace** `mempalace_search` | Checks for prior research |
-| 2 | **BMAD** `bmad-domain-research` | Deep dive into domain/industry terminology, rules, patterns |
-| 3 | **BMAD** `bmad-market-research` | Competition landscape, customer needs, market trends |
-| 4 | **BMAD** `bmad-technical-research` | Tech stack options, feasibility, build-vs-buy |
-| 5 | **BMAD** `bmad-product-brief` | Synthesises findings into product brief |
-| 6 | **BMAD** `bmad-prfaq` | Working Backwards — stress-tests product concept |
-| 7 | **BMAD** `bmad-agent-pm` + `bmad-create-prd` | PM creates PRD from brief; `bmad-validate-prd` checks quality; `bmad-edit-prd` fixes issues |
-| 8 | **BMAD** `bmad-party-mode` | Multi-agent roundtable: PM + Analyst + Architect review |
-| 9 | **MemPalace** `mempalace_add_drawer` | Saves market insights + product decisions |
-| → | Output | Research artifacts, product brief, validated PRD, open questions |
-
-#### `/vsaf-sprint plan|status|story` — Sprint management *(new)*
+| 1 | **BMAD** `bmad-domain-research` | Domain/industry terminology, rules, patterns |
+| 2 | **BMAD** `bmad-market-research` | Competition, customer needs, market trends |
+| 3 | **BMAD** `bmad-technical-research` | Tech stack options, feasibility, build-vs-buy |
+| 4 | **BMAD** `bmad-product-brief` | Synthesises findings into product brief |
+| 5 | **BMAD** `bmad-prfaq` | Working Backwards — stress-tests product concept |
+| 6 | **BMAD** `bmad-agent-pm` + `bmad-create-prd` | PM creates initial PRD from brief |
+| 7 | **BMAD** `bmad-party-mode` | Multi-agent roundtable: PM + Analyst + Architect |
+| → | Output | Product brief, validated PRD, open questions |
+
+---
+
+### `/vsaf-sprint plan|status|story` — Sprint management
+
 | Mode | Tool | Does |
 |------|------|------|
-| **plan** | **BMAD** `bmad-create-epics-and-stories` | Breaks PRD into epics + prioritised user stories |
+| **plan** | **BMAD** `bmad-create-epics-and-stories` | Breaks PRD into epics + prioritised stories |
 | **plan** | **BMAD** `bmad-sprint-planning` | Assigns stories to sprint, identifies dependencies |
-| **plan** | **MemPalace** `mempalace_add_drawer` | Saves sprint decisions, priorities, trade-offs |
 | **status** | **BMAD** `bmad-sprint-status` | Progress %, burndown, blocked items, risks |
-| **story** | **BMAD** `bmad-create-story` | Creates detailed story file with full context for implementation |
+| **story** | **BMAD** `bmad-create-story` | Creates detailed story file for implementation |
 | → | Output | Sprint plan, status dashboard, or story file |
 
-#### `/vsaf-onboard` — Understand the codebase
+---
+
+### `/vsaf-onboard` — Understand the codebase
+
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **GitNexus** `mcp__gitnexus__query` + `group_list` | Maps modules, clusters, entry points, hot symbols |
-| 2 | **MemPalace** `mempalace_search` × 3 | Surfaces past architecture decisions, patterns, rationale |
-| → | Output | Project overview: architecture, patterns, key decisions, risk areas |
+| 1 | **GitNexus** `READ gitnexus://repo/{name}/context` | Codebase overview — size, index freshness, health |
+| 2 | **GitNexus** `READ gitnexus://repo/{name}/clusters` | Functional areas + cohesion scores |
+| 3 | **GitNexus** `READ gitnexus://repo/{name}/processes` | All execution flows in the codebase |
+| 4 | **GitNexus** `group_list` + `group_query` | Module groupings + inter-module relationships |
+| 5 | **GitNexus** `route_map` *(API projects)* | Maps all API routes to handlers |
+| 6 | **GitNexus** `context` on 3-5 key symbols | 360° view on main entry points — callers, callees, process participation |
+| 7 | *(Claude)* | Reads existing docs, synthesises project overview: architecture, patterns, key decisions, risk areas |
+| → | Output | Full mental model: modules, flows, API surface, hot symbols, risk areas |
+
+---
+
+### `/vsaf-plan <feature>` — Scope + impact + approach
+
+Output of this step: **approved scope document** (not yet PRD — that's next).
 
-#### `/vsaf-plan <feature>` — Analyse and plan
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **MemPalace** `mempalace_search` | Checks for prior decisions that affect this feature |
-| 2 | **BMAD** `bmad-agent-analyst` (Mary) | Elicits FRs, NFRs, edge cases, scope boundaries |
-| 3 | **GitNexus** `mcp__gitnexus__impact` + `query` | Blast radius — how many modules touched, risk level |
-| 4 | **Graphify** `/graphify path A B` *(if needed)* | Traces dependency path between two services |
-| 5 | **BMAD** `bmad-agent-architect` (Winston) | Proposes architecture approach, compares alternatives |
-| 5b | **BMAD** `bmad-create-architecture` *(if HIGH risk / >3 modules)* | Formal ADR → `docs/project/planning-artifacts/adr-[feature].md` |
-| 6 | **BMAD** `bmad-brainstorming` | Creative exploration — min. 20 alternatives / risk angles |
-| 7 | **BMAD** `bmad-advanced-elicitation` | Pre-mortem + red team — challenges chosen approach, finds failure modes |
-| → | Output | Scope, impact, approach, pre-mortem findings, rejected alternatives |
-
-#### `/vsaf-doc` — Write the SRS
+| 1 | **BMAD** `bmad-agent-analyst` | Elicits FRs, NFRs, edge cases, scope boundaries |
+| 2 | **GitNexus** `impact` + `query` | Blast radius — modules touched, risk level |
+| 2b | **GitNexus** `group_query` | Module boundaries — which groups are affected, interface contracts |
+| 3 | **BMAD** `bmad-agent-architect` | Proposes architecture approach, compares alternatives |
+| 3b | **BMAD** `bmad-create-architecture` *(HIGH risk / >3 modules)* | Formal ADR → `docs/project/planning-artifacts/adr-[feature].md` |
+| 4 | **Superpowers** `brainstorming` | Structured approach exploration — trade-offs, constraints, 2-3 viable options |
+| 4b | **BMAD** `bmad-brainstorming` | Creative exploration — min. 20 alternatives / risk angles |
+| 4c | **Superpowers** `dispatching-parallel-agents` *(>2 approaches)* | Parallel deep-dive research on top candidate approaches |
+| 5 | **BMAD** `bmad-advanced-elicitation` | Pre-mortem + red team — finds failure modes |
+| → | Output | Scope doc: boundaries, impact level, chosen approach, rejected alternatives |
+
+> **Gate:** If impact > 3 modules → split into smaller features before proceeding.
+
+---
+
+### `/vsaf-doc-prd` — Write the PRD
+
+Input: approved scope document from `/vsaf-plan`.
+Output: `docs/project/planning-artifacts/prd-[feature].md` — *what* to build, for whom, why.
+
+| Step | Tool | Does |
+|------|------|------|
+| 1 | **BMAD** `bmad-agent-pm` + `bmad-create-prd` | Writes PRD: goals, user stories, FRs, NFRs, success metrics |
+| 2 | **BMAD** `bmad-validate-prd` | Validates quality — completeness, clarity, testability |
+| 3 | **BMAD** `bmad-edit-prd` *(if FAIL)* | Fixes issues, re-validates |
+| 4 | **BMAD** `bmad-party-mode` *(HIGH risk features)* | Multi-agent roundtable (PM + Analyst + Architect) — catches blind spots single-agent misses |
+| → | Output | Approved `docs/project/planning-artifacts/prd-[feature].md` |
+
+> **PRD vs SRS:** PRD = business contract (why/what). SRS = engineering contract (how). Both are required before coding.
+
+---
+
+### `/vsaf-doc-srs` — Write the SRS
+
+Input: approved PRD from `/vsaf-doc-prd`.
+Output: `docs/project/srs/[feature].md` — *how* to build it.
+
 | Step | Tool | Does |
 |------|------|------|
 | 0 | *(Claude)* | Detects mode: **CREATE** (new SRS) or **EDIT** (modify existing) |
-| 1 | **MemPalace** `mempalace_search` | Checks for old decisions to reference in SRS |
-| 2a | **BMAD** `bmad-create-prd` *or* *(Claude)* | **CREATE mode**: writes SRS/PRD with FRs/NFRs + traceability IDs |
-| 2b | **BMAD** `bmad-edit-prd` | **EDIT mode**: modifies existing SRS in-place, preserves traceability IDs, flags testcase impact |
-| 3 | **BMAD** `bmad-validate-prd` | Validates SRS quality; if FAIL in EDIT mode → `bmad-edit-prd` fixes again |
-| 4 | *(Claude)* | Writes implement notes: affected modules, technical constraints |
-| 5 | **MemPalace** `mempalace_add_drawer` | Persists chosen approach + rejected alternatives |
-| → | Output | Validated `docs/project/srs/[feature].md` + testcase impact report |
-
-#### `/vsaf-test <path/to/srs>` — Generate testcases
+| 1a | *(Claude)* | **CREATE**: derives SRS from PRD — FRs/NFRs with traceability IDs |
+| 1b | **BMAD** `bmad-edit-prd` | **EDIT**: modifies existing SRS in-place, preserves traceability IDs, flags testcase impact |
+| 2 | **GitNexus** `context` on key symbols | Validates technical feasibility — are the symbols/APIs the SRS references real and reachable? |
+| 2b | **GitNexus** `group_contracts` *(cross-module features)* | Understands interface contracts between modules the SRS will touch |
+| 3 | **BMAD** `bmad-validate-prd` | Validates SRS quality; FAIL → fix and re-validate |
+| 4 | *(Claude)* | Writes implementation notes: affected modules, technical constraints |
+| → | Output | Validated `docs/project/srs/[feature].md` |
+
+> **Change request mid-build:** If requirements change after SRS is approved → run `/vsaf-doc-srs` in EDIT mode → re-run `/vsaf-test <srs>` to update testcases → resume `/vsaf-build`. Do not proceed with stale SRS.
+
+---
+
+### `/vsaf-test <path/to/srs>` — Generate testcases
+
+Input: approved SRS.
+Output: `docs/project/testcases/[feature].md` — testcase contract used in build and post-build verification.
+
 | Step | Tool | Does |
 |------|------|------|
+| 0 | **GitNexus** `query({query: "test <feature>"})` | Finds existing test patterns and conventions in the codebase — follow, don't reinvent |
 | 1 | **BMAD** `bmad-qa-generate-e2e-tests` | Derives unit / integration / edge-case tests from SRS FRs/NFRs |
-| 2 | **BMAD** `bmad-review-edge-case-hunter` | Finds unhandled boundaries, race conditions, null/empty cases — adds tests |
+| 2 | **BMAD** `bmad-review-edge-case-hunter` | Finds unhandled boundaries, race conditions, null/empty cases |
 | 3 | *(Claude)* | Validates every FR/NFR has ≥ 1 test, builds traceability matrix |
 | 4 | *(Claude)* | Saves to `docs/project/testcases/[feature].md` |
-| 5 | **BMAD** `bmad-check-implementation-readiness` | **Quality gate** — blocks build if SRS/testcase/architecture gaps found |
-| → | Output | Testcase contract + implementation readiness verdict (PASS/FAIL) |
+| 5 | **BMAD** `bmad-check-implementation-readiness` | **Quality gate** — blocks build if SRS/testcase/architecture gaps |
+| → | Output | Testcase contract + readiness verdict (PASS/FAIL) |
+
+---
+
+### `/vsaf-build <prd> <srs> <testcases>` — Implement with TDD
+
+> **Before writing a single line of code**, Claude reads and confirms understanding of all 3 input documents: PRD (what/why), SRS (how/FRs/NFRs), testcases (acceptance criteria). Implementation must not begin until this is complete.
+
+| Step | Tool | Does |
+|------|------|------|
+| 0 | *(Claude)* | **Reads PRD + SRS + testcases in full.** Confirms FR/NFR → testcase mapping. Reports any gaps before starting. |
+| 0b | **Superpowers** `brainstorming` | Brainstorms implementation approaches — trade-offs, risk, alternative designs before committing to a plan |
+| 1 | **Superpowers** `writing-plans` *or* *(Claude)* | Generates atomic task list from SRS + testcases. Each task maps to ≥1 FR/NFR. |
+| 1b | **Superpowers** `subagent-driven-development` *(plan >20 tasks)* | Alternative: dispatches tasks to sub-agents with two-phase review pipeline |
+| 2 | **Superpowers** `executing-plans` + `test-driven-development` | TDD loop per task: RED → GREEN → REFACTOR → COMMIT |
+| 2b | **GitNexus** `detect_changes` | Verifies only intended files changed before each commit |
+| 2c | **Superpowers** `verification-before-completion` | After each task: explicit verification that outcome matches spec — not just "tests pass" |
+| 3 | **BMAD** `bmad-checkpoint-preview` *(every 3-5 tasks)* | Human-in-the-loop — progress summary, flag issues, ask to continue |
+| 4 | **Superpowers** `systematic-debugging` | On failure: structured hypothesis → experiment → conclusion |
+| 4b | **BMAD** `bmad-correct-course` *(scope drift detected)* | Assesses impact, proposes plan adjustment. If requirements changed → stop, update SRS first. |
+| → | Output | Working code, all tests passing, verified against spec, 1 commit per task |
+
+> **3-strike rule:** Task fails 3 times → STOP. Architectural problem, not execution. Re-read SRS + testcases and redesign the task.
+
+---
+
+### `/vsaf-test run <path/to/testcases>` — Run tests + record results
+
+Run after `/vsaf-build` completes. Executes the full test suite against the implementation and writes a structured results file.
+
+| Step | Tool | Does |
+|------|------|------|
+| 1 | *(Claude)* | Re-reads testcase file, confirms all tests are present |
+| 2 | *(Claude + project test runner)* | Runs test suite (unit + integration + e2e) |
+| 3 | *(Claude)* | Records pass/fail per testcase, maps results back to FR/NFR traceability IDs |
+| 4 | **GitNexus** `detect_changes({scope: "compare", base_ref: "main"})` | Verifies tests cover all changed files/symbols — flags untested changes |
+| 5 | **GitNexus** `shape_check` *(optional)* | Validates no architectural constraints violated by the implementation |
+| 6 | *(Claude)* | Saves results to `docs/project/testcases/[feature]-results.md` (includes coverage + constraint compliance) |
+| 7 | *(Claude)* | **Gate:** if any FR/NFR has 0 passing tests OR untested changes detected → blocks ship, reports failures |
+| → | Output | `docs/project/testcases/[feature]-results.md` with pass rate, coverage, constraint check, and failure details |
+
+> Results file is required input for `/vsaf-ship`. Ship is blocked if gate fails.
+
+---
+
+### `/vsaf-ship` — Review and ship
+
+Input: working code + test results file (from `/vsaf-test run`).
 
-#### `/vsaf-build <path/to/srs> <path/to/testcases>` — Implement with TDD
 | Step | Tool | Does |
 |------|------|------|
-| 0 | **Superpowers** check | Detects plugin. If yes → uses write-plan, execute-plan, TDD, debugging. If no → warns + fallback |
-| 1 | **MemPalace** `mempalace_search` | Last check — no old decisions conflict with implementation |
-| 2 | *(Claude)* | Reads SRS + testcases, confirms FR/NFR → testcase mapping |
-| 3 | **Superpowers** `write-plan` *or* *(Claude)* | Generates atomic task list from SRS + testcases |
-| 4 | **Superpowers** `execute-plan` + `test-driven-development` *or* **Claude Code** | TDD loop per task. Large plans (20+): `subagent-driven-development` |
-| 4b | **GitNexus** `mcp__gitnexus__detect_changes` | Verifies only intended files changed before each commit |
-| 4.5 | **BMAD** `bmad-checkpoint-preview` *(every 3-5 tasks)* | Human-in-the-loop review — summarise progress, flag issues, ask user to continue |
-| 5 | **Superpowers** `systematic-debugging` *or* manual | On failure: structured hypothesis → experiment → conclusion |
-| 5b | **BMAD** `bmad-correct-course` *(if scope drift detected)* | Assesses impact of scope change, proposes adjusted plan vs re-plan |
-| → | Output | Working code, all tests passing, 1 commit per task |
-
-#### `/vsaf-ship` — Review, sync, and record
+| 0 | **GitNexus** `detect_changes({scope: "compare", base_ref: "main"})` | Full branch scope check — confirms only expected files/symbols changed |
+| 1 | **Superpowers** `requesting-code-review` | Structured handoff: what changed, why, what to watch for — gives reviewer context |
+| 2 | **Superpowers** `code-review` *or* **BMAD** `bmad-code-review` | Layer 1 — code quality, patterns, SOLID |
+| 2b | **Superpowers** `receiving-code-review` *(if feedback)* | Systematic response to reviewer pushback — no ad-hoc fixes |
+| 3 | **BMAD** `bmad-review-adversarial-general` + `bmad-review-edge-case-hunter` | Layer 1.5 — cynical attack + boundary analysis. Triage: MUST FIX / SHOULD FIX / NOTED |
+| 4 | **GitNexus** `shape_check` | Architectural constraint validation — no violations shipped |
+| 5 | **GitNexus** `vsaf index` | Layer 2 — updates call graph to reflect new code |
+| 6 | **Superpowers** `verification-before-completion` | Final gate — explicit verification that all deliverables match spec |
+| 7 | **Superpowers** `finishing-a-development-branch` | Pre-PR checklist — runs final checks before push |
+| 8 | *(git)* | Push branch, open PR (must include: impact summary, test results link, adversarial triage) |
+| → | Output | Shipped feature, updated graph, PR ready for review |
+
+---
+
+### `/vsaf-retro` — Retrospective
+
+> Run at end of sprint or end of epic. Separate from ship. Data-backed, not opinion-based.
+
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **Superpowers** `code-review` + `verification-before-completion` *or* **BMAD** `bmad-code-review` | Layer 1 — code quality, patterns, SOLID |
-| 2 | **BMAD** `bmad-review-adversarial-general` + `bmad-review-edge-case-hunter` | Layer 1.5 — cynical attack + boundary analysis. Triage: MUST FIX / SHOULD FIX / NOTED |
-| 3 | **GitNexus** `gitnexus analyze` / `vsaf index` | Layer 2 — updates call graph to reflect new code |
-| 4 | **Superpowers** `finishing-a-development-branch` *or* manual | Pre-PR checklist |
-| 5 | **MemPalace** `mempalace_add_drawer` + `diary_write` | Saves decisions, adversarial findings, session summary |
-| 6 | *(git)* | Push branch, open PR with impact + test + adversarial summary |
-| 7 | **BMAD** `bmad-retrospective` *(end of epic only)* | Lessons learned → MemPalace. What went well / what to improve |
-| → | Output | Shipped feature, updated graph, persistent knowledge, follow-up tasks |
-
-#### `/vsaf-docs` — Documentation & knowledge sync *(new)*
+| 1 | **GitNexus** `detect_changes({scope: "compare", base_ref: "<sprint-start-tag>"})` | Total sprint changes — files, symbols, processes affected |
+| 2 | **GitNexus** `READ gitnexus://repo/{name}/context` | Codebase health metrics post-sprint — size, complexity, index freshness |
+| 3 | **GitNexus** `group_status` | Module health — any module degraded during sprint? |
+| 4 | **BMAD** `bmad-retrospective` | What went well, what to improve, action items — informed by data from steps 1-3 |
+| 5 | **BMAD** `bmad-sprint-status` | Final sprint metrics — velocity, burndown, completion rate |
+| → | Output | Data-backed retro: sprint impact, module health, action items for next sprint planning |
+
+---
+
+### `/vsaf-docs` — Documentation & knowledge sync
+
+> Run once per sprint, after all features are shipped.
+
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **GitNexus** `query` + **MemPalace** `search` | Scans codebase + decisions, finds stale docs |
+| 1 | **GitNexus** `query` | Scans codebase, finds stale docs |
 | 2 | **BMAD** `bmad-document-project` | Generates/updates project documentation from code |
 | 3 | **BMAD** `bmad-generate-project-context` | Creates `project-context.md` — AI agent instructions |
-| 4 | **BMAD** `bmad-agent-tech-writer` (Paige) | Reviews docs for clarity, completeness, consistency |
-| 5 | **BMAD** `bmad-editorial-review-prose` + `bmad-editorial-review-structure` | Polish prose + restructure for readability |
+| 4 | **BMAD** `bmad-agent-tech-writer` | Reviews docs for clarity, completeness, consistency |
+| 5 | **BMAD** `bmad-editorial-review-prose` + `bmad-editorial-review-structure` | Polish prose + restructure |
 | 6 | **BMAD** `bmad-distillator` | Compresses long docs into LLM-optimised format |
 | 7 | **BMAD** `bmad-index-docs` | Generates `index.md` for each docs folder |
-| 8 | **Graphify** `/graphify . --wiki` | Builds agent-crawlable wiki from codebase |
-| 9 | **MemPalace** `diary_write` | Records what was updated/replaced |
-| → | Output | Updated docs, project context, wiki, doc indexes |
+| → | Output | Updated docs, project context, doc indexes |
 
-### Generated docs path convention
+---
+
+## Generated docs path convention
 
 | Artifact | Path |
 |----------|------|
+| PRD | `docs/project/planning-artifacts/prd-<feature>.md` |
 | SRS | `docs/project/srs/<feature>.md` |
 | Testcases | `docs/project/testcases/<feature>.md` |
-| Planning artifacts | `docs/project/planning-artifacts/` |
+| Test results | `docs/project/testcases/<feature>-results.md` |
+| Other planning artifacts | `docs/project/planning-artifacts/` |
 | Implementation artifacts | `docs/project/implementation-artifacts/` |
 
-### Command naming map
-
-- `/vsaf-onboarding` → `vsaf-onboard`
-- `/vsaf-planning <requirement>` → `vsaf-plan` + `vsaf-doc`
-- `/vsaf-testcase <path/to/srs>` → `vsaf-test <path/to/srs>`
-- `/vsaf-implement <srs> <testcases>` → `vsaf-build <srs> <testcases>`
-
-See [1-setup-guide.md § Your First Project](docs/onboarding/1-setup-guide.md#5-your-first-project--a-walkthrough)
-for a walkthrough, or [2-workflow-guide.md § JWT Demo](docs/onboarding/2-workflow-guide.md#4-full-sdlc-demo)
-for a full code-by-code example.
+---
 
-## Tools
+## Command naming map
 
-| Tool | What It Does | Cost |
-|---|---|---|
-| **Claude Code** | AI coding agent — everything else plugs into it | $20/mo |
-| **BMAD Method** | AI agents for full lifecycle: PM, Analyst, Architect, QA, Tech Writer, Code Review + 40 skills | Free |
-| **Superpowers** | Claude Code plugin: plan execution, TDD, debugging, code review, pre-PR checklist *(optional — BMAD/manual fallback)* | Free |
-| **GitNexus** | Code knowledge graph via MCP — impact analysis, dependency queries | Free |
-| **MemPalace** | Knowledge base — verbatim storage of decisions, temporal knowledge graph | Free |
-| **Graphify** | Any input → knowledge graph → clustered communities, dependency tracing, wiki | Free |
+| Alias | Resolves to |
+|-------|-------------|
+| `/vsaf-onboarding` | `vsaf-onboard` |
+| `/vsaf-planning <req>` | `vsaf-plan` + `vsaf-doc-prd` + `vsaf-doc-srs` |
+| `/vsaf-testcase <srs>` | `vsaf-test <path/to/srs>` |
+| `/vsaf-implement <prd> <srs> <tc>` | `vsaf-build <prd> <srs> <testcases>` |
+| `/vsaf-doc` | DEPRECATED — use `vsaf-doc-prd` then `vsaf-doc-srs` |
 
 ---
 
-**Core principles:** Discover before planning. Onboard first. SRS before implementation.
-Testcases derived from SRS. Impact analysis before touching any symbol.
-Run `gitnexus_detect_changes` before commit. 2-layer review before every PR.
-Re-index after every merge. Mine decisions weekly. Sync docs every sprint.
-MemPalace = decisions. Not CLAUDE.md.
+## Core principles
+
+1. **Discover before planning.** Research the domain before writing PRD.
+2. **Onboard first.** Understand the codebase before touching it.
+3. **PRD before SRS.** Business contract before engineering contract.
+4. **SRS before code.** Engineering contract before implementation.
+5. **Testcases from SRS.** Every FR/NFR must have a testcase before coding starts.
+6. **Read all 3 docs before coding.** PRD + SRS + testcases — no exceptions.
+7. **Impact analysis before every symbol edit.** `gitnexus_impact` is mandatory.
+8. **Run tests, write results.** `/vsaf-test run` after build, before ship.
+9. **2-layer review before every PR.** Code review → graph sync.
+10. **Re-index after every merge.** `vsaf index` keeps GitNexus accurate.
+11. **Split when impact is HIGH.** > 3 modules or > 400 lines → separate PRs.
+12. **Retroactive SRS for hotfixes.** No hotfix closes without backfill docs.