@ydtb/specsmd 0.1.22

package/flows/aidlc/skills/construction/navigator.md

@@ -0,0 +1,196 @@
+# Skill: Construction Navigator
+
+---
+
+## Role
+
+Entry point for Construction Agent. Routes to appropriate skill based on state.
+
+**NO Checkpoint** - Navigator is a routing skill, not a decision point.
+
+---
+
+## Progress Display
+
+Show workflow position with checkpoint markers:
+
+```text
+### Construction Workflow (2 Checkpoints per Bolt)
+
+[Checkpoint 1] Which bolt to work on? --> bolt-list skill
+      |
+[Domain + Logical Design]
+      |
+[Checkpoint 2] Design Review --> bolt-start skill
+      |
+[Code + Tests] --> Auto-validate if tests pass
+      |
+[What's Next?] --> Next bolt / Done
+```
+
+---
+
+## Goal
+
+Present the Construction Agent's skills and guide the user to the appropriate next action.
+
+---
+
+## Input
+
+- **Optional**: `--unit` - Current unit context
+- **Optional**: `--bolt-id` - Current bolt context
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Determine Context
+
+Load current construction state:
+
+- Check for in-progress bolts
+- Identify which units have planned bolts
+- Calculate overall construction progress
+
+### 2. Present Menu
+
+```markdown
+## Construction Agent
+
+{Context section if bolt/unit is active}
+
+### Skills
+
+1 - **List Bolts**: View all bolts and status (`bolt-list`)
+2 - **Bolt Status**: Detailed status of a bolt (`bolt-status --bolt-id="{id}"`)
+3 - **Start/Continue Bolt**: Execute bolt stages (`bolt-start --bolt-id="{id}"`)
+4 - **Plan Bolts**: Plan new bolts → Inception (`bolt-plan --unit="{unit}"`)
+
+### Current State
+{Show in-progress bolts and overall progress}
+
+### Suggested Next Step
+→ {Recommended action based on state}
+
+**Type a number (1-4) or specify a bolt ID to work on.**
+```
+
+### 3. Context-Aware Suggestions
+
+Based on construction state, suggest actions:
+
+- **No bolts planned** → Redirect to Inception for planning
+- **Bolts planned, none started** → Start first bolt
+- **Bolt in-progress** → Continue current bolt
+- **Bolt blocked** → Show blocker, suggest resolution
+- **All bolts complete for unit** → Proceed to Operations
+
+### 4. Handle Selection
+
+When user selects an option:
+
+1. Acknowledge the selection
+2. Load the corresponding skill file
+3. Execute with current context
+
+---
+
+## Output (With Active Bolt)
+
+```markdown
+## Construction Agent
+
+### Active Bolt: `{bolt-id}`
+**Unit**: `{unit-name}`
+**Type**: {bolt-type}
+**Stage**: {current_stage} ({n}/{total})
+
+### Progress
+[████████████░░░░░░░░] 60% (3/5 stages)
+
+### Quick Actions
+
+1 - **Continue Current Bolt**: Resume work (`bolt-start --bolt-id="{bolt-id}"`)
+2 - **View Bolt Status**: Detailed status (`bolt-status --bolt-id="{bolt-id}"`)
+3 - **List All Bolts**: See all bolts (`bolt-list`)
+4 - **Switch Bolt**: Select a different bolt
+
+### Suggested Next Step
+→ Continue working on `{bolt-id}` - currently at {stage} stage
+
+**Press Enter to continue or type a number.**
+```
+
+---
+
+## Output (No Active Bolt)
+
+```markdown
+## Construction Agent
+
+### No Active Bolt
+
+### Available Bolts
+
+- [ ] `001-auth-service` (auth-service, DDD) - planned
+- [ ] `002-auth-service` (auth-service, DDD) - planned
+- [ ] `003-api-gateway` (api-gateway, Simple) - planned
+
+### Quick Actions
+
+1 - **Start 001-auth-service**: Begin first bolt
+2 - **List all bolts**: View with details
+3 - **View bolt status**: Check specific bolt
+
+### Suggested Next Step
+→ Start construction with `001-auth-service`
+
+**Type a number or enter a bolt ID.**
+```
+
+---
+
+## Output (All Bolts Complete)
+
+```markdown
+## Construction Agent
+
+### Construction Complete for Unit: `{unit-name}`
+
+All {n} bolts have been completed:
+
+- ✅ `001-{unit-name}` - Completed 2024-12-05 (3h)
+- ✅ `005-{unit-name}` - Completed 2024-12-06 (4h)
+
+### Summary
+- Stories delivered: {n}
+- Tests passing: ✅
+- Ready for deployment
+
+### Next Step
+→ Proceed to Operations: `/specsmd-operations-agent --unit="{unit}"`
+
+Or work on another unit's bolts.
+```
+
+---
+
+## Transition
+
+After user selection:
+
+- → Load selected skill
+- → Skill contains the Checkpoint markers
+- → Execute skill process
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit/bolt state (optional)
+output: Menu with skill options, suggested next step
+checkpoints: 0 (routing only)
+```

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
+```