@anhth2/spec-driven-dev-plugin 0.6.0 → 0.7.0

package/bin/index.js

@@ -19,30 +19,64 @@ const showHelp   = args.includes('--help') || args.includes('-h');
 const moduleIdx  = args.indexOf('--module');
 const moduleName = moduleIdx !== -1 ? args[moduleIdx + 1] : null;
 
+// --services backend:java-spring,web-admin:react,app-mobile:flutter
+const servicesIdx = args.indexOf('--services');
+const servicesRaw = servicesIdx !== -1 ? args[servicesIdx + 1] : null;
+const serviceList = servicesRaw
+  ? servicesRaw.split(',').map(s => {
+      const [name, mod] = s.trim().split(':');
+      return { name: name.trim(), module: (mod || '').trim() };
+    }).filter(s => s.name)
+  : [];
+
 const AVAILABLE_MODULES = [
   'java-spring', 'angular', 'react', 'nextjs',
   'dotnet', 'golang', 'php-laravel', 'context-engineering',
+  'flutter', 'react-native', 'ios-swiftui', 'android-compose',
 ];
 
+// Language/framework labels per module (for generated project-context.yaml)
+const MODULE_STACK = {
+  'java-spring':      { language: 'Java 17',      framework: 'Spring Boot 3.x' },
+  'golang':           { language: 'Go',            framework: 'Gin / Echo' },
+  'dotnet':           { language: 'C#',            framework: '.NET / ASP.NET Core' },
+  'php-laravel':      { language: 'PHP',           framework: 'Laravel' },
+  'context-engineering': { language: 'TypeScript', framework: 'Node.js' },
+  'react':            { language: 'TypeScript',    framework: 'React' },
+  'nextjs':           { language: 'TypeScript',    framework: 'Next.js' },
+  'vue':              { language: 'TypeScript',    framework: 'Vue 3' },
+  'nuxt':             { language: 'TypeScript',    framework: 'Nuxt 3' },
+  'angular':          { language: 'TypeScript',    framework: 'Angular' },
+  'flutter':          { language: 'Dart',          framework: 'Flutter' },
+  'react-native':     { language: 'TypeScript',    framework: 'React Native / Expo' },
+  'ios-swiftui':      { language: 'Swift',         framework: 'SwiftUI' },
+  'android-compose':  { language: 'Kotlin',        framework: 'Jetpack Compose' },
+};
+
 if (showHelp) {
   console.log('Usage: npx @anhth2/spec-driven-dev-plugin [options]');
   console.log('');
   console.log('Install modes:');
-  console.log('  --init             NEW: Install framework to .agent/ + create shortcuts in .claude/commands/');
-  console.log('                         Recommended for new projects. Run upgrade.sh to upgrade later.');
-  console.log('  --project          Install full commands to ./.claude/commands/ (project-scoped, legacy)');
-  console.log('  (no flag)          Install full commands to ~/.claude/commands/ (global, legacy)');
+  console.log('  --init                    Install framework to .agent/ + create shortcuts in .claude/commands/');
+  console.log('                            Recommended for new projects. Run upgrade.sh to upgrade later.');
+  console.log('  --project                 Install full commands to ./.claude/commands/ (project-scoped, legacy)');
+  console.log('  (no flag)                 Install full commands to ~/.claude/commands/ (global, legacy)');
   console.log('');
   console.log('Options:');
-  console.log('  --module <name>    Copy stack module to .agent/modules/<name>/');
-  console.log('  --hooks            Install data-guard hook to .claude/hooks/ + update .claude/settings.json');
+  console.log('  --module <name>           Copy stack module to .agent/modules/<name>/');
+  console.log('  --services <list>         Monorepo setup: install into each service subfolder in one command.');
+  console.log('                            Format: name:module,name:module,...');
+  console.log('                            Example: backend:java-spring,web-admin:react,app-mobile:flutter');
+  console.log('  --hooks                   Install data-guard hook to .claude/hooks/ + update .claude/settings.json');
   console.log('');
   console.log('Available modules:');
   AVAILABLE_MODULES.forEach(m => console.log(`  ${m}`));
   console.log('');
   console.log('Examples:');
-  console.log('  npx @anhth2/spec-driven-dev-plugin --init                         # new project setup');
+  console.log('  npx @anhth2/spec-driven-dev-plugin --init                         # single-service project');
   console.log('  npx @anhth2/spec-driven-dev-plugin --init --module java-spring    # with stack module');
+  console.log('  npx @anhth2/spec-driven-dev-plugin --init \\');
+  console.log('    --services backend:java-spring,web-admin:react,app-mobile:flutter  # monorepo setup');
   console.log('  npx @anhth2/spec-driven-dev-plugin --project --hooks              # legacy project install');
   process.exit(0);
 }
