@ngocsangairvds/vsaf 3.0.10 → 3.0.12

package/README.md

@@ -10,6 +10,9 @@ every decision. $20/month total.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
+│  DISCOVERY         BMAD (agents)                                     │
+│                    PM · Analyst · domain/market/tech research        │
+├──────────────────────────────────────────────────────────────────────┤
 │  PLANNING          BMAD (agents)                                     │
 │                    Analyst · Architect · Brainstorming · QA          │
 ├──────────────────────────────────────────────────────────────────────┤
@@ -21,6 +24,9 @@ every decision. $20/month total.
 ├──────────────────────────────────────────────────────────────────────┤
 │  IMPLEMENTATION    Claude Code + Superpowers                         │
 │                    TDD execution, code review                        │
+├──────────────────────────────────────────────────────────────────────┤
+│  KNOWLEDGE         Graphify + BMAD (tech writer, editors)            │
+│                    wiki, docs sync, distillation                     │
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -95,26 +101,56 @@ Run `npx @ngocsangairvds/vsaf@latest --help` for the full list. Highlights:
 
 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)*
 
 ## Workflow
 
-Every feature follows an **SRS-first cycle**:
+Full product lifecycle:
 
 ```
-/vsaf-onboard → /vsaf-plan → /vsaf-doc → /vsaf-test → /vsaf-build → /vsaf-ship
+/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
 ```
 
-Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
-`gitnexus_impact` before editing symbols and `gitnexus_detect_changes` before commit.
+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.
 
 ### Flow breakdown
 
+#### `/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)*
+| Mode | Tool | Does |
+|------|------|------|
+| **plan** | **BMAD** `bmad-create-epics-and-stories` | Breaks PRD into epics + prioritised user 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 |
+| → | Output | Sprint plan, status dashboard, or story file |
+
 #### `/vsaf-onboard` — Understand the codebase
 | Step | Tool | Does |
 |------|------|------|
@@ -130,44 +166,72 @@ Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
 | 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 |
-| → | Output | Scope, impact report, chosen approach, rejected alternatives |
+| 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
 | 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 |
-| 2 | *(Claude)* | Writes SRS with FRs/NFRs/acceptance criteria + traceability IDs → `docs/project/srs/` |
-| 3 | *(Claude)* | Writes implement notes: affected modules, technical constraints |
-| 4 | **MemPalace** `mempalace_add_drawer` | Persists chosen approach + rejected alternatives |
-| → | Output | `docs/project/srs/[feature].md` ready for testcase generation |
+| 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
 | Step | Tool | Does |
 |------|------|------|
 | 1 | **BMAD** `bmad-qa-generate-e2e-tests` | Derives unit / integration / edge-case tests from SRS FRs/NFRs |
-| 2 | *(Claude)* | Validates every FR/NFR has ≥ 1 test, records gaps |
-| 3 | *(Claude)* | Builds FR/NFR → Testcase ID traceability matrix |
+| 2 | **BMAD** `bmad-review-edge-case-hunter` | Finds unhandled boundaries, race conditions, null/empty cases — adds tests |
+| 3 | *(Claude)* | Validates every FR/NFR has ≥ 1 test, builds traceability matrix |
 | 4 | *(Claude)* | Saves to `docs/project/testcases/[feature].md` |
-| → | Output | Testcase contract — used as implementation guardrails |
+| 5 | **BMAD** `bmad-check-implementation-readiness` | **Quality gate** — blocks build if SRS/testcase/architecture gaps found |
+| → | Output | Testcase contract + implementation readiness verdict (PASS/FAIL) |
 
 #### `/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 | **Claude Code** (TDD loop) | RED → GREEN → REFACTOR per testcase group |
-| 3b | **GitNexus** `mcp__gitnexus__detect_changes` | Verifies only intended files changed before each commit |
+| 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
 | Step | Tool | Does |
 |------|------|------|
-| 1 | **Superpowers** `superpowers:code-review` | Layer 1 — structure, naming, SOLID, patterns |
-| 2 | **GitNexus** `gitnexus analyze` / `vsaf index` | Layer 2 — updates call graph to reflect new code |
-| 3 | **MemPalace** `mempalace_add_drawer` + `diary_write` | Saves decisions + session summary for future sessions |
-| 4 | *(git)* | Push branch, open PR with impact summary + test results |
-| → | Output | Shipped feature, updated graph, persistent knowledge |
+| 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)*
+| Step | Tool | Does |
+|------|------|------|
+| 1 | **GitNexus** `query` + **MemPalace** `search` | Scans codebase + decisions, 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 |
+| 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 |
 
 ### Generated docs path convention
 
@@ -187,21 +251,23 @@ Bug fixes (Quick Flow) may use mini-SRS + mini-testcases, but still require
 
 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 command-by-command example.
+for a full code-by-code example.
 
 ## Tools
 
 | Tool | What It Does | Cost |
 |---|---|---|
 | **Claude Code** | AI coding agent — everything else plugs into it | $20/mo |
-| **BMAD Method** | AI agents for planning: Analyst, Architect, Brainstorming, QA | Free |
-| **Superpowers** | Methodology engine: code review | Free |
+| **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 |
 
 ---
 
-**Core principles:** 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 and after major decisions.
+**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.

package/bin/vsaf.js

@@ -17,8 +17,8 @@ USAGE
   vsaf clean      Clean GitNexus index
 
 GLOBAL  (once per machine → ~/.claude/)
-  Skills  : bmad (41), vsaf (5), gitnexus (6)
-  Binaries: gitnexus, mempalace
+  Skills  : bmad (41), vsaf (5), gitnexus (6), graphify (1)
+  Binaries: gitnexus, mempalace, graphify
 
 PER PROJECT  (per repo, run inside the repo root)
   .claude/settings.json   Local AI settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "3.0.10",
+  "version": "3.0.12",
   "description": "VSAF — Agentic AI SDLC Framework. 4 integrated tools: BMAD, GitNexus, Superpowers, MemPalace. 2-layer review.",
   "keywords": ["claude", "claude-code", "ai", "sdlc", "framework", "bmad", "gitnexus", "mempalace"],
   "bin": {

package/src/global.js

@@ -15,6 +15,7 @@ async function installGlobal() {
   installSkills();
   installBinary('gitnexus', () => exec('npm install -g gitnexus'));
   installPipx('mempalace', 'mempalace');
+  installPipx('graphify', 'graphifyy');
 
   console.log('\n\x1b[32m\x1b[1m✓ Global infra ready.\x1b[0m\n');
 }

package/src/status.js

@@ -11,6 +11,7 @@ async function showStatus() {
   checkSkills();
   checkCmd('gitnexus',  'GitNexus');
   checkCmd('mempalace', 'MemPalace');
+  checkCmd('graphify',  'Graphify');
 
   // ── Project ────────────────────────────────────────────────────────────────
   console.log('\n\x1b[1mProject  (current repo)\x1b[0m');

package/src/workflow.js

@@ -19,7 +19,13 @@ function runIndex() {
 
 function runReview() {
   step('Review (2-layer)');
-  info('Layer 1: Methodology review — run in Claude Code: /superpowers:code-review');
+
+  info('Layer 1: Code review');
+  info('  If Superpowers installed → run in Claude Code: /superpowers:code-review');
+  info('  Otherwise             → run in Claude Code: /bmad-code-review');
+  warn('  Superpowers is a Claude Code plugin. To install:');
+  warn('    /plugin install superpowers@claude-plugins-official');
+
   info('Layer 2: Knowledge graph sync');
   const indexOk = runIndex();