@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/README.md

@@ -1,420 +1,756 @@
-# VSAF — SDLC Agentic Framework
+# VSAF
 
-A development framework for Claude Code. Plan with AI agents, understand impact
-before coding, execute with TDD guardrails. $20/month total.
+DAG-based workflow engine for AI coding agents. Define multi-step workflows in YAML, execute them with AI providers, and monitor runs in realtime through a web dashboard.
 
----
+## What It Does
 
-## Architecture
+VSAF orchestrates complex AI workflows as directed acyclic graphs (DAGs). Each node in a DAG can be a prompt (sent to an AI provider), a bash command, or a reusable command template. Nodes declare dependencies, conditional execution rules, and context isolation — VSAF handles the rest.
 
-3 tools, 5 workflow phases:
+```
+vsaf run fix-issue --args "fix #42"
+```
 
 ```
-┌────────────────────────────────────────────────────────┐
-│  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         │
-└────────────────────────────────────────────────────────┘
+extract-issue-number ✓  1.2s
+fetch-issue          ✓  0.8s
+classify             ✓  2.1s
+investigate          ●  running...
+plan                 ⊘  skipped
+bridge-artifacts     ○  pending
+implement            ○  pending
+validate             ○  pending
 ```
 
-| 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 |
+## Features
+
+- **YAML workflow definitions** — declarative DAGs with prompt, bash, and command node types
+- **Dependency-based execution** — wave-based parallel scheduling, conditional branching, trigger rules
+- **Variable resolution** — reference outputs from upstream nodes (`$classify.output.issue_type`)
+- **Workspace isolation** — each run executes in an ephemeral temp directory, changes applied on success
+- **Run persistence** — run state saved to JSON after each node, supports resume on failure
+- **Provider-agnostic** — pluggable AI provider adapters (Claude Code adapter included)
+- **Web dashboard** — Angular SPA with workflow management and realtime SSE monitoring
+- **REST API** — Fastify server for programmatic access to workflows and runs
+- **MCP server** — Model Context Protocol integration for Claude Code
+- **Skill pack system** — 38 bundled skills (18 SDLC + 15 BMAD + 5 mattpocock lean)
+- **AJV validation** — JSON Schema validation for workflow definitions
+- **Cycle detection** — DAG cycle detection prevents infinite loops
+- **Error recovery** — configurable retry backoff strategies for failed nodes
 
 ---
 
-## Quickstart
+## Installation
 
-Requires **Node.js ≥ 18**, **Git**, and a **Claude Code subscription** ($20/mo).
+### Prerequisites
+
+| Requirement | Version | Check |
+|---|---|---|
+| Node.js | >= 20.0.0 | `node -v` |
+| npm | >= 9.0.0 | `npm -v` |
+| git | any | `git --version` |
+| Claude Code CLI | latest | `claude --version` |
+| GitHub CLI (optional) | any | `gh --version` |
+
+**Claude Code CLI** is required for prompt and command nodes. **GitHub CLI** is required only for workflows that interact with GitHub (e.g., `fix-issue` uses `gh issue view`).
+
+### Option 1: Global Install (Recommended)
 
 ```bash
-git clone <this-repo> && cd vsaf
-npx @ngocsangairvds/vsaf@latest init
-npx @ngocsangairvds/vsaf@latest status
+npm install -g @ngocsangairvds/vsaf
+vsaf --version
 ```
 
-One manual step inside Claude Code:
+### Option 2: Project-Local Install
 
+```bash
+npm install -D @ngocsangairvds/vsaf
+npx vsaf --version
 ```
