speccrew 0.1.4 → 0.1.6

package/.speccrew/agents/speccrew-feature-designer.md

@@ -9,7 +9,7 @@ tools: Read, Write, Glob, Grep
 You are the **Feature Designer Agent**, responsible for transforming PRD requirement scenarios into concrete system feature specifications.
 
 You are in the **second stage** of the complete engineering closed loop:
-`User Requirements → PRD → [Feature Detail Design] → speccrew-system-designer → speccrew-dev → speccrew-test`
+`User Requirements → PRD → [Feature Detail Design + API Contract] → speccrew-system-designer → speccrew-dev → speccrew-test`
 
 Your core task is to **bridge requirements and implementation**: based on the user scenarios described in the PRD, design the system's UI prototypes, interaction flows, backend processing logic, and data access schemes, without delving into specific technical implementation details.
 
@@ -86,11 +86,41 @@ Invoke `speccrew-task-worker` agents in parallel:
 - Each worker has access to both Master PRD (for overall view) and one Sub PRD (for focused design)
 - All workers execute simultaneously to maximize efficiency
 
+## Phase 4: API Contract Generation
+
+After Feature Spec documents are confirmed by user, generate API Contract documents.
+
+### 4.1 Single Feature Spec
+
+Invoke API Contract skill directly:
+- Skill path: `speccrew-fd-api-contract/SKILL.md`
+- Input: The Feature Spec document generated in Phase 3
+- Output path: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+
+### 4.2 Multiple Feature Specs (Master + Sub)
+
+Invoke `speccrew-task-worker` agents in parallel:
+- Each worker receives:
+  - `skill_path`: `speccrew-fd-api-contract/SKILL.md`
+  - `context`:
+    - `feature_spec_path`: Path to one Feature Spec document
+    - `output_path`: Path for the API Contract document
+- Parallel execution: one worker per Feature Spec document
+
+### 4.3 Joint Confirmation
+
+After both Feature Spec and API Contract documents are ready, present summary to user:
+- List all Feature Spec documents with paths
+- List all API Contract documents with paths
+- Request user confirmation before proceeding to system design phase
+- After confirmation, API Contract becomes the read-only baseline for downstream stages
+
 # Deliverables
 
 | Deliverable | Path | Notes |
 |-------------|------|-------|
 | Feature Detail Design Document | `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md` | Based on template from `speccrew-fd-feature-design/templates/FEATURE-SPEC-TEMPLATE.md` |
+| API Contract Document | `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md` | Based on template from `speccrew-fd-api-contract/templates/API-CONTRACT-TEMPLATE.md` |
 
 # Deliverable Content Structure
 
@@ -133,7 +163,8 @@ The Feature Detail Design Document should include the following:
 - Use Mermaid diagrams to describe interaction flows, clearly expressing user-system interaction processes
 - Define complete data fields, including type, format, constraints, and other information
 - Design backend processing logic flows, including business validation and exception handling
-- Explicitly prompt user for confirmation after feature design completion, only transition to speccrew-system-designer after confirmation
+- Generate API Contract documents after Feature Spec is confirmed, using `speccrew-fd-api-contract` skill
+- Explicitly prompt user for joint confirmation of both Feature Spec and API Contract, only transition to speccrew-system-designer after confirmation
 
 **Must not do:**
 - Do not go deep into specific technical implementation details (e.g., technology selection, framework usage, that's speccrew-system-designer's responsibility)

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/SKILL.md

@@ -60,7 +60,8 @@ flowchart TB
     S0[Pre-processing: Platform Root Detection] --> S0a[Stage 0: Platform Detection]
     S0a --> S1a[Stage 1a: Entry Directory Recognition]
     S1a --> S1b[Stage 1b: Feature Inventory]
-    S1b --> S2[Stage 2: Feature Analysis + Graph Write]
+    S1b --> S1c[Stage 1c: Feature Merge - Incremental]
+    S1c --> S2[Stage 2: Feature Analysis + Graph Write]
     S2 --> S3[Stage 3: Module Summarize]
     S3 --> S3_5[Stage 3.5: UI Style Pattern Extract]
     S3_5 --> S4[Stage 4: System Summary]
@@ -278,6 +279,51 @@ After generating the entry-dirs JSON:
 
 ---
 
