specsmd 0.0.1

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

@@ -0,0 +1,343 @@
+# Skill: Replan Bolts (Construction Context)
+
+---
+
+## Role
+
+Utility skill to modify bolt plans during Construction - add, split, or reorder bolts.
+
+**NO Checkpoint** - Replanning is a utility operation. Changes are validated through normal bolt execution checkpoints.
+
+---
+
+## Goal
+
+Replan bolts during Construction phase - add new bolts, split existing ones, or reorder based on learnings during execution.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to replan bolts for
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--action` - One of: `status`, `append`, `split`, `reorder`
+
+---
+
+## Process
+
+### 1. Read Existing Bolts
+
+**CRITICAL**: Always start by reading all existing bolts for the unit.
+
+```markdown
+## Current Bolt Status: {unit-name}
+
+- ✅ **bolt-auth-service-1** ({bolt-type}): 001-user-signup, 002-user-login - completed - No dependencies
+- ⏳ **bolt-auth-service-2** ({bolt-type}): 003-password-reset, 004-email-verify - in-progress - requires bolt-1
+- [ ] **bolt-auth-service-3** ({bolt-type}): 005-mfa-setup - planned - requires bolt-2
+
+### Summary
+
+- **Completed**: 1
+- **In Progress**: 1
+- **Planned**: 1
+- **Total Stories Covered**: 5
+```
+
+### 2. Determine Action
+
+Ask user what they want to do:
+
+```markdown
+## Replanning Options
+
+What would you like to do?
+
+1. **View Status** - See current bolt plan and progress
+2. **Append Bolts** - Add new bolts for uncovered stories or new work
+3. **Split Bolt** - Break a large planned bolt into smaller ones
+4. **Reorder** - Change execution order or adjust dependencies
+
+Select an option (1-4):
+```
+
+---
+
+## Action: Append New Bolts
+
+### When to Use
+
+- New stories added during construction
+- Discovered work not covered by existing bolts
+- Need additional bolts for edge cases
+
+### Process
+
+1. **Check uncovered stories**:
+
+   ```markdown
+   ## Uncovered Stories
+
+   Stories not assigned to any bolt:
+
+   - [ ] **006-session-mgmt**: Session management - Should
+   - [ ] **007-api-keys**: API key generation - Could
+   ```
+
+2. **Determine next bolt ID**:
+   - Read existing bolts, find highest sequence number
+   - Next bolt: `bolt-{unit}-{N+1}`
+
+3. **Create new bolt(s)**:
+   - Use template: `.specsmd/aidlc/templates/construction/bolt-template.md`
+   - All bolts use type `ddd-construction-bolt` (see: `.specsmd/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md`)
+   - Set `requires_bolts` based on dependencies
+   - Include complexity assessment (aggregate of included stories)
+   - Update `enables_bolts` on existing bolts if needed
+
+4. **Output**:
+
+   ```markdown
+   ## Bolts Appended
+
+   Created 1 new bolt:
+
+   - [ ] **bolt-auth-service-4** ({bolt-type}): 006-session-mgmt, 007-api-keys - requires bolt-3
+
+   Updated dependency graph:
+   bolt-1 → bolt-2 → bolt-3 → bolt-4 (NEW)
+
+   File created: `memory-bank/bolts/bolt-auth-service-4.md`
+   ```
+
+---
+
+## Action: Split Bolt
+
+### When to Use
+
+- Bolt is taking too long
+- Bolt scope creep discovered
+- Need to parallelize work
+
+### Rules
+
+- 🛑 **Cannot split completed bolts**
+- ⚠️ **Splitting in-progress bolt requires confirmation** (will mark current as completed at current stage)
+- ✅ **Can freely split planned bolts**
+
+### Process
+
+1. **Select bolt to split**:
+
+   ```markdown
+   ## Select Bolt to Split
+
+   Splittable bolts (planned or in-progress):
+
+   - ⏳ **bolt-auth-service-2** ({bolt-type}): 003-password-reset, 004-email-verify, 005-mfa-setup - in-progress - ⚠️ Confirm to split
+   - [ ] **bolt-auth-service-3** ({bolt-type}): 006-session-mgmt, 007-api-keys, 008-rate-limit - planned - ✅ Can split
+
+   Enter bolt ID to split:
+   ```
+
+2. **Propose split**:
+
+   ```markdown
+   ## Split Proposal: bolt-auth-service-3
+
+   Current: 3 stories (006-session-mgmt, 007-api-keys, 008-rate-limit)
+
+   Proposed split:
+
+   - **bolt-auth-service-3a**: 006-session-mgmt - Core feature
+   - **bolt-auth-service-3b**: 007-api-keys, 008-rate-limit - Related edge cases
+
+   Accept this split? (yes/no/customize)
+   ```
+
+3. **Execute split**:
+   - Archive or update original bolt file
+   - Create new bolt files with `3a`, `3b` suffixes (or next sequence)
+   - Update dependencies on dependent bolts
+   - Update `enables_bolts` on prerequisite bolts
+
+4. **Output**:
+
+   ```markdown
+   ## Bolt Split Complete
+
+   Original: bolt-auth-service-3 (archived)
+
+   Created:
+
+   - [ ] **bolt-auth-service-3** ({bolt-type}): 006-session-mgmt - requires bolt-2
+   - [ ] **bolt-auth-service-4** ({bolt-type}): 007-api-keys, 008-rate-limit - requires bolt-3
+
+   Updated files:
+   - `memory-bank/bolts/bolt-auth-service-3.md` (updated)
+   - `memory-bank/bolts/bolt-auth-service-4.md` (created)
+   - `memory-bank/bolts/bolt-auth-service-2.md` (updated enables_bolts)
+   ```
+
+---
+
+## Action: Reorder Bolts
+
+### When to Use
+
+- Dependencies changed during construction
+- Need to prioritize different bolt
+- Discovered blocking dependency
+
+### Rules
+
+- 🛑 **Cannot reorder completed bolts**
+- 🛑 **Cannot move bolt before its dependencies**
+- ⚠️ **Reordering in-progress bolt pauses it**
+
+### Process
+
+1. **Show current order**:
+
+   ```markdown
+   ## Current Execution Order
+
+   bolt-1 (completed) → bolt-2 (in-progress) → bolt-3 (planned) → bolt-4 (planned)
+
+   - 1 - **bolt-auth-service-1**: completed - ❌ Cannot move
+   - 2 - **bolt-auth-service-2**: in-progress - ⚠️ Will pause if moved
+   - 3 - **bolt-auth-service-3**: planned - ✅ Can move
+   - 4 - **bolt-auth-service-4**: planned - ✅ Can move
+   ```
+
+2. **Get new order**:
+
+   ```markdown
+   Enter new order for planned bolts (comma-separated IDs):
+   Example: bolt-auth-service-4, bolt-auth-service-3
+
+   This will execute bolt-4 before bolt-3.
+   ```
+
+3. **Validate dependencies**:
+   - Check if new order violates any `requires_bolts`
+   - Warn if dependency issue found
+
+4. **Execute reorder**:
+   - Update `requires_bolts` and `enables_bolts` in affected bolt files
+   - Recalculate execution sequence
+
+5. **Output**:
+
+   ```markdown
+   ## Reorder Complete
+
+   New execution order:
+
+   bolt-1 (completed) → bolt-2 (in-progress) → bolt-4 (planned) → bolt-3 (planned)
+
+   Updated files:
+   - `memory-bank/bolts/bolt-auth-service-3.md` (requires_bolts updated)
+   - `memory-bank/bolts/bolt-auth-service-4.md` (requires_bolts updated)
+   ```
+
+---
+
+## Dependency Management
+
+When modifying bolts, always update dependencies:
+
+### Frontmatter Fields
+
+```yaml
+---
+id: bolt-auth-service-3
+type: ddd-construction-bolt
+requires_bolts: [bolt-auth-service-2]
+enables_bolts: [bolt-auth-service-4]
+requires_units: []
+complexity:
+  avg_complexity: 2
+  avg_uncertainty: 1
+  max_dependencies: 2
+  testing_scope: 2
+---
+```
+
+Note: Do NOT use comments inside YAML frontmatter. Keep it clean.
+
+See full template: `.specsmd/aidlc/templates/construction/bolt-template.md`
+
+### Validation Rules
+
+1. **No circular dependencies**: A → B → C → A is invalid
+2. **No orphaned bolts**: Every bolt (except first) must have `requires_bolts`
+3. **Consistent enables/requires**: If A enables B, then B requires A
+
+---
+
+## Human Validation Point
+
+> "I've analyzed the current bolt plan for `{unit-name}`. There are {n} bolts: {completed} completed, {in_progress} in progress, {planned} planned. What would you like to do? (1) View status, (2) Append bolts, (3) Split a bolt, (4) Reorder bolts"
+
+---
+
+## Construction Log
+
+**IMPORTANT**: After ANY replanning action, update the construction log.
+
+### Location
+
+`{unit-path}/construction-log.md`
+
+### On First Replan
+
+If construction log doesn't exist, create it using template:
+`.specsmd/aidlc/templates/construction/construction-log-template.md`
+
+Initialize with:
+
+- Original bolt plan from inception
+- First replanning entry
+
+### On Every Replan
+
+Add entry to Replanning History:
+
+```markdown
+| {today} | {action} | {change description} | {reason} | Yes |
+```
+
+Update Current Bolt Structure to reflect changes.
+
+### Example
+
+After splitting bolt-2:
+
+```markdown
+## Replanning History
+
+- **2025-12-07**: split - bolt-2 → bolt-2, bolt-3 - Scope too large - ✅ Approved
+```
+
+---
+
+## Transition
+
+After replanning:
+
+- → **Bolt Start** (`.specsmd/skills/construction/bolt-start.md`) - continue execution
+- → **Bolt Status** (`.specsmd/skills/construction/bolt-status.md`) - verify changes
+- → **Inception Agent** - if major scope change requires new stories
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, action (status|append|split|reorder)
+output: Updated bolt plan with dependency graph
+checkpoints: 0 (utility operation)
+```

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

