specsmd 0.0.0-dev

package/flows/aidlc/skills/operations/verify.md

@@ -0,0 +1,224 @@
+# Skill: Verify Deployment
+
+---
+
+## Role
+
+Post-deployment validation skill. Runs health checks and smoke tests.
+
+**NO Checkpoint** - Verification is an automated check, not a decision point.
+
+Verification happens after each deploy skill checkpoint. If verification fails, recommend rollback.
+
+---
+
+## Goal
+
+Confirm that a deployment is healthy, functional, and meeting acceptance criteria before proceeding to next environment.
+
+---
+
+## Input
+
+- **Required**: `--unit` - The unit to verify
+- **Required**: `.specsmd/aidlc/memory-bank.yaml` - artifact schema
+- **Optional**: `--env` - Target environment (default: last deployed)
+- **Optional**: `--version` - Specific version (default: currently deployed)
+
+---
+
+## Process
+
+### 1. Load Deployment Context
+
+From `deployment/history.md`:
+
+- Current deployed version
+- Deployment timestamp
+- Previous version (for comparison)
+
+### 2. Execute Health Checks
+
+- [ ] **Endpoint Health**: GET `/health` → 200 OK
+- [ ] **Readiness**: GET `/ready` → 200 OK
+- [ ] **Database**: Connection test → Connected
+- [ ] **Cache**: Connection test → Connected
+- [ ] **External APIs**: Connectivity check → Reachable
+
+### 3. Run Smoke Tests
+
+Execute critical path tests:
+
+- [ ] **Authentication**: Login flow works (if applicable)
+- [ ] **Core CRUD**: Basic operations work (required)
+- [ ] **API Endpoints**: Key endpoints respond (required)
+- [ ] **Error Handling**: Errors handled gracefully (required)
+
+### 4. Check Metrics
+
+Verify operational metrics are within bounds:
+
+- [ ] **Response Time**: < SLA (p95 latency)
+- [ ] **Error Rate**: < 1% (4xx/5xx responses)
+- [ ] **CPU**: < 80% (resource utilization)
+- [ ] **Memory**: < 80% (resource utilization)
+
+### 5. Compare to Baseline
+
+If previous version exists:
+
+- Error rate comparison
+- Latency comparison
+- Resource usage comparison
+
+### 6. Document Results
+
+Create `deployment/verification-{version}.md`:
+
+```markdown
+---
+version: {version}
+environment: {env}
+verified: {timestamp}
+status: passed|failed
+---
+
+## Verification Report: {version}
+
+### Health Checks
+
+- ✅ **Endpoint**: 200 OK, 15ms
+- ✅ **Database**: Connected
+- ✅ **Cache**: Connected
+
+### Smoke Tests
+
+- ✅ **Login Flow**: 234ms
+- ✅ **Create Item**: 156ms
+- ✅ **API Health**: 12ms
+
+### Metrics
+
+- ✅ **p95 Latency**: 145ms (threshold: <200ms)
+- ✅ **Error Rate**: 0.02% (threshold: <1%)
+
+### Baseline Comparison
+
+- **p95 Latency**: 142ms → 145ms (+2%)
+- **Error Rate**: 0.01% → 0.02% (+0.01%)
+
+### Conclusion
+{passed|failed}: {summary}
+```
+
+---
+
+## Output (Verification Passed)
+
+```markdown
+## Verification Passed: {unit-name}
+
+### Status: ✅ VERIFIED
+
+### Results Summary
+
+- ✅ **Health Checks**: {n}/{n} passed
+- ✅ **Smoke Tests**: {n}/{n} passed
+- ✅ **Metric Checks**: {n}/{n} passed
+
+### Key Metrics
+
+- ✅ **Response Time (p95)**: {value}ms
+- ✅ **Error Rate**: {value}%
+- ✅ **Uptime**: 100%
+
+### Environment Status
+
+- ✅ **{env}**: `{version}` - Verified
+
+### Documentation Created
+- `{unit-path}/deployment/verification-{version}.md`
+
+### Actions
+
+1 - **monitor**: Setup monitoring for this unit
+2 - **deploy**: Deploy to next environment
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **monitor** - Setup monitoring for `{unit-name}`
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Output (Verification Failed)
+
+```markdown
+## Verification Failed: {unit-name}
+
+### Status: ❌ FAILED
+
+### Failed Checks
+
+- ❌ **{check1}**: Expected {expected}, got {actual}
+- ❌ **{check2}**: Expected {expected}, got {actual}
+
+### Error Details
+{error messages or logs}
+
+### Impact Assessment
+
+- **Severity**: {critical|high|medium|low}
+- **Affected**: {what's broken}
+
+### Recommended Action
+⚠️ **ROLLBACK RECOMMENDED**
+
+Previous stable version: `{prev-version}`
+
+Rollback command:
+deploy --unit="{unit}" --env="{env}" --version="{prev-version}"
+
+### Actions
+
+1 - **rollback**: Rollback to previous version
+2 - **investigate**: Investigate root cause
+3 - **menu**: Return to operations menu
+
+### Suggested Next Step
+→ **rollback** - Restore `{prev-version}` immediately
+
+**Type a number or press Enter for suggested action.**
+```
+
+---
+
+## Human Validation Point
+
+On success:
+> "Verification passed for `{unit}` v`{version}` in {env}. All {n} checks passed. Ready to proceed to {next-action}?"
+
+On failure:
+> "⚠️ Verification FAILED for `{unit}` v`{version}`. {n} checks failed. Recommend rollback to `{prev-version}`. Proceed with rollback?"
+
+---
+
+## Transition
+
+After verification:
+
+- → **Monitor** (`.specsmd/skills/operations/monitor.md`) - if verified and final environment
+- → **Deploy** (`.specsmd/skills/operations/deploy.md`) - to next environment if verified
+- → **Rollback** - if verification fails (deploy previous version)
+
+---
+
+## Test Contract
+
+```yaml
+input: Unit name, environment, version
+output: Verification report with health checks, smoke tests, metrics
+checkpoints: 0 (automated validation only)
+```

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

@@ -0,0 +1,205 @@
+# 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: {UUU}-{unit-name}
+intent: {NNN}-{intent-name}
+type: ddd-construction-bolt
+status: planned
+stories:
+  - story-1
+  - story-2
+created: {YYYY-MM-DDTHH:MM:SSZ}
+started: null
+completed: null
+current_stage: null
+stages_completed: []
+
+# Bolt Dependencies (for execution ordering)
+requires_bolts: []          # Bolts that must complete before this bolt can start
+enables_bolts: []           # Bolts that become unblocked when this bolt completes
+requires_units: []          # Units that must exist (usually empty)
+blocks: false               # Computed: true if any requires_bolts are incomplete
+
+# 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: 001-auth-service
+intent: 001-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
+
+requires_bolts: []
+enables_bolts:
+  - bolt-auth-service-2
+requires_units: []
+blocks: false
+
+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/ddd-construction-bolt/adr-template.md

@@ -0,0 +1,49 @@
+---
+bolt: {bolt-id}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+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: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
+stage: model
+status: complete
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# 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: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
+stage: design
+status: complete
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# 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: {UUU}-{unit-name}
+bolt: {BBB}-{unit-name}
+stage: test
+status: complete
+updated: {YYYY-MM-DDTHH:MM:SSZ}
+---
+
+# 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