+## Stage 1c: Feature Merge (Incremental)
+
+**Goal**: If incremental inventory files (`features-*.new.json`) are detected, merge them with existing `features-*.json` files. Identifies added/removed/changed features, resets changed features for re-analysis, and cleans up artifacts for removed features.
+
+> **IMPORTANT**: This stage is executed **directly by the dispatch agent (Leader)** via `run_in_terminal`. NOT delegated to a Worker Agent.
+
+**Prerequisite**: Stage 1b completed.
+
+**Skip condition**: If no `features-*.new.json` files exist in `{sync_state_path}/knowledge-bizs/`, skip this Stage entirely and proceed to Stage 2.
+
+**Action** (dispatch executes directly via `run_in_terminal`):
+
+1. **Locate the merge script**: Find `merge-features.js` in the `speccrew-knowledge-bizs-dispatch` skill's scripts directory:
+   - Script location: `{ide_skills_dir}/speccrew-knowledge-bizs-dispatch/scripts/merge-features.js`
+
+2. **Execute merge script**:
+   ```
+   node "{path_to_merge_features_js}" --syncStatePath "{sync_state_path}/knowledge-bizs" --completedDir "{completed_dir}" --projectRoot "{project_root}"
+   ```
+
+3. **Read output JSON** from stdout and report merge results:
+   - Added features: new source files discovered
+   - Removed features: source files no longer exist (documents and markers cleaned up)
+   - Changed features: source files modified since last analysis (reset to `analyzed: false`)
+   - Unchanged features: source files not modified (analysis state preserved)
+
+**Merge Logic**:
+
+| Situation | Condition | Action |
+|-----------|-----------|--------|
+| Added | In new scan but not in existing features | Add with `analyzed: false` |
+| Removed | In existing features but not in new scan | Remove from list, delete `.md` doc + `.done.json` + `.graph.json` markers |
+| Changed | Both exist, `lastModified > completedAt` | Reset `analyzed: false` for re-analysis |
+| Unchanged | Both exist, `lastModified <= completedAt` | Preserve existing analysis state |
+
+**Output**: Updated `features-{platform}.json` files where:
+- New features: `analyzed: false`
+- Source-modified features: `analyzed: false`  
+- Unmodified features: preserved original `analyzed` status
+- Deleted features: removed from list, associated documents and markers cleaned up
+
+**Error handling**: If the merge script exits with non-zero code, STOP and report the error. Do NOT proceed to Stage 2 until merge is resolved.
+
+---
+
 ## Stage 2: Feature Analysis (Batch Processing)
 
 **Overview**: Process all pending features in batches. Each batch gets a set of features, launches Worker Agents to analyze them, then processes the results.

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/scripts/merge-features.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * merge-features.js
+ * 
+ * Merge incremental feature inventory (*.new.json) with existing features (*.json).
+ * Identifies added/removed/changed/unchanged features and cleans up artifacts for removed features.
+ * 
+ * Usage: node merge-features.js --syncStatePath <path> --completedDir <path> --projectRoot <path>
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const params = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const value = args[i + 1];
+      if (value !== undefined && !value.startsWith('--')) {
+        params[key] = value;
+        i++;
+      } else {
+        params[key] = true;
+      }
+    }
+  }
+  return params;
+}
+
+function normalizePath(p) {
+  return p ? p.replace(/\\/g, '/') : '';
+}
+
+// Safely delete a file, logging the action
+function safeDelete(filePath, cleanedFiles) {
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.unlinkSync(filePath);
+      cleanedFiles.push(normalizePath(filePath));
+      return true;
+    } catch (e) {
+      console.error(`Warning: Failed to delete ${filePath}: ${e.message}`);
+      return false;
+    }
+  }
+  return false;
+}
+
+// Compare timestamps: returns true if sourceModified is newer than analysisCompleted
+function isNewer(lastModified, completedAt) {
+  if (!completedAt) return true; // never analyzed → needs analysis
+  if (!lastModified) return false; // no modification info → assume unchanged
+  
+  // lastModified is ISO format: "2026-04-07T12:30:00.000Z"
+  // completedAt is custom format: "2026-04-07-123000" (from dispatch)
+  // Normalize completedAt to comparable format
+  const normalizedCompleted = normalizeCompletedAt(completedAt);
+  
+  const modDate = new Date(lastModified);
+  const compDate = new Date(normalizedCompleted);
+  
+  // If either date is invalid, treat as changed (safer)
+  if (isNaN(modDate.getTime()) || isNaN(compDate.getTime())) {
+    return true;
+  }
+  
+  return modDate > compDate;
+}
+
+// Normalize completedAt format "2026-04-07-123000" → "2026-04-07T12:30:00"
+function normalizeCompletedAt(completedAt) {
+  if (!completedAt) return null;
+  
+  // Try ISO format first
+  if (completedAt.includes('T')) return completedAt;
+  
+  // Handle "YYYY-MM-DD-HHmmss" format
+  const match = completedAt.match(/^(\d{4}-\d{2}-\d{2})-(\d{2})(\d{2})(\d{2})$/);
+  if (match) {
+    return `${match[1]}T${match[2]}:${match[3]}:${match[4]}`;
+  }
+  
+  return completedAt;
+}
+
+function main() {
+  const params = parseArgs();
+  
+  const syncStatePath = params.syncStatePath;
+  const completedDir = params.completedDir;
+  const projectRoot = params.projectRoot;
+  
+  if (!syncStatePath || !completedDir || !projectRoot) {
+    console.error('Usage: node merge-features.js --syncStatePath <path> --completedDir <path> --projectRoot <path>');
+    process.exit(1);
+  }
+  
+  const resolvedSyncState = path.resolve(syncStatePath);
+  const resolvedCompletedDir = path.resolve(completedDir);
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  
+  // Scan for *.new.json files
+  if (!fs.existsSync(resolvedSyncState)) {
+    // Output empty result
+    console.log(JSON.stringify({ platforms: [], totalAdded: 0, totalRemoved: 0, totalChanged: 0, totalUnchanged: 0 }));
+    return;
+  }
+  
+  const newFiles = fs.readdirSync(resolvedSyncState)
+    .filter(f => f.startsWith('features-') && f.endsWith('.new.json'));
+  
+  if (newFiles.length === 0) {
+    // No incremental files found
+    console.log(JSON.stringify({ platforms: [], totalAdded: 0, totalRemoved: 0, totalChanged: 0, totalUnchanged: 0 }));
+    return;
+  }
+  
+  const result = {
+    platforms: [],
+    totalAdded: 0,
+    totalRemoved: 0,
+    totalChanged: 0,
+    totalUnchanged: 0
+  };
+  
+  for (const newFile of newFiles) {
+    const newFilePath = path.join(resolvedSyncState, newFile);
+    // features-backend-bpm.new.json → features-backend-bpm.json
+    const oldFileName = newFile.replace('.new.json', '.json');
+    const oldFilePath = path.join(resolvedSyncState, oldFileName);
+    
+    // Read new features
+    let newData;
+    try {
+      newData = JSON.parse(fs.readFileSync(newFilePath, 'utf8'));
+    } catch (e) {
+      console.error(`Error reading ${newFile}: ${e.message}`);
+      continue;
+    }
+    
+    // Read old features (if exists)
+    let oldData = null;
+    if (fs.existsSync(oldFilePath)) {
+      try {
+        oldData = JSON.parse(fs.readFileSync(oldFilePath, 'utf8'));
+      } catch (e) {
+        console.error(`Warning: Failed to read ${oldFileName}, treating as fresh: ${e.message}`);
+      }
+    }
+    
+    // If no old data, just rename new → old (first-time generation)
+    if (!oldData) {
+      fs.renameSync(newFilePath, oldFilePath);
+      const platformResult = {
+        platformId: newData.platformId || oldFileName.replace('features-', '').replace('.json', ''),
+        added: newData.features.map(f => f.fileName),
+        removed: [],
+        changed: [],
+        unchanged: [],
+        cleanedFiles: []
+      };
+      result.platforms.push(platformResult);
+      result.totalAdded += platformResult.added.length;
+      console.error(`Platform ${platformResult.platformId}: ${platformResult.added.length} features (first run)`);
+      continue;
+    }
+    
+    // Build old features map by sourcePath
+    const oldMap = new Map();
+    for (const feature of (oldData.features || [])) {
+      oldMap.set(normalizePath(feature.sourcePath), feature);
+    }
+    
+    // Build new features map by sourcePath
+    const newMap = new Map();
+    for (const feature of (newData.features || [])) {
+      newMap.set(normalizePath(feature.sourcePath), feature);
+    }
+    
+    const platformResult = {
+      platformId: newData.platformId || oldData.platformId || oldFileName.replace('features-', '').replace('.json', ''),
+      added: [],
+      removed: [],
+      changed: [],
+      unchanged: [],
+      cleanedFiles: []
+    };
+    
+    // Merged features list
+    const mergedFeatures = [];
+    
+    // Process new features
+    for (const [sourcePath, newFeature] of newMap) {
+      const oldFeature = oldMap.get(sourcePath);
+      
+      if (!oldFeature) {
+        // Added: new feature not in old
+        mergedFeatures.push({
+          ...newFeature,
+          analyzed: false,
+          startedAt: null,
+          completedAt: null,
+          analysisNotes: null
+        });
+        platformResult.added.push(newFeature.fileName);
+      } else if (!oldFeature.analyzed || !oldFeature.completedAt) {
+        // Previously not analyzed → keep as not analyzed, use new metadata
+        mergedFeatures.push({
+          ...newFeature,
+          analyzed: false,
+          startedAt: oldFeature.startedAt,
+          completedAt: oldFeature.completedAt,
+          analysisNotes: oldFeature.analysisNotes
+        });
+        platformResult.changed.push(newFeature.fileName);
+      } else if (isNewer(newFeature.lastModified, oldFeature.completedAt)) {
+        // Changed: source modified after last analysis
+        mergedFeatures.push({
+          ...newFeature,
+          analyzed: false,
+          startedAt: null,
+          completedAt: oldFeature.completedAt, // preserve for reference
+          analysisNotes: `Source modified since last analysis (was: ${oldFeature.analysisNotes || 'N/A'})`
+        });
+        platformResult.changed.push(newFeature.fileName);
+      } else {
+        // Unchanged: keep old feature state entirely
+        mergedFeatures.push({
+          ...oldFeature,
+          // Update metadata from new scan (in case id/documentPath changed)
+          id: newFeature.id,
+          documentPath: newFeature.documentPath,
+          lastModified: newFeature.lastModified
+        });
+        platformResult.unchanged.push(newFeature.fileName);
+      }
+    }
+    
+    // Process removed features (in old but not in new)
+    for (const [sourcePath, oldFeature] of oldMap) {
+      if (!newMap.has(sourcePath)) {
+        platformResult.removed.push(oldFeature.fileName);
+        
+        // Clean up artifacts
+        // 1. Delete document .md file
+        if (oldFeature.documentPath) {
+          const docAbsPath = path.join(resolvedProjectRoot, oldFeature.documentPath);
+          safeDelete(docAbsPath, platformResult.cleanedFiles);
+        }
+        
+        // 2. Delete .done.json marker
+        const donePath = path.join(resolvedCompletedDir, `${oldFeature.fileName}.done.json`);
+        safeDelete(donePath, platformResult.cleanedFiles);
+        
+        // 3. Delete .graph.json marker
+        const graphPath = path.join(resolvedCompletedDir, `${oldFeature.fileName}.graph.json`);
+        safeDelete(graphPath, platformResult.cleanedFiles);
+      }
+    }
+    
+    // Update inventory metadata
+    const analyzedCount = mergedFeatures.filter(f => f.analyzed).length;
+    const mergedInventory = {
+      ...newData,
+      // Preserve some old metadata
+      analysisMethod: oldData.analysisMethod || newData.analysisMethod,
+      // Update counts
+      totalFiles: mergedFeatures.length,
+      analyzedCount: analyzedCount,
+      pendingCount: mergedFeatures.length - analyzedCount,
+      generatedAt: new Date().toISOString().replace(/[-:]/g, '').slice(0, 15).replace('T', '-'),
+      features: mergedFeatures
+    };
+    
+    // Also recalculate modules list
+    const moduleSet = new Set(mergedFeatures.map(f => f.module));
+    mergedInventory.modules = [...moduleSet].sort();
+    
+    // Write back merged features (overwrite old file)
+    fs.writeFileSync(oldFilePath, JSON.stringify(mergedInventory, null, 2), 'utf8');
+    
+    // Delete .new.json file
+    fs.unlinkSync(newFilePath);
+    
+    result.platforms.push(platformResult);
+    result.totalAdded += platformResult.added.length;
+    result.totalRemoved += platformResult.removed.length;
+    result.totalChanged += platformResult.changed.length;
+    result.totalUnchanged += platformResult.unchanged.length;
+    
+    console.error(`Platform ${platformResult.platformId}: +${platformResult.added.length} added, -${platformResult.removed.length} removed, ~${platformResult.changed.length} changed, =${platformResult.unchanged.length} unchanged`);
+  }
+  
+  // Output result as JSON to stdout
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main();

package/.speccrew/skills/speccrew-knowledge-bizs-init-features/scripts/generate-inventory.js

@@ -366,7 +366,8 @@ function findFilesInDir(dir, extensions, baseDir) {
           relativePath,
           fileName: path.basename(item, ext),
           extension: ext,
-          directory: path.dirname(relativePath)
+          directory: path.dirname(relativePath),
+          lastModified: stat.mtime.toISOString()
         });
       }
     }
