specsmd 0.0.0-dev.3 → 0.0.0-dev.31

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`
@@ -25,7 +29,7 @@ You are now the **Construction Agent** for specsmd AI-DLC.
 1. **Read Schema**: `.specsmd/aidlc/memory-bank.yaml`
 2. **Verify Unit**: Check unit exists and has completed inception
 3. **Load Bolts**: Find bolts for this unit
-4. **Determine State**: Check which bolts are planned/in-progress/completed
+4. **Determine State**: Check which bolts are planned/in-progress/complete
 5. **Present Menu or Continue**: Show status or continue active bolt
 
 ---

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/flows/aidlc/memory-bank.yaml

@@ -81,13 +81,14 @@ schema:
   story-index: "memory-bank/story-index.md"
   inception-log: "memory-bank/intents/{intent-name}/inception-log.md"
   construction-log: "memory-bank/intents/{intent-name}/units/{unit-name}/construction-log.md"
+  decision-index: "memory-bank/standards/decision-index.md"
 
   # Agent Ownership
   # Note: Both Inception and Construction can plan/create bolts
   # Inception: initial planning, Construction: replanning during execution
   ownership:
     inception: [intents, units, stories, story-index, bolts]  # Plans bolts initially
-    construction: [units, bolts]                               # Executes and can replan bolts
+    construction: [units, bolts, decision-index]               # Executes, can replan bolts, maintains decision index
     operations: [operations]
 
 # Global Story Index Options

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-list.md

@@ -52,7 +52,7 @@ For each bolt, determine progress:
 
 - **planned**: 0% - Not started
 - **in-progress**: `stages_completed / total_stages`
-- **completed**: 100%
+- **complete**: 100%
 - **blocked**: Show blocker reason
 
 ### 5. Display Results

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/construction/bolt-status.md

@@ -81,7 +81,7 @@ Check for issues:
 - **Unit**: `{unit-name}`
 - **Intent**: `{intent-name}`
 - **Type**: {bolt-type}
-- **Status**: {planned|in-progress|completed|blocked}
+- **Status**: {planned|in-progress|complete|blocked}
 
 ### Progress
 [██████████░░░░░░░░░░] 50% (2/4 stages)

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/skills/master/analyze-context.md

@@ -53,7 +53,7 @@ For recent/active intents:
 Check `schema.bolts` directory:
 
 - Are there bolt instance files?
-- What is their status? (planned, in-progress, completed)
+- What is their status? (planned, in-progress, complete)
 - What stage are in-progress bolts at?
 
 ### 5. Determine Phase

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`, `complete`, `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
@@ -113,7 +134,7 @@ complexity:
 
 - **planned**: Bolt created, not started
 - **in-progress**: Currently being executed
-- **completed**: All stages done
+- **complete**: All stages done
 - **blocked**: Cannot proceed due to dependency
 
 ---

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

@@ -272,6 +272,7 @@ Suggest an ADR when you identify:
 3 - **Identify ADR-worthy decisions**: Create decision list
 4 - **Present opportunities to user**: Get user selection
 5 - **Create ADR documents**: Generate selected ADRs
+6 - **Update decision index**: Add entries to `memory-bank/standards/decision-index.md`
 
 **Artifact**: `adr-{number}-{slug}.md` (zero or more)
 **Template**: `.specsmd/aidlc/templates/construction/bolt-types/ddd-construction-bolt/adr-template.md`
@@ -282,7 +283,8 @@ Suggest an ADR when you identify:
 1. Review stories, domain model, and technical design
 2. Compare against loaded project standards
 3. If decision-worthy patterns detected, present opportunities to user
-4. Handle user response and proceed to checkpoint
+4. Handle user response (create selected ADRs or skip)
+5. Update decision index (if ADRs created) and proceed to checkpoint
 
 **Step 3 Output Format**:
 
@@ -299,10 +301,35 @@ Would you like to create ADRs for any of these? (Enter numbers, "all", or "skip"
 
 **Step 4 Decision Handling**:
 
-- **User selects numbers or "all"** → Generate ADRs using template, then proceed to checkpoint
+- **User selects numbers or "all"** → Generate ADRs using template, then update decision index
 - **User selects "skip"** → Proceed to checkpoint with "No ADRs created"
 - **No ADR opportunities identified** → Auto-proceed to checkpoint with "No ADR-worthy decisions found"
 
+**Step 5 Decision Index Update**:
+
+For each ADR created, add an entry to `memory-bank/standards/decision-index.md`:
+
+1. If `decision-index.md` doesn't exist, create it from template: `.specsmd/aidlc/templates/standards/decision-index-template.md`
+2. Add entry for each ADR in the following format:
+
+```markdown
+### ADR-{n}: {title}
+- **Status**: {status from ADR frontmatter}
+- **Date**: {YYYY-MM-DD from ADR created timestamp}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context section}. {First sentence from Decision section}.
+- **Read when**: {Generate guidance based on the ADR's domain - describe scenarios when agents should read this ADR}
+```
+
+3. Update frontmatter: increment `total_decisions`, update `last_updated` timestamp
+
+**"Read when" Guidance Examples**:
+- "Working on authentication flows or session management"
+- "Implementing caching strategies or data persistence patterns"
+- "Designing API contracts or integration points"
+- "Handling error cases or implementing retry logic"
+
 **Example ADR**:
 
 ```markdown
@@ -330,6 +357,7 @@ Implement CQRS pattern with separate read models for task queries.
 - [ ] Project standards compared
 - [ ] User presented with ADR opportunities (if any)
 - [ ] Selected ADRs created (or explicitly skipped)
+- [ ] Decision index updated (if ADRs were created)
 
 **Important**: Do not force ADRs. Only suggest when there's genuine value. Simple bolts with straightforward decisions don't need ADRs.
 
@@ -495,6 +523,34 @@ status: in-progress
 
 ## Bolt Context Loading
 
+### Prior Decision Lookup (All Stages)
+
+**Before starting any stage**, scan the decision index for relevant prior ADRs:
+
+1. Read `memory-bank/standards/decision-index.md` (if it exists)
+2. Match the current bolt's domain/scope against "Read when" fields
+3. Load full ADRs for any matching entries
+4. Consider these decisions as constraints or guidance for the current work
+
+**Example**: If working on a bolt for "user-service" and the decision index contains:
+```
+### ADR-001: Use JWT for Authentication
+- **Read when**: Working on authentication flows or user services
+```
+→ Load and consider `ADR-001` before starting design work.
+
+**Present relevant ADRs to user** at bolt start:
+```
+## Relevant Prior Decisions
+
+Found {n} ADR(s) that may apply to this bolt:
+- ADR-001: Use JWT for Authentication → [View](bolts/001-auth-service/adr-001-jwt-auth.md)
+
+These decisions may constrain or guide your approach. Proceed? (y/n)
+```
+
+### Bolt Folder Artifacts (Stages 4-5)
+
 For stages that build on previous work (Stage 4: Implement, Stage 5: Test), load all artifacts from the bolt folder:
 
 **Location**: `memory-bank/bolts/{bolt-id}/`
@@ -515,14 +571,16 @@ This ensures the implementation and test stages have full context from earlier d
 1. **Load bolt instance** from path defined by `schema.bolts`
 2. **Read `bolt_type` field** (e.g., `ddd-construction-bolt`)
 3. **Load this definition** from `.specsmd/aidlc/templates/construction/bolt-types/`
-4. **Check `current_stage`** in bolt instance
-5. **Load bolt folder artifacts** if stage requires previous context (see Bolt Context Loading)
-6. **Execute stage** following activities defined here
-7. **Create artifacts** using templates
-8. **⛔ STOP and present completion summary** - DO NOT continue automatically
-9. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
-10. **Only after approval**: Update bolt state and advance to next stage
-
-**⛔ CRITICAL**: Steps 8-9 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
+4. **Scan decision index** for relevant prior ADRs (see Prior Decision Lookup)
+5. **Present relevant ADRs** to user if any found, get confirmation to proceed
+6. **Check `current_stage`** in bolt instance
+7. **Load bolt folder artifacts** if stage requires previous context (see Bolt Folder Artifacts)
+8. **Execute stage** following activities defined here
+9. **Create artifacts** using templates
+10. **⛔ STOP and present completion summary** - DO NOT continue automatically
+11. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
+12. **Only after approval**: Update bolt state and advance to next stage
+
+**⛔ CRITICAL**: Steps 10-11 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
 
 The Construction Agent is **bolt-type agnostic** - it reads stages from this file and executes them.

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/flows/aidlc/templates/standards/decision-index-template.md

@@ -0,0 +1,32 @@
+---
+last_updated: {YYYY-MM-DDTHH:MM:SSZ}
+total_decisions: 0
+---
+
+# Decision Index
+
+This index tracks all Architecture Decision Records (ADRs) created during Construction bolts.
+Use this to find relevant prior decisions when working on related features.
+
+## How to Use
+
+**For Agents**: Scan the "Read when" fields below to identify decisions relevant to your current task. Before implementing new features, check if existing ADRs constrain or guide your approach. Load the full ADR for matching entries.
+
+**For Humans**: Browse decisions chronologically or search for keywords. Each entry links to the full ADR with complete context, alternatives considered, and consequences.
+
+---
+
+## Decisions
+
+<!-- Entries are appended below in reverse chronological order (newest first) -->
+<!-- Format for each entry:
+
+### ADR-{n}: {title}
+- **Status**: {proposed|accepted|deprecated|superseded}
+- **Date**: {YYYY-MM-DD}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context}. {First sentence from Decision}.
+- **Read when**: {Agent guidance - domain keywords and scenarios when this ADR is relevant}
+
+-->