@anhth2/spec-driven-dev-plugin 0.5.0

package/ARCHITECTURE.md

@@ -0,0 +1,243 @@
+# Framework Architecture
+
+> **Nguyên tắc**: Nhìn file này để hiểu toàn bộ framework trước khi đọc bất kỳ file chi tiết nào.
+
+---
+
+## Layer Diagram
+
+```
+╔══════════════════════════════════════════════════════════════════════╗
+║               SPEC-DRIVEN DEV FRAMEWORK  v0.3                       ║
+╚══════════════════════════════════════════════════════════════════════╝
+
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 0 — PROTECTION                           (luôn chạy trước)   │
+│                                                                      │
+│  hooks/data-guard.js   → PreToolUse hook: chặn đọc file nhạy cảm   │
+│  rules/data-protection.md → Quy tắc declarative cho AI agent        │
+└──────────────────────────────────────────────────────────────────────┘
+                               │ safe ↓ blocked → ✋ STOP
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 1 — ENTRY POINT                          (user trigger)       │
+│                                                                      │
+│  commands/*.tmpl              skills/*/SKILL.tmpl                   │
+│  (slash commands)             (auto-trigger by description match)    │
+│  /generate-bdd                detect: "tạo BDD", "sinh feature"     │
+│  /generate-code               detect: "viết code", "implement"      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │ both built by bin/build.js
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 2 — SHARED STEPS                         (DRY, injected)      │
+│                                                                      │
+│  steps/gate.md            → resolve target file + CHECKPOINT        │
+│  steps/context-loader.md  → load project config + rules             │
+│  steps/report-footer.md   → standard output format                  │
+│                                                                      │
+│  Injected at build time via {{include:steps/X.md}}                  │
+│  Source: *.tmpl  →  Output: *.md  (gitignored)                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │ context loaded
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 3 — PROJECT CONTEXT              (read from consumer project) │
+│                                                                      │
+│  .agent/project-context.yaml  → paths, tech_stack, domains          │
+│  CLAUDE.md                    → architecture, coding standards       │
+│  rules/data-protection.md     → what AI must never access           │
+│  .agent/modules/{stack}/      → stack rules (plug-in, optional)     │
+└──────────────────────────────────────────────────────────────────────┘
+                               │ context-aware
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 4 — EXECUTION                            (command logic)      │
+│                                                                      │
+│  DISCOVERY        PRD / BDD           CODE / TEST     DEBUG          │
+│  /define-product  /generate-prd       /generate-code  /fix-bug      │
+│                   /refine-prd         /generate-tests /debug        │
+│                   /generate-bdd       /run-tests      /validate-    │
+│                   /generate-tech-docs /smoke-test      traces       │
+│                   /review-code        /setup-ai-first               │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+┌──────────────────────────────────────────────────────────────────────┐
+│  LAYER 5 — OUTPUT                       (artifacts in consumer proj) │
+│                                                                      │
+│  specs/product-definition/   specs/prd/   specs/bdd/               │
+│  tech-docs/                  src/         .trace/   .agent/review/ │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Data Flow — Một command chạy như thế nào
+
+```
+User types: /generate-bdd specs/prd/payment/PAY-01.md
+                │
+                ▼
+[L0] data-guard.js checks tool calls in real-time
+     → nếu AI cố đọc .env / *.key → BLOCK + warn
+                │
+                ▼
+[L1] commands/generate-bdd.md được Claude đọc
+     (assembled từ generate-bdd.tmpl + injected steps)
+                │
+                ▼
+[L2] gate.md   → resolve file path từ $ARGUMENTS
+     context-loader.md → đọc project-context.yaml, CLAUDE.md,
+                          rules/data-protection.md,
+                          modules/{stack}/stack-profile.yaml
+                │
+                ▼
+[L3] Claude biết: tech_stack, domains, architecture rules,
+     sensitive files to avoid, stack-specific patterns
+                │
+                ▼
+[L4] generate-bdd logic:
+     → đọc PRD → extract UC/BR/AC
+     → apply BDD rules R1-R10
+     → viết specs/bdd/{domain}/{UC-ID}.feature
+                │
+                ▼
+[L5] Output: specs/bdd/payment/PAY-01-UC1.feature
+```
+
+---
+
+## Build System
+
+```
+Source (committed to git)        Build output (gitignored)
+──────────────────────────       ─────────────────────────
+commands/*.tmpl         ──┐
+skills/**/SKILL.tmpl    ──┤  node bin/build.js  →  commands/*.md
+steps/*.md   (shared)   ──┘                         skills/**/SKILL.md
+
+Trigger:
+  npm run build          ← manual
+  prepublishOnly hook    ← auto before npm publish
+  bin/index.js install   ← auto when user runs npx
+```
+
+---
+
+## Module Plug-in System
+
+```
+Available modules (modules/):
+  java-spring, angular, react, nextjs,
+  dotnet, golang, php-laravel, context-engineering
+
+Usage:
+  npx @anhth2/spec-driven-dev --module java-spring
+    └─ copies modules/java-spring/ → consumer/.agent/modules/java-spring/
+
+At runtime, context-loader.md reads:
+  .agent/modules/{tech_stack.module}/stack-profile.yaml
+  .agent/modules/{tech_stack.module}/architecture-snippets/
+```
+
+---
+
+## Hook System — Data Protection
+
+```
+Consumer project setup:
+  .claude/settings.json   ← registers hook (provided as template)
+  hooks/data-guard.js     ← copied from this package on install
+
+Runtime:
+  Every tool use (Read, Write, Edit, Bash)
+       │
+       ▼
+  data-guard.js checks:
+    .env* / *.key / *.pem / *secret* / *password* / *credential*
+    application-prod.* / appsettings.Production.*
+       │
+    safe → allow   blocked → exit(2) + warn user
+```
+
+---
+
+## Future — Sub-Agent Pattern (v2 roadmap)
+
+Khi một số command quá nặng cho single context window:
+
+```
+Main session (orchestrator — lightweight, chỉ coordinate)
+  │
+  ├─ spawn spec-agent ──→ /refine-prd analysis (own context window)
+  │    └─ returns: findings.yaml
+  │
+  ├─ spawn codegen-agent ──→ /generate-code UC1 (own context window)
+  │    └─ returns: src/ changes
+  │
+  └─ spawn test-agent ──→ /generate-tests UC1 (own context window)
+       └─ returns: test files
+
+Benefits:
+  - Main session không bị bloat bởi large file reads
+  - Mỗi agent focus vào 1 task, ít hallucination hơn
+  - Parallel execution cho multiple UCs
+
+Implementation path:
+  1. Tạo steps/spawn-agent.md — pattern + handoff payload format
+  2. Tạo commands/orchestrate-feature.tmpl — top-level orchestrator
+  3. Sub-agent commands nhận input qua $ARGUMENTS (JSON payload)
+```
+
+---
+
+## Directory Map
+
+```
+spec-driven-dev/
+├── ARCHITECTURE.md          ← Đọc đây trước  ◀◀◀
+├── bin/
+│   ├── build.js             ← assembles *.tmpl → *.md
+│   └── index.js             ← npm installer + hook installer
+├── commands/
+│   └── *.tmpl               ← slash commands (14 commands)
+├── hooks/
+│   ├── data-guard.js        ← PreToolUse sensitive file protection
+│   └── settings.json        ← hook registration template
+├── modules/
+│   └── {stack}/             ← 8 stacks: java-spring, angular, react,
+│       ├── module.yaml          nextjs, dotnet, golang, php-laravel,
+│       ├── stack-profile.yaml   context-engineering
+│       └── architecture-snippets/
+├── rules/
+│   ├── data-protection.md   ← what AI must NEVER read/write
+│   └── workflow.md          ← general AI behavior rules
+├── skills/
+│   └── {name}/SKILL.tmpl    ← Claude plugin skills (7 skills)
+├── steps/
+│   ├── gate.md              ← shared: file resolve + checkpoint
+│   ├── context-loader.md    ← shared: load all project context
+│   └── report-footer.md     ← shared: standard output format
+└── templates/
+    ├── project-context.yaml ← consumer project config template
+    ├── architecture.template.md
+    └── platform-guide.template.md
+```
+
+---
+
+## Maintenance Guide
+
+| Muốn thay đổi gì | Sửa file nào |
+|------------------|-------------|
+| Logic của 1 command cụ thể | `commands/{name}.tmpl` |
+| Logic của 1 skill cụ thể | `skills/{name}/SKILL.tmpl` |
+| Gate / checkpoint pattern | `steps/gate.md` |
+| Context loading | `steps/context-loader.md` |
+| Report format | `steps/report-footer.md` |
+| Sensitive file patterns | `hooks/data-guard.js` + `rules/data-protection.md` |
+| Stack-specific rules | `modules/{stack}/stack-profile.yaml` |
+| Project setup template | `templates/project-context.yaml` |
+| Build system | `bin/build.js` |
+| Installer | `bin/index.js` |
+
+Sau khi sửa bất kỳ `.tmpl` hoặc `steps/*.md`:
+```bash
+npm run build   # regenerate tất cả *.md
+```

package/bin/build.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+/**
+ * build.js — Assembles templates → .md files
+ *
+ * Processes:
+ *   commands/*.tmpl       → commands/*.md
+ *   skills/**\/SKILL.tmpl → skills/**\/SKILL.md
+ *
+ * Replaces {{include:steps/gate.md}}, {{include:steps/context-loader.md}},
+ * and {{include:steps/report-footer.md}} with the actual file contents.
+ *
+ * Usage: node bin/build.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const COMMANDS_DIR = path.join(ROOT, 'commands');
+const SKILLS_DIR = path.join(ROOT, 'skills');
+
+// Cache for step file contents
+const stepCache = {};
+
+/**
+ * Load a step file by name, caching the result.
+ * @param {string} stepPath - e.g. "steps/gate.md"
+ * @returns {string} file contents
+ */
+function loadStep(stepPath) {
+  if (stepCache[stepPath]) return stepCache[stepPath];
+
+  const fullPath = path.join(ROOT, stepPath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Step file not found: ${fullPath}`);
+  }
+  const content = fs.readFileSync(fullPath, 'utf8');
+  stepCache[stepPath] = content;
+  return content;
+}
+
+/**
+ * Process a single .tmpl file: resolve all {{include:...}} markers
+ * and write the output as a .md file (replacing .tmpl extension with .md).
+ *
+ * @param {string} tmplFile - full path to the .tmpl file
+ * @param {string} label    - display label for logging (e.g. "generate-code")
+ * @returns {{ label: string, success: boolean, error?: string }}
+ */
+function buildTemplate(tmplFile, label) {
+  const outFile = tmplFile.replace(/\.tmpl$/, '.md');
+
+  try {
+    let content = fs.readFileSync(tmplFile, 'utf8');
+
+    // Replace all {{include:...}} markers
+    content = content.replace(/\{\{include:([^}]+)\}\}/g, (match, includePath) => {
+      const trimmed = includePath.trim();
+      return loadStep(trimmed);
+    });
+
+    fs.writeFileSync(outFile, content, 'utf8');
+    return { label, success: true };
+  } catch (err) {
+    return { label, success: false, error: err.message };
+  }
+}
+
+/**
+ * Recursively find all files matching a predicate under a directory.
+ * @param {string} dir
+ * @param {(filename: string) => boolean} predicate
+ * @returns {string[]} absolute paths
+ */
+function findFiles(dir, predicate) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(fullPath, predicate));
+    } else if (predicate(entry.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+let allSucceeded = 0;
+let allFailed = 0;
+
+// ── 1. Build commands/*.tmpl → commands/*.md ──────────────────────────────────
+
+console.log('');
+console.log('Building commands from templates...');
+console.log('');
+
+const commandTmplFiles = fs.readdirSync(COMMANDS_DIR)
+  .filter(f => f.endsWith('.tmpl'))
+  .map(f => path.join(COMMANDS_DIR, f));
+
+if (commandTmplFiles.length === 0) {
+  console.log('  (no .tmpl files found in commands/)');
+} else {
+  const commandResults = commandTmplFiles.map(f => {
+    const basename = path.basename(f, '.tmpl');
+    return buildTemplate(f, basename);
+  });
+
+  for (const r of commandResults) {
+    if (r.success) {
+      console.log(`  ✅ ${r.label}.tmpl → ${r.label}.md`);
+      allSucceeded++;
+    } else {
+      console.log(`  ❌ ${r.label}.tmpl → FAILED: ${r.error}`);
+      allFailed++;
+    }
+  }
+}
+
+// ── 2. Build skills/**/SKILL.tmpl → skills/**/SKILL.md ───────────────────────
+
+console.log('');
+console.log('Building skills from templates...');
+console.log('');
+
+const skillTmplFiles = findFiles(SKILLS_DIR, name => name === 'SKILL.tmpl');
+
+if (skillTmplFiles.length === 0) {
+  console.log('  (no SKILL.tmpl files found in skills/)');
+} else {
+  const skillResults = skillTmplFiles.map(f => {
+    // Use the parent directory name as the label (e.g., "code", "debug")
+    const skillName = path.basename(path.dirname(f));
+    return buildTemplate(f, `skills/${skillName}/SKILL`);
+  });
+
+  for (const r of skillResults) {
+    if (r.success) {
+      console.log(`  ✅ ${r.label}.tmpl → ${r.label}.md`);
+      allSucceeded++;
+    } else {
+      console.log(`  ❌ ${r.label}.tmpl → FAILED: ${r.error}`);
+      allFailed++;
+    }
+  }
+}
+
+// ── 3. Populate core/ directory (distributable) ──────────────────────────────
+//
+// core/ mirrors what gets installed into .agent/ in consumer projects.
+// It is gitignored but included in the npm package (via "files" whitelist).
+
+const CORE_DIR = path.join(ROOT, 'core');
+const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const VERSION  = pkg.version;
+
+console.log('');
+console.log('Populating core/ (distributable) ...');
+console.log('');
+
+// Clean and recreate core/
+if (fs.existsSync(CORE_DIR)) {
+  fs.rmSync(CORE_DIR, { recursive: true });
+}
+fs.mkdirSync(CORE_DIR, { recursive: true });
+
+/**
+ * Recursively copy src → dest, optionally filtering files by name.
+ * @param {string} src
+ * @param {string} dest
+ * @param {((name: string) => boolean) | null} fileFilter  null = copy all files
+ */
+function copyDirToCore(src, dest, fileFilter) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath  = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirToCore(srcPath, destPath, fileFilter);
+    } else if (!fileFilter || fileFilter(entry.name)) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+const coreMappings = [
+  // Built command .md files (not .tmpl sources)
+  { src: COMMANDS_DIR,              dest: path.join(CORE_DIR, 'commands'),  filter: f => f.endsWith('.md') },
+  // Step files (gate, context-loader, spawn-agent, report-footer)
+  { src: path.join(ROOT, 'steps'),  dest: path.join(CORE_DIR, 'steps'),    filter: null },
+  // Hook scripts
+  { src: path.join(ROOT, 'hooks'),  dest: path.join(CORE_DIR, 'hooks'),    filter: null },
+  // Data-protection and workflow rules
+  { src: path.join(ROOT, 'rules'),  dest: path.join(CORE_DIR, 'rules'),    filter: null },
+  // PRD / architecture templates
+  { src: path.join(ROOT, 'templates'), dest: path.join(CORE_DIR, 'templates'), filter: null },
+  // Stack module profiles
+  { src: path.join(ROOT, 'modules'),   dest: path.join(CORE_DIR, 'modules'),   filter: null },
+  // Built skill .md files (not .tmpl sources)
+  { src: SKILLS_DIR,                dest: path.join(CORE_DIR, 'skills'),   filter: f => !f.endsWith('.tmpl') },
+];
+
+for (const { src, dest, filter } of coreMappings) {
+  copyDirToCore(src, dest, filter);
+  const rel = path.relative(ROOT, dest);
+  console.log(`  ✅ ${rel}/`);
+}
+
+// Write FRAMEWORK_VERSION so upgrade.sh can compare installed vs latest
+fs.writeFileSync(path.join(CORE_DIR, 'FRAMEWORK_VERSION'), VERSION + '\n', 'utf8');
+console.log(`  ✅ core/FRAMEWORK_VERSION  (v${VERSION})`);
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+
+const total = allSucceeded + allFailed;
+console.log('');
+
+if (allFailed === 0) {
+  console.log(`Build complete: ${allSucceeded}/${total} templates assembled.`);
+} else {
+  console.log(`Build finished with errors: ${allSucceeded}/${total} succeeded.`);
+  process.exit(1);
+}
+
+console.log('');