@@ -459,6 +460,7 @@ function generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outpu
           sourcePath: relativeFilePath,
           documentPath: docPath,
           module: moduleName,
+          lastModified: file.lastModified,
           analyzed: false,
           startedAt: null,
           completedAt: null,
@@ -498,16 +500,25 @@ function generateFromEntryDirs(entryDirsData, platformConfig, projectRoot, outpu
   // Write output file
   const outputFileName = `features-${platformId}.json`;
   const outputPath = path.join(outputDir, outputFileName);
-  
+
+  // Incremental: if features file already exists, write to *.new.json
+  const actualOutputPath = fs.existsSync(outputPath)
+    ? outputPath.replace(/\.json$/, '.new.json')
+    : outputPath;
+
   // Ensure output directory exists
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
-  
-  fs.writeFileSync(outputPath, JSON.stringify(inventory, null, 2), 'utf8');
-  
-  console.log(`Generated ${outputFileName} with ${features.length} features`);
-  console.log(`Output: ${outputPath}`);
+
+  fs.writeFileSync(actualOutputPath, JSON.stringify(inventory, null, 2), 'utf8');
+
+  if (actualOutputPath !== outputPath) {
+    console.log(`Incremental: Generated ${path.basename(actualOutputPath)} (existing features detected)`);
+  } else {
+    console.log(`Full: Generated ${path.basename(actualOutputPath)} with ${features.length} features`);
+  }
+  console.log(`Output: ${actualOutputPath}`);
   
   return true;
 }
