specsmd 0.0.1

package/flows/aidlc/skills/construction/bolt-status.md

@@ -0,0 +1,185 @@
+# Skill: Bolt Status
+
+---
+
+## Role
+
+Informational skill to display detailed status of a specific bolt.
+
+**NO Checkpoint** - This is a read-only status skill, not a decision point.
+
+---
+
+## Goal
+
+Display detailed status of a specific bolt instance including stage progress, artifacts created, and blockers.
+
+---
+
+## Input
+
+- **Required**: `--bolt-id` - The bolt instance ID
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+
+---
+
+## Process
+
+### 1. Load Bolt File
+
+Read bolt file from path defined by `schema.bolts`:
+
+- Parse frontmatter for metadata
+- Extract: status, type, current_stage, stages_completed, stories
+
+### 2. Load Bolt Type Definition
+
+Read the bolt type from `.specsmd/aidlc/templates/construction/bolt-types/{bolt_type}.md`:
+
+- Get total stages for this bolt type
+- Get stage names and expected outputs
+
+### 3. Verify Artifacts
+
+For each completed stage, verify artifacts exist based on bolt type definition:
+
+- ✅ **{stage-1-name}**: `{artifact-from-bolt-type}` - Found
+- ✅ **{stage-2-name}**: `{artifact-from-bolt-type}` - Found
+- ⏳ **{current-stage}**: {expected-output} - In Progress
+
+*Note: Artifact names come from the bolt type definition, not hardcoded here.*
+
+### 4. Calculate Metrics
+
+```markdown
+### Progress Metrics
+- **Stages**: {completed}/{total} ({percentage}%)
+- **Stories**: {stories covered}
+- **Started**: {start date}
+- **Elapsed**: {time since start}
+```
+
+### 5. Identify Blockers
+
+Check for issues:
+
+- Missing prerequisite bolts
+- Failed tests
+- Unresolved design decisions
+- External dependencies
+
+---
+
+## Output
+
+```markdown
+## Bolt Status: {bolt-id}
+
+### Overview
+
+- **ID**: `{bolt-id}`
+- **Unit**: `{unit-name}`
+- **Intent**: `{intent-name}`
+- **Type**: {bolt-type}
+- **Status**: {planned|in-progress|completed|blocked}
+
+### Progress
+[██████████░░░░░░░░░░] 50% (2/4 stages)
+
+### Stage Breakdown
+
+- ✅ **1. {stage-1}**: Complete → `{artifact-1}`
+- ✅ **2. {stage-2}**: Complete → `{artifact-2}`
+- ⏳ **3. {stage-3}**: Current ← working
+- [ ] **4. {stage-4}**: Pending
+
+*Stage names and artifacts are read from the bolt type definition.*
+
+### Stories Covered
+
+- ✅ **{SSS}-{story-slug}**: {story-title} - Implemented
+- ⏳ **{SSS}-{story-slug}**: {story-title} - In Progress
+
+### Artifacts Created
+
+- `memory-bank/bolts/{bolt-id}/{artifact-1}` (from bolt type)
+- `memory-bank/bolts/{bolt-id}/{artifact-2}` (from bolt type)
+- `src/{unit}/...` (implementation files)
+
+### Current Stage Details
+**Stage**: {current_stage}
+**Activities**:
+- {activity 1}
+- {activity 2}
+
+**Expected Output**:
+- {output 1}
+
+### Blockers
+{None | List of blockers with details}
+
+### Next Action
+→ Continue with {current_stage} stage
+→ Command: `bolt-start --bolt-id="{bolt-id}"`
+```
+
+---
+
+## Output (Completed Bolt)
+
+```markdown
+## Bolt Status: {bolt-id}
+
+### Overview
+
+- **Status**: ✅ **COMPLETED**
+- **Completed**: {date}
+- **Duration**: {time}
+
+### All Stages Complete
+
+- ✅ **1. {stage-1}**: {date} → `{artifact-1}`
+- ✅ **2. {stage-2}**: {date} → `{artifact-2}`
+- ✅ **3. {stage-3}**: {date} → {output-3}
+- ✅ **4. {stage-4}**: {date} → {output-4}
+
+*Stage names and artifacts are read from the bolt type definition.*
+
+### Stories Delivered
+
+- ✅ **{SSS}-{story-slug}**: {story-title} - All criteria passed
+- ✅ **{SSS}-{story-slug}**: {story-title} - All criteria passed
+
+### Summary
+All {n} stories implemented and tested.
+
+### Next Action
+→ Start next bolt: `bolt-start --bolt-id="{next-bolt}"`
+→ Or proceed to Operations if all bolts complete
+```
+
+---
+
+## Human Validation Point
+
+> "Bolt `{bolt-id}` is {status}. {summary}. Would you like to continue working on it or view another bolt?"
+
+---
+
+## Transition
+
+After viewing status:
+
+- → **Bolt Start** (`.specsmd/skills/construction/bolt-start.md`) - continue the bolt
+- → **Bolt List** (`.specsmd/skills/construction/bolt-list.md`) - view other bolts
+- → **Operations Agent** - if all bolts for unit are complete
+
+---
+
+## Test Contract
+
+```yaml
+input: Bolt ID
+output: Detailed status with stage progress, artifacts, blockers
+checkpoints: 0 (informational only)
+```

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
+
+- [ ] `bolt-auth-1` (auth-service, DDD) - planned
+- [ ] `bolt-auth-2` (auth-service, DDD) - planned
+- [ ] `bolt-api-1` (api-gateway, BDD) - planned
+
+### Quick Actions
+
+1 - **Start bolt-auth-1**: Begin first bolt
+2 - **List all bolts**: View with details
+3 - **View bolt status**: Check specific bolt
+
+### Suggested Next Step
+→ Start construction with `bolt-auth-1`
+
+**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:
+
+- ✅ `bolt-{unit}-1` - Completed 2024-12-05 (3h)
+- ✅ `bolt-{unit}-2` - 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/inception/bolt-plan.md

@@ -0,0 +1,338 @@
+# Skill: Plan Bolts
+
+---
+
+## Progress Display
+
+Show at start of this skill:
+
+```text
+### Inception Progress
+- [x] Intent created
+- [x] Requirements gathered
+- [ ] Generating artifacts...  ← current
+    - [x] System Context
+    - [x] Units
+    - [x] Stories
+    - [ ] Bolt Plan  ← this skill
+- [ ] Artifacts reviewed (Checkpoint 3)
+- [ ] Ready for Construction
+```
+
+---
+
+## Checkpoints in This Skill
+
+**NO INDIVIDUAL Checkpoint** - This skill is part of the batched artifact generation.
+
+All artifacts (Context, Units, Stories, Bolts) are reviewed together at **Checkpoint 3** in the `review` skill.
+
+---
+
+## Goal
+
+Group User Stories into logical Bolts (execution sessions) that will guide the Construction Phase.
+
+---
+
+## Input
+
+- **Required**: Unit name
+- **Required**: `unit-brief.md` for the unit (contains `default_bolt_type` if specified)
+- **Required**: Stories for the unit (`stories/*.md`)
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Required**: `.specsmd/aidlc/templates/standards/catalog.yaml` - project type definitions
+
+---
+
+## Process
+
+### 1. Analyze Stories
+
+Review all stories to understand:
+
+- Dependencies between stories
+- Complexity and effort estimates
+- Logical groupings by domain/feature
+
+### 2. Determine Bolt Type
+
+**Read bolt type from unit-brief.md or use default based on unit type.**
+
+1. **Check unit-brief.md frontmatter** for `default_bolt_type`:
+   ```yaml
+   ---
+   unit: expense-tracker-ui
+   unit_type: frontend
+   default_bolt_type: simple-construction-bolt
+   ---
+   ```
+
+2. **If not specified**, use defaults based on unit type:
+   - `unit_type: frontend` → `simple-construction-bolt`
+   - `unit_type: cli` → `simple-construction-bolt`
+   - `unit_type: backend` or unspecified → `ddd-construction-bolt`
+
+3. **Bolt type templates** are located at:
+   `.specsmd/aidlc/templates/construction/bolt-types/{bolt-type}.md`
+
+**Available bolt types**:
+- `ddd-construction-bolt` - For domain-heavy backend work (5 stages)
+- `simple-construction-bolt` - For UI, integrations, utilities (3 stages)
+- `spike-bolt` - For research and exploration
+
+### 3. Assess Story Complexity
+
+For each story, evaluate these factors:
+
+| Factor | Question | Low (1) | Medium (2) | High (3) |
+|--------|----------|---------|------------|----------|
+| **Complexity** | How intricate is the logic? | CRUD, known patterns | Business rules, validation | Novel algorithms, complex logic |
+| **Uncertainty** | How clear are requirements? | Fully specified | Some ambiguity | Many unknowns (→ spike) |
+| **Dependencies** | What external things does it need? | Self-contained | Internal APIs/units | External systems, 3rd party |
+| **Testing** | What validation is needed? | Unit tests | Integration tests | E2E + manual validation |
+
+### 4. Group Stories into Bolts
+
+**Grouping rules:**
+
+1. **Cohesion**: Stories for same domain concept → same bolt
+2. **Dependencies**: Story A needs Story B → same or adjacent bolt
+3. **Balance**: Mix high + low complexity stories
+4. **Limit**: Max 5-6 stories per bolt
+5. **Risk**: Any story with High (3) Uncertainty → spike bolt first
+
+**Suggested groupings:**
+
+- **Bolt 1**: Setup & Core Entities (foundational stories)
+- **Bolt 2**: Primary Operations (main CRUD/business logic)
+- **Bolt 3**: Integration & Edge Cases (advanced stories)
+
+### 5. Analyze Dependencies
+
+**CRITICAL**: Before defining sequence, analyze ALL dependencies:
+
+#### 5a. Story Dependencies (within bolt)
+
+For each story, check:
+
+- Does it depend on another story's output?
+- Does it require data/models from another story?
+
+#### 5b. Bolt Dependencies (within unit)
+
+For each bolt, determine:
+
+- `requires_bolts`: Which bolts must complete first?
+- `enables_bolts`: Which bolts are waiting on this one?
+
+#### 5c. Unit Dependencies (cross-unit)
+
+For each bolt, check if it depends on another unit:
+
+- `requires_units`: Which units must be complete?
+- Example: `api-bolt-1` may require `auth-service` unit to be complete
+
+**Dependency Analysis Output**:
+
+```markdown
+## Dependency Analysis
+
+### Within-Unit Dependencies
+
+- **bolt-auth-2** requires bolt-auth-1 (Needs User entity)
+- **bolt-auth-3** requires bolt-auth-2 (Needs Auth service)
+
+### Cross-Unit Dependencies
+
+- **bolt-api-1** requires auth-service unit (Needs auth tokens)
+- **bolt-payment-1** requires user-service unit (Needs user data)
+
+### Dependency Warnings
+- ⚠️ bolt-api-1 blocked until auth-service unit complete
+- ⚠️ Circular dependency detected: {if any}
+```
+
+### 6. Define Bolt Sequence
+
+Establish execution order based on dependencies:
+
+```markdown
+## Bolt Sequence
+
+```text
+
+[Bolt 1] ──► [Bolt 2] ──► [Bolt 3]
+   │            │
+   ▼            ▼
+ Entity      API Layer
+ Setup       Implementation
+
+```
+
+## Cross-Unit Dependencies
+
+```text
+
+[auth-service] ──► [api-service]
+                        │
+                        ▼
+                   [payment-service]
+
+```
+
+### 7. Create Bolt Instance Files (CRITICAL)
+
+**⚠️ YOU MUST CREATE INDIVIDUAL BOLT DIRECTORIES WITH bolt.md FILES**
+**⚠️ DO NOT CREATE A SUMMARY DOCUMENT CALLED "bolt-plan.md"**
+
+1. **Read Path**: Check `schema.bolts` from `.specsmd/aidlc/memory-bank.yaml`
+   *(Default: `memory-bank/bolts/{bolt-id}/`)*
+
+2. **Create Directory + File Per Bolt**:
+   For EACH bolt in the plan:
+   - Create directory: `memory-bank/bolts/bolt-{unit}-{N}/`
+   - Create file inside: `memory-bank/bolts/bolt-{unit}-{N}/bolt.md`
+   - Use template: `.specsmd/aidlc/templates/construction/bolt-template.md`
+
+   **Example**: If planning 3 bolts for auth unit, CREATE THESE:
+
+   ```text
+   memory-bank/bolts/bolt-auth-1/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+   memory-bank/bolts/bolt-auth-2/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+   memory-bank/bolts/bolt-auth-3/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+   ```
+
+   **Stage artifacts will be added to same directory during construction:**
+
+   ```text
+   memory-bank/bolts/bolt-auth-1/
+   ├── bolt.md                      ← You create this now
+   └── {stage-artifacts}            ← Created during construction (varies by bolt type)
+   ```
+
+   *Note: Artifact names depend on bolt type (e.g., DDD bolts create `ddd-01-domain-model.md`, simple bolts create `spec.md`).*
+
+3. **Bolt File Structure** (CRITICAL: Include all dependencies in frontmatter):
+
+   ```markdown
+   ---
+   id: bolt-{unit}-{sequence}
+   unit: {unit-name}
+   intent: {intent-name}
+   type: {bolt-type}  # From unit-brief.md or default (ddd-construction-bolt, simple-construction-bolt)
+   status: planned
+   stories: [story-1, story-2]
+   created: {date}
+
+   # Dependency Tracking (REQUIRED)
+   requires_bolts: [bolt-auth-1]           # Bolts that must complete first
+   enables_bolts: [bolt-auth-3, bolt-api-1] # Bolts that depend on this
+   requires_units: [auth-service]           # Units that must be complete
+   blocks: false                            # true if waiting on dependency
+
+   # Complexity Assessment (aggregate of included stories)
+   complexity:
+     avg_complexity: 2        # 1=Low, 2=Medium, 3=High
+     avg_uncertainty: 1       # 1=Low, 2=Medium, 3=High
+     max_dependencies: 2      # Highest dependency score among stories
+     testing_scope: 2         # 1=Unit, 2=Integration, 3=E2E
+   ---
+
+   ## Bolt: {bolt-id}
+
+   ### Objective
+   {What this bolt will accomplish}
+
+   ### Stories Included
+
+   - [ ] **{story-id}**: {description} - Priority: {priority}
+
+   ### Expected Outputs
+   - {artifact 1}
+   - {artifact 2}
+
+   ### Dependencies
+
+   #### Bolt Dependencies (within intent)
+
+   - **bolt-auth-1** (Required): Completed
+   - **bolt-auth-2** (Optional): In Progress
+
+   #### Unit Dependencies (cross-unit)
+
+   - **auth-service**: Needs auth tokens - Completed
+
+   #### Enables (other bolts waiting on this)
+   - bolt-auth-3
+   - bolt-api-1
+   ```
+
+### 8. Validate Plan
+
+Check the plan against:
+
+- [ ] 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
+- [ ] Cross-unit dependencies are explicit
+
+---
+
+## Output
+
+### Directories & Files Created (REQUIRED)
+
+**⚠️ YOU MUST CREATE THESE DIRECTORIES AND FILES:**
+
+```text
+memory-bank/bolts/bolt-{unit}-1/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+memory-bank/bolts/bolt-{unit}-2/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+memory-bank/bolts/bolt-{unit}-3/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+```
+
+**⚠️ DO NOT CREATE:**
+
+- `bolt-plan.md` (summary doc)
+- `README.md` files
+- Flat files like `bolt-{unit}-1.md`
+
+### Summary (displayed to user)
+
+```markdown
+## Bolt Plan Complete: {unit-name}
+
+### Bolts Created
+
+- [ ] **bolt-{unit}-1** ({bolt-type}): 001-user-signup, 002-user-login
+- [ ] **bolt-{unit}-2** ({bolt-type}): 003-password-reset, 004-email-verify
+- [ ] **bolt-{unit}-3** ({bolt-type}): 005-mfa-setup
+
+### Dependency Graph
+bolt-{unit}-1 ──► bolt-{unit}-2 ──► bolt-{unit}-3
+
+### Directories Created
+✅ `memory-bank/bolts/bolt-{unit}-1/bolt.md`
+✅ `memory-bank/bolts/bolt-{unit}-2/bolt.md`
+✅ `memory-bank/bolts/bolt-{unit}-3/bolt.md`
+
+### Total
+- {n} bolts created
+- {n} stories covered
+```
+
+**No menu** - Skill complete, return to agent.
+
+---
+
+## Test Contract
+
+```yaml
+input: Stories for unit
+output: Bolt directories with bolt.md files
+checkpoints: 0 (part of Checkpoint 3 batch)
+```