specky-sdd 3.2.0 → 3.2.1

package/dist/templates/templates/data-model.md

@@ -0,0 +1,35 @@
+<!-- markdownlint-disable -->
+# Data Model: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+
+---
+
+## Entities
+
+{{#each entities}}
+### {{name}}
+
+**Description**: {{description}}
+
+| Attribute | Type | Required | Description |
+|-----------|------|----------|-------------|
+{{#each attributes}}
+| {{name}} | {{type}} | {{required}} | {{description}} |
+{{/each}}
+
+{{/each}}
+
+## Relationships
+
+```mermaid
+erDiagram
+{{mermaid_erd}}
+```
+
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}

package/dist/templates/templates/design.md

@@ -0,0 +1,104 @@
+<!-- markdownlint-disable -->
+# {{project_name}} — Design
+
+> Complete system design covering architecture, data, APIs, security, infrastructure, and decisions.
+
+---
+
+## 1. System Context (C4 Level 1)
+
+> Who uses the system and what external systems does it integrate with?
+
+{{system_context}}
+
+---
+
+## 2. Container Architecture (C4 Level 2)
+
+> What are the deployable units (APIs, databases, queues, frontends) and how do they communicate?
+
+{{container_architecture}}
+
+---
+
+## 3. Component Design (C4 Level 3)
+
+> What are the internal modules/services within each container and their responsibilities?
+
+{{component_design}}
+
+---
+
+## 4. Code-Level Design (C4 Level 4)
+
+> Key classes, interfaces, patterns, and their relationships.
+
+{{code_level_design}}
+
+---
+
+## 5. System Diagrams
+
+{{#each diagrams}}
+### {{this}}
+{{/each}}
+
+---
+
+## 6. Data Model
+
+> Entities, relationships, storage strategy, and data flow.
+
+{{data_models}}
+
+---
+
+## 7. API Contracts
+
+> Endpoints, request/response schemas, authentication, and error codes.
+
+{{api_contracts}}
+
+---
+
+## 8. Infrastructure & Deployment
+
+> How the system is deployed, scaled, monitored, and operated.
+
+{{infrastructure}}
+
+---
+
+## 9. Security Architecture
+
+> Authentication, authorization, encryption, secrets management, and threat model.
+
+{{security_architecture}}
+
+---
+
+## 10. Architecture Decision Records
+
+{{#each adrs}}
+### {{this}}
+{{/each}}
+
+---
+
+## 11. Error Handling Strategy
+
+> How errors are detected, logged, propagated, and recovered from.
+
+{{error_handling}}
+
+---
+
+## 12. Cross-Cutting Concerns
+
+> Logging, monitoring, caching, configuration, feature flags, and observability.
+
+{{cross_cutting}}
+
+---
+
+**Covers:** {{requirement_references}}

package/dist/templates/templates/devcontainer.md

@@ -0,0 +1,36 @@
+<!-- markdownlint-disable -->
+# Dev Container: {{title}}
+
+**Feature**: {{feature_id}}
+**Base Image**: {{base_image}}
+**Date**: {{date}}
+
+---
+
+## Configuration
+
+```json
+{{devcontainer_json}}
+```
+
+## Included Features
+
+{{#each features}}
+- {{this}}
+{{/each}}
+
+## VS Code Extensions
+
+{{#each extensions}}
+- {{this}}
+{{/each}}
+
+## Getting Started
+
+1. Open VS Code in the project root
+2. Press `Ctrl+Shift+P` → "Dev Containers: Reopen in Container"
+3. Wait for the container to build
+4. Start developing!
+
+Alternatively, use GitHub Codespaces:
+- Run `sdd_setup_codespaces` to create a cloud environment

package/dist/templates/templates/dockerfile.md

@@ -0,0 +1,34 @@
+<!-- markdownlint-disable -->
+# Container Configuration: {{title}}
+
+**Feature**: {{feature_id}}
+**Language**: {{language}}
+**Framework**: {{framework}}
+**Date**: {{date}}
+
+---
+
+## Dockerfile
+
+```dockerfile
+{{dockerfile_content}}
+```
+
+## Docker Compose
+
+```yaml
+{{compose_content}}
+```
+
+## .dockerignore
+
+```
+{{dockerignore_content}}
+```
+
+## Build & Run
+
+```bash
+docker build -t {{image_name}} .
+docker run -p {{port}}:{{port}} {{image_name}}
+```

package/dist/templates/templates/journey.md

@@ -0,0 +1,73 @@
+<!-- markdownlint-disable -->
+# {{project_name}} — SDD Journey
+
+> Complete documentation of the Spec-Driven Development process for this project.
+
+---
+
+## 1. Methodology Overview
+
+This project was built using **Spec-Driven Development (SDD)**, a methodology that enforces traceability between requirements, design, implementation, and tests. SDD uses a 10-phase pipeline where each phase builds on the previous one, and every artifact is traceable to a requirement.
+
+### The 10 Phases
+
+| # | Phase | Purpose | Required Artifact |
+|---|-------|---------|-------------------|
+| 1 | Init | Establish project constitution | CONSTITUTION.md |
+| 2 | Discover | Explore problem space | Discovery Q&A |
+| 3 | Specify | Write EARS requirements | SPECIFICATION.md |
+| 4 | Clarify | Resolve ambiguity | Clarification Q&A |
+| 5 | Design | Architecture & system design | DESIGN.md |
+| 6 | Tasks | Implementation breakdown | TASKS.md |
+| 7 | Analyze | Quality gate | ANALYSIS.md |
+| 8 | Implement | Build following the plan | CHECKLIST.md |
+| 9 | Verify | Validate against spec | VERIFICATION.md |
+| 10 | Release | Documentation & deployment | PR + Docs |
+
+---
+
+## 2. Phase-by-Phase Journey
+
+{{phase_journey}}
+
+---
+
+## 3. Quality Gate Results
+
+{{gate_results}}
+
+---
+
+## 4. Diagrams Generated
+
+{{diagrams_summary}}
+
+---
+
+## 5. Architecture Decisions
+
+{{architecture_decisions}}
+
+---
+
+## 6. Traceability Matrix
+
+{{traceability_matrix}}
+
+---
+
+## 7. Metrics & Coverage
+
+{{metrics_summary}}
+
+---
+
+## 8. Lessons & Observations
+
+{{lessons}}
+
+---
+
+**Generated by:** SDD Pipeline v{{version}}
+**Date:** {{date}}
+**Total Phases Completed:** {{phases_completed}}/10

package/dist/templates/templates/onboarding.md

@@ -0,0 +1,49 @@
+<!-- markdownlint-disable -->
+# Developer Onboarding: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+
+---
+
+## Welcome
+
+> This guide helps you understand and contribute to **{{title}}**.
+
+## What This Feature Does
+
+{{feature_description}}
+
+## Architecture Overview
+
+{{architecture_overview}}
+
+## Getting Started
+
+1. Clone the repository
+2. Install dependencies
+3. Read `.specs/{{feature_id}}/SPECIFICATION.md`
+4. Review `.specs/{{feature_id}}/DESIGN.md`
+5. Check `.specs/{{feature_id}}/TASKS.md` for open tasks
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| EARS Notation | Requirements follow the Easy Approach to Requirements Syntax |
+| SDD Pipeline | Spec → Design → Tasks → Implement → Verify |
+| Traceability | Every task traces to a requirement (REQ-XXX-NNN) |
+| Quality Gates | Each phase requires validation before advancing |
+
+## Where to Find Things
+
+| What | Where |
+|------|-------|
+| Requirements | `.specs/{{feature_id}}/SPECIFICATION.md` |
+| Architecture | `.specs/{{feature_id}}/DESIGN.md` |
+| Tasks | `.specs/{{feature_id}}/TASKS.md` |
+| Quality Report | `.specs/{{feature_id}}/ANALYSIS.md` |
+
+## How to Contribute
+
+{{contribution_guide}}

package/dist/templates/templates/research.md

@@ -0,0 +1,39 @@
+<!-- markdownlint-disable -->
+# Research: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+**Status**: {{status}}
+
+---
+
+## Open Questions
+
+{{#each questions}}
+### {{id}}: {{question}}
+
+**Context**: {{context}}
+
+**Findings**: {{findings}}
+
+**Sources**: {{sources}}
+
+**Recommendation**: {{recommendation}}
+
+**Status**: {{status}}
+
+---
+
+{{/each}}
+
+## Summary
+
+| Question | Status | Recommendation |
+|----------|--------|---------------|
+{{#each questions}}
+| {{id}} | {{status}} | {{recommendation}} |
+{{/each}}
+
+## Next Steps
+
+[TODO: next_steps]

package/dist/templates/templates/runbook.md

@@ -0,0 +1,40 @@
+<!-- markdownlint-disable -->
+# Operational Runbook: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+**Version**: {{version}}
+
+---
+
+## Deployment
+
+{{deployment_steps}}
+
+## Health Checks
+
+| Endpoint | Expected | Interval |
+|----------|----------|----------|
+{{#each health_checks}}
+| {{endpoint}} | {{expected}} | {{interval}} |
+{{/each}}
+
+## Monitoring & Alerts
+
+{{monitoring}}
+
+## Troubleshooting
+
+| Symptom | Cause | Resolution |
+|---------|-------|-----------|
+{{#each troubleshooting}}
+| {{symptom}} | {{cause}} | {{resolution}} |
+{{/each}}
+
+## Rollback Procedure
+
+{{rollback}}
+
+## Contacts
+
+{{contacts}}

package/dist/templates/templates/specification.md

@@ -0,0 +1,50 @@
+<!-- markdownlint-disable -->
+# {{project_name}} — Specification
+
+> All requirements use **EARS notation** (Easy Approach to Requirements Syntax). Each requirement is testable, unambiguous, and traceable to the Constitution's success criteria.
+
+---
+
+## Table of Contents
+
+- [1. Core Requirements](#1-core-requirements)
+- [2. Functional Requirements](#2-functional-requirements)
+- [3. Non-Functional Requirements](#3-non-functional-requirements)
+- [Acceptance Criteria Summary](#acceptance-criteria-summary)
+
+---
+
+## 1. Core Requirements
+
+{{requirements_core}}
+
+---
+
+## 2. Functional Requirements
+
+{{requirements_functional}}
+
+---
+
+## 3. Non-Functional Requirements
+
+{{requirements_nonfunctional}}
+
+---
+
+## Acceptance Criteria Summary
+
+| ID | Requirement | Test Method |
+|----|-------------|-------------|
+{{acceptance_criteria_table}}
+
+---
+
+## Self-Assessment
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| EARS notation compliance | {{ears_compliance}} | |
+| Testability | {{testability_score}} | Every requirement has acceptance criteria |
+| Traceability | {{traceability_score}} | Every requirement traces to Constitution |
+| Uniqueness of IDs | {{uniqueness_score}} | No duplicate requirement IDs |

package/dist/templates/templates/sync-report.md

@@ -0,0 +1,44 @@
+<!-- markdownlint-disable -->
+# Sync Report: {{project_name}}
+
+> Drift analysis between specification and implementation.
+
+---
+
+## Summary
+
+- **In Sync:** {{in_sync}}
+- **Last Checked:** {{last_checked}}
+- **Drift Items:** {{drift_count}}
+
+---
+
+## Requirements Coverage
+
+| Requirement | Implementation | Status |
+|-------------|---------------|--------|
+{{coverage_table}}
+
+---
+
+## Drift Items
+
+{{#each drift_items}}
+- {{this}}
+{{/each}}
+
+---
+
+## Orphan Code
+
+Files not traced to any requirement:
+
+{{#each orphan_files}}
+- {{this}}
+{{/each}}
+
+---
+
+## Recommendation
+
+{{recommendation}}

package/dist/templates/templates/tasks.md

@@ -0,0 +1,39 @@
+<!-- markdownlint-disable -->
+# {{project_name}} — Tasks
+
+> Sequenced implementation tasks with pre-implementation gates, `[P]` parallel markers, effort estimates, and requirement traceability.
+
+---
+
+## Pre-Implementation Gates
+
+Before writing any code, the following gates must pass:
+
+{{#each gates}}
+- [ ] {{this}}
+{{/each}}
+
+---
+
+## Task Breakdown
+
+| ID | Task | [P] | Effort | Depends On | Traces To |
+|----|------|-----|--------|------------|-----------|
+| {{task_table}} | | | | | |
+
+---
+
+## Dependency Graph
+
+```
+{{dependency_graph}}
+```
+
+---
+
+## Effort Summary
+
+| Phase | Tasks | Parallel | Effort |
+|-------|-------|----------|--------|
+| {{effort_summary}} | | | |
+| **Total** | **{{total_tasks}}** | **{{parallel_tasks}}** | **{{total_effort}}** |

package/dist/templates/templates/terraform.md

@@ -0,0 +1,38 @@
+<!-- markdownlint-disable -->
+# Infrastructure as Code: {{title}}
+
+**Feature**: {{feature_id}}
+**Provider**: {{provider}}
+**Cloud**: {{cloud}}
+**Date**: {{date}}
+
+---
+
+## Modules
+
+{{#each modules}}
+### {{name}}
+
+{{description}}
+
+**Resources**: {{resources}}
+
+{{/each}}
+
+## Variables
+
+| Name | Type | Description | Default | Required |
+|------|------|-------------|---------|----------|
+{{#each variables}}
+| {{name}} | {{type}} | {{description}} | {{default}} | {{required}} |
+{{/each}}
+
+## Architecture Diagram
+
+```mermaid
+{{diagram}}
+```
+
+## Validation
+
+Run `sdd_validate_iac` to validate this configuration via Terraform MCP.

package/dist/templates/templates/test-stub.md

@@ -0,0 +1,34 @@
+# Test Stubs — {{feature_name}}
+
+> Auto-generated by Specky SDD from acceptance criteria in SPECIFICATION.md and TASKS.md.
+
+---
+
+## Framework: {{framework}}
+
+## Traceability
+
+| Test ID | Requirement | Description |
+|---------|-------------|-------------|
+{{#each stubs}}
+| {{id}} | {{requirement_id}} | {{description}} |
+{{/each}}
+
+## Generated File
+
+- **Output:** `{{output_file}}`
+- **Total Tests:** {{total_tests}}
+- **Framework:** {{framework}}
+
+## Next Steps
+
+1. Open the generated test file at `{{output_file}}`
+2. Replace each `TODO: implement test` placeholder with real assertions
+3. Run your test suite to verify all stubs execute
+4. Map each passing test back to its requirement ID for traceability
+
+## Notes
+
+- Each test stub traces to an acceptance criterion from SPECIFICATION.md
+- Test IDs (TC-001, TC-002, ...) map to requirement IDs (REQ-001, REQ-002, ...)
+- Stubs are intentionally minimal — add setup, teardown, and assertions as needed

package/dist/templates/templates/user-stories.md

@@ -0,0 +1,39 @@
+<!-- markdownlint-disable -->
+# User Stories: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+**Total Stories**: {{total_count}}
+
+---
+
+{{#each stories}}
+## {{id}}: {{title}} (Priority: {{priority}})
+
+{{description}}
+
+### Acceptance Criteria
+
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+### Independent Test
+
+{{independent_test}}
+
+### User Flow
+
+```mermaid
+{{flow_diagram}}
+```
+
+---
+
+{{/each}}
+
+## Overview Diagram
+
+```mermaid
+{{overview_diagram}}
+```

package/dist/templates/templates/verification.md

@@ -0,0 +1,33 @@
+<!-- markdownlint-disable -->
+# Task Verification Report: {{title}}
+
+**Feature**: {{feature_id}}
+**Date**: {{date}}
+**Pass Rate**: {{pass_rate}}%
+
+---
+
+## Verification Results
+
+| Task | Claimed | Verified | Phantom? | Evidence |
+|------|---------|----------|----------|----------|
+{{#each results}}
+| {{task_id}} | {{claimed_status}} | {{verified_status}} | {{phantom}} | {{evidence}} |
+{{/each}}
+
+## Summary
+
+- **Total Tasks**: {{total_tasks}}
+- **Verified**: {{verified_count}}
+- **Phantom Completions**: {{phantom_count}}
+- **Pass Rate**: {{pass_rate}}%
+
+## Diagram
+
+```mermaid
+{{diagram}}
+```
+
+## Gate Decision
+
+{{gate_decision}}