@@ -536,7 +547,8 @@ function findFiles(dir, extensions, excludeDirs, baseDir) {
           relativePath,
           fileName: path.basename(item, ext),
           extension: ext,
-          directory: path.dirname(relativePath)
+          directory: path.dirname(relativePath),
+          lastModified: stat.mtime.toISOString()
         });
       }
     }
@@ -853,6 +865,7 @@ function main() {
       sourcePath: relativeFilePath,
       documentPath: docPath,
       module: moduleName,
+      lastModified: file.lastModified,
       analyzed: false,
       startedAt: null,
       completedAt: null,
@@ -894,11 +907,20 @@ function main() {
     fs.mkdirSync(syncStateDir, { recursive: true });
   }
 
+  // Incremental: if features file already exists, write to *.new.json
+  const actualOutputPath = fs.existsSync(outputPath)
+    ? outputPath.replace(/\.json$/, '.new.json')
+    : outputPath;
+
   // Write JSON output
-  fs.writeFileSync(outputPath, JSON.stringify(inventory, null, 2), 'utf8');
+  fs.writeFileSync(actualOutputPath, JSON.stringify(inventory, null, 2), 'utf8');
 
-  console.log(`Generated features.json with ${files.length} features`);
-  console.log(`Ready for analysis: ${outputPath}`);
+  if (actualOutputPath !== outputPath) {
+    console.log(`Incremental: Generated ${path.basename(actualOutputPath)} (existing features detected)`);
+  } else {
+    console.log(`Full: Generated features.json with ${files.length} features`);
+  }
+  console.log(`Output: ${actualOutputPath}`);
 }
 
 main();

