specsmd 0.0.1

package/flows/aidlc/templates/construction/bolt-template.md

@@ -0,0 +1,193 @@
+# Bolt Instance Template
+
+## 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)
+
+---
+
+Use this template when creating new bolt instances during bolt planning.
+
+**Directory Structure**: Each bolt gets its own directory containing the bolt metadata and stage artifacts:
+
+```text
+memory-bank/bolts/{bolt-id}/
+├── bolt.md                      # Bolt instance metadata (this template)
+├── ddd-01-domain-model.md       # Stage 1 artifact (created during execution)
+├── ddd-02-technical-design.md   # Stage 2 artifact (created during execution)
+└── ddd-03-test-report.md        # Stage 4 artifact (created during execution)
+```
+
+---
+
+## Frontmatter
+
+```yaml
+---
+id: bolt-{unit}-{sequence}
+unit: {unit-name}
+intent: {intent-name}
+type: ddd-construction-bolt
+status: planned
+stories:
+  - story-1
+  - story-2
+created: {YYYY-MM-DD}
+started: null
+completed: null
+current_stage: null
+stages_completed: []
+
+# 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
+---
+```
+
+---
+
+## Content
+
+```markdown
+# Bolt: {bolt-id}
+
+## Overview
+
+{Brief description of what this bolt will accomplish}
+
+## Objective
+
+{Specific goal of this bolt tied to the stories it covers}
+
+## Stories Included
+
+- **{story-1}**: {title} (Must)
+- **{story-2}**: {title} (Should)
+
+## Bolt Type
+
+**Type**: {type name}
+**Definition**: `.specsmd/aidlc/templates/construction/bolt-types/{type}.md`
+
+## Stages
+
+- [ ] **1. {stage-1}**: Pending → {artifact}
+- [ ] **2. {stage-2}**: Pending → {artifact}
+- [ ] **3. {stage-3}**: Pending → {artifact}
+- [ ] **4. {stage-4}**: Pending → {artifact}
+
+## Dependencies
+
+### Requires
+- {Previous bolt or None}
+
+### Enables
+- {Next bolt or deployment}
+
+## Success Criteria
+
+- [ ] All stories implemented
+- [ ] All acceptance criteria met
+- [ ] Tests passing
+- [ ] Code reviewed
+
+## Notes
+
+{Any additional context or considerations}
+```
+
+---
+
+## Status Values
+
+- **planned**: Bolt created, not started
+- **in-progress**: Currently being executed
+- **completed**: All stages done
+- **blocked**: Cannot proceed due to dependency
+
+---
+
+## Stage Status Symbols
+
+- [ ] = Pending
+- ⏳ = In Progress
+- ✅ = Complete
+- 🚫 = Blocked
+
+---
+
+## Example
+
+```yaml
+---
+id: bolt-auth-service-1
+unit: auth-service
+intent: user-authentication
+type: ddd-construction-bolt
+status: in-progress
+stories:
+  - story-1
+  - story-2
+created: 2024-12-05
+started: 2024-12-05
+completed: null
+current_stage: design
+stages_completed:
+  - name: model
+    completed: 2024-12-05T10:00:00Z
+    artifact: ddd-01-domain-model.md
+
+complexity:
+  avg_complexity: 2
+  avg_uncertainty: 1
+  max_dependencies: 1
+  testing_scope: 2
+---
+
+# Bolt: bolt-auth-service-1
+
+## Overview
+
+First bolt for authentication service covering user registration and login.
+
+## Objective
+
+Implement core authentication functionality including user registration with email verification and secure login.
+
+## Stories Included
+
+- **story-1**: User can register (Must)
+- **story-2**: User can login (Must)
+
+## Bolt Type
+
+**Type**: DDD Construction Bolt
+**Definition**: `.specsmd/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md`
+
+## Stages
+
+- ✅ **1. model**: Complete → ddd-01-domain-model.md
+- ⏳ **2. design**: In Progress → ddd-02-technical-design.md ← current
+- [ ] **3. implement**: Pending → src/auth-service/
+- [ ] **4. test**: Pending → ddd-03-test-report.md
+
+## Dependencies
+
+### Requires
+- None (first bolt)
+
+### Enables
+- bolt-auth-service-2 (MFA implementation)
+
+## Success Criteria
+
+- ✅ Domain model defined
+- [ ] API design complete
+- [ ] Implementation complete
+- [ ] Tests passing
+```

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