-/plugin install superpowers@claude-plugins-official
-```
 
-Restart Claude Code after installing Superpowers.
+### Option 3: Install from Source
+
+```bash
+git clone https://github.com/YOUR_USERNAME/vsaf.git
+cd vsaf
+npm install && npm run build
+npm link
+vsaf --version
+```
 
 ---
 
-## Documentation
+## Quick Start
 
-| # | Doc | Covers |
-|---|-----|--------|
-| 1 | [1-setup-guide.md](docs/onboarding/1-setup-guide.md) | Install, tool overview, first walkthrough, glossary |
-| 2 | [2-workflow-guide.md](docs/onboarding/2-workflow-guide.md) | Deep dives, coordination playbooks, JWT demo, troubleshooting |
-| 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) | Vietnamese version of the workflow guide |
+```bash
+# Initialize in your project
+cd /path/to/your/project
+vsaf init
 
-**New here?** Start with **1-setup-guide** → then **4-milestones**.
+# Check environment
+vsaf doctor
 
----
+# List available workflows
+vsaf list
 
-## Directory Layout
+# Run a workflow
+vsaf run fix-issue --args "fix #42"
 
+# Start the web dashboard
+vsaf serve --port 3000 --open
 ```
-.
-├── .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
+
+`vsaf init` creates the `.vsaf/` directory:
+
+```
+.vsaf/
+├── config.yaml          ← Project configuration
+├── workflows/           ← Workflow definitions (3 built-in)
+│   ├── fix-issue.yaml
+│   ├── idea-to-pr.yaml
+│   └── code-review.yaml
+├── commands/            ← Reusable prompt templates (10 built-in)
+│   ├── investigate-issue.md
+│   └── ... (9 more)
+└── storage/             ← Run state persistence (add to .gitignore)
 ```
 
 ---
 
-## Daily Operations
+## CLI Commands
 
-| Command | What It Does |
+| Command | Description |
 |---|---|
-| `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 |
+| `vsaf init` | Initialize `.vsaf/` directory with config and default workflows |
+| `vsaf run <workflow>` | Execute a workflow by name |
+| `vsaf run <workflow> --resume <runId>` | Resume an interrupted run |
+| `vsaf list` | List available workflows |
+| `vsaf status` | Show recent run statuses |
+| `vsaf doctor` | Check environment and dependencies |
+| `vsaf serve` | Start API server and web dashboard |
+| `vsaf mcp` | Start MCP server for Claude Code integration |
+| `vsaf install <pack>` | Install a skill pack globally (e.g. `vsaf install sdlc`) |
+| `vsaf skill` | Manage skills: `add`, `list`, `info`, `remove`, `init` |
+
+### `vsaf serve`
 
----
+```bash
+vsaf serve [--port 3000] [--open]
+```
 
-## Workflow
+Starts a Fastify server exposing a REST API and the Angular dashboard.
 
-### Standard Flow (features)
+### `vsaf mcp`
 