@@ -0,0 +1,289 @@
+# Skill: Start/Continue Bolt
+
+---
+
+## Bolt Type Execution
+
+Stages, activities, outputs, and checkpoints come from the bolt type definition:
+`.specsmd/aidlc/templates/construction/bolt-types/{bolt_type}.md`
+
+**ALWAYS read bolt type first. Never assume stages or checkpoints.**
+
+---
+
+## Goal
+
+Execute a bolt instance through its defined stages, producing artifacts with human validation at checkpoints defined by the bolt type.
+
+---
+
+## Input
+
+- **Required**: `--bolt-id` - The bolt instance ID
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--stage` - Specific stage to execute (for resuming)
+
+---
+
+## Process
+
+### 1. Load Bolt Context
+
+Read bolt file from path defined by `schema.bolts`:
+
+- Verify bolt exists and is not completed
+- Extract: bolt_type, unit, intent, stories, current_stage
+
+### 2. Load Bolt Type Definition (CRITICAL)
+
+**Using the bolt_type extracted in Step 1**, load the bolt type definition:
+
+**Location**: `.specsmd/aidlc/templates/construction/bolt-types/{bolt_type}.md`
+
+**This step is NON-NEGOTIABLE. You MUST:**
+
+1. Read the bolt type file COMPLETELY before any stage execution
+2. Extract and understand:
+   - **Stages**: Names, sequence, count
+   - **Activities**: What to do in each stage
+   - **Outputs**: Artifacts to produce
+   - **Constraints**: Forbidden actions per stage
+   - **Completion Criteria**: How to know a stage is done
+   - **Checkpoints**: Where to pause for human validation
+
+**The bolt type IS the execution plan. Follow it exactly.**
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│  bolt instance defines bolt_type                           │
+│  bolt_type definition dictates stages and execution        │
+│  bolt-start does NOT define stages or checkpoints          │
+└────────────────────────────────────────────────────────────┘
+```
+
+### 3. Load Agent Context
+
+Load context as defined in `.specsmd/aidlc/context-config.yaml` for the `construction` agent:
+
+```yaml
+agents:
+  construction:
+    required_context:
+      - path: standards/tech-stack.md
+      - path: standards/coding-standards.md
+    optional_context:
+      - path: standards/system-architecture.md
+      - path: standards/api-conventions.md
+```
+
+1. Load all `required_context` files (warn if missing with `critical: true`)
+2. Load `optional_context` files if they exist
+
+**Note**: This is agent-level context. Bolt-type-specific context loading may be added later.
+
+### 4. Determine Current Stage
+
+Based on bolt state:
+
+- **planned** → Start with first stage, set status to `in-progress`
+- **in-progress** → Continue from `current_stage`
+- **completed** → Inform user bolt is done
+- **blocked** → Show blocker, ask how to resolve
+
+### 5. Execute Stage
+
+For the current stage, follow the bolt type definition:
+
+1. **Present Stage Context**:
+
+   ```markdown
+   ## Stage: {stage-name}
+
+   ### Objective
+   {From bolt type definition}
+
+   ### Activities
+   {From bolt type definition}
+
+   ### Expected Output
+   {From bolt type definition}
+
+   ### Stories in Scope
+   {From bolt instance}
+   ```
+
+2. **Perform Activities**:
+   - Follow bolt type's activity instructions exactly
+   - Create artifacts as specified
+   - Respect constraints (e.g., "no code in this stage")
+
+3. **Generate Outputs**:
+   - Create specified output artifacts
+   - Use templates if specified by bolt type
+   - Place in correct paths per schema
+
+### 6. Handle Checkpoints (As Defined by Bolt Type)
+
+The bolt type definition specifies:
+
+- **Which stages have checkpoints**
+- **What to present at each checkpoint**
+- **What approval means**
+
+If the current stage has a checkpoint:
+
+```text
+## Stage Complete: {stage-name}
+
+{Present summary as specified by bolt type}
+
+Ready to proceed?
+1 - Approve and continue
+2 - Need changes (specify)
+```
+
+**Wait for user response before proceeding.**
+
+If the bolt type specifies automatic validation criteria, follow those rules.
+
+### 7. Update Bolt File
+
+After stage completion:
+
+- Add stage to `stages_completed` with timestamp
+- Update `current_stage` to next stage
+- If final stage, set `status: completed` and `completed` timestamp
+
+**⚠️ TIMESTAMP FORMAT**: See `memory-bank.yaml` → `conventions.timestamps`
+
+```yaml
+---
+status: in-progress
+current_stage: {next-stage-from-bolt-type}
+stages_completed:
+  - {stage-name}: {timestamp}
+---
+```
+
+**On bolt completion**, also update:
+
+```yaml
+completed: {timestamp}
+```
+
+### 8. Continue or Complete
+
+Based on condition:
+
+- **More stages remain** → Proceed to next stage
+- **Final stage complete** → Mark bolt complete, suggest next bolt
+- **User stops** → Save progress, can resume later
+
+---
+
+## Update Construction Log
+
+**IMPORTANT**: Update the construction log at key execution points.
+
+### Location
+
+`{unit-path}/construction-log.md`
+
+### On First Bolt Start
+
+If construction log doesn't exist, create it using template:
+`.specsmd/aidlc/templates/construction/construction-log-template.md`
+
+### On Bolt Start
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} started - Stage 1: {stage-name}
+```
+
+### On Stage Completion
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} stage-complete - {stage-name} → {next-stage}
+```
+
+### On Bolt Completion
+
+```markdown
+- **{ISO-8601-timestamp}**: {bolt-id} completed - All {n} stages done
+```
+
+---
+
+## Output (Stage Execution)
+
+```markdown
+## Executing Bolt: {bolt-id}
+
+### Current Stage: {stage-name}
+**Type**: {bolt-type}
+**Progress**: Stage {n} of {total}
+
+### Activities Performed
+1. ✅ {activity 1}
+2. ✅ {activity 2}
+3. ⏳ {activity 3 - in progress}
+
+### Artifacts Created
+- `{path/to/artifact}` - {description}
+
+### Stories Addressed
+- ✅ **{SSS}-{story-slug}**: {criteria} - Complete
+- ⏳ **{SSS}-{story-slug}**: {criteria} - In Progress
+
+---
+
+### Checkpoint (if defined by bolt type)
+> "{checkpoint prompt from bolt type definition}"
+```
+
+---
+
+## Output (Bolt Completed)
+
+```markdown
+## Bolt Complete: {bolt-id}
+
+### Summary
+- **Type**: {bolt-type}
+- **Duration**: {time elapsed}
+- **Stages Completed**: {all stages from bolt type}
+
+### Artifacts Produced
+{List artifacts as defined by bolt type}
+
+### Stories Delivered
+- ✅ **{SSS}-{story-slug}**: Complete
+- ✅ **{SSS}-{story-slug}**: Complete
+
+### Actions
+
+1 - **next**: Start next bolt
+2 - **list**: Review all bolts for this unit
+3 - **operations**: Proceed to Operations (if all complete)
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Transition
+
+After bolt completion:
+
+- → **Next Bolt** - if more bolts in unit
+- → **Operations Agent** - if all unit bolts complete
+
+---
+
+## Test Contract
+
+```yaml
+input: bolt-id, bolt type definition
+output: Artifacts as defined by bolt type
+checkpoints: As defined by bolt type (0 to N)
+```