@@ -0,0 +1,250 @@
+# Bolt Type: BDD 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
+
+---
+
+## Metadata
+
+```yaml
+bolt_type: bdd-construction-bolt
+name: BDD Construction Bolt
+description: Behavior-Driven Development with specification, implementation, and testing
+version: 1.0.0
+suitable_for:
+  - Feature-focused development
+  - User story implementation
+  - Scenarios with clear Given-When-Then flows
+stages_count: 3
+```
+
+---
+
+## Overview
+
+This bolt type implements Behavior-Driven Development (BDD) methodology through three stages focused on specifications, implementation, and acceptance testing.
+
+**Best For**:
+
+- Feature-driven development
+- User-facing functionality
+- Clear user stories with acceptance criteria
+- Scenarios that can be expressed in Given-When-Then format
+
+---
+
+## Stages
+
+### Stage 1: specify
+
+**Objective**: Define behavior specifications in Gherkin format
+
+**Duration**: Hours (typically 1-2 hours)
+
+**Activities**:
+
+1 - **Review user stories**: Analyze stories and acceptance criteria
+2 - **Write feature files**: Create Gherkin specifications
+3 - **Define happy paths**: Document expected successful flows
+4 - **Define edge cases**: Document boundary conditions
+5 - **Define error scenarios**: Document error handling behaviors
+6 - **Review with stakeholders**: Validate specifications
+
+**Artifact**: `specifications.md` and `.feature` files
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/specifications.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: specify
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Behavior Specifications: {unit-name}
+
+### Feature Overview
+{Feature description}
+
+### Scenarios
+
+#### Scenario 1: {Happy Path}
+​```gherkin
+Given {precondition}
+When {action}
+Then {expected outcome}
+​```
+
+#### Scenario 2: {Edge Case}
+
+​```gherkin
+Given {precondition}
+When {action}
+Then {expected outcome}
+​```
+
+### Background
+
+{Shared context for all scenarios}
+
+### Data Examples
+
+- **{Field}**: Valid: {examples} - Invalid: {examples}
+
+```
+
+**Completion Criteria**:
+
+- [ ] All user stories have scenarios
+- [ ] Happy paths covered
+- [ ] Edge cases covered
+- [ ] Error handling scenarios defined
+- [ ] Scenarios reviewed and approved
+
+**⛔ HUMAN Checkpoint**: Present specification summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: implement
+
+**Objective**: Implement the specified behaviors
+
+**Duration**: Hours to days (varies by complexity)
+
+**Activities**:
+
+1 - **Setup step definitions**: Create test framework structure
+2 - **Implement Given steps**: Build context setup code
+3 - **Implement When steps**: Build action code
+4 - **Implement Then steps**: Build assertion code
+5 - **Implement production code**: Build feature implementation
+6 - **Wire specs to implementation**: Connect tests to code
+
+**Artifact**: Source code
+**Location**: `src/{unit}/`
+
+**Project Structure**:
+
+```text
+
+src/{unit}/
+├── features/
+│   └── *.feature          # Gherkin specs
+├── steps/
+│   └──*_steps.{ext}      # Step definitions
+├── src/
+│   └── ...                # Production code
+└── support/
+    └── ...                # Test utilities
+
+```
+
+**Completion Criteria**:
+
+- [ ] All step definitions implemented
+- [ ] Production code implements features
+- [ ] All scenarios executable
+- [ ] Code follows standards
+
+**⛔ HUMAN Checkpoint**: Present implementation summary and **STOP**. Wait for user to confirm before proceeding to Stage 3.
+
+---
+
+### Stage 3: validate
+
+**Objective**: Run acceptance tests and verify behaviors
+
+**Duration**: Hours (typically 1-2 hours)
+
+**Activities**:
+
+1 - **Run all feature tests**: Execute test suite
+2 - **Fix any failing scenarios**: Address issues
+3 - **Generate living documentation**: Create doc report
+4 - **Verify acceptance criteria**: Validate against stories
+5 - **Stakeholder sign-off**: Get approval
+
+**Artifact**: `acceptance-report.md`
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/acceptance-report.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: validate
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Acceptance Report: {unit-name}
+
+### Test Results
+
+- **{Feature}**: {scenarios} scenarios - {passed} passed, {failed} failed
+
+### Acceptance Criteria Status
+
+- ✅/❌ **{Story}**: {Criteria} - Scenario: {name} - {Status}
+
+### Living Documentation
+{Link to generated docs}
+
+### Sign-off
+- [ ] Developer verified
+- [ ] Stakeholder approved
+```
+
+**Completion Criteria**:
+
+- [ ] All scenarios passing
+- [ ] Acceptance criteria met
+- [ ] Living documentation generated
+- [ ] Stakeholder sign-off received
+
+**⛔ HUMAN Checkpoint**: Present acceptance report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## Stage Execution
+
+### Sequence
+
+```text
+specify → implement → validate
+```
+
+### State Tracking
+
+```yaml
+---
+current_stage: implement
+stages_completed:
+  - name: specify
+    completed: 2024-12-05T10:00:00Z
+    artifact: specifications.md
+status: in-progress
+---
+```
+
+### Human Validation
+
+Specifications require stakeholder review before implementation.

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/adr-template.md

@@ -0,0 +1,49 @@
+---
+bolt: {bolt-id}
+created: {timestamp}
+status: proposed | accepted | deprecated | superseded
+superseded_by: {adr-number if applicable}
+---
+
+# ADR-{number}: {title}
+
+## Context
+
+{Describe the situation that requires a decision. What is the problem or opportunity? What constraints exist? What forces are at play?}
+
+## Decision
+
+{State the decision clearly. What did we decide to do?}
+
+## Rationale
+
+{Explain why this decision was made. What alternatives were considered? Why were they rejected?}
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Why Rejected |
+|-------------|------|------|--------------|
+| {option 1} | | | |
+| {option 2} | | | |
+
+## Consequences
+
+### Positive
+
+- {Benefit 1}
+- {Benefit 2}
+
+### Negative
+
+- {Trade-off 1}
+- {Trade-off 2}
+
+### Risks
+
+- {Risk 1 and mitigation}
+
+## Related
+
+- **Stories**: {related story IDs}
+- **Standards**: {if this should be added to standards later}
+- **Previous ADRs**: {related ADR numbers}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-01-domain-model-template.md

