@abdullah-alnahas/claude-sdd 0.6.0 → 0.8.0

package/skills/spec-first/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: Spec-First Development
 description: >
-  This skill guides interactive specification development, turning rough ideas into formal documents before
-  any code is written. It should be used when the user is starting a new project or feature, wants to create
-  specs or plans, is adopting an existing project, or says things like "I want to build something," "let's
-  plan this out," "write a spec for this," or "let's design this first."
+  Use when starting a new project or feature, creating specs or plans, adopting an existing project,
+  or when the user says "I want to build something," "let's plan this out," "write a spec," or
+  "let's design this first." Use before any non-trivial implementation that lacks a spec.
 ---
 
 # Spec-First Development
@@ -64,6 +63,7 @@ For existing projects, use the adoption flow instead of starting from scratch. S
 
 - **architecture-aware** — for deeper architectural guidance during Stage 4
 - **tdd-discipline** — for test planning from behavior specs (use `references/templates/test-plan.md`)
+- **iterative-execution** — delivers features against the specs produced here
 - **guardrails** — enforces spec-first as a pre-implementation check
 
 ## References

package/skills/tdd-discipline/SKILL.md

@@ -1,16 +1,19 @@
 ---
 name: TDD Discipline
 description: >
-  This skill enforces test-driven development discipline with the Red/Green/Refactor cycle and traceability
-  from behavior spec to test to code. It should be used when the user asks to write tests, add test coverage,
-  discuss testing strategy, fix a bug, or says "how should I test this?", "add tests for this," "write tests first,"
-  "fix this bug," or "debug this."
+  Use when writing tests, adding test coverage, fixing bugs, debugging, or when any new code needs
+  to be written. Use when the user says "write tests," "add tests," "fix this bug," "debug this,"
+  or "how should I test this?"
 ---
 
 # 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.
 
+## Spirit vs. Letter
+
+The spirit of TDD is: **know what correct behavior looks like before writing the code.** The Red/Green/Refactor cycle is the mechanism, but the principle is that you define "done" before you start. If a situation genuinely doesn't benefit from a test-first approach (see "When TDD Is Overhead" below), skip the mechanism — but never skip the principle of defining expected behavior first.
+
 ## Red → Green → Refactor
 
 1. **Red**: Write a failing test that describes the desired behavior
@@ -19,6 +22,21 @@ Tests are not an afterthought — they are the first expression of intent. Write
 
 This cycle applies at every level: unit, integration, e2e.
 
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're about to skip TDD:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll write tests after the code works" | That's test-after, not TDD. Write the test first. |
+| "This is too simple to need a test" | Simple code with no test becomes complex code with no test. |
+| "I know this works, I'll just verify manually" | Manual verification doesn't persist. Tests do. |
+| "The test is obvious, I'll skip to code" | If it's obvious, it takes 30 seconds to write. Do it. |
+| "I need to see the code structure first" | Write the test to discover the structure. That's the point. |
+| "This is just a refactor, tests already pass" | Run the tests. Confirm they pass. Then refactor. |
+| "Writing a test for this would be too complex" | If you can't test it, you can't verify it. Simplify the design. |
+| "I'll add tests in the next iteration" | Next iteration never comes. Write them now. |
+
 ## 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. They are complementary: TDD ensures correctness at the unit level; iterative execution ensures spec satisfaction at the feature level. See the **iterative-execution** skill for the full outer cycle.
@@ -50,13 +68,12 @@ Code: FormHandler.submit()
 
 This chain ensures nothing is built without a reason and nothing specified goes untested. If a test has no spec criterion, either add the criterion to the spec or question whether the test is needed. If a spec criterion has no test, that is a finding — even if the code works.
 
-## References
-
 ## Related Skills
 
 - **iterative-execution** — the outer delivery cycle that uses TDD internally
 - **spec-first** — produces behavior specs that drive test design (see `spec-first/references/templates/test-plan.md`)
 - **guardrails** — enforces TDD during implementation
+- **performance-optimization** — uses TDD to preserve correctness during optimization
 
 ## References
 