@@ -144,7 +178,128 @@ if (isInit) {
     installDataGuardHook();
   }
 
-  // 5. Summary
+  // 5. Monorepo: install into each service subfolder
+  if (serviceList.length > 0) {
+    console.log('');
+    console.log(`Setting up ${serviceList.length} service workspace(s)...`);
+
+    for (const svc of serviceList) {
+      const svcDir         = path.join(projectRoot, svc.name);
+      const svcAgentDir    = path.join(svcDir, '.agent');
+      const svcClaudeCmds  = path.join(svcDir, '.claude', 'commands');
+
+      console.log('');
+      console.log(`  ── ${svc.name} (${svc.module || 'no module'}) ──`);
+
+      // Create service dir if needed
+      fs.mkdirSync(svcDir, { recursive: true });
+
+      // Copy core → service/.agent/
+      copyDirRecursive(coreDir, svcAgentDir);
+      console.log(`  ✅ ${svc.name}/.agent/`);
+
+      // Install module
+      if (svc.module) {
+        if (!AVAILABLE_MODULES.includes(svc.module)) {
+          console.log(`  ⚠️  Unknown module "${svc.module}" — skipped`);
+        } else {
+          const srcMod  = path.join(ROOT, 'modules', svc.module);
+          const destMod = path.join(svcAgentDir, 'modules', svc.module);
+          if (fs.existsSync(srcMod)) {
+            fs.mkdirSync(destMod, { recursive: true });
+            copyDirRecursive(srcMod, destMod);
+            console.log(`  ✅ ${svc.name}/.agent/modules/${svc.module}/`);
+          }
+        }
+      }
+
+      // Create .claude/commands/ shortcuts
+      fs.mkdirSync(svcClaudeCmds, { recursive: true });
+      const svcCmdFiles = fs.readdirSync(path.join(svcAgentDir, 'commands')).filter(f => f.endsWith('.md'));
+      for (const cmdFile of svcCmdFiles) {
+        const cmdName = cmdFile.replace('.md', '');
+        const shortcut =
+          `# /${cmdName}\n\nRead the full command definition from \`.agent/commands/${cmdFile}\`` +
+          ` and execute it with arguments: $ARGUMENTS\n`;
+        fs.writeFileSync(path.join(svcClaudeCmds, cmdFile), shortcut, 'utf8');
+      }
+      console.log(`  ✅ ${svc.name}/.claude/commands/ (${svcCmdFiles.length} shortcuts)`);
+
+      // Generate project-context.yaml (only if not already present)
+      const ctxPath = path.join(svcAgentDir, 'project-context.yaml');
+      if (!fs.existsSync(ctxPath)) {
+        const stack = MODULE_STACK[svc.module] || { language: 'TODO', framework: 'TODO' };
+        const yaml = [
+          `project:`,
+          `  name: ${path.basename(projectRoot)} — ${svc.name}`,
+          ``,
+          `tech_stack:`,
+          `  language: ${stack.language}`,
+          `  framework: ${stack.framework}`,
+          `  module: ${svc.module || 'TODO'}`,
+          ``,
+          `conventions:`,
+          `  ticket_prefix: FEAT`,
+          ``,
+          `paths:`,
+          `  specs_dir: ../specs/bdd`,
+          `  prd_dir: ../specs/prd`,
+          `  tech_docs_dir: ../specs/tech-docs`,
+          `  domain_knowledge_dir: ../specs/domain-knowledge`,
+          `  business_dictionary: ../specs/domain-knowledge/business-dictionary.md`,
+          `  core_entities: ../specs/domain-knowledge/core-entities.md`,
+          `  refinement_dir: ../specs/.review`,
+          `  product_definitions_dir: ../specs/product-definition`,
+          `  trace_dir: ../.trace`,
+          ``,
+        ].join('\n');
+        fs.writeFileSync(ctxPath, yaml, 'utf8');
+        console.log(`  ✅ ${svc.name}/.agent/project-context.yaml (generated)`);
+      } else {
+        console.log(`  ℹ️  ${svc.name}/.agent/project-context.yaml (already exists — skipped)`);
+      }
+    }
+
+    // Generate root project-context.yaml for PO/BA (only if not present)
+    const rootCtxPath = path.join(agentDir, 'project-context.yaml');
+    if (!fs.existsSync(rootCtxPath)) {
+      const svcYaml = serviceList.map(s => [
+        `  - name: ${s.name}`,
+        `    module: ${s.module || 'TODO'}`,
+        `    description: ""`,
+      ].join('\n')).join('\n');
+      const rootYaml = [
+        `project:`,
+        `  name: ${path.basename(projectRoot)}`,
+        ``,
+        `tech_stack:`,
+        `  language: multi-service`,
+        ``,
+        `services:`,
+        svcYaml,
+        ``,
+        `conventions:`,
+        `  ticket_prefix: FEAT`,
+        ``,
+        `paths:`,
+        `  specs_dir: specs/bdd`,
+        `  prd_dir: specs/prd`,
+        `  tech_docs_dir: specs/tech-docs`,
+        `  domain_knowledge_dir: specs/domain-knowledge`,
+        `  business_dictionary: specs/domain-knowledge/business-dictionary.md`,
+        `  core_entities: specs/domain-knowledge/core-entities.md`,
+        `  refinement_dir: specs/.review`,
+        `  product_definitions_dir: specs/product-definition`,
+        `  trace_dir: .trace`,
+        ``,
+      ].join('\n');
+      fs.writeFileSync(rootCtxPath, rootYaml, 'utf8');
+      console.log('');
+      console.log('  ✅ .agent/project-context.yaml (root — PO/BA workspace, generated)');
+    }
+  }
+
+  // 6. Summary
   console.log('');
   if (failedShortcuts.length > 0) {
     console.log(`⚠️  ${commandFiles.length - failedShortcuts.length}/${commandFiles.length} shortcuts created.`);
@@ -152,9 +307,23 @@ if (isInit) {
   }
   console.log(`✅ Framework v${frameworkVersion} installed!`);
   console.log('');
-  console.log('Next steps:');
-  console.log('  1. Open Claude Code and run /setup-ai-first');
-  console.log('  2. Commit .agent/ to git so your whole team has the framework');
+  if (serviceList.length > 0) {
+    console.log('Monorepo workspaces ready:');
+    console.log('  PO/BA    → open Claude Code at project root');
+    serviceList.forEach(s => {
+      console.log(`  ${s.name.padEnd(10)} → open Claude Code at ./${s.name}/`);
+    });
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Fill in CLAUDE.md in each service subfolder (architecture + coding standards)');
+    console.log('  2. Fill in .agent/project-context.yaml in each subfolder (review generated values)');
+    console.log('  3. PO/BA: open root in Claude Code and run /setup-ai-first');
+    console.log('  4. Commit everything to git so the whole team has the framework');
+  } else {
+    console.log('Next steps:');
+    console.log('  1. Open Claude Code and run /setup-ai-first');
+    console.log('  2. Commit .agent/ to git so your whole team has the framework');
+  }
   console.log('');
   console.log('To upgrade later:  bash scripts/upgrade.sh');
   console.log('                   (or: npx @anhth2/spec-driven-dev-plugin@latest --init)');

package/commands/debug.md

@@ -34,7 +34,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -143,7 +143,7 @@ If `paths` section is absent, use these defaults:
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
@@ -220,6 +220,26 @@ If the file does not exist → skip silently.
 
 ---
 
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -230,6 +250,7 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
@@ -257,13 +278,112 @@ Proceed to the next step of the calling command.
 
 ---
 
-## Input — Paste one of:
-1. Stack trace / error log
-2. Test failure output
-3. File path + description of unexpected behavior
-4. A specific question about a code snippet
+## Step 1 — Classify debug type
+
+After loading context, display this prompt and wait for the user's choice:
+
+```
+DEBUG SESSION
+──────────────────────────────────────────────────────────────
+  What's your situation?
+
+  1  I already have a stack trace / error log  → paste it
+  2  I need to reproduce the error first       → show me the run command
+  3  A test is failing                         → I'll run tests, then paste output
+  4  Code question (no runtime needed)         → ask away
+──────────────────────────────────────────────────────────────
+Enter 1 / 2 / 3 / 4:
+```
+
+Wait for the user's choice, then follow the corresponding path below.
+
+---
+
+### Path 1 — Already have error output
+
+Ask:
+```
+Paste your stack trace / error log below:
+```
+
+Wait for input, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+
+---
+
+### Path 2 — Need to reproduce first
+
+Display the run command from `conventions.service_run` in `project-context.yaml`:
+
+```
+Start your service first:
+
+  {conventions.service_run}
+
+(If you use Docker: `docker compose up -d`, then verify with `docker compose ps`)
+
+Once the service is running:
+  1. Trigger the behavior that causes the error
+  2. Copy the full stack trace or error log
+  3. Paste it here
+
+Waiting for your error output...
+```
+
+Wait for the user to paste the error, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+
+If `conventions.service_run` is not set → show:
+```
+⚠️  service_run is not configured in .agent/project-context.yaml.
+    Add it so this command can show the correct start command:
+
+    conventions:
+      service_run: "mvn spring-boot:run"   # or: npm run dev / go run . / etc.
+```
+Then ask the user to start the service manually and paste the error when ready.
+
+---
+
+### Path 3 — Test is failing
+
+Display the test command from `conventions.test_command` in `project-context.yaml`:
+
+```
+Run your tests first:
+
+  {conventions.test_command}
+
+Once the run finishes, paste the full test failure output here.
+
+Waiting...
+```
+
+Wait for the user to paste the failure output, then proceed to [Test Failure Analysis](#test-failure-analysis).
+
+If `conventions.test_command` is not set → show:
+```
+⚠️  test_command is not configured in .agent/project-context.yaml.
+    Add it so this command can show the correct test command:
+
+    conventions:
+      test_command: "mvn test"   # or: npm test / go test ./... / etc.
+```
+Then ask the user to run tests manually and paste the output when ready.
+
+---
+
+### Path 4 — Code question
+
+Ask:
+```
+Describe your question or paste the code snippet you're asking about:
+```
+
+Wait for input, then answer directly using loaded project context (architecture rules, layer order, coding standards from CLAUDE.md).
+
+---
 
 ## Stack Trace Analysis
+
 Read from **bottom up** — `Caused by:` is the real root cause:
 ```
 Caused by: {RealException}  ← start here
@@ -272,20 +392,83 @@ Caused by: {RealException}  ← start here
 
 ## Common Error Patterns
 
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
 | Error | Likely Cause | Fix Direction |
 |-------|-------------|---------------|
 | NullPointerException | Null object access; Optional not handled | Check Optional.orElseThrow, null guards |
 | ClassCastException | Wrong type assumption | Check type at assignment/return |
 | OutOfMemoryError | Loading too much data | Add pagination |
 | StackOverflowError | Infinite recursion | Find recursive call with no base case |
-| Connection refused | Dependency not running | Check config URLs |
+| Connection refused | Dependency not running | Check config URLs / start service |
 | 401 Unauthorized | Token expired, wrong config | Verify token, check auth config |
 | 403 Forbidden | Wrong role | Check auth annotations |
 | DB constraint violation | Duplicate key, null in NOT NULL | Check data and constraints |
 | Serialization error | Circular reference | Check DTO/mapper config |
 | Test assertion mismatch | Wrong mock or wrong expected | Re-read mock setup |
 
+#### context-engineering (AI/LLM pipelines)
+
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `APIError` / `RateLimitError` | LLM quota exceeded or service down | Check API key, rate limits; add exponential backoff |
+| `TokenLimitError` / `context_length_exceeded` | Input prompt too long | Truncate/chunk input; review prompt template size |
+| `AuthenticationError` | API key invalid or expired | Check env var; rotate key |
+| Response validation / schema mismatch | LLM output doesn't match expected format | Add output parser; retry with stricter prompt |
+| `JSONDecodeError` on LLM output | Model returned non-JSON text | Add JSON extraction post-processing or stricter system prompt |
+| Hanging / slow test | Real LLM called in test instead of mock | Verify `patch('...')` applied; add timeout guard |
+| Flaky results across runs | Non-deterministic LLM response | Use fixed mock in tests; check temperature = 0 for determinism |
+
+### If `platform_type = web-frontend`
+
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `Cannot read properties of undefined` | Data not loaded yet | Add loading guard / optional chaining `?.` |
+| `useEffect` infinite loop | Dependency array wrong | Review deps, use stable refs / `useCallback` |
+| `Cannot update state on unmounted component` | Async resolves after unmount | Cancel in cleanup / use AbortController |
+| CORS error | API not configured | Check backend CORS config or dev proxy setup |
+| 401 Unauthorized | Token expired or missing | Refresh token / check Authorization header |
+| White screen / no output | Unhandled render error | Check browser console, add ErrorBoundary |
+| Type error (Zod / TypeScript) | API response shape mismatch | Compare actual response vs type definition |
+| `act(...)` warning in test | Async state update | Wrap in `act(async () => {...})` |
+| Module not found | Import path wrong | Check relative path / tsconfig alias |
+
+### If `platform_type = mobile`
+
+#### Flutter
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `Null check operator on null value` | Nullable not guarded | Add `?` or null check before `!` |
+| `pumpAndSettle timed out` | Async not completing in test | Use `pump(Duration(...))` |
+| `setState called after dispose` | Async continues after widget removed | Cancel in `dispose()` |
+| `RenderFlex overflow` | Widget too wide for screen | Wrap with `Flexible`, `Expanded`, or `SingleChildScrollView` |
+| BLoC state not updating | Event not dispatched | Verify `bloc.add(Event())` is called |
+| `MissingPluginException` | Native plugin not linked | Run `flutter clean && flutter pub get` |
+
+#### React Native
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `undefined is not an object` | Null prop access | Add null check / optional chaining |
+| Metro bundler error | Cache stale | `npx react-native start --reset-cache` |
+| `VirtualizedLists nested` | FlatList inside ScrollView | Use `nestedScrollEnabled` or restructure |
+| Navigation `undefined` | `useNavigation` outside navigator | Wrap component inside correct navigator |
+| `act(...)` warning | Async state update in test | Wrap in `act(async () => {...})` |
+
+#### iOS / Android
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `SIGABRT` / `EXC_BAD_ACCESS` (iOS) | Nil dereference | Add optional binding `if let` / `guard let` |
+| `IllegalStateException` (Android) | Lifecycle violation | Check if fragment/activity still attached |
+| `NetworkOnMainThreadException` | Network call on UI thread | Move to coroutine / background thread |
+| Build fails after pod install | Pod cache stale | `pod deintegrate && pod install` |
+| `Hilt injection failed` | Missing `@AndroidEntryPoint` | Add annotation to Activity/Fragment |
+
 ## Test Failure Analysis
+
 ```
 Expected: {value}
 Actual  : {value}
@@ -293,6 +476,8 @@ Actual  : {value}
 ```
 1. What is the gap? 2. Is mock setup correct? 3. Is assertion logically correct?
 
+---
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -323,6 +508,7 @@ Suggest the logical next command based on workflow phase:
 
 | Current command         | Suggest next                                  |
 |-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
@@ -331,13 +517,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
 | /generate-tests         | `/run-tests {UC-ID}`                          |
 | /run-tests (passing)    | `/review-code {UC-ID}`                        |
 | /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
 | /review-code            | `/smoke-test {UC-ID}` or create PR            |
 | /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |