specsmd 0.0.0-dev.8 → 0.0.0-dev.80

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

@@ -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.cjs 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.cjs 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
@@ -563,7 +594,7 @@ const lastStage = process.argv['--last-stage'] || null;
 
 if (!boltId) {
     console.error(`${colors.red}Error:${colors.reset} Bolt ID required`);
-    console.error(`${colors.dim}Usage: node bolt-complete.js <bolt-id> [--last-stage <stage-name>]${colors.reset}`);
+    console.error(`${colors.dim}Usage: node bolt-complete.cjs <bolt-id> [--last-stage <stage-name>]${colors.reset}`);
     process.exit(1);
 }
 

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

@@ -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.cjs
+ *   node .specsmd/aidlc/scripts/status-integrity.cjs --fix
  *
  * Cross-platform: Works on Linux, macOS, Windows via Node.js
  */
@@ -577,15 +577,15 @@ const shouldFix = args.includes('--fix') || args.includes('-f');
 
 if (args.includes('--help') || args.includes('-h')) {
     console.log(`
-Usage: node status-integrity.js [options]
+Usage: node status-integrity.cjs [options]
 
 Options:
   --fix, -f    Automatically fix status inconsistencies
   --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.cjs
+  node .specsmd/aidlc/scripts/status-integrity.cjs --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.cjs │
 │  → Do NOT manually edit story files                        │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -235,7 +235,7 @@ stages_completed:
 ⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 You CANNOT report bolt completion without:
-1. Running the bolt-complete.js script
+1. Running the bolt-complete.cjs script
 2. Showing the script output to the user
 
 If you skip this, the memory-bank becomes inconsistent.
@@ -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.cjs {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,311 @@
+# 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

@@ -290,6 +290,7 @@ 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
@@ -302,6 +303,7 @@ Check the plan against:
 - [ ] `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)
 - [ ] Each bolt has clear outputs