specsmd 0.0.0-dev.2 → 0.0.0-dev.21

package/README.md

@@ -29,8 +29,9 @@ Track your AI-DLC progress with our sidebar extension for VS Code and compatible
 > **Note:** Works with any VS Code-based IDE including [Cursor](https://cursor.sh), [Google Antigravity](https://antigravity.google), [Windsurf](https://codeium.com/windsurf), and others.
 
 **Install from:**
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd)
-- [GitHub Releases (VSIX)](https://github.com/fabriqaai/specs.md/releases)
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd) — VS Code, GitHub Codespaces
+- [Open VSX Registry](https://open-vsx.org/extension/fabriqaai/specsmd) — Cursor, Windsurf, Amazon Kiro, Google Antigravity, VSCodium, Gitpod, Google IDX
+- [GitHub Releases (VSIX)](https://github.com/fabriqaai/specs.md/releases) — Manual installation
 
 ---
 
@@ -306,6 +307,13 @@ Specs and Memory Bank provide structured context for AI agents. Agents reload co
 | **Cursor** | Full support | Rules in `.cursor/rules/` (`.mdc` format) |
 | **GitHub Copilot** | Full support | Agents in `.github/agents/` (`.agent.md` format) |
 | **Google Antigravity** | Full support | Agents in `.agent/agents/` |
+| **Windsurf** | Full support | Workflows in `.windsurf/workflows/` |
+| **Amazon Kiro** | Full support | Steering in `.kiro/steering/` |
+| **Gemini CLI** | Full support | Commands in `.gemini/commands/` (`.toml` format) |
+| **Cline** | Full support | Rules in `.clinerules/` |
+| **Roo Code** | Full support | Commands in `.roo/commands/` |
+| **OpenAI Codex** | Full support | Config in `.codex/` |
+| **OpenCode** | Full support | Agents in `.opencode/agent/` |
 
 ---
 

package/flows/aidlc/commands/construction-agent.md

@@ -1,3 +1,7 @@
+---
+description: Building phase agent - execute bolts through DDD stages (model, test, implement)
+---
+
 # Activate Construction Agent
 
 **Command**: `/specsmd-construction-agent`

package/flows/aidlc/commands/inception-agent.md

@@ -1,3 +1,7 @@
+---
+description: Planning phase agent - requirements gathering, story creation, and bolt planning
+---
+
 # Activate Inception Agent
 
 **Command**: `/specsmd-inception-agent`

package/flows/aidlc/commands/master-agent.md

@@ -1,3 +1,7 @@
+---
+description: Master orchestrator for AI-DLC - routes to appropriate phase/agent based on project state
+---
+
 # Activate Master Agent
 
 **Command**: `/specsmd-master-agent`

package/flows/aidlc/commands/operations-agent.md

@@ -1,3 +1,7 @@
+---
+description: Deployment phase agent - build, deploy, verify, and monitor releases
+---
+
 # Activate Operations Agent
 
 **Command**: `/specsmd-operations-agent`

package/{scripts → flows/aidlc/scripts}/artifact-validator.js

@@ -10,9 +10,9 @@
  * - Timestamp format (ISO 8601 without milliseconds)
  *
  * Usage:
- *   node .specsmd/scripts/artifact-validator.js
- *   node .specsmd/scripts/artifact-validator.js --json
- *   node .specsmd/scripts/artifact-validator.js --fix
+ *   node .specsmd/aidlc/scripts/artifact-validator.js
+ *   node .specsmd/aidlc/scripts/artifact-validator.js --json
+ *   node .specsmd/aidlc/scripts/artifact-validator.js --fix
  *
  * Cross-platform: Works on Linux, macOS, Windows via Node.js
  */

package/{scripts → flows/aidlc/scripts}/bolt-complete.js

@@ -115,11 +115,11 @@
  *
  *   From agent skill (bolt-start.md Step 10):
  *
- *     node .specsmd/scripts/bolt-complete.js 016-analytics-tracker
+ *     node .specsmd/aidlc/scripts/bolt-complete.js 016-analytics-tracker
  *
  *   With optional stage name:
  *
- *     node .specsmd/scripts/bolt-complete.js 016-analytics-tracker --last-stage test
+ *     node .specsmd/aidlc/scripts/bolt-complete.js 016-analytics-tracker --last-stage test
  *
  * ═══════════════════════════════════════════════════════════════════════════════
  */
@@ -510,6 +510,29 @@ async function updateIntentStatus(bolt) {
     return { updated: false };
 }
 
+/**
+ * Validate bolt status before allowing completion
+ *
+ * Pre-flight checks to ensure:
+ * - Bolt is in "in-progress" status (can't complete already-complete or not-started bolts)
+ * - Bolt has not already been completed
+ */
+function validateBoltStatus(bolt) {
+    const status = bolt.frontmatter.status || 'unknown';
+
+    // Cannot complete a bolt that's already complete
+    if (status === 'complete') {
+        return { valid: false, reason: 'Bolt is already complete' };
+    }
+
+    // Bolt should be in-progress before completing
+    if (status !== 'in-progress') {
+        return { valid: false, reason: `Bolt status is "${status}", expected "in-progress"` };
+    }
+
+    return { valid: true };
+}
+
 /**
  * Main: Mark bolt as complete with all dependent updates
  */
@@ -522,6 +545,14 @@ async function boltMarkComplete(boltId, lastStage) {
         // Step 1: Read bolt file
         const bolt = await readBolt(boltId);
 
+        // Step 1.5: Validate bolt status before proceeding
+        const validation = validateBoltStatus(bolt);
+        if (!validation.valid) {
+            console.error(`\n${colors.red}Error:${colors.reset} ${validation.reason}`);
+            console.error(`${colors.dim}Use bolt-status command to check current state.${colors.reset}`);
+            return 1;
+        }
+
         console.log(`${colors.dim}Bolt: ${bolt.id}${colors.reset}`);
         console.log(`${colors.dim}Intent: ${bolt.frontmatter.intent}${colors.reset}`);
         console.log(`${colors.dim}Unit: ${bolt.frontmatter.unit}${colors.reset}`);
@@ -537,11 +568,11 @@ async function boltMarkComplete(boltId, lastStage) {
         console.log(`\n${colors.dim}Stories: ${colors.green}${storyResults.updated} updated${colors.reset}, ${colors.dim}${storyResults.skipped} skipped${colors.reset}${storyResults.errors > 0 ? `, ${colors.red}${storyResults.errors} errors${colors.reset}` : ''}\n`);
 
         // Step 4: Update unit status
-        const unitResult = await updateUnitStatus(bolt);
+        await updateUnitStatus(bolt);
         console.log();
 
         // Step 5: Update intent status
-        const intentResult = await updateIntentStatus(bolt);
+        await updateIntentStatus(bolt);
         console.log();
 
         // Final summary

package/{scripts → flows/aidlc/scripts}/status-integrity.js

@@ -7,8 +7,8 @@
  * Status must cascade correctly: Bolt complete → Stories complete → Unit complete → Intent complete
  *
  * Usage:
- *   node .specsmd/scripts/status-integrity.js
- *   node .specsmd/scripts/status-integrity.js --fix
+ *   node .specsmd/aidlc/scripts/status-integrity.js
+ *   node .specsmd/aidlc/scripts/status-integrity.js --fix
  *
  * Cross-platform: Works on Linux, macOS, Windows via Node.js
  */
@@ -584,8 +584,8 @@ Options:
   --help, -h   Show this help message
 
 Examples:
-  node .specsmd/scripts/status-integrity.js
-  node .specsmd/scripts/status-integrity.js --fix
+  node .specsmd/aidlc/scripts/status-integrity.js
+  node .specsmd/aidlc/scripts/status-integrity.js --fix
 `);
     process.exit(0);
 }

package/flows/aidlc/skills/construction/bolt-start.md

@@ -182,6 +182,23 @@ Ready to proceed?
 
 If the bolt type specifies automatic validation criteria, follow those rules.
 
+### 8b. Final Stage Checkpoint (CRITICAL RE-READ)
+
+**⚠️ If this is the FINAL stage of the bolt**, before presenting completion:
+
+1. **STOP** and re-read **Step 10** from this skill
+2. This step is often skipped due to context distance - re-reading prevents this
+3. Do NOT report bolt as complete until you have executed Step 10
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  FINAL STAGE DETECTED                                       │
+│  → Re-read Step 10 NOW                                     │
+│  → You MUST run: node .specsmd/aidlc/scripts/bolt-complete.js │
+│  → Do NOT manually edit story files                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
 ### 9. Update Bolt File on Stage Completion
 
 **Trigger**: After EACH stage completion (not just final stage).
@@ -210,14 +227,25 @@ stages_completed:
 
 ---
 
-### 10. Mark Bolt Complete (CRITICAL - MANDATORY ON FINAL STAGE)
+### 10. Mark Bolt Complete (HARD GATE - MANDATORY ON FINAL STAGE)
 
 **Trigger**: ONLY when this is the FINAL stage.
 
-**⚠️ DO NOT SKIP THIS STEP. When the final stage completes, you MUST run the command below.**
+```text
+⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+You CANNOT report bolt completion without:
+1. Running the bolt-complete.js script
+2. Showing the script output to the user
+
+If you skip this, the memory-bank becomes inconsistent.
+Do NOT manually edit story files - the script handles everything.
+```
+
+**Run this command:**
 
 ```bash
-node .specsmd/scripts/bolt-complete.js {bolt-id}
+node .specsmd/aidlc/scripts/bolt-complete.js {bolt-id}
 ```
 
 **What this command does (deterministically):**

package/flows/aidlc/skills/inception/bolt-plan.md

@@ -289,10 +289,23 @@ Establish execution order based on dependencies:
 
 Check the plan against:
 
+**Frontmatter Validation (CRITICAL - check each bolt.md)**:
+
+- [ ] `id` - Bolt identifier present
+- [ ] `unit` - Parent unit ID present
+- [ ] `intent` - Parent intent ID present
+- [ ] `type` - Bolt type specified (`ddd-construction-bolt` or `simple-construction-bolt`)
+- [ ] `status` - Set to `planned`
+- [ ] `stories` - **Array of story IDs included** (NOT just in body, MUST be in frontmatter)
+- [ ] `created` - Timestamp present
+- [ ] `requires_bolts` - Dependency array present (can be empty `[]`)
+- [ ] `enables_bolts` - Enables array present (can be empty `[]`)
+- [ ] `complexity` - Complexity block with all 4 fields
+
+**Content Validation**:
+
 - [ ] All stories are assigned to bolts
 - [ ] Dependencies are respected (bolt-to-bolt AND unit-to-unit)
-- [ ] All dependencies documented in frontmatter
-- [ ] Complexity assessment included for each bolt
 - [ ] Each bolt has clear outputs
 - [ ] No bolt is too large (max 5-6 stories)
 - [ ] No circular dependencies exist

package/flows/aidlc/templates/construction/bolt-template.md

@@ -57,6 +57,27 @@ complexity:
 
 ---
 
+## Required Frontmatter Fields (VALIDATION CHECKLIST)
+
+Before creating a bolt, verify ALL required fields are present:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | **YES** | Bolt identifier (format: `{BBB}-{unit-name}`) |
+| `unit` | **YES** | Parent unit ID |
+| `intent` | **YES** | Parent intent ID |
+| `type` | **YES** | Bolt type (`ddd-construction-bolt` or `simple-construction-bolt`) |
+| `status` | **YES** | Current status (`planned`, `in-progress`, `completed`, `blocked`) |
+| `stories` | **YES** | Array of story IDs included in this bolt |
+| `created` | **YES** | Creation timestamp |
+| `requires_bolts` | **YES** | Array of bolt IDs this depends on (can be empty `[]`) |
+| `enables_bolts` | **YES** | Array of bolt IDs waiting on this (can be empty `[]`) |
+| `complexity` | **YES** | Complexity assessment block |
+
+**If any required field is missing, the bolt is INVALID.**
+
+---
+
 ## Content
 
 ```markdown

package/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md

@@ -270,6 +270,11 @@ created: {YYYY-MM-DDTHH:MM:SSZ}
 - **Tests**: {passed}/{total} passed
 - **Coverage**: {percentage}%
 
+### Test Files
+
+- [x] `{path/to/test-file.test.ts}` - {what this test file covers}
+- [x] `{path/to/another.test.ts}` - {what this test file covers}
+
 ### Acceptance Criteria Validation
 
 - ✅/❌ **{Criterion}**: {Status}

package/lib/analytics/tracker.js

@@ -56,7 +56,12 @@ class AnalyticsTracker {
             const Mixpanel = require('mixpanel');
             this.mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
                 protocol: 'https',
-                host: 'api-eu.mixpanel.com'  // EU endpoint for GDPR compliance
+                host: 'api-eu.mixpanel.com',  // EU endpoint for GDPR compliance
+                // Note: geolocate: true enables IP-based geolocation for analytics.
+                // This data is used solely for aggregate usage insights (e.g., country-level
+                // adoption patterns). No personal identifiers are collected. Users can
+                // opt out via the --no-telemetry flag or SPECSMD_NO_TELEMETRY env var.
+                geolocate: true
             });
 
             // Generate IDs
@@ -117,7 +122,7 @@ class AnalyticsTracker {
         if (waitForDelivery) {
             return new Promise((resolve) => {
                 try {
-                    this.mixpanel.track(eventName, eventData, (err) => {
+                    this.mixpanel.track(eventName, eventData, () => {
                         // Resolve regardless of error - silent failure
                         resolve();
                     });

package/lib/installer.js

@@ -229,6 +229,9 @@ async function installFlow(flowKey, toolKeys) {
   if (await fs.pathExists(path.join(flowPath, 'shared'))) {
     await fs.copy(path.join(flowPath, 'shared'), path.join(targetFlowDir, 'shared'));
   }
+  if (await fs.pathExists(path.join(flowPath, 'scripts'))) {
+    await fs.copy(path.join(flowPath, 'scripts'), path.join(targetFlowDir, 'scripts'));
+  }
 
   // Copy config files
   if (await fs.pathExists(path.join(flowPath, 'memory-bank.yaml'))) {
@@ -250,20 +253,6 @@ async function installFlow(flowKey, toolKeys) {
 
   CLIUtils.displayStatus('', 'Installed flow resources', 'success');
 
-  // Step 2.5: Install local scripts for deterministic operations
-  // These scripts are version-matched to the installed specsmd version
-  const scriptsDir = path.join(specsmdDir, 'scripts');
-  await fs.ensureDir(scriptsDir);
-
-  const sourceScriptsDir = path.join(__dirname, '..', 'scripts');
-  if (await fs.pathExists(sourceScriptsDir)) {
-    await fs.copy(sourceScriptsDir, scriptsDir);
-    CLIUtils.displayStatus('', 'Installed local scripts', 'success');
-  }
-
-  // Note: Scripts are invoked directly via relative path (e.g., node .specsmd/scripts/bolt-complete.js)
-  // No npm scripts added to package.json to avoid dependency on package.json for execution
-
   // NOTE: memory-bank/ is NOT created during installation
   // It will be created when user runs project-init
   // This allows us to detect if project is initialized by checking for memory-bank/standards/

package/lib/installers/WindsurfInstaller.js

@@ -1,8 +1,5 @@
 const ToolInstaller = require('./ToolInstaller');
-const fs = require('fs-extra');
 const path = require('path');
-const CLIUtils = require('../cli-utils');
-const { theme } = CLIUtils;
 
 class WindsurfInstaller extends ToolInstaller {
     get key() {
@@ -20,57 +17,6 @@ class WindsurfInstaller extends ToolInstaller {
     get detectPath() {
         return '.windsurf';
     }
-
-    /**
-     * Override to add frontmatter for Windsurf workflows
-     */
-    async installCommands(flowPath, config) {
-        const targetCommandsDir = this.commandsDir;
-        console.log(theme.dim(`  Installing workflows to ${targetCommandsDir}/...`));
-        await fs.ensureDir(targetCommandsDir);
-
-        const commandsSourceDir = path.join(flowPath, 'commands');
-
-        if (!await fs.pathExists(commandsSourceDir)) {
-            console.log(theme.warning(`  No commands folder found at ${commandsSourceDir}`));
-            return [];
-        }
-
-        const commandFiles = await fs.readdir(commandsSourceDir);
-        const installedFiles = [];
-
-        for (const cmdFile of commandFiles) {
-            if (cmdFile.endsWith('.md')) {
-                const sourcePath = path.join(commandsSourceDir, cmdFile);
-                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
-
-                const targetFileName = `specsmd-${prefix}${cmdFile}`;
-                const targetPath = path.join(targetCommandsDir, targetFileName);
-
-                // Extract agent name from target filename (e.g., "specsmd-master-agent.md" -> "specsmd-master-agent")
-                const agentName = targetFileName.replace(/\.md$/, '');
-
-                // Read source content and add Windsurf frontmatter
-                let content = await fs.readFile(sourcePath, 'utf8');
-
-                // Add Windsurf-specific frontmatter if not present
-                if (!content.startsWith('---')) {
-                    const frontmatter = `---
-description: ${agentName}
----
-
-`;
-                    content = frontmatter + content;
-                }
-
-                await fs.writeFile(targetPath, content);
-                installedFiles.push(targetFileName);
-            }
-        }
-
-        CLIUtils.displayStatus('', `Installed ${installedFiles.length} workflows for ${this.name}`, 'success');
-        return installedFiles;
-    }
 }
 
 module.exports = WindsurfInstaller;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.2",
+  "version": "0.0.0-dev.21",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {