specsmd 0.0.0-dev.5 → 0.0.0-dev.50

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

@@ -194,7 +194,7 @@ If the bolt type specifies automatic validation criteria, follow those rules.
 ┌─────────────────────────────────────────────────────────────┐
 │  FINAL STAGE DETECTED                                       │
 │  → Re-read Step 10 NOW                                     │
-│  → You MUST run: node .specsmd/scripts/bolt-complete.js    │
+│  → You MUST run: node .specsmd/aidlc/scripts/bolt-complete.js │
 │  → Do NOT manually edit story files                        │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -245,7 +245,7 @@ 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/construction/prototype-apply.md

@@ -0,0 +1,305 @@
+# Skill: Prototype Apply
+
+---
+
+## Goal
+
+Apply a vibe-coded prototype's design and components to the real implementation during bolt execution. This skill bridges the gap between extracted prototype specifications and production code.
+
+---
+
+## When to Use
+
+Use this skill when:
+- A bolt references a prototype in its scope
+- You need to implement UI that matches a prototype screenshot
+- The design system from vibe-to-spec should be applied to code
+- Visual acceptance criteria reference prototype screens
+
+---
+
+## Input
+
+- **Required**: Bolt ID currently being executed
+- **Required**: Prototype reference (path or name)
+- **Optional**: Specific screen to implement
+- **Optional**: Component to focus on
+
+**Prerequisite**: The **vibe-to-spec** skill must have been run on this prototype during Inception.
+
+---
+
+## Process
+
+### Step 1: Load Prototype Context
+
+Load all relevant prototype artifacts:
+
+```text
+## Loading Prototype Context
+
+Prototype: {prototype-name}
+Bolt: {bolt-id}
+
+### Available Artifacts
+- [ ] design-system.md - {loaded/not found}
+- [ ] component-catalog.md - {loaded/not found}
+- [ ] screen-inventory.md - {loaded/not found}
+- [ ] user-flows.md - {loaded/not found}
+
+### Bolt Scope Match
+Matching prototype screens to bolt scope:
+- {screen-1} → {story-1}
+- {screen-2} → {story-2}
+```
+
+---
+
+### Step 2: Extract Implementation Requirements
+
+From the prototype artifacts, extract what needs to be built:
+
+```markdown
+## Implementation Requirements
+
+### Screen: {screen-name}
+**Prototype Source**: {screenshot-path}
+**Target Location**: {src/path/to/component}
+
+### Design Tokens to Apply
+```typescript
+// From prototype design-system.md
+const tokens = {
+  colors: {
+    primary: '{hex}',
+    secondary: '{hex}',
+    background: '{hex}',
+    // ...
+  },
+  typography: {
+    fontFamily: '{font}',
+    // ...
+  },
+  spacing: {
+    xs: '{px}',
+    // ...
+  }
+}
+```
+
+### Components to Implement
+| Component | Prototype Ref | Target File | Status |
+|-----------|---------------|-------------|--------|
+| {Sidebar} | screen-2.png | Sidebar.tsx | pending |
+| {ChatList} | screen-2.png | ChatList.tsx | pending |
+| {MessageBubble} | screen-3.png | MessageBubble.tsx | pending |
+
+### Layout Structure
+```
+{ASCII representation of layout from prototype}
+┌─────────────────────────────────────────┐
+│ Header                                  │
+├──────────┬──────────────────────────────┤
+│ Sidebar  │ Main Content                 │
+│          │                              │
+│          │                              │
+├──────────┴──────────────────────────────┤
+│ Footer / Input Area                     │
+└─────────────────────────────────────────┘
+```
+```
+
+---
+
+### Step 3: Map to Project Standards
+
+Cross-reference with project standards:
+
+```markdown
+## Standards Alignment
+
+### Tech Stack Match
+- **Prototype suggests**: {vanilla CSS / Tailwind / etc.}
+- **Project standard**: {from tech-stack.md}
+- **Action**: {adapt prototype to use project's styling approach}
+
+### Component Library Match
+- **Prototype components**: {custom / Bootstrap / etc.}
+- **Project standard**: {from tech-stack.md}
+- **Action**: {map prototype components to project's component library}
+
+### Coding Standards
+- **File naming**: {from coding-standards.md}
+- **Component structure**: {from coding-standards.md}
+```
+
+---
+
+### Step 4: Generate Implementation Code
+
+Generate code that matches the prototype while following project standards.
+
+**IMPORTANT**: If the `/frontend-design` skill is available, invoke it for high-quality, production-grade frontend code that avoids generic AI aesthetics. The frontend-design skill specializes in creating distinctive, polished UI components.
+
+**For each component**:
+
+1. **Analyze prototype visually** (use screenshot)
+2. **Extract structure from HTML** (if available)
+3. **Apply project's styling approach**
+4. **Ensure accessibility**
+5. **Add responsive behavior**
+
+```typescript
+// Example output structure
+/**
+ * Component: {ComponentName}
+ * Prototype: {screenshot-reference}
+ *
+ * Visual acceptance criteria:
+ * - {criterion from prototype}
+ * - {criterion from prototype}
+ */
+export function ComponentName({ props }: Props) {
+  // Implementation matching prototype
+}
+```
+
+---
+
+### Step 5: Visual Verification Checklist
+
+Create a verification checklist comparing implementation to prototype:
+
+```markdown
+## Visual Verification: {screen-name}
+
+### Layout
+- [ ] Overall structure matches prototype
+- [ ] Spacing between elements is consistent
+- [ ] Responsive breakpoints work correctly
+
+### Colors
+- [ ] Primary color matches: {hex}
+- [ ] Background color matches: {hex}
+- [ ] Text colors match design system
+
+### Typography
+- [ ] Font family applied correctly
+- [ ] Font sizes match design system
+- [ ] Font weights are correct
+
+### Components
+- [ ] {Component-1} matches prototype
+- [ ] {Component-2} matches prototype
+- [ ] Interactive states (hover, focus, active) implemented
+
+### Interactions
+- [ ] {Interaction-1} works as shown in flow
+- [ ] {Interaction-2} works as shown in flow
+
+### Screenshots for Comparison
+- Prototype: `{prototype-path}`
+- Implementation: `{screenshot after implementation}`
+```
+
+---
+
+## Output
+
+### Implementation Summary
+
+```markdown
+## Prototype Applied: {screen-name}
+
+### Components Implemented
+| Component | File | Lines | Status |
+|-----------|------|-------|--------|
+| {Sidebar} | src/components/Sidebar.tsx | 45-120 | complete |
+| {ChatList} | src/components/ChatList.tsx | 1-80 | complete |
+
+### Design System Applied
+- Color tokens: {n} applied
+- Typography: {n} styles applied
+- Spacing: {n} values applied
+
+### Deviations from Prototype
+| Aspect | Prototype | Implementation | Reason |
+|--------|-----------|----------------|--------|
+| {color} | #xxx | #yyy | Project standard |
+| {font} | Inter | system-ui | Performance |
+
+### Visual Verification
+- [ ] Side-by-side comparison reviewed
+- [ ] Responsive behavior verified
+- [ ] Accessibility checked
+
+### Files Modified
+- `{file-1}` - {description}
+- `{file-2}` - {description}
+
+### Next Steps
+1 - Continue with next screen
+2 - Run visual regression tests
+3 - Review with stakeholder
+```
+
+---
+
+## Integration with Bolt Workflow
+
+### During DDD Construction Bolt
+
+In the **Implement** stage:
+1. Load prototype context for relevant screens
+2. Generate components matching prototype
+3. Apply design system tokens
+4. Create visual verification checklist
+
+### During Simple Construction Bolt
+
+In the **Implement** stage:
+1. Reference prototype for UI components
+2. Use extracted design tokens
+3. Follow component catalog structure
+
+---
+
+## Visual Diff Support
+
+When available, use UI diff tools to compare:
+
+```text
+## Visual Diff Report
+
+### Screen: {screen-name}
+- Prototype: {prototype-screenshot}
+- Implementation: {current-screenshot}
+- Diff: {highlighted differences}
+
+### Discrepancies Found
+1. {location}: {expected} vs {actual}
+2. {location}: {expected} vs {actual}
+
+### Action Required
+- [ ] Fix discrepancy 1
+- [ ] Fix discrepancy 2
+- [ ] Accept as intentional deviation
+```
+
+---
+
+## Test Contract
+
+```yaml
+input:
+  - Bolt ID with prototype reference
+  - Prototype artifacts from vibe-to-spec
+output:
+  - Implementation code matching prototype
+  - Visual verification checklist
+  - Deviation documentation
+integration:
+  - Works within bolt execution flow
+  - References design-system.md
+  - Follows project standards
+```

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