-```
-[Product level — once per product]
-/vsaf-discover → /vsaf-sprint plan
+Starts a Model Context Protocol (MCP) server that exposes VSAF workflows and skills to Claude Code. Configure in `.mcp.json` for automatic integration.
 
-[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
+### `vsaf install`
 
-[End of sprint]
-/vsaf-docs → /vsaf-sprint status → /vsaf-retro → next sprint
+```bash
+vsaf install sdlc   # Deploy 38 skills to ~/.claude/skills/
 ```
 
-### Quick Flow (bug fixes / small changes)
+### `vsaf skill`
 
+```bash
+vsaf skill list              # List installed skills
+vsaf skill info <name>       # Show skill details
+vsaf skill add <path>        # Add a skill from file
+vsaf skill remove <name>     # Remove a skill
+vsaf skill init              # Scaffold a new skill template
 ```
-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
+
+---
+
+## Writing Workflows
+
+### Basic Workflow
+
+Create `.vsaf/workflows/my-workflow.yaml`:
+
+```yaml
+name: my-workflow
+description: A custom workflow
+
+provider: claude
+model: sonnet
+
+nodes:
+  - id: step1
+    prompt: |
+      Analyze this request: $ARGUMENTS
+      Output a summary.
+
+  - id: step2
+    bash: |
+      echo "Step 1 output was: $step1.output"
+    depends_on: [step1]
+
+  - id: step3
+    prompt: |
+      Based on: $step2.output
+      Generate a final report.
+    depends_on: [step2]
 ```
 
-### Hotfix Flow (production incidents — bypass, then backfill)
+Run it:
 
+```bash
+vsaf run my-workflow --args "analyze the auth module"
 ```
-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)
+
+### Node Types
+
+| Type | Field | Description |
+|---|---|---|
+| **prompt** | `prompt:` | Send text to the AI provider |
+| **bash** | `bash:` | Run a shell command |
+| **command** | `command:` | Execute a reusable command template from `.vsaf/commands/` |
+
+### Node Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | yes | Unique node identifier |
+| `prompt` / `bash` / `command` | yes | Node content (exactly one) |
+| `depends_on` | no | List of node IDs that must complete first |
+| `when` | no | Condition expression — node skipped if false |
+| `trigger_rule` | no | `all_success` (default) or `one_success` |
+| `context` | no | `fresh` (new AI session) or `inherit` (default) |
+| `model` | no | Override the workflow-level model |
+| `allowed_tools` | no | Restrict AI tool access (empty array = no tools) |
+| `output_format` | no | JSON Schema for structured output |
+
+### Variables
+
+| Pattern | Description | Example |
+|---|---|---|
+| `$ARGUMENTS` | Args passed to `vsaf run --args` | `"fix #42"` |
+| `$node-id.output` | Text output of a completed node | `"bug"` |
+| `$node-id.output.field` | Field from structured output | `"enhancement"` |
+| `$ARTIFACTS_DIR` | Shared directory for file passing | `/tmp/vsaf-run-abc/artifacts` |
+
+### Conditional Branching
+
+```yaml
+nodes:
+  - id: classify
+    prompt: |
+      Classify this as 'bug' or 'feature': $ARGUMENTS
+    output_format:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [bug, feature]
+      required: [type]
+
+  - id: fix-bug
+    prompt: Fix this bug: $ARGUMENTS
+    depends_on: [classify]
+    when: "$classify.output.type == 'bug'"
+
+  - id: build-feature
+    prompt: Implement this feature: $ARGUMENTS
+    depends_on: [classify]
+    when: "$classify.output.type == 'feature'"
+
+  - id: finalize
+    prompt: Wrap up the work.
+    depends_on: [fix-bug, build-feature]
+    trigger_rule: one_success  # Only need one branch to succeed
 ```
 
-> **Hotfix rule:** Impact analysis is never skipped. Gates are minimised, not removed.
-> Retroactive SRS + testcases must be completed before the next sprint starts.
+### Using Commands (Reusable Prompts)
+
+Create `.vsaf/commands/my-command.md`:
 
+```markdown
+---
+description: A reusable prompt template
+argument-hint: The task description
 ---
 
-## Flow breakdown
+You are an expert engineer. Your task:
 
-### `/vsaf-discover <product/domain>` — Product discovery
+$ARGUMENTS
 
-> Run once when starting a new product. Skip for features inside an existing product.
+Previous analysis: $classify.output
 
-| 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 |
+Write your implementation to the codebase. Save notes to $ARTIFACTS_DIR/notes.md.
+```
 
----
+Reference it in a workflow:
 
-### `/vsaf-sprint plan|status|story` — Sprint management
+```yaml
+  - id: implement
+    command: my-command
+    depends_on: [classify]
+    context: fresh    # Start a new AI session
+    model: opus       # Use a stronger model
+```
 
-| 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 |
+### Structured Output
+
+Force JSON output from AI nodes:
+
+```yaml
+  - id: analyze
+    prompt: Analyze this code and rate its quality.
+    output_format:
+      type: object
+      properties:
+        score:
+          type: string
+          enum: ["A", "B", "C", "D", "F"]
+        issues:
+          type: string
+      required: [score, issues]
+
+  - id: report
+    prompt: |
+      The code scored: $analyze.output.score
+      Issues: $analyze.output.issues
+    depends_on: [analyze]
+```
 
----
+### Passing Files Between Nodes
 
-### `/vsaf-onboard` — Understand the codebase
+Nodes can share files via `$ARTIFACTS_DIR`:
 
-| 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 |
+```yaml
+nodes:
+  - id: investigate
+    prompt: |
+      Investigate the issue. Write findings to $ARTIFACTS_DIR/investigation.md
 
