VSAF — SDLC Agentic Framework

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:

┌────────────────────────────────────────────────────────┐
│  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         │
└────────────────────────────────────────────────────────┘

| 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, Git, and a Claude Code subscription ($20/mo).

git clone <this-repo> && cd vsaf
npx @ngocsangairvds/vsaf@latest init
npx @ngocsangairvds/vsaf@latest status

One manual step inside Claude Code:

/plugin install superpowers@claude-plugins-official

Restart Claude Code after installing Superpowers.

Documentation

| # | Doc | Covers | |---|-----|--------| | 1 | 1-setup-guide.md | Install, tool overview, first walkthrough, glossary | | 2 | 2-workflow-guide.md | Deep dives, coordination playbooks, JWT demo, troubleshooting | | 3 | 3-cheatsheet.md | 1-page command reference — print and pin | | 4 | 4-milestones.md | Day 1 / Week 1 / Month 1 ramp-up path | | 5 | 5-faq.md | Mindset questions every new dev asks | | — | 2-workflow-guide.vi.md | Vietnamese version of the workflow guide |

New here? Start with 1-setup-guide → then 4-milestones.

Directory Layout

.
├── .claude/
│   ├── settings.json       # Local AI settings
│   └── skills/             # VSAF + BMAD + GitNexus skills
├── _bmad/                  # BMAD agent workspace
├── docs/project/           # Generated artifacts (PRD, SRS, testcases, plans)
├── docs/
│   ├── architecture/       # Architecture documents (from BMAD Architect)
│   └── onboarding/         # Developer onboarding docs
├── assets/templates/       # Project scaffold templates
├── scripts/
│   └── setup-vsaf.sh       # Full setup automation (used by `vsaf init`)
├── CLAUDE.md               # Claude Code system prompt — workflow rules
└── AGENTS.md               # GitNexus rules for AI agents

Daily Operations

| Command | What It Does | |---|---| | vsaf init | Install or update all tools | | vsaf index | Re-index codebase (GitNexus) — run after every merge | | vsaf review | 2-layer review coordinator | | vsaf status | Show status of all installed tools |

Main skill commands inside Claude Code:

| 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

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)

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

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

/vsaf-discover <product/domain> — Product discovery

Run once when starting a new product. Skip for features inside an existing product.

| Step | Tool | Does | |------|------|------| | 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 stories | | plan | BMAD bmad-sprint-planning | Assigns stories to sprint, identifies dependencies | | status | BMAD bmad-sprint-status | Progress %, burndown, blocked items, risks | | story | BMAD bmad-create-story | Creates detailed story file for implementation | | → | Output | Sprint plan, status dashboard, or story file |

/vsaf-onboard — Understand the codebase

| Step | Tool | Does | |------|------|------| | 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).

| Step | Tool | Does | |------|------|------| | 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) | | 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 | | 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 | | → | 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).

| Step | Tool | Does | |------|------|------| | 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 | 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 | 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 | 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 | | → | Output | Updated docs, project context, doc indexes |

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 | | Test results | docs/project/testcases/<feature>-results.md | | Other planning artifacts | docs/project/planning-artifacts/ | | Implementation artifacts | docs/project/implementation-artifacts/ |

Command naming map

| 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

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.