specsmd 0.0.1

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

@@ -0,0 +1,259 @@
+# Bolt Type: TDD 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: tdd-construction-bolt
+name: TDD Construction Bolt
+description: Test-Driven Development with red-green-refactor cycle
+version: 1.0.0
+suitable_for:
+  - Algorithm implementation
+  - Utility functions
+  - Pure logic without external dependencies
+  - Libraries and reusable components
+stages_count: 3
+```
+
+---
+
+## Overview
+
+This bolt type implements Test-Driven Development (TDD) methodology through the classic red-green-refactor cycle: write failing tests, make them pass, then refactor.
+
+**Best For**:
+
+- Algorithm and logic implementation
+- Utility functions and helpers
+- Pure functions without side effects
+- Libraries and SDKs
+- Components with clear inputs/outputs
+
+---
+
+## Stages
+
+### Stage 1: test-first
+
+**Objective**: Write failing tests that specify expected behavior
+
+**Duration**: Hours (typically 1-3 hours)
+
+**Activities**:
+
+1 - **Analyze requirements**: Identify test cases and edge cases
+2 - **Write unit tests**: Create tests for core functionality (failing)
+3 - **Write edge case tests**: Cover boundary conditions
+4 - **Write error tests**: Cover error conditions
+5 - **Run tests**: Confirm they fail (RED state)
+
+**Artifact**: `test-spec.md` and test files
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/test-spec.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: test-first
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Test Specification: {unit-name}
+
+### Test Cases
+
+#### Core Functionality
+
+- **{Test name}**: Input: {input} → Expected: {output}
+- **{Test name}**: Input: {input} → Expected: {output}
+
+#### Edge Cases
+
+- **{Test name}**: Input: {input} → Expected: {output}
+
+#### Error Conditions
+
+- **{Test name}**: Input: {input} → Expected Error: {error}
+
+### Test Run (RED)
+- Total tests: {n}
+- Passing: 0
+- Failing: {n}
+
+Status: 🔴 RED (all tests failing as expected)
+```
+
+**Completion Criteria**:
+
+- [ ] All functionality has tests
+- [ ] Edge cases covered
+- [ ] Error cases covered
+- [ ] All tests compile/parse
+- [ ] All tests fail (RED state)
+
+**⛔ HUMAN Checkpoint**: Present test specification and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+
+---
+
+### Stage 2: implement
+
+**Objective**: Write minimal code to make tests pass
+
+**Duration**: Hours (varies by complexity)
+
+**Activities**:
+
+1 - **Implement first test**: Write simplest code that passes
+2 - **Iterate through tests**: Make each test pass in turn
+3 - **Run full suite**: Confirm all tests pass
+4 - **Review implementation**: Check for issues
+
+**Artifact**: Source code
+**Location**: `src/{unit}/`
+
+**Approach**:
+
+```text
+for each failing test:
+    1. Write simplest code that passes the test
+    2. Run tests
+    3. Commit if green
+    4. Move to next test
+```
+
+**Completion Criteria**:
+
+- [ ] All tests passing (GREEN state)
+- [ ] Implementation is minimal
+- [ ] No over-engineering
+- [ ] All acceptance criteria met
+
+**⛔ HUMAN Checkpoint**: Present implementation summary and **STOP**. Wait for user to confirm before proceeding to Stage 3.
+
+---
+
+### Stage 3: refactor
+
+**Objective**: Improve code quality while keeping tests green
+
+**Duration**: Hours (typically 1-2 hours)
+
+**Activities**:
+
+1 - **Review code**: Identify improvement opportunities
+2 - **Remove duplication**: Apply DRY principle
+3 - **Improve naming**: Make names clear and descriptive
+4 - **Extract functions**: Create clean, focused functions
+5 - **Optimize if needed**: Improve performance where necessary
+6 - **Run tests after each change**: Maintain green state
+
+**Artifact**: `refactor-report.md`
+**Location**: Path defined by `schema.units` in `.specsmd/aidlc/memory-bank.yaml`
+*(Default: `{intents-path}/{intent}/units/{unit}/refactor-report.md`)*
+
+**Template Structure**:
+
+```markdown
+---
+stage: refactor
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Refactor Report: {unit-name}
+
+### Improvements Made
+
+- **{Change}**: Before: {old} → After: {new} - Reason: {why}
+
+### Code Quality Metrics
+
+- **Cyclomatic Complexity**: Before: {n} → After: {n}
+- **Lines of Code**: Before: {n} → After: {n}
+- **Test Coverage**: Before: {n}% → After: {n}%
+
+### Test Status
+- All tests: ✅ PASSING
+- Coverage: {n}%
+
+### Final State
+Status: 🟢 GREEN (refactored and tested)
+```
+
+**Completion Criteria**:
+
+- [ ] All tests still passing
+- [ ] Code is clean and readable
+- [ ] No duplication
+- [ ] Functions are small and focused
+- [ ] Naming is clear
+
+**⛔ HUMAN Checkpoint**: Present refactor report and **STOP**. Wait for user to confirm bolt completion.
+
+---
+
+## Stage Execution
+
+### Sequence
+
+```text
+test-first (RED) → implement (GREEN) → refactor (REFACTOR)
+```
+
+### The TDD Cycle
+
+```text
+    ┌──────────┐
+    │   RED    │  Write failing test
+    └────┬─────┘
+         │
+         ▼
+    ┌──────────┐
+    │  GREEN   │  Make it pass
+    └────┬─────┘
+         │
+         ▼
+    ┌──────────┐
+    │ REFACTOR │  Improve code
+    └────┬─────┘
+         │
+         └──────► Next test case
+```
+
+### State Tracking
+
+```yaml
+---
+current_stage: refactor
+stages_completed:
+  - name: test-first
+    completed: 2024-12-05T10:00:00Z
+    tests_written: 15
+  - name: implement
+    completed: 2024-12-05T12:00:00Z
+    tests_passing: 15
+status: in-progress
+---
+```

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

@@ -0,0 +1,129 @@
+# Construction Log Template
+
+Use this template to track construction progress and replanning decisions for a unit.
+
+---
+
+## Location
+
+`{intents-path}/{intent}/units/{unit}/construction-log.md`
+
+---
+
+## Template
+
+```markdown
+---
+unit: {unit-name}
+intent: {intent-name}
+created: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+---
+
+# Construction Log: {unit-name}
+
+## Original Plan
+
+**From Inception**: {number} bolts planned
+**Planned Date**: {inception-date}
+
+| Bolt ID | Stories | Type |
+|---------|---------|------|
+| {bolt-1} | {stories} | {type} |
+| {bolt-2} | {stories} | {type} |
+
+## Replanning History
+
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+
+## Current Bolt Structure
+
+| Bolt ID | Stories | Status | Changed |
+|---------|---------|--------|---------|
+| {bolt-1} | {stories} | ✅ completed | - |
+| {bolt-2} | {stories} | ⏳ in-progress | - |
+| {bolt-3} | {stories} | [ ] planned | Split from bolt-2 |
+
+## Execution History
+
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| {date} | {bolt-id} | started | Stage 1: {stage-name} |
+| {date} | {bolt-id} | stage-complete | {stage} → {next-stage} |
+| {date} | {bolt-id} | completed | All {n} stages done |
+
+## Execution Summary
+
+| Metric | Value |
+|--------|-------|
+| Original bolts planned | {n} |
+| Current bolt count | {n} |
+| Bolts completed | {n} |
+| Bolts in progress | {n} |
+| Bolts remaining | {n} |
+| Replanning events | {n} |
+
+## Notes
+
+{Any additional observations or decisions made during construction}
+```
+
+---
+
+## When to Create
+
+Create this file when:
+
+1. First bolt for a unit starts (initialize with original plan)
+2. Any replanning action occurs (append, split, reorder)
+
+---
+
+## When to Update
+
+Update this file when:
+
+1. A bolt starts (add to Execution History, update Current Bolt Structure)
+2. A stage completes (add to Execution History)
+3. A bolt completes (add to Execution History, update Current Bolt Structure, update Execution Summary)
+4. A replanning action occurs (add to Replanning History, update Current Bolt Structure)
+5. Construction completes (add final summary to Notes)
+
+---
+
+## Replanning History Actions
+
+| Action | Description |
+|--------|-------------|
+| `append` | New bolt(s) added to plan |
+| `split` | Existing bolt split into multiple |
+| `reorder` | Execution order changed |
+| `scope-change` | Stories added/removed from bolt |
+
+---
+
+## Example Entries
+
+### Replanning History Example
+
+```markdown
+| Date | Action | Change | Reason | Approved |
+|------|--------|--------|--------|----------|
+| 2025-12-07 | split | bolt-2 → bolt-2, bolt-3 | Scope too large for single bolt | Yes |
+| 2025-12-08 | append | Added bolt-4 | New stories from feedback | Yes |
+| 2025-12-09 | reorder | bolt-4 before bolt-3 | Dependency discovered | Yes |
+```
+
+### Execution History Example
+
+```markdown
+| Date | Bolt | Event | Details |
+|------|------|-------|---------|
+| 2025-12-07 | bolt-auth-1 | started | Stage 1: Model |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Model → Design |
+| 2025-12-07 | bolt-auth-1 | stage-complete | Design → Implement |
+| 2025-12-08 | bolt-auth-1 | stage-complete | Implement → Test |
+| 2025-12-08 | bolt-auth-1 | completed | All 4 stages done |
+| 2025-12-08 | bolt-auth-2 | started | Stage 1: Model |
+```