----
+  - id: plan
+    bash: cat $ARTIFACTS_DIR/investigation.md
+    depends_on: [investigate]
 
-### `/vsaf-plan <feature>` — Scope + impact + approach
+  - id: implement
+    prompt: |
+      Here is the investigation: $plan.output
+      Now implement the fix.
+    depends_on: [plan]
+```
 
-Output of this step: **approved scope document** (not yet PRD — that's next).
+### Resume Failed Runs
 
-| 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 |
+If a workflow fails mid-execution, resume from where it left off:
 
-> **Gate:** If impact > 3 modules → split into smaller features before proceeding.
+```bash
+vsaf status                                     # Find the run ID
+vsaf run fix-issue --resume run-a1b2c3d4e5f6    # Skip completed nodes
+```
 
 ---
 
-### `/vsaf-doc-prd` — Write the PRD
+## SDLC Skill Pack
 
-Input: approved scope document from `/vsaf-plan`.
-Output: `docs/project/planning-artifacts/prd-[feature].md` — *what* to build, for whom, why.
+VSAF ships with a complete SDLC skill pack — 38 skills organized into workflows for building features and fixing bugs with TDD discipline.
 
-| 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` |
+### Setup
 
-> **PRD vs SRS:** PRD = business contract (why/what). SRS = engineering contract (how). Both are required before coding.
+```bash
+# 1. Install the skill pack globally
+vsaf install sdlc
 
----
+# 2. Initialize VSAF in your project
+cd /path/to/your/project
+vsaf init
+
+# 3. Inside Claude Code — bootstrap SDLC documentation layer
+/sdlc-init
 
-### `/vsaf-doc-srs` — Write the SRS
+# 4. Onboard project knowledge
+/sdlc-onboard-docs    # Build docs knowledge graph (graphify)
+/sdlc-onboard-code    # Index code (GitNexus) + environment check
+```
 
-Input: approved PRD from `/vsaf-doc-prd`.
-Output: `docs/project/srs/[feature].md` — *how* to build it.
+After setup, the project should have:
 