package/skills/using-sdd/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: Using SDD
+description: >
+  Use at the start of every session and before every response to determine which SDD skills apply.
+  This is the meta-skill — it teaches skill discovery and invocation discipline.
+---
+
+# Using SDD Skills
+
+You have access to SDD (Spec-Driven Development) skills that enforce development discipline. **Check for applicable skills before every response.**
+
+## The Rule
+
+**Invoke relevant skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should check. If it turns out to be wrong for the situation, you don't need to use it.
+
+## Available Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| **guardrails** | ANY coding task — implement, build, fix, refactor, add, change, modify |
+| **spec-first** | New project/feature, creating specs/plans, adopting a project |
+| **tdd-discipline** | Writing tests, adding coverage, fixing bugs, debugging |
+| **iterative-execution** | Implementing a feature from spec, iterating to match requirements |
+| **architecture-aware** | Structuring code, design patterns, component integration, ADRs |
+| **performance-optimization** | Optimizing, profiling, speeding up, reducing resource usage |
+
+## Skill Priority Order
+
+When multiple skills apply, use this order:
+
+1. **Guardrails first** — always active for any coding task. This is the discipline layer.
+2. **Process skills second** (spec-first, tdd-discipline, iterative-execution) — these determine HOW to approach the task.
+3. **Domain skills third** (architecture-aware, performance-optimization) — these provide specialized guidance.
+
+## Rationalization Red Flags
+
+These thoughts mean STOP — you're rationalizing skipping a skill:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions about code are tasks. Check guardrails. |
+| "I need more context first" | Skill check comes BEFORE exploration. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can just do this quickly" | Quick work is where discipline matters most. |
+| "This doesn't need a formal skill" | If a skill exists for this task type, use it. |
+| "I remember the skill" | Skills evolve. Read the current version. |
+| "This doesn't count as implementation" | If you're changing code, guardrails apply. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "The user said to skip guardrails" | Only `/sdd-yolo` disables guardrails. Verbal requests don't count. |
+| "I already know what to do" | Knowing the task ≠ following the discipline. |
+
+## Context Modes
+
+SDD supports three context modes that adjust which guardrails are active. Switch with `/sdd-mode <mode>`.
+
+| Mode | Pre-Implementation | Completion Review | Scope Guard | Use For |
+|------|-------------------|-------------------|-------------|---------|
+| **dev** (default) | Active | Active | Strict | Building, implementing, fixing |
+| **review** | Skipped | Active | Normal | Code review, auditing, verification |
+| **research** | Skipped | Skipped | Relaxed | Exploring, investigating, prototyping |
+
+## Skill Classification
+
+**Rigid skills** (follow exactly, don't adapt away discipline):
+- guardrails
+- tdd-discipline
+
+**Flexible skills** (adapt principles to context):
+- spec-first
+- architecture-aware
+- iterative-execution
+- performance-optimization
+
+## Spirit vs. Letter
+
+Follow the **spirit** of each skill, not just its checklist. The goal is disciplined development that produces correct, simple, spec-compliant code. If following a checklist item mechanically would produce worse results than thoughtful application of the principle behind it, follow the principle. But this is never an excuse to skip steps — it's a reason to apply them thoughtfully.
+
+## References
+
+See: `references/skill-creation-process.md`

package/skills/using-sdd/references/skill-creation-process.md

@@ -0,0 +1,54 @@
+# Skill Creation Process
+
+Creating new SDD skills follows a RED/GREEN/REFACTOR approach — the same TDD discipline applied to the skills themselves.
+
+## RED: Identify the Failure
+
+Before writing a skill, you need evidence of a failure pattern:
+
+1. **Observe the failure** — identify a specific, repeatable behavior problem (e.g., the agent skips verification, over-engineers, ignores specs)
+2. **Document the failure** — write down exactly what went wrong, with concrete examples
+3. **Pressure test** — verify this isn't a one-off. Does it happen across different tasks, projects, or prompts?
+
+If you can't reproduce the failure consistently, you don't need a skill yet. You need more data.
+
+## GREEN: Write the Minimal Skill
+
+Write the smallest skill that addresses the failure:
+
+1. **Frontmatter** — name + CSO-format description ("Use when..." with trigger conditions only)
+2. **One core principle** — the single behavioral change needed
+3. **Detection** — how the agent recognizes it's about to fail
+4. **Response** — what the agent should do instead
+5. **Rationalization table** — 4-8 entries mapping excuses to counters
+
+The skill should be under 500 words at this stage. If it's longer, you're solving too many problems at once.
+
+## REFACTOR: Plug Loopholes
+
+Deploy the minimal skill and observe:
+
+1. **Does the agent follow it?** If not, the trigger conditions in the description may be wrong — fix them.
+2. **Does the agent rationalize around it?** Add entries to the rationalization table for each observed excuse.
+3. **Does it create new problems?** If the skill causes over-correction (e.g., too rigid in cases where flexibility is needed), add "When This Skill Is Overhead" section.
+4. **Is it too broad?** Split into focused skills. One skill should address one failure pattern cluster.
+
+## Checklist
+
+Before shipping a new skill:
+
+- [ ] Failure pattern documented with 3+ examples
+- [ ] Description uses "Use when..." CSO format
+- [ ] Rationalization table has 4+ entries
+- [ ] Skill body under 3000 words
+- [ ] References directory exists (even if empty initially)
+- [ ] Added to `using-sdd` skill table
+- [ ] Added to `scripts/verify-skills.sh` SKILLS array
+- [ ] Rigid vs. flexible classification documented in `using-sdd`
+
+## Anti-Patterns
+
+- **Speculative skills**: Writing a skill for a problem you haven't observed yet
+- **Kitchen-sink skills**: Cramming multiple unrelated concerns into one skill
+- **Checklist-only skills**: Lists of rules without detection/response guidance
+- **Aspirational skills**: Describing ideal behavior without addressing the specific failure that motivated the skill