@abdullah-alnahas/claude-sdd 0.1.0

package/skills/spec-first/references/templates/app-description.md

@@ -0,0 +1,22 @@
+# App Description: [Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## Problem Statement
+[What problem does this solve? Who has this problem?]
+
+## Users
+[Who are the primary users? Secondary users?]
+
+## Core Value Proposition
+[In one sentence, why does this exist?]
+
+## Success Criteria
+[How do we know this is working? Measurable outcomes.]
+
+## Non-Goals
+[What this explicitly does NOT do.]
+
+## Constraints
+[Deadlines, budget, technical limitations, regulatory requirements.]

package/skills/spec-first/references/templates/architecture.md

@@ -0,0 +1,26 @@
+# Architecture: [Project Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## System Overview
+[High-level description of how the system is structured.]
+
+## Components
+[List major components and their responsibilities.]
+
+| Component | Responsibility | Communication |
+|-----------|---------------|---------------|
+| [Name] | [What it does] | [How it talks to others] |
+
+## Patterns
+[What architectural patterns are used and why.]
+
+## Integration Points
+[External systems, APIs, databases this connects to.]
+
+## Data Flow
+[How data moves through the system.]
+
+## Key Decisions
+[Link to ADRs or list critical architectural decisions with rationale.]

package/skills/spec-first/references/templates/behavior-spec.md

@@ -0,0 +1,28 @@
+# Behavior Spec: [Feature Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## Overview
+[Brief description of the feature/behavior being specified.]
+
+## Acceptance Criteria
+
+### [Scenario Name]
+**Given** [precondition]
+**When** [action]
+**Then** [expected result]
+
+### [Scenario Name]
+**Given** [precondition]
+**When** [action]
+**Then** [expected result]
+
+## Non-Goals
+[What this feature explicitly does NOT do.]
+
+## Edge Cases
+[Known edge cases and expected behavior.]
+
+## Error Handling
+[What happens when things go wrong.]

package/skills/spec-first/references/templates/retrospective.md

@@ -0,0 +1,19 @@
+# Retrospective: [Feature/Project Name]
+
+**Date**: [Date]
+**Duration**: [How long did this take]
+
+## What Went Well
+- [Thing that worked]
+
+## What Didn't Go Well
+- [Thing that was painful or failed]
+
+## What We Learned
+- [Insight for next time]
+
+## Action Items
+- [ ] [Concrete improvement to make]
+
+## Spec Accuracy
+[How well did the spec predict the actual implementation? What was missing or wrong?]

package/skills/spec-first/references/templates/roadmap.md

@@ -0,0 +1,23 @@
+# Roadmap: [Project Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## Phase 1: MVP
+**Goal**: [What ships first and why]
+
+- [ ] [Feature/task]
+- [ ] [Feature/task]
+
+## Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+
+- [ ] [Feature/task]
+- [ ] [Feature/task]
+
+## Deferred
+[Things explicitly not in scope for now, with rationale.]
+
+## Risks
+[What could block progress. Dependencies, unknowns, technical risk.]

package/skills/spec-first/references/templates/stack.md

@@ -0,0 +1,27 @@
+# Stack: [Project Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## Language
+[Primary language and version. Rationale.]
+
+## Framework
+[Framework and version. Why this one.]
+
+## Build & Tooling
+[Build system, linter, formatter, bundler.]
+
+## Testing
+[Test framework, coverage tool, testing strategy.]
+
+## Storage
+[Database, cache, file storage. Why these choices.]
+
+## Deployment
+[Where and how this runs. CI/CD pipeline.]
+
+## Key Dependencies
+| Dependency | Purpose | Version |
+|-----------|---------|---------|
+| [name] | [why] | [version] |

package/skills/spec-first/references/templates/test-plan.md