package/flows/aidlc/templates/construction/standards/coding-standards.md

@@ -0,0 +1,29 @@
+# Coding Standards
+
+## General Principles
+
+- {e.g., DRY, KISS, SOLID}
+- {e.g., Clean Code practices}
+
+## Naming Conventions
+
+- Variables: {e.g., camelCase}
+- Functions: {e.g., camelCase}
+- Classes: {e.g., PascalCase}
+- Files: {e.g., kebab-case}
+
+## Formatting
+
+- Indentation: {e.g., 2 spaces}
+- Line Length: {e.g., 80 characters}
+- Braces: {e.g., K&R style}
+
+## Comments & Documentation
+
+- {e.g., JSDoc for functions}
+- {e.g., Explain WHY, not WHAT}
+
+## Testing
+
+- {e.g., Unit tests for all business logic}
+- {e.g., Integration tests for API endpoints}

package/flows/aidlc/templates/construction/standards/system-architecture.md

@@ -0,0 +1,22 @@
+# System Architecture
+
+## Overview
+
+{High-level system description}
+
+## Architecture Diagram
+
+{Mermaid diagram or description}
+
+## Components
+
+- {Component 1}: {Purpose}
+- {Component 2}: {Purpose}
+
+## Data Flow
+
+{How data moves through the system}
+
+## Technology Stack
+
+{Languages, frameworks, databases, etc.}

package/flows/aidlc/templates/construction/standards/tech-stack.md

@@ -0,0 +1,19 @@
+# Tech Stack
+
+## Core Technologies
+
+- Language: {e.g., TypeScript, Python}
+- Framework: {e.g., React, Next.js, Django}
+- Database: {e.g., PostgreSQL, MongoDB}
+
+## Infrastructure
+
+- Cloud Provider: {e.g., AWS, GCP}
+- Containerization: {e.g., Docker, Kubernetes}
+- CI/CD: {e.g., GitHub Actions}
+
+## Tools & Libraries
+
+- Testing: {e.g., Jest, Pytest}
+- Linting: {e.g., ESLint, Pylint}
+- Documentation: {e.g., MkDocs, Storybook}

package/flows/aidlc/templates/inception/inception-log-template.md