-| 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` |
+```
+your-project/
+├── .vsaf/              ← Engine config, skills, workflows, storage
+│   └── docs/              ← STATUS.md, KNOWLEDGE.md, features/
+├── .mcp.json              ← VSAF + GitNexus MCP servers
+├── CONTEXT.md             ← Shared domain language
+├── .gitnexus/             ← Code index
+└── graphify-out/          ← Docs knowledge graph
+```
 
-> **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.
+### Workflows
 
----
+#### Full Pipelines
 
-### `/vsaf-test <path/to/srs>` — Generate testcases
+| Workflow | Command | Description |
+|---|---|---|
+| `master-sdlc` | `/vsaf master-sdlc --args "feature description"` | Full 9-phase feature pipeline |
+| `hotfix` | `/vsaf hotfix --args "path/to/bug-report.md"` | TDD-driven hotfix from bug report |
+| `onboarding` | `/vsaf onboarding` | Docs + code knowledge indexing |
 
-Input: approved SRS.
-Output: `docs/project/testcases/[feature].md` — testcase contract used in build and post-build verification.
+#### Sub-workflows (crash-safe, run independently)
 
-| 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) |
+| Workflow | Command | Phases |
+|---|---|---|
+| `sdlc-thinking` | `/vsaf sdlc-thinking` | Discovery → PRD |
+| `sdlc-design` | `/vsaf sdlc-design` | Architecture → SRS |
+| `sdlc-testcase` | `/vsaf sdlc-testcase` | Test Design |
+| `sdlc-build` | `/vsaf sdlc-build` | Implement → Test Gate (loop 3x) |
+| `sdlc-qa` | `/vsaf sdlc-qa` | Review → Feature Complete → Ship |
+| `hotfix-tdd` | `/vsaf hotfix-tdd` | TDD RED → GREEN → Test Gate (loop 3x) |
 
----
+### Master-SDLC Flow (New Feature)
 
-### `/vsaf-build <prd> <srs> <testcases>` — Implement with TDD
+9 phases, each produces artifacts on disk for session continuity:
 
-> **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.
+```
+/vsaf master-sdlc --args "Add OAuth2 authentication to REST API"
+```
 
-| 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 |
+| Phase | Skill | Output | Description |
+|---|---|---|---|
+| 1 | `discovery` | `01-discovery.md` | Scan system → grill user with questions → brainstorm |
+| 2 | `prd` | `02-prd.md` | PRD via BMAD elicitation + adversarial review |
+| 3 | `architecture` | `03-adr.md` | Grill constraints → architecture design + epics |
+| 4 | `srs` | `05-srs.md` | Detailed SRS + edge cases + interface verification |
+| 5 | `test-design` | `06-testcases.md` | Test cases from SRS (tests before code — TDD) |
+| 6 | `implement` | code changes | Subagent-driven TDD implementation |
+| 6b | `test-gate` | npm test | Automated test verification (loop 3x on fail) |
+| 7 | `review` | `08-review.md` | Code review + quality gate + impact analysis |
+| 8 | `feature-complete` | KNOWLEDGE.md | Update shared knowledge before shipping |
+| 9 | `ship` | git commit + PR | Commit source code + create pull request |
 
-> **3-strike rule:** Task fails 3 times → STOP. Architectural problem, not execution. Re-read SRS + testcases and redesign the task.
+Artifacts saved to `.vsaf/docs/features/{feature-name}/`. Each phase checks prerequisites — if the session crashes, resume from the last completed phase.
 
----
+### Hotfix Flow (Bug Fix)
 
-### `/vsaf-test run <path/to/testcases>` — Run tests + record results
+TDD-driven: receives a bug report, analyzes, writes failing test, fixes, reviews, ships.
 
-Run after `/vsaf-build` completes. Executes the full test suite against the implementation and writes a structured results file.
+```
+/vsaf hotfix --args "path/to/bug-report.md"
+```
+
+| Phase | Skill | Description |
+|---|---|---|
+| 1 | `hotfix-analyze` | Read bug report → GitNexus impact → root cause |
+| 2 | `hotfix-red` | TDD RED — write test that reproduces the bug (MUST FAIL) |
+| 3 | `hotfix-green` | TDD GREEN — minimal fix to pass the test (MUST PASS) |
+| 3b | `test-gate` | Full test suite — loop back to green on fail (max 3x) |
+| 4 | `hotfix-review` | Minimality check + test quality + impact |
+| 5 | `ship` | Git commit + PR |
+
+Artifacts saved to `.vsaf/docs/hotfixes/{bug-id}/`.
+
+### Crash Recovery
+
+Long sessions can crash (context overflow, network). Sub-workflows let you resume without restarting the full pipeline:
+
+```bash
+# Session 1: thinking phase
+/vsaf sdlc-thinking --args "Add OAuth2"
+# → crash during PRD → 01-discovery.md already saved
 
-| 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 |
+# Session 2: resume just the PRD skill
+/sdlc-prd
+# → PRD completed, 02-prd.md saved
 
-> Results file is required input for `/vsaf-ship`. Ship is blocked if gate fails.
+# Session 3: continue with design
+/vsaf sdlc-design
+
+# Session 4: build
+/vsaf sdlc-build
+
+# Session 5: ship
+/vsaf sdlc-qa
+```
+
+Each phase reads input from files on disk — **no data is lost between sessions**.
+
+### Individual Skills
+
+Every SDLC phase can be invoked directly as a Claude skill:
+
+```
+/sdlc-init              # Setup
+/sdlc-onboard-docs      # Index docs
+/sdlc-onboard-code      # Index code
+/sdlc-discovery         # Phase 1
+/sdlc-prd               # Phase 2
+/sdlc-architecture      # Phase 3
+/sdlc-srs               # Phase 4
+/sdlc-test-design       # Phase 5
+/sdlc-implement         # Phase 6
+/sdlc-review            # Phase 7
+/sdlc-feature-complete  # Phase 8
+/sdlc-ship              # Phase 9
+/sdlc-sdlc-health       # Health check
+/hotfix-analyze         # Hotfix Phase 1
+/hotfix-red             # Hotfix Phase 2
+/hotfix-green           # Hotfix Phase 3
+/hotfix-review          # Hotfix Phase 4
+```
+
+### SDLC Skills (18)
+
+| Skill | Purpose |
+|---|---|
+| `setup` | Install dependencies and configure environment |
+| `init` | Bootstrap .vsaf/docs/, .mcp.json, CONTEXT.md |
+| `onboard-docs` | Docs scan → graphify → CONTEXT.md |
+| `onboard-code` | GitNexus index + Claude review + env check |
+| `discovery` | Grill questions → brainstorm + GitNexus |
+| `prd` | PRD with BMAD elicitation + adversarial review |
+| `architecture` | Grill constraints → architecture + epics |
+| `srs` | SRS + edge cases + GitNexus shape_check |
+| `test-design` | Test design from SRS (TDD: tests before code) |
+| `implement` | Subagent-driven TDD + SonarQube rules |
+| `review` | Code review + quality gate + impact analysis |
+| `feature-complete` | Update CONTEXT.md, KNOWLEDGE.md, re-index |
+| `ship` | Git commit + PR via gh CLI |
+| `sdlc-health` | Health check — verify all prerequisites |
+| `hotfix-analyze` | Bug report → GitNexus + deep thinking → root cause |
+| `hotfix-red` | TDD RED — write failing test that reproduces bug |
+| `hotfix-green` | TDD GREEN — minimal fix to pass the test |
+| `hotfix-review` | Quick review — minimality + test quality |
+
+### Bundled BMAD Skills (15)
+
+Used by discovery, prd, architecture, srs, test-design, and review phases:
+
+| Skill | Purpose |
+|---|---|
+| `bmad-advanced-elicitation` | Push LLM to reconsider and deepen analysis |
+| `bmad-brainstorming` | Facilitate interactive brainstorming |
+| `bmad-domain-research` | Conduct domain and industry research |
+| `bmad-prfaq` | Working Backwards PRFAQ challenge |
+| `bmad-create-prd` | Create a PRD from scratch |
+| `bmad-validate-prd` | Validate a PRD against standards |
+| `bmad-review-adversarial-general` | Cynical review and challenge assumptions |
+| `bmad-create-architecture` | Create architecture solution design |
+| `bmad-create-epics-and-stories` | Break requirements into epics and stories |
+| `bmad-check-implementation-readiness` | Validate PRD, UX, Architecture completeness |
+| `bmad-agent-analyst` | Strategic business analyst |
+| `bmad-review-edge-case-hunter` | Walk every branching path for edge cases |
+| `bmad-code-review` | Review code changes adversarially |
+| `bmad-party-mode` | Orchestrate group discussion simulations |
+| `bmad-qa-generate-e2e-tests` | Generate end-to-end automated tests |
+
+### Bundled Mattpocock Lean Skills (5)
+
+Lean alternative for bugfix and known-domain flows:
+
+| Skill | Purpose |
+|---|---|
+| `grill-me` | Interview relentlessly to extract requirements |
+| `diagnose` | Disciplined diagnosis loop for bugs |
+| `zoom-out` | Step back and evaluate broader context |
+| `tdd` | Test-driven development with strict RED/GREEN |
+| `improve-codebase-architecture` | Find deepening opportunities in architecture |
 
 ---
 
-### `/vsaf-ship` — Review and ship
+## Configuration
 
-Input: working code + test results file (from `/vsaf-test run`).
+`.vsaf/config.yaml`:
 
-| 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 |
+```yaml
+provider: claude          # AI provider (only 'claude' currently)
+model: sonnet             # Default model: haiku, sonnet, opus
+
+isolation:
+  type: ephemeral         # Workspace strategy
+  cleanup: after_success  # after_success | after_always | never
+  exclude:                # Directories excluded from workspace copy
+    - node_modules
+    - .git
+    - dist
+    - build
+    - .vsaf/storage
+  max_workspaces: 5
+```
+
+**Cleanup policies:**
+- `after_success` — keep workspace on failure for debugging
+- `after_always` — always delete
+- `never` — never delete (fills disk)
+
+Add to `.gitignore`:
+
+```
+.vsaf/storage/
+```
 
 ---
 
-### `/vsaf-retro` — Retrospective
+## REST API
 
-> Run at end of sprint or end of epic. Separate from ship. Data-backed, not opinion-based.
+All endpoints prefixed with `/api`. Start with `vsaf serve`.
 
-| 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 |
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/health` | Health check |
+| `GET` | `/api/workflows` | List workflows |
+| `GET` | `/api/workflows/:name` | Workflow detail (full DAG as JSON) |
+| `POST` | `/api/runs` | Start a run → `202 { runId }` |
+| `GET` | `/api/runs` | List runs |
+| `GET` | `/api/runs/:runId` | Run detail (status + node results) |
+| `GET` | `/api/runs/:runId/events` | SSE stream (realtime events) |
+
+`POST /api/runs` returns `202 Accepted` immediately — the workflow runs async. Subscribe to SSE events for realtime progress.
+
+### SSE Events
+
+```
+event: node:start
+data: {"nodeId":"classify","timestamp":"..."}
+
+event: node:complete
+data: {"nodeId":"classify","durationMs":2100,"output":"bug"}
+
+event: node:skip
+data: {"nodeId":"plan","reason":"condition not met"}
+
+event: run:complete
+data: {"success":true,"totalMs":45200}
+```
 
 ---
 
-### `/vsaf-docs` — Documentation & knowledge sync
+## Architecture
 
-> Run once per sprint, after all features are shipped.
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Browser (Angular SPA)                  │
+│   Dashboard ──── Workflow Detail ──── Run Execution      │
+│    (HTTP)           (HTTP)           (EventSource)       │
+└──────────┬───────────┬────────────────┬──────────────────┘
+           ▼           ▼                ▼
+┌──────────────────────────────────────────────────────────┐
+│                  Fastify Server (packages/cli)            │
+│   /api/health   /api/workflows/*   /api/runs/* + SSE     │
+│                              ExecutionManager             │
+│   @fastify/static ──→ Angular dist/ (SPA fallback)       │
+└──────────────────────────┬───────────────────────────────┘
+                           ▼
+┌──────────────────────────────────────────────────────────┐
+│                  Core Engine (packages/core)              │
+│   DAG Parser → DAG Executor → Node Runner                │
+│   Variable Resolver · Condition Evaluator                │
+│   Workspace Manager · Run Store · Provider Registry      │
+│   AJV Validation · Contract Checks · Cycle Detection     │
+└──────────────────────────────────────────────────────────┘
+```
 
-| 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 |
+Strict dependency direction: **web → (HTTP) → cli → core**. Published as a single npm package `@ngocsangairvds/vsaf`.
+
+| Package | Responsibility |
+|---|---|
+| `packages/core` | Engine library: parsing, execution, providers, isolation, persistence |
+| `packages/cli` | CLI commands + Fastify API server + MCP server |
+| `packages/web` | Angular SPA dashboard (private, not published separately) |
+
+### Design Decisions
+
+| Decision | Choice | Why |
+|---|---|---|
+| DAG scheduling | Wave-based parallel scan | Simple, no topological sort, natural parallelism |
+| Workspace isolation | Copy project to temp dir | Prevents partial changes on failure, safe rollback |
+| Run persistence | JSON files, one per run | No database, human-readable, easy to debug |
+| API framework | Fastify 5 | TypeScript-first, fast, built-in `inject()` for testing |
+| Realtime | SSE (not WebSocket) | One-way sufficient, simpler protocol |
+| Frontend | Angular 19 standalone | Strong TypeScript integration, lazy-loaded routes |
+| AI adapter | Shell out to `claude` CLI | No SDK dependency, simple to test |
+| Schema validation | AJV | Industry standard JSON Schema |
+| MCP integration | Stdio-based MCP server | Native Claude Code protocol, zero network config |
+| Skill distribution | `vsaf install` → `~/.claude/skills/` | Global install once, available across all projects |
+
+### Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Language | TypeScript 6 |
+| Runtime | Node.js >= 20 |
+| Build | tsc (project references) |
+| API Server | Fastify 5 |
+| Frontend | Angular 19 + Tailwind CSS 4 |
+| Realtime | Server-Sent Events (SSE) |
+| Testing | Vitest |
+| AI Provider | Claude Code (extensible) |
+| AI Integration | Model Context Protocol (MCP) |
+| Schema Validation | AJV |
 
 ---
 
-## Generated docs path convention
+## Programmatic Usage
 
-| 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/` |
+Use `@ngocsangairvds/vsaf` as a library:
+
+```typescript
+import { parseWorkflow, DAGExecutor, ProviderRegistry, ClaudeCodeAdapter } from '@ngocsangairvds/vsaf';
+import { readFileSync } from 'fs';
+
+// Parse workflow
+const yaml = readFileSync('.vsaf/workflows/fix-issue.yaml', 'utf-8');
+const graph = parseWorkflow(yaml);
+
+console.log(graph.name);           // "fix-issue"
+console.log(graph.nodes.size);     // 10
+
+// Execute with provider
+const registry = new ProviderRegistry();
+registry.register(new ClaudeCodeAdapter());
+const provider = registry.get('claude');
+
+const executor = new DAGExecutor(provider, workspacePath, projectPath, graph, {
+  onNodeStart: (id) => console.log(`▶ ${id}`),
+  onNodeComplete: (id, r) => console.log(`✓ ${id} (${r.durationMs}ms)`),
+  onNodeSkip: (id, reason) => console.log(`⊘ ${id}: ${reason}`),
+  onNodeFail: (id, err) => console.error(`✗ ${id}: ${err}`),
+});
+
+const result = await executor.execute('fix #42', artifactsPath);
+```
 
 ---
 
-## Command naming map
+## Development
 
-| 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` |
+```bash
+npm install          # Install dependencies
+npm test             # Run tests
+npm run test:watch   # Watch mode
+npm run lint         # Type check
+npm run build        # Build all packages
+```
+
+```
+vsaf/
+├── packages/core/     ← Engine library
+├── packages/cli/      ← CLI + API server + MCP
+├── packages/web/      ← Angular dashboard
+├── skills/            ← Skill pack definitions
+├── workflows/         ← Default workflow YAML files
+├── commands/          ← Default command templates
+└── tests/             ← Vitest test suites
+```
 
 ---
 
-## 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.
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `vsaf: command not found` | `npm install -g @ngocsangairvds/vsaf` or use `npx vsaf` |
+| `claude: command not found` | Install Claude Code CLI |
+| `gh: command not found` | Install GitHub CLI: `brew install gh` or https://cli.github.com |
+| `.vsaf/ already exists` | `rm -rf .vsaf/` then `vsaf init` |
+| `Workflow not found` | Check `vsaf list`. Ensure `.vsaf/workflows/xxx.yaml` exists |
+| `Command not found` | Ensure `.vsaf/commands/xxx.md` exists with correct frontmatter |
+| Run stuck / no progress | Check `claude --print "hello"` works. Check network |
+| `vsaf serve` shows "Web UI not built" | Build Angular: `cd packages/web && npx ng build` |
+| Workspace disk full | Set `cleanup: after_always` in config.yaml or `rm -rf /tmp/vsaf-*` |
+
+## License
+
+MIT