specsmd 0.0.0-dev.4 → 0.0.0-dev.41

package/flows/aidlc/skills/inception/vibe-to-spec.md

@@ -0,0 +1,406 @@
+# Skill: Vibe to Spec
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [ ] Prototype analyzed  ← current
+- [ ] Design system extracted
+- [ ] Components cataloged
+- [ ] Requirements derived
+- [ ] Ready for standard inception flow
+```
+
+---
+
+## Checkpoints in This Skill
+
+| Checkpoint | Purpose | Wait For |
+|------------|---------|----------|
+| Checkpoint 1 | Prototype inventory review | User confirmation |
+| Checkpoint 2 | Design system approval | User approval |
+| Checkpoint 3 | Derived requirements review | User approval |
+
+---
+
+## Goal
+
+Convert a vibe-coded prototype (screenshots, HTML exports, or design mockups) into formal specsmd artifacts that feed into the standard inception workflow.
+
+---
+
+## Input
+
+- **Required**: Path to prototype folder (e.g., `proto/`, `mockups/`, `discovery/`)
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: Intent name to associate with (creates new if not provided)
+- **Optional**: Existing design system to extend
+
+**Supported Prototype Formats**:
+- PNG/JPG screenshots
+- HTML exports (with associated CSS/JS in `_files` folders)
+- Figma exports
+- PDF mockups
+
+---
+
+## Process
+
+### Step 1: Inventory Prototype Assets
+
+Scan the prototype folder and catalog all assets:
+
+```text
+## Prototype Inventory
+
+Scanning: {prototype-path}
+
+### Screenshots Found
+- {filename}.png - {brief description based on visual analysis}
+- ...
+
+### HTML Exports Found
+- {filename}.html - {title or main heading}
+- ...
+
+### Asset Folders
+- {filename}_files/ - CSS, JS, images
+- ...
+
+Total: {n} screens identified
+```
+
+**Checkpoint 1**: Present inventory for user confirmation.
+
+```text
+I found {n} screens in your prototype. Here's what I see:
+
+1. {screen-1-description}
+2. {screen-2-description}
+...
+
+Is this complete? Are there screens I'm missing or misinterpreting?
+1 - Yes, continue analysis
+2 - Let me clarify (provide corrections)
+```
+
+**Wait for user response.**
+
+---
+
+### Step 2: Analyze Each Screen
+
+For each screen, extract:
+
+**Visual Analysis** (use image analysis capabilities):
+- Layout structure (sidebar, main content, header, footer)
+- Color palette (primary, secondary, accent, background)
+- Typography (headings, body text, labels)
+- Component patterns (buttons, inputs, cards, lists)
+- Interactive elements (forms, menus, modals)
+
+**HTML Analysis** (if available):
+- Component structure from markup
+- CSS classes and styling patterns
+- JavaScript interactions
+
+**Output per screen**:
+```markdown
+### Screen: {screen-name}
+**Source**: {filename}
+**Purpose**: {inferred purpose}
+
+#### Layout
+- Structure: {e.g., sidebar-main, header-content-footer}
+- Responsive hints: {any visible breakpoint patterns}
+
+#### Components Identified
+- [ ] {component-1}: {description}
+- [ ] {component-2}: {description}
+
+#### Interactions
+- {interaction-1}: {trigger} → {result}
+
+#### Design Tokens
+- Primary color: {hex}
+- Text color: {hex}
+- Background: {hex}
+- Border radius: {px}
+- Spacing unit: {px}
+```
+
+---
+
+### Step 3: Synthesize Design System
+
+Combine analysis from all screens into a unified design system:
+
+```markdown
+## Design System: {prototype-name}
+
+### Color Palette
+| Token | Value | Usage |
+|-------|-------|-------|
+| primary | {hex} | Buttons, links, accents |
+| secondary | {hex} | Secondary actions |
+| background | {hex} | Page background |
+| surface | {hex} | Card backgrounds |
+| text-primary | {hex} | Main text |
+| text-secondary | {hex} | Muted text |
+| border | {hex} | Borders, dividers |
+| success | {hex} | Success states |
+| error | {hex} | Error states |
+
+### Typography
+| Element | Font | Size | Weight |
+|---------|------|------|--------|
+| h1 | {font} | {size} | {weight} |
+| h2 | {font} | {size} | {weight} |
+| body | {font} | {size} | {weight} |
+| label | {font} | {size} | {weight} |
+| caption | {font} | {size} | {weight} |
+
+### Spacing Scale
+- xs: {px}
+- sm: {px}
+- md: {px}
+- lg: {px}
+- xl: {px}
+
+### Border Radius
+- sm: {px}
+- md: {px}
+- lg: {px}
+- full: 9999px
+
+### Shadows
+- sm: {shadow}
+- md: {shadow}
+- lg: {shadow}
+
+### Component Patterns
+{list of reusable patterns identified}
+```
+
+**Checkpoint 2**: Present design system for approval.
+
+```text
+### Design System Review
+
+I've extracted the following design system from your prototype:
+
+{full design system}
+
+Does this accurately capture your prototype's visual language?
+1 - Yes, continue to derive requirements
+2 - Need adjustments (specify what's wrong)
+```
+
+**Wait for user response.**
+
+---
+
+### Step 4: Catalog Components
+
+Create a component catalog from the prototype:
+
+```markdown
+## Component Catalog: {prototype-name}
+
+### Navigation Components
+- **Sidebar**: {description, screens where found}
+- **Header**: {description}
+- **Breadcrumb**: {description}
+
+### Form Components
+- **Text Input**: {variants, validation states}
+- **Button**: {variants: primary, secondary, ghost}
+- **Select/Dropdown**: {description}
+- **Checkbox/Radio**: {description}
+
+### Display Components
+- **Card**: {variants}
+- **List**: {variants}
+- **Table**: {if present}
+- **Modal/Dialog**: {if present}
+
+### Feedback Components
+- **Toast/Notification**: {if present}
+- **Loading States**: {spinners, skeletons}
+- **Empty States**: {if present}
+- **Error States**: {if present}
+
+### Layout Components
+- **Container**: {max-width, padding}
+- **Grid**: {columns, gaps}
+- **Stack**: {spacing patterns}
+```
+
+---
+
+### Step 5: Map User Flows
+
+Identify user flows from screen sequences:
+
+```markdown
+## User Flows
+
+### Flow 1: {flow-name}
+**Screens**: {screen-1} → {screen-2} → {screen-3}
+**Goal**: {what user accomplishes}
+**Steps**:
+1. User sees {screen-1}, {action}
+2. System shows {screen-2}
+3. User {action}
+4. System {result}
+
+### Flow 2: {flow-name}
+...
+```
+
+---
+
+### Step 6: Derive Requirements
+
+Transform visual analysis into formal requirements:
+
+```markdown
+## Derived Requirements
+
+### Functional Requirements (from prototype)
+
+#### FR-P1: {Component/Feature Name}
+- **Source**: {screenshot reference}
+- **Description**: {what it does based on visual}
+- **Acceptance Criteria**:
+  - [ ] {visual criterion 1}
+  - [ ] {visual criterion 2}
+- **Components**: {list of components needed}
+- **Priority**: {inferred from prominence}
+
+#### FR-P2: {Component/Feature Name}
+...
+
+### Non-Functional Requirements (inferred)
+
+#### NFR-P1: Visual Consistency
+- Design system must be applied consistently
+- All components follow extracted patterns
+
+#### NFR-P2: Responsive Design
+- {any responsive hints from prototype}
+
+### Open Questions
+- {things that aren't clear from prototype}
+- {interactions that need clarification}
+```
+
+**Checkpoint 3**: Present derived requirements.
+
+```text
+### Derived Requirements Review
+
+Based on your prototype, I've derived these requirements:
+
+{full requirements list}
+
+### Open Questions
+{list of clarifications needed}
+
+How should we proceed?
+1 - Requirements look good, create intent and continue inception
+2 - Need to adjust requirements
+3 - Answer open questions first
+```
+
+**Wait for user response.**
+
+---
+
+## Output
+
+### Artifacts Created
+
+Save to `memory-bank/prototypes/{prototype-name}/`:
+
+1. **screen-inventory.md** - Catalog of all screens
+2. **design-system.md** - Extracted design tokens and patterns
+3. **component-catalog.md** - Component inventory
+4. **user-flows.md** - Identified user flows
+5. **derived-requirements.md** - Requirements ready for inception
+
+### Summary Output
+
+```markdown
+## Vibe-to-Spec Complete: {prototype-name}
+
+### Prototype Analysis
+- **Screens analyzed**: {n}
+- **Components identified**: {n}
+- **User flows mapped**: {n}
+- **Requirements derived**: {n}
+
+### Artifacts Created
+- `memory-bank/prototypes/{name}/screen-inventory.md`
+- `memory-bank/prototypes/{name}/design-system.md`
+- `memory-bank/prototypes/{name}/component-catalog.md`
+- `memory-bank/prototypes/{name}/user-flows.md`
+- `memory-bank/prototypes/{name}/derived-requirements.md`
+
+### Next Steps
+
+1 - **intent-create**: Create intent using derived requirements
+2 - **requirements**: Refine requirements with standard flow
+3 - **review**: Review all prototype artifacts
+
+### Suggested Next Step
+→ **intent-create** - Create intent "{suggested-name}" from prototype
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Integration with Inception Flow
+
+After vibe-to-spec completes:
+
+1. **intent-create** can reference `derived-requirements.md`
+2. **requirements** skill can import and refine FR-P* items
+3. **context** skill can use component catalog for system boundaries
+4. **units** skill can organize by identified flows
+5. **stories** skill can generate from user flow mapping
+
+---
+
+## Construction Phase Reference
+
+When Construction Agent starts a bolt that references this prototype:
+
+1. Load `design-system.md` for styling decisions
+2. Reference `component-catalog.md` for component specs
+3. Use screenshots as visual acceptance criteria
+4. Apply extracted design tokens to implementation
+5. **Use frontend-design skill if available** - When implementing UI components, invoke the `/frontend-design` skill for high-quality, production-grade frontend code that avoids generic AI aesthetics
+
+---
+
+## Test Contract
+
+```yaml
+input: Prototype folder with screenshots/HTML
+output:
+  - screen-inventory.md
+  - design-system.md
+  - component-catalog.md
+  - user-flows.md
+  - derived-requirements.md
+checkpoints: 3
+  - Checkpoint 1: Prototype inventory confirmed
+  - Checkpoint 2: Design system approved
+  - Checkpoint 3: Derived requirements approved
+```

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,36 @@ 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}
+```
+
+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 +358,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 +524,37 @@ 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:
+
+```text
+### 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:
+
+```text
+## 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 +575,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}
+
+-->