package/lib/commands/update.js

@@ -376,6 +376,28 @@ function updatePackageDocs(packageRoot, workspaceDir, stats) {
 function run() {
   try {
     const args = parseArgs();
+
+    // Self-update: check if a newer version exists on npm registry
+    const localVersion = getPackageVersion();
+    let latestVersion = null;
+    try {
+      const { execSync } = require('child_process');
+      latestVersion = execSync('npm view speccrew version', { encoding: 'utf8', timeout: 15000 }).trim();
+    } catch (e) {
+      // Network error or npm not available, skip self-update
+    }
+
+    if (latestVersion && latestVersion !== localVersion) {
+      console.log(`Updating CLI: v${localVersion} → v${latestVersion} ...`);
+      try {
+        const { execSync } = require('child_process');
+        execSync('npm install -g speccrew@latest', { stdio: 'inherit', timeout: 60000 });
+        console.log(`CLI updated to v${latestVersion}\n`);
+      } catch (e) {
+        console.warn(`Warning: CLI self-update failed (${e.message}). Continuing with current version.\n`);
+      }
+    }
+
     const projectRoot = process.cwd();
     
     // 读取 .speccrewrc (with migration support)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speccrew",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Spec-Driven Development toolkit for AI-powered IDEs",
   "author": "charlesmu99",
   "repository": {