specsmd 0.0.1

package/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md

@@ -0,0 +1,273 @@
+# Bolt Type: Simple Construction
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+
+## Success Metrics
+
+- ✅ Activities presented as numbered lists (not tables)
+- ✅ Stage progress shown with status indicators
+- ✅ Human checkpoints clearly marked
+
+## Failure Modes
+
+- ❌ Using ASCII table for activities
+- ❌ Auto-advancing without human confirmation
+- ❌ Skipping stages
+
+---
+
+## ⛔ CRITICAL: Stage Execution Sequence
+
+**Stages MUST be executed in this exact order:**
+
+```text
+Stage 1: Spec → Stage 2: Implement → Stage 3: Test
+```
+
+**Stage Overview:**
+
+- ✅/[ ] **1. Spec** (Required) → `spec.md`
+- ✅/[ ] **2. Implement** (Required) → Source code
+- ✅/[ ] **3. Test** (Required) → Tests + `test-report.md`
+
+**Rules**:
+
+- Each stage MUST be completed before the next begins
+- **⛔ Human validation is MANDATORY at each stage checkpoint - STOP and WAIT for approval**
+- NEVER auto-advance to next stage without explicit user confirmation
+
+---
+
+## Metadata
+
+```yaml
+bolt_type: simple-construction-bolt
+name: Simple Construction Bolt
+description: Lightweight construction for UI, integrations, utilities, and non-DDD work
+version: 1.0.0
+suitable_for:
+  - Frontend pages and components
+  - Simple backend endpoints
+  - Integrations with external APIs
+  - Utilities and helper modules
+  - Scripts and automation
+  - CLI commands
+stages_count: 3
+```
+
+---
+
+## Overview
+
+This bolt type provides a lightweight construction process for work that doesn't need full domain modeling. It's ideal for UI work, integrations, utilities, and any code where the design is straightforward.
+
+**Best For**:
+
+- Frontend pages, components, layouts
+- Simple CRUD endpoints without complex business logic
+- Third-party API integrations
+- Utility functions and helpers
+- CLI commands and scripts
+- Configuration and setup tasks
+
+**NOT For** (use `ddd-construction-bolt` instead):
+
+- Complex domain logic with business rules
+- Systems requiring bounded contexts
+- Services with rich domain models
+
+---
+
+## Stages
+
+### Stage 1: Spec
+
+**Objective**: Define what to build with clear requirements
+
+**Duration**: Minutes to hours (typically 15-60 minutes)
+
+**Activities**:
+
+1 - **Review stories**: Understand what needs to be built
+2 - **Define scope**: List specific deliverables
+3 - **Identify dependencies**: External APIs, other units, libraries
+4 - **Define acceptance criteria**: How will we know it's done?
+5 - **Note technical approach**: High-level implementation notes
+
+**Artifact**: `spec.md`
+**Location**: `memory-bank/bolts/{bolt-id}/spec.md`
+
+**Template Structure**:
+
+```markdown
+---
+stage: spec
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Spec: {unit-name}
+
+### Objective
+{What this bolt will accomplish}
+
+### Deliverables
+- {Deliverable 1}
+- {Deliverable 2}
+
+### Dependencies
+- {Dependency 1}: {why needed}
+
+### Technical Approach
+{Brief notes on how to implement}
+
+### Acceptance Criteria
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+```
+
+**Completion Criteria**:
+
+- [ ] Stories reviewed and understood
+- [ ] Deliverables clearly defined
+- [ ] Dependencies identified
+- [ ] Acceptance criteria documented
+
+**⛔ HUMAN Checkpoint**: Present spec summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: Implement
+
+**Objective**: Write the code
+
+**Duration**: Hours (varies by complexity)
+
+**Activities**:
+
+1 - **Setup structure**: Create files and folders
+2 - **Implement core functionality**: Build the main features
+3 - **Handle edge cases**: Error handling, validation
+4 - **Add documentation**: Code comments, JSDoc/docstrings
+5 - **Run linting**: Ensure code style compliance
+
+**Artifact**: Source code
+**Location**: As defined in project structure (e.g., `src/`, `app/`, `pages/`)
+
+**Completion Criteria**:
+
+- [ ] All deliverables from spec implemented
+- [ ] Code follows project coding standards
+- [ ] Linting passes
+- [ ] Code is documented
+
+**⛔ HUMAN Checkpoint**: Present implementation summary and **STOP**. Wait for user to confirm before proceeding to Stage 3.
+
+---
+
+### Stage 3: Test
+
+**Objective**: Verify the implementation works correctly
+
+**Duration**: Minutes to hours (typically 30-120 minutes)
+
+**Activities**:
+
+1 - **Write unit tests**: Test individual functions/components
+2 - **Write integration tests**: Test API endpoints or component interactions
+3 - **Run test suite**: Execute all tests
+4 - **Verify acceptance criteria**: Check against spec
+5 - **Document results**: Create test report
+
+**Artifact**: `test-report.md`
+**Location**: `memory-bank/bolts/{bolt-id}/test-report.md`
+
+**Template Structure**:
+
+```markdown
+---
+stage: test
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Test Report: {unit-name}
+
+### Summary
+
+- **Tests**: {passed}/{total} passed
+- **Coverage**: {percentage}%
+
+### Acceptance Criteria Validation
+
+- ✅/❌ **{Criterion}**: {Status}
+
+### Issues Found
+{Any issues discovered during testing}
+
+### Notes
+{Additional observations}
+```
+
+**Completion Criteria**:
+
+- [ ] All tests passing
+- [ ] Acceptance criteria verified
+- [ ] Test report created
+
+**⛔ HUMAN Checkpoint**: Present test report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## State Tracking
+
+Bolt instance tracks progress:
+
+```yaml
+---
+current_stage: implement
+stages_completed:
+  - name: spec
+    completed: 2024-12-05T10:00:00Z
+    artifact: spec.md
+status: in-progress
+---
+```
+
+---
+
+## Bolt Context Loading
+
+For Stage 2 (Implement) and Stage 3 (Test), load all artifacts from the bolt folder:
+
+**Location**: `memory-bank/bolts/{bolt-id}/`
+
+**Load all files in this folder**, which may include:
+
+- `bolt.md` - Bolt instance metadata
+- `spec.md` - Spec from Stage 1
+
+This ensures implementation and test stages have context from the spec.
+
+---
+
+## Usage by Construction Agent
+
+1. **Load bolt instance** from path defined by `schema.bolts`
+2. **Read `bolt_type` field** (e.g., `simple-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
+6. **Execute stage** following activities defined here
+7. **Create artifacts** as specified
+8. **⛔ STOP and present completion summary** - DO NOT continue automatically
+9. **Wait for user confirmation** - user must explicitly approve
+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.
+
+The Construction Agent is **bolt-type agnostic** - it reads stages from this file and executes them.

package/flows/aidlc/templates/construction/bolt-types/spike-bolt.md

@@ -0,0 +1,240 @@
+# Bolt Type: Spike (Research)
+
+## Mandatory Output Rules (READ FIRST)
+
+- 🚫 **NEVER** use ASCII tables for options - they break at different terminal widths
+- ✅ **ALWAYS** use numbered list format: `N - **Option**: Description`
+- ✅ **ALWAYS** use status indicators: ✅ (done) ⏳ (current) [ ] (pending) 🚫 (blocked)
+
+## Success Metrics
+
+- ✅ Activities presented as numbered lists (not tables)
+- ✅ Stage progress shown with status indicators
+- ✅ Human checkpoints clearly marked
+
+## Failure Modes
+
+- ❌ Using ASCII table for activities
+- ❌ Auto-advancing without human confirmation
+- ❌ Exceeding time-box without approval
+
+---
+
+## Metadata
+
+```yaml
+bolt_type: spike-bolt
+name: Spike Bolt
+description: Research and proof-of-concept for unknown areas
+version: 1.0.0
+suitable_for:
+  - Technical research
+  - Proof of concept
+  - Evaluating technologies
+  - Risk mitigation
+stages_count: 2
+```
+
+---
+
+## Overview
+
+This bolt type is for research and proof-of-concept work when there are unknowns that need investigation before committing to implementation.
+
+**Best For**:
+
+- Evaluating new technologies
+- Proof of concept for risky approaches
+- Research before estimation
+- Validating assumptions
+- Learning and experimentation
+
+**Important**: Spike bolts produce **knowledge**, not production code. The output is documentation, not deployable software.
+
+---
+
+## Stages
+
+### Stage 1: explore
+
+**Objective**: Investigate the unknown area and document findings
+
+**Duration**: Time-boxed (hours to days, strictly limited)
+
+**Activities**:
+
+1 - **Define research questions**: List what needs to be answered
+2 - **Investigate options**: Research and document alternatives
+3 - **Build throwaway prototypes**: Create proof-of-concept code
+4 - **Test assumptions**: Validate or invalidate beliefs
+5 - **Identify risks**: Document potential issues
+6 - **Evaluate trade-offs**: Compare options
+
+**Artifact**: `spike-exploration.md`
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/spike-exploration.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: explore
+bolt: {bolt-id}
+created: {timestamp}
+time_box: {hours}
+---
+
+## Spike Exploration: {topic}
+
+### Research Questions
+1. {question 1}
+2. {question 2}
+
+### Options Investigated
+
+- **{Option}**: {Description} - Pros: {list} - Cons: {list}
+
+### Prototype Notes
+{What was built, what was learned}
+
+### Assumptions Tested
+
+- **{Assumption}**: Valid: {yes/no} - Evidence: {details}
+
+### Risks Identified
+
+- **{Risk}**: Likelihood: {H/M/L} - Impact: {H/M/L} - Mitigation: {approach}
+```
+
+**Completion Criteria**:
+
+- [ ] All research questions addressed
+- [ ] Options evaluated
+- [ ] Prototypes built (if applicable)
+- [ ] Assumptions validated or invalidated
+- [ ] Risks documented
+
+**⛔ HUMAN Checkpoint**: Present exploration summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: document
+
+**Objective**: Consolidate findings into actionable recommendations
+
+**Duration**: Hours (typically 1-2 hours)
+
+**Activities**:
+
+1 - **Summarize findings**: Create high-level summary
+2 - **Make recommendations**: Propose best approach
+3 - **Estimate implementation**: Provide effort estimates
+4 - **Identify next bolts**: Suggest follow-up work
+5 - **Present to team**: Share knowledge
+
+**Artifact**: `spike-report.md`
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/spike-report.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: document
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Spike Report: {topic}
+
+### Summary
+{High-level summary of what was learned}
+
+### Key Findings
+1. {finding 1}
+2. {finding 2}
+
+### Recommendation
+**Recommended Approach**: {option}
+
+**Rationale**: {why this option}
+
+### Implementation Estimate
+
+- **{Component}**: Effort: {estimate} - Confidence: {H/M/L}
+
+### Risks to Monitor
+
+- **{Risk}**: Mitigation: {strategy}
+
+### Suggested Next Steps
+1. {Create bolt for...}
+2. {Update requirements with...}
+3. {Add story for...}
+
+### Artifacts to Archive
+- [ ] Prototype code (if reusable): {location}
+- [ ] Research notes: {location}
+```
+
+**Completion Criteria**:
+
+- [ ] Findings documented
+- [ ] Clear recommendation made
+- [ ] Estimates provided
+- [ ] Next steps identified
+- [ ] Knowledge shared with team
+
+**⛔ HUMAN Checkpoint**: Present spike report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## Stage Execution
+
+### Sequence
+
+```text
+explore → document
+```
+
+### Time-Boxing
+
+Spikes **MUST** be time-boxed:
+
+- Define maximum duration upfront
+- Stop when time-box expires
+- Document whatever was learned
+- Don't extend without explicit approval
+
+### State Tracking
+
+```yaml
+---
+current_stage: document
+stages_completed:
+  - name: explore
+    completed: 2024-12-05T16:00:00Z
+    time_spent: 4h
+status: in-progress
+time_box: 8h
+time_remaining: 4h
+---
+```
+
+---
+
+## Important Notes
+
+### Spike Output
+
+- **NOT** production code
+- **NOT** deployable software
+- **IS** knowledge and documentation
+- **IS** input for real construction bolts
+
+### After a Spike
+
+1. Review findings with team
+2. Update requirements if needed
+3. Create real construction bolts
+4. Archive or delete prototype code