@@ -0,0 +1,55 @@
+---
+unit: {unit-name}
+bolt: {bolt-id}
+stage: model
+status: complete
+updated: {date}
+---
+
+# Static Model - {Unit Name}
+
+## Bounded Context
+
+{Define the bounded context for this unit}
+
+## Domain Entities
+
+| Entity | Properties | Business Rules |
+|--------|------------|----------------|
+| {Entity} | {properties} | {rules} |
+
+## Value Objects
+
+| Value Object | Properties | Constraints |
+|--------------|------------|-------------|
+| {ValueObject} | {properties} | {constraints} |
+
+## Aggregates
+
+| Aggregate Root | Members | Invariants |
+|----------------|---------|------------|
+| {Root} | {members} | {invariants} |
+
+## Domain Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| {Event} | {trigger} | {payload} |
+
+## Domain Services
+
+| Service | Operations | Dependencies |
+|---------|------------|--------------|
+| {Service} | {operations} | {dependencies} |
+
+## Repository Interfaces
+
+| Repository | Entity | Methods |
+|------------|--------|---------|
+| {Repository} | {entity} | {methods} |
+
+## Ubiquitous Language
+
+| Term | Definition |
+|------|------------|
+| {term} | {definition} |

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-02-technical-design-template.md

@@ -0,0 +1,67 @@
+---
+unit: {unit-name}
+bolt: {bolt-id}
+stage: design
+status: complete
+updated: {date}
+---
+
+# Technical Design - {Unit Name}
+
+## Architecture Pattern
+
+{Selected pattern and rationale - e.g., Hexagonal, Clean Architecture}
+
+## Layer Structure
+
+```text
+┌─────────────────────────────┐
+│      Presentation           │  API/UI
+├─────────────────────────────┤
+│      Application            │  Use Cases
+├─────────────────────────────┤
+│        Domain               │  Business Logic
+├─────────────────────────────┤
+│     Infrastructure          │  Database/External
+└─────────────────────────────┘
+```
+
+## API Design
+
+| Endpoint | Method | Request | Response |
+|----------|--------|---------|----------|
+| {endpoint} | {GET/POST/etc} | {request schema} | {response schema} |
+
+## Data Persistence
+
+| Table | Columns | Relationships |
+|-------|---------|---------------|
+| {table} | {columns} | {relationships} |
+
+## Security Design
+
+| Concern | Approach |
+|---------|----------|
+| Authentication | {approach} |
+| Authorization | {approach} |
+| Data Encryption | {approach} |
+
+## NFR Implementation
+
+| Requirement | Design Approach |
+|-------------|-----------------|
+| Performance | {approach} |
+| Scalability | {approach} |
+| Reliability | {approach} |
+
+## Error Handling
+
+| Error Type | Code | Response |
+|------------|------|----------|
+| {type} | {code} | {response} |
+
+## External Dependencies
+
+| Service | Purpose | Integration |
+|---------|---------|-------------|
+| {service} | {purpose} | {REST/Event/etc} |

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-03-test-report-template.md

@@ -0,0 +1,62 @@
+---
+unit: {unit-name}
+bolt: {bolt-id}
+stage: test
+status: complete
+updated: {date}
+---
+
+# Test Report - {Unit Name}
+
+## Test Summary
+
+| Category | Passed | Failed | Skipped | Coverage |
+|----------|--------|--------|---------|----------|
+| Unit | {n} | {n} | {n} | {n}% |
+| Integration | {n} | {n} | {n} | {n}% |
+| Security | {n} | {n} | {n} | - |
+| Performance | {n} | {n} | {n} | - |
+| **Total** | {n} | {n} | {n} | {n}% |
+
+## Acceptance Criteria Validation
+
+| Story | Criteria | Status |
+|-------|----------|--------|
+| {story-id} | {criteria} | ✅/❌ |
+
+## Unit Tests
+
+{Unit test results and notable tests}
+
+## Integration Tests
+
+{Integration test results}
+
+## Security Tests
+
+{Security test results - authentication, authorization, injection, etc.}
+
+## Performance Tests
+
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| Response Time (p95) | {target} | {actual} | ✅/❌ |
+| Throughput | {target} | {actual} | ✅/❌ |
+
+## Coverage Report
+
+{Coverage details by module/layer}
+
+## Issues Found
+
+| Issue | Severity | Status |
+|-------|----------|--------|
+| {issue} | {High/Medium/Low} | {Fixed/Open} |
+
+## Ready for Operations
+
+- [ ] All acceptance criteria met
+- [ ] Code coverage > 80%
+- [ ] No critical/high severity issues open
+- [ ] Performance targets met
+- [ ] Security tests passing