@@ -0,0 +1,25 @@
+# Test Plan: [Feature Name]
+
+**Version**: 0.1
+**Date**: [Date]
+
+## Strategy
+[Unit, integration, e2e — what level of testing and why.]
+
+## Coverage Goals
+[What percentage/areas must be covered.]
+
+## Test Cases
+
+### Unit Tests
+| Test | Input | Expected Output | Traces to |
+|------|-------|-----------------|-----------|
+| [name] | [input] | [output] | [spec criterion] |
+
+### Integration Tests
+| Test | Components | Expected Behavior | Traces to |
+|------|-----------|-------------------|-----------|
+| [name] | [components] | [behavior] | [spec criterion] |
+
+## Not Tested
+[What's explicitly not tested and why.]

package/skills/tdd-discipline/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: TDD Discipline
+description: >
+  Test-driven development enforcement — Red/Green/Refactor cycle, test co-location, traceability from behavior spec to test to code.
+  Use when writing tests, discussing TDD, coverage, verification, or validation.
+version: 1.0.0
+---
+
+# TDD Discipline
+
+Tests are not an afterthought — they are the first expression of intent. Write the test that describes the behavior, watch it fail, then write the minimum code to make it pass.
+
+## Red → Green → Refactor
+
+1. **Red**: Write a failing test that describes the desired behavior
+2. **Green**: Write the minimum code to make the test pass
+3. **Refactor**: Clean up without changing behavior (tests still pass)
+
+This cycle applies at every level: unit, integration, e2e.
+
+## Relationship to Iterative Execution
+
+TDD is the **inner discipline** — how you write each piece of code. Iterative execution is the **outer cycle** — how you deliver a complete feature against a spec. Every "implement" step in the iterative execution cycle uses TDD internally. They are complementary: TDD ensures code correctness at the unit level; iterative execution ensures spec satisfaction at the feature level.
+
+## When TDD Adds Value
+
+- Business logic with clear inputs/outputs
+- Data transformations
+- State machines
+- API contracts
+- Bug fixes (write a test that reproduces the bug first)
+
+## When TDD Is Overhead
+
+- UI layout/styling (use visual testing instead)
+- Prototype/spike code (throw-away by definition)
+- Simple CRUD with no logic (test the framework, not your code)
+- One-off scripts
+
+## Traceability
+
+Every test should trace back to a behavior spec criterion:
+
+```
+Spec: "Given a logged-in user, when they submit a form, then data is saved"
+Test: test_submit_form_saves_data()
+Code: FormHandler.submit()
+```
+
+This chain ensures nothing is built without a reason and nothing specified goes untested.
+
+## References
+
+See: `references/test-strategies.md`
+See: `references/traceability.md`

package/skills/tdd-discipline/references/test-strategies.md

@@ -0,0 +1,36 @@
+# Test Strategies
+
+## Unit Tests
+**Scope**: Single function or class in isolation.
+**Speed**: Fast (milliseconds).
+**Dependencies**: Mocked/stubbed.
+**Use for**: Pure logic, calculations, transformations, validation rules.
+
+## Integration Tests
+**Scope**: Multiple components working together.
+**Speed**: Medium (seconds).
+**Dependencies**: Real (or realistic fakes).
+**Use for**: API endpoints, database queries, service interactions, middleware chains.
+
+## End-to-End Tests
+**Scope**: Full system from user perspective.
+**Speed**: Slow (seconds to minutes).
+**Dependencies**: All real.
+**Use for**: Critical user journeys, smoke tests, deployment verification.
+
+## Test Doubles
+
+| Type | What it does | When to use |
+|------|-------------|-------------|
+| **Stub** | Returns canned data | When you need predictable input |
+| **Mock** | Verifies interactions | When you need to verify a call was made |
+| **Fake** | Working implementation (simplified) | When stubs are too limited (e.g., in-memory DB) |
+| **Spy** | Records calls for later assertion | When you want to observe without controlling |
+
+## Guidance
+
+- Prefer stubs over mocks — test behavior, not implementation
+- One assertion per test (or one logical assertion)
+- Test names describe the behavior, not the method: `test_expired_token_returns_401` not `test_validateToken`
+- Co-locate tests with source when possible (`foo.ts` → `foo.test.ts`)
+- Don't test private methods — test through the public interface

package/skills/tdd-discipline/references/traceability.md

@@ -0,0 +1,53 @@
+# Traceability — Behavior → Test → Code
+
+## Purpose
+
+Every line of code should trace back to a reason. Traceability ensures:
+- Nothing is built without a spec
+- Nothing specified goes untested
+- Nothing tested lacks implementation
+- Changes can be assessed for impact
+
+## The Trace Chain
+
+```
+Behavior Spec Criterion → Test Case → Implementation Code
+```
+
+Example:
+```
+Spec: "Users can reset their password via email"
+  ↓
+Test: test_password_reset_sends_email()
+Test: test_password_reset_with_invalid_email_returns_error()
+Test: test_password_reset_token_expires_after_1_hour()
+  ↓
+Code: PasswordResetService.initiate()
+Code: PasswordResetService.validateToken()
+```
+
+## Trace Matrix
+
+For critical features, maintain a trace matrix:
+
+| Spec Criterion | Test(s) | Implementation | Status |
+|---------------|---------|----------------|--------|
+| User can reset password | `test_password_reset_*` | `PasswordResetService` | Complete |
+| Reset token expires in 1h | `test_token_expiry` | `TokenValidator.isValid()` | Complete |
+| Invalid email returns error | `test_invalid_email_error` | `PasswordResetService.initiate()` | Complete |
+
+## When to Use Full Traceability
+
+- Safety-critical systems
+- Regulatory requirements
+- Complex business logic
+- Anything where "did we build what was specified?" is a real question
+
+## When Lightweight Tracing Is Fine
+
+- Internal tools
+- Prototypes
+- Simple CRUD
+- Well-understood domains
+
+For lightweight: just ensure test names reference the behavior they verify.