@@ -0,0 +1,134 @@
+# Inception Log Template
+
+Use this template to track inception progress and decisions for an intent.
+
+---
+
+## Location
+
+`{intents-path}/{intent}/inception-log.md`
+
+---
+
+## Template
+
+```markdown
+---
+intent: {intent-name}
+created: {YYYY-MM-DD}
+completed: {YYYY-MM-DD or null}
+status: {in-progress | complete}
+---
+
+# Inception Log: {intent-name}
+
+## Overview
+
+**Intent**: {brief description}
+**Type**: {green-field | brown-field | defect-fix | refactoring}
+**Created**: {date}
+
+## Artifacts Created
+
+| Artifact | Status | File |
+|----------|--------|------|
+| Requirements | ✅ | requirements.md |
+| System Context | ✅ | system-context.md |
+| Units | ✅ | units/{unit-name}/unit-brief.md |
+| Stories | ✅ | units/{unit-name}/stories/*.md |
+| Bolt Plan | ✅ | memory-bank/bolts/bolt-*.md |
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Functional Requirements | {n} |
+| Non-Functional Requirements | {n} |
+| Units | {n} |
+| Stories | {n} |
+| Bolts Planned | {n} |
+
+## Units Breakdown
+
+| Unit | Stories | Bolts | Priority |
+|------|---------|-------|----------|
+| {unit-1} | {n} | {n} | Must |
+| {unit-2} | {n} | {n} | Should |
+
+## Decision Log
+
+| Date | Decision | Rationale | Approved |
+|------|----------|-----------|----------|
+
+## Scope Changes
+
+| Date | Change | Reason | Impact |
+|------|--------|--------|--------|
+
+## Ready for Construction
+
+**Checklist**:
+- [ ] All requirements documented
+- [ ] System context defined
+- [ ] Units decomposed
+- [ ] Stories created for all units
+- [ ] Bolts planned
+- [ ] Human review complete
+
+## Next Steps
+
+1. Begin Construction Phase
+2. Start with Unit: {first-unit}
+3. Execute: `/specsmd-construction-agent --unit="{first-unit}"`
+
+## Dependencies
+
+{Execution order based on unit dependencies}
+```
+
+---
+
+## When to Create
+
+Create this file when:
+
+1. Intent is created (intent-create skill)
+2. Initialize with basic metadata and empty sections
+
+---
+
+## When to Update
+
+Update this file when:
+
+1. An artifact is completed (update Artifacts Created table)
+2. A decision is made during inception (add to Decision Log)
+3. Scope changes (add to Scope Changes)
+4. Inception completes (mark status complete, fill summary)
+
+---
+
+## Decision Log Examples
+
+```markdown
+## Decision Log
+
+| Date | Decision | Rationale | Approved |
+|------|----------|-----------|----------|
+| 2025-12-07 | Split auth into 2 units | Separation of concerns | Yes |
+| 2025-12-07 | Use JWT over sessions | Stateless API requirement | Yes |
+| 2025-12-08 | Add MFA to scope | Security requirement from review | Yes |
+```
+
+---
+
+## Scope Changes Examples
+
+```markdown
+## Scope Changes
+
+| Date | Change | Reason | Impact |
+|------|--------|--------|--------|
+| 2025-12-08 | Added MFA stories | Security requirement | +2 stories, +1 bolt |
+| 2025-12-09 | Removed social login | Out of scope for MVP | -3 stories, -1 bolt |
+```

package/flows/aidlc/templates/inception/project/README.md

@@ -0,0 +1,55 @@
+# Project Context
+
+This directory contains project-level context and metadata.
+
+## Purpose
+
+The `memory-bank/project/` directory stores information about your overall project that persists across all intents and units.
+
+## Files to Create
+
+- **project-brief.md**: High-level project overview, goals, and scope
+- **tech-stack.md**: Technology choices and rationale
+- **team.md**: Team structure and roles
+- **conventions.md**: Coding standards, naming conventions, etc.
+
+## Example: project-brief.md
+
+```markdown
+---
+created: 2024-11-22
+updated: 2024-11-22
+---
+
+# Project Brief
+
+## Project Name
+{Your project name}
+
+## Overview
+{Brief description of what this project does}
+
+## Business Goals
+- {Goal 1}
+- {Goal 2}
+
+## Target Users
+{Who will use this system}
+
+## Success Criteria
+- {Measurable criterion 1}
+- {Measurable criterion 2}
+
+## Timeline
+- Inception: {dates}
+- Construction: {dates}
+- Launch: {target date}
+```
+
+## Getting Started
+
+1. Create `project-brief.md` with your project overview
+2. Document your tech stack in `tech-stack.md`
+3. Add any other project-level context as needed
+
+These files will be referenced by agents throughout the AI-DLC workflow.