speccrew 0.1.0

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/STATUS-FORMATS.md

@@ -0,0 +1,74 @@
+# Status File Formats (Bizs Pipeline)
+
+This document defines the status tracking formats for the bizs pipeline.
+
+> **Note**: Stage 2 and Stage 3 status tracking is now handled directly within `features-{platform}.json` files and Worker return values. The legacy `stage2-status.json` and `stage3-status.json` files have been removed.
+
+---
+
+## Feature Status Tracking (Stage 2)
+
+Feature analysis status is tracked directly in `features-{platform}.json` files located at:
+- `speccrew-workspace/knowledges/base/sync-state/knowledge-bizs/features-{platform}.json`
+
+**Feature Object Schema**:
+```json
+{
+  "id": "string (unique feature identifier)",
+  "fileName": "string",
+  "sourcePath": "string",
+  "documentPath": "string",
+  "module": "string",
+  "analyzed": "boolean",
+  "status": "pending | in_progress | completed | failed",
+  "startedAt": "ISO timestamp (optional)",
+  "completedAt": "ISO timestamp (optional)",
+  "error": "string (optional, when status=failed)",
+  "analysisNotes": "string (optional, notes from analysis; may contain [WARN: document missing] if document was not generated)"
+}
+```
+
+**Example Feature Entry**:
+```json
+{
+  "id": "user-index-vue",
+  "fileName": "index",
+  "sourcePath": "frontend-web/src/views/system/user/index.vue",
+  "documentPath": "speccrew-workspace/knowledges/bizs/web/system/user/index.md",
+  "module": "system",
+  "analyzed": true,
+  "status": "completed",
+  "startedAt": "2024-01-15T10:30:00Z",
+  "completedAt": "2024-01-15T10:35:00Z"
+}
+```
+
+---
+
+## Module Status Tracking (Stage 3)
+
+Module summarization status is determined by aggregating feature statuses from `features-{platform}.json`:
+
+| Module Status | Condition |
+|---------------|-----------|
+| `pending` | Module has features but no overview document exists |
+| `completed` | Overview document exists at `{module}/{module}-overview.md` |
+| `failed` | Worker explicitly reported failure |
+
+---
+
+## Field Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `features[].id` | string | Unique feature identifier (used for marker file naming) |
+| `features[].fileName` | string | Feature file name |
+| `features[].sourcePath` | string | Source code file path |
+| `features[].documentPath` | string | Generated documentation path |
+| `features[].module` | string | Module code_name |
+| `features[].analyzed` | boolean | Whether feature has been analyzed |
+| `features[].status` | string | `pending`, `in_progress`, `completed`, `failed` |
+| `features[].startedAt` | string | ISO timestamp when analysis started |
+| `features[].completedAt` | string | ISO timestamp when analysis completed |
+| `features[].error` | string | Error message when status is `failed` |
+| `features[].analysisNotes` | string | Analysis notes from Worker; contains `[WARN: document missing at {path}]` if document was expected but not found |

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/scripts/batch-orchestrator.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+/**
+ * Batch Orchestrator - Main control script for Stage 2 loop.
+ *
+ * This script simplifies the Stage 2 loop in SKILL.md by merging
+ * "get batch" and "process previous batch results" steps into a single call.
+ *
+ * Modes:
+ *   1. get-batch: Get the next batch of features to process
+ *   2. process-results: Process the previous batch results
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+// Parse command line arguments
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        mode: null,
+        syncStatePath: null,
+        batchSize: 5,
+        graphRoot: null,
+        graphWriteScript: null,
+        platformId: null
+    };
+
+    // First non-option argument is the mode
+    let modeFound = false;
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        // Skip if it's a flag
+        if (arg.startsWith('--')) {
+            switch (arg) {
+                case '--syncStatePath':
+                case '-SyncStatePath':
+                    result.syncStatePath = args[++i];
+                    break;
+                case '--batchSize':
+                case '-BatchSize':
+                    result.batchSize = parseInt(args[++i], 10) || 5;
+                    break;
+                case '--graphRoot':
+                case '-GraphRoot':
+                    result.graphRoot = args[++i];
+                    break;
+                case '--graphWriteScript':
+                case '-GraphWriteScript':
+                    result.graphWriteScript = args[++i];
+                    break;
+                case '--platformId':
+                case '-PlatformId':
+                    result.platformId = args[++i];
+                    break;
+            }
+        } else if (!modeFound) {
+            // First non-flag argument is the mode
+            result.mode = arg;
+            modeFound = true;
+        }
+    }
+
+    return result;
+}
+
+// Get the path to a script in the same directory
+function getScriptPath(scriptName) {
+    return path.join(__dirname, scriptName);
+}
+
+// Mode 1: Get the next batch of features
+function getBatch(args) {
+    if (!args.syncStatePath) {
+        throw new Error('--syncStatePath is required for get-batch mode');
+    }
+
+    const getNextBatchScript = getScriptPath('get-next-batch.js');
+
+    const commandArgs = [
+        getNextBatchScript,
+        '--syncStatePath', args.syncStatePath,
+        '--batchSize', String(args.batchSize)
+    ];
+
+    // Execute get-next-batch.js and capture output
+    const output = execFileSync('node', commandArgs, { encoding: 'utf8' });
+
+    // Parse the output (JSON array of features)
+    const batch = JSON.parse(output);
+
+    // Determine the response based on whether there are features
+    if (batch.length === 0) {
+        return {
+            action: 'done',
+            message: 'All features have been processed'
+        };
+    } else {
+        return {
+            action: 'process',
+            batch: batch,
+            batchSize: batch.length,
+            iteration: null // Could be enhanced with state tracking
+        };
+    }
+}
+
+// Mode 2: Process the previous batch results
+function processResults(args) {
+    if (!args.syncStatePath) {
+        throw new Error('--syncStatePath is required for process-results mode');
+    }
+    if (!args.graphRoot) {
+        throw new Error('--graphRoot is required for process-results mode');
+    }
+    if (!args.graphWriteScript) {
+        throw new Error('--graphWriteScript is required for process-results mode');
+    }
+    if (!args.platformId) {
+        throw new Error('--platformId is required for process-results mode');
+    }
+
+    const processBatchResultsScript = getScriptPath('process-batch-results.js');
+
+    const commandArgs = [
+        processBatchResultsScript,
+        '--syncStatePath', args.syncStatePath,
+        '--graphRoot', args.graphRoot,
+        '--graphWriteScript', args.graphWriteScript,
+        '--platformId', args.platformId
+    ];
+
+    // Execute process-batch-results.js and capture output
+    const output = execFileSync('node', commandArgs, { encoding: 'utf8' });
+
+    // Parse and return the output (JSON result)
+    return JSON.parse(output);
+}
+
+function main() {
+    try {
+        const args = parseArgs();
+
+        if (!args.mode) {
+            console.error('Error: Mode is required. Use "get-batch" or "process-results"');
+            console.error('Usage:');
+            console.error('  node batch-orchestrator.js get-batch --syncStatePath <path> [--batchSize 5]');
+            console.error('  node batch-orchestrator.js process-results --syncStatePath <path> --graphRoot <path> --graphWriteScript <path> --platformId <id>');
+            process.exit(1);
+        }
+
+        let result;
+
+        switch (args.mode) {
+            case 'get-batch':
+                result = getBatch(args);
+                break;
+            case 'process-results':
+                result = processResults(args);
+                break;
+            default:
+                throw new Error(`Unknown mode: ${args.mode}. Use "get-batch" or "process-results"`);
+        }
+
+        // Output result as JSON
+        console.log(JSON.stringify(result, null, 2));
+
+    } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+main();

package/.speccrew/skills/speccrew-knowledge-bizs-dispatch/scripts/get-next-batch.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * Get the next batch of features to process from features-*.json files.
+ *
+ * Scans the sync-state directory for all features-*.json files and extracts
+ * features where analyzed=false or analyzed field is missing.
+ * Additionally excludes features that have a corresponding .done.json file in the
+ * completed/ directory (indicating Worker has finished but results not yet processed).
+ * Returns a JSON array limited to BatchSize items.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse command line arguments
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        syncStatePath: null,
+        batchSize: 5
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--syncStatePath':
+            case '-SyncStatePath':
+                result.syncStatePath = args[++i];
+                break;
+            case '--batchSize':
+            case '-BatchSize':
+                result.batchSize = parseInt(args[++i], 10) || 5;
+                break;
+        }
+    }
+
+    return result;
+}
+
+function main() {
+    try {
+        const args = parseArgs();
+
+        if (!args.syncStatePath) {
+            console.error('Error: --syncStatePath is required');
+            process.exit(1);
+        }
+
+        // Resolve full path
+        const fullPath = path.resolve(args.syncStatePath);
+        if (!fs.existsSync(fullPath)) {
+            console.error(`SyncStatePath not found: ${args.syncStatePath}`);
+            process.exit(1);
+        }
+
+        // Path to completed directory
+        const completedDir = path.join(fullPath, 'completed');
+
+        // Build set of completed feature fileNames (for fast lookup)
+        const completedFeatureFileNames = new Set();
+        const completedFeatureIds = new Set();
+        if (fs.existsSync(completedDir) && fs.statSync(completedDir).isDirectory()) {
+            const doneFiles = fs.readdirSync(completedDir).filter(f => f.endsWith('.done.json'));
+            for (const doneFile of doneFiles) {
+                // Read .done.json file content to extract fileName or featureId
+                const doneFilePath = path.join(completedDir, doneFile);
+                try {
+                    const doneRawContent = fs.readFileSync(doneFilePath, 'utf8');
+                    const doneContent = JSON.parse(doneRawContent);
+                    // Use fileName field if available, fallback to featureId
+                    if (doneContent.fileName) {
+                        completedFeatureFileNames.add(doneContent.fileName);
+                    }
+                    if (doneContent.featureId) {
+                        completedFeatureIds.add(doneContent.featureId);
+                    }
+                } catch (error) {
+                    console.warn(`Warning: Failed to read .done.json file ${doneFile}: ${error.message}`);
+                    // Fallback: use filename without extension (legacy behavior)
+                    const baseName = path.basename(doneFile, '.done.json');
+                    completedFeatureIds.add(baseName);
+                }
+            }
+        }
+
+        // Find all features-*.json files
+        const featureFiles = fs.readdirSync(fullPath).filter(f => {
+            return f.startsWith('features-') && f.endsWith('.json') && fs.statSync(path.join(fullPath, f)).isFile();
+        });
+
+        const candidateFeatures = [];
+
+        for (const fileName of featureFiles) {
+            const filePath = path.join(fullPath, fileName);
+            const rawContent = fs.readFileSync(filePath, 'utf8');
+            const content = JSON.parse(rawContent);
+
+            const platformType = content.platformType;
+            const platformSubtype = content.platformSubtype || null;
+            const sourcePath = content.sourcePath;
+            const techStack = content.techStack;
+            const platformName = content.platformName;
+
+            if (!content.features || !Array.isArray(content.features)) {
+                continue;
+            }
+
+            for (const feature of content.features) {
+                // Check if feature needs analysis: analyzed=false or analyzed field missing
+                const needsAnalysis = !('analyzed' in feature) || feature.analyzed === false;
+
+                if (!needsAnalysis) {
+                    continue;
+                }
+
+                // Use feature's id and fileName fields
+                const featureId = feature.id;
+                const featureFileName = feature.fileName;
+
+                // Skip if already completed (has .done.json file)
+                // Check both fileName (new format) and featureId (legacy format)
+                if (completedFeatureFileNames.has(featureFileName) || completedFeatureIds.has(featureId)) {
+                    continue;
+                }
+
+                candidateFeatures.push({
+                    sourceFile: fileName,
+                    platformName: platformName,
+                    platformType: platformType,
+                    platformSubtype: platformSubtype,
+                    sourcePath: sourcePath,
+                    techStack: techStack,
+                    feature: feature
+                });
+            }
+        }
+
+        // Take only the first BatchSize items
+        const batchFeatures = candidateFeatures.slice(0, args.batchSize);
+
+        // Output as JSON
+        console.log(JSON.stringify(batchFeatures, null, 2));
+    } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+main();

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Get all pending features from features-*.json files.
+ *
+ * Scans the sync-state directory for all features-*.json files and extracts
+ * features where status='pending' or status field is missing (backward compatibility).
+ * Returns a flat JSON array with platform metadata attached to each feature for easy dispatch.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse command line arguments
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        syncStatePath: null,
+        platformId: null
+    };
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--syncStatePath':
+            case '-SyncStatePath':
+                result.syncStatePath = args[++i];
+                break;
+            case '--platformId':
+            case '-platformId':
+                result.platformId = args[++i];
+                break;
+        }
+    }
+
+    return result;
+}
+
+function main() {
+    try {
+        const args = parseArgs();
+
+        if (!args.syncStatePath) {
+            console.error('Error: --syncStatePath is required');
+            process.exit(1);
+        }
+
+        // Resolve full path
+        const fullPath = path.resolve(args.syncStatePath);
+        if (!fs.existsSync(fullPath)) {
+            console.error(`SyncStatePath not found: ${args.syncStatePath}`);
+            process.exit(1);
+        }
+
+        // Find features-*.json files, filtered by platformId if specified
+        let featureFiles = fs.readdirSync(fullPath).filter(f => {
+            return f.startsWith('features-') && f.endsWith('.json') && fs.statSync(path.join(fullPath, f)).isFile();
+        });
+
+        // If platformId is specified, filter to only the matching file
+        if (args.platformId) {
+            const targetFile = `features-${args.platformId}.json`;
+            featureFiles = featureFiles.filter(f => f === targetFile);
+        }
+
+        const pendingFeatures = [];
+
+        for (const fileName of featureFiles) {
+            const filePath = path.join(fullPath, fileName);
+            const rawContent = fs.readFileSync(filePath, 'utf8');
+            const content = JSON.parse(rawContent);
+
+            const platformType = content.platformType;
+            const platformSubtype = content.platformSubtype || null;
+            const sourcePath = content.sourcePath;
+            const techStack = content.techStack;
+            const platformName = content.platformName;
+
+            if (!content.features || !Array.isArray(content.features)) {
+                continue;
+            }
+
+            for (const feature of content.features) {
+                if (!('status' in feature) || feature.status === 'pending') {
+                    pendingFeatures.push({
+                        sourceFile: fileName,
+                        platformName: platformName,
+                        platformType: platformType,
+                        platformSubtype: platformSubtype,
+                        sourcePath: sourcePath,
+                        techStack: techStack,
+                        feature: feature
+                    });
+                }
+            }
+        }
+
+        // Output as JSON
+        console.log(JSON.stringify(pendingFeatures, null, 2));
+    } catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+main();