@leeovery/claude-technical-workflows 2.0.9 → 2.0.10

package/README.md

@@ -5,25 +5,16 @@
 </p>
 
 <p align="center">
-  <a href="#how-do-i-use-this">How to Use</a> •
+  <a href="#what-is-this">What is this?</a> •
+  <a href="#how-do-i-use-it">How to Use</a> •
   <a href="#installation">Installation</a> •
-  <a href="#the-six-phase-workflow">Workflow</a> •
   <a href="#skills">Skills</a> •
-  <a href="#commands">Commands</a> •
-  <a href="#how-it-works">How It Works</a> •
   <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-## Versions
-
-| Version | Package Manager | Status     | Branch                                                                 |
-|---------|-----------------|------------|------------------------------------------------------------------------|
-| 2.x     | npm             | **Active** | `main`                                                                 |
-| 1.x     | Composer        | Deprecated | [`v1`](https://github.com/leeovery/claude-technical-workflows/tree/v1) |
-
-## About
+## What is this?
 
 A six-phase workflow for Claude Code that captures context, decisions, and rationale before any code is written, then implements and validates the work against those artifacts.
 
@@ -47,7 +38,22 @@ Review         → Validate against spec
 
 **Model compatibility:** These skills have been developed and refined for Claude Code running on **Opus 4.5**. Different models may exhibit different edge cases, and future model releases may require adjustments to the prompts and workflows.
 
-## How do I use this?
+### Quick Install
+
+**Marketplace** (cached globally):
+```
+/plugin marketplace add leeovery/claude-plugins-marketplace
+/plugin install claude-technical-workflows@claude-plugins-marketplace
+```
+
+**npm** (copied to your repo):
+```bash
+npm install -D @leeovery/claude-technical-workflows
+```
+
+See [Installation](#installation) for details and trade-offs.
+
+## How do I use it?
 
 You have two entry points:
 
@@ -84,12 +90,10 @@ Run the command directly or ask Claude to run it. Each command gathers the conte
 
 ## Installation
 
-Two installation methods are available:
-
-| Method | Best for | Trade-off |
-|--------|----------|-----------|
-| **Marketplace** | Local Claude Code | Simple install, skills cached globally |
-| **npm** | Claude Code for Web | Skills copied to repo, requires npm |
+| Method | Where files live | Best for |
+|--------|------------------|----------|
+| **Marketplace** | `~/.claude/plugins/` (global cache) | Quick setup, don't need files in repo |
+| **npm** | `.claude/` in your project | Ownership, version control, Claude Code for Web |
 
 ### Option 1: Claude Marketplace
 
@@ -98,15 +102,15 @@ Two installation methods are available:
 /plugin install claude-technical-workflows@claude-plugins-marketplace
 ```
 
-> **Note:** Marketplace plugins are cached globally (`~/.claude/plugins/`) and won't be available in Claude Code for Web since files aren't in your repository.
+Skills are cached globally. They won't be available in Claude Code for Web since files aren't in your repository.
 
-### Option 2: npm (Recommended for Web)
+### Option 2: npm
 
 ```bash
 npm install -D @leeovery/claude-technical-workflows
 ```
 
-Skills are copied to `.claude/` in your project and can be committed to your repository—making them available in Claude Code for Web.
+Skills are copied to `.claude/` and can be committed—giving you ownership and making them available everywhere including Claude Code for Web.
 
 <details>
 <summary>pnpm users</summary>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-implementation/SKILL.md

@@ -22,12 +22,18 @@ You're at step 5. Execute the plan. Don't re-debate decisions.
 
 ## Hard Rules
 
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
 1. **No code before tests** - Write the failing test first. Always.
-2. **No test changes to pass** - If code doesn't pass, fix the code. Tests can only be fixed if genuinely broken or poorly designed, never to accommodate broken code.
+2. **No test changes to pass** - Fix the code, not the test.
 3. **No scope expansion** - If it's not in the plan, don't build it.
 4. **No assumptions** - Uncertain? Check specification. Still uncertain? Stop and ask.
 5. **Commit after green** - Every passing test = commit point.
 
+**Pragmatic TDD**: The discipline is test-first sequencing, not artificial minimalism. Write complete, functional implementations - don't fake it with hardcoded returns. "Minimal" means no gold-plating beyond what the test requires.
+
+See **[tdd-workflow.md](references/tdd-workflow.md)** for the full TDD cycle, violation recovery, and guidance on when tests can change.
+
 ## Workflow
 
 ### IMPORTANT: Setup Instructions
@@ -50,24 +56,20 @@ Complete ALL setup steps before proceeding to implementation work.
    - Load the output adapter: `skills/technical-planning/references/output-{format}.md`
    - Follow the **Implementation** section for how to read tasks and update progress
 
-3. **Validate scope** (if specific phase or task was requested)
+3. **Read the TDD workflow** - Load **[tdd-workflow.md](references/tdd-workflow.md)** before writing any code. This is mandatory.
+
+4. **Validate scope** (if specific phase or task was requested)
    - If the requested phase or task doesn't exist in the plan, STOP immediately
    - Ask the user for clarification - don't assume or proceed with a different scope
    - Wait for the user to either correct the scope or ask you to stop
 
-4. **For each phase**:
-   - Announce phase start
-   - Review phase acceptance criteria
-   - For each task:
-     - Derive test from task's micro acceptance criteria
-     - Write failing test
-     - Implement minimal code to pass
-     - Refactor if needed (only when green)
-     - Commit
+5. **For each phase**:
+   - Announce phase start and review acceptance criteria
+   - For each task: follow the TDD cycle loaded in step 3
    - Verify all phase acceptance criteria met
    - **Ask user before proceeding to next phase**
 
-5. **Reference specification** when rationale unclear
+6. **Reference specification** when rationale unclear
 
 ## Progress Announcements
 

package/skills/technical-implementation/references/environment-setup.md

@@ -62,7 +62,7 @@ Each output adapter contains prerequisites and installation instructions for tha
 
 ## Example Setup Document
 
-```markdown
+````markdown
 # Environment Setup
 
 Instructions for setting up the implementation environment.
@@ -100,4 +100,4 @@ Run tests to verify setup:
 ```bash
 php artisan test
 ```
-```
+````

package/skills/technical-implementation/references/plan-execution.md

@@ -21,7 +21,7 @@ Plans live in `docs/workflow/planning/{topic}.md` with phases and tasks.
 
 For each phase:
 1. Announce phase start with acceptance criteria
-2. For each task: derive test → write failing test → implement → commit
+2. For each task: follow the TDD cycle in **[tdd-workflow.md](tdd-workflow.md)**
 3. Verify all acceptance criteria met
 4. **Wait for user confirmation before next phase**
 

package/skills/technical-implementation/references/tdd-workflow.md

@@ -8,56 +8,76 @@
 
 RED → GREEN → REFACTOR → COMMIT
 
-Repeat for each task.
+Repeat for each task. **Never skip steps. Never reorder.**
+
+### Pragmatic TDD
+
+This is pragmatic TDD, not purist. The mandatory discipline is **test-first sequencing**:
+- You MUST write a failing test before implementation
+- You MUST see it fail for the right reason
+- You MUST NOT change tests to make broken code pass
+
+But write **complete, functional implementations** - don't artificially minimize with hardcoded returns or fake values that you'll "fix later". "Minimal" means no gold-plating beyond what the test requires, not "return 42 and triangulate".
+
+## TDD Violation Recovery
+
+**If you catch yourself violating TDD, stop immediately and recover:**
+
+| Violation | Recovery |
+|-----------|----------|
+| Wrote code before test | DELETE the code. Write the failing test. Then rewrite the code. |
+| Multiple failing tests | Comment out all but one. Fix that one. Uncomment next. |
+| Test passes immediately | Suspicious. Verify the test actually exercises your code. Check for false positives. |
+| Changed test to make code pass | REVERT the test change. Fix the implementation instead. |
+| "While I'm here" improvement | STOP. Is it in the plan? No? Don't do it. |
+
+**These are not suggestions. Skipping recovery corrupts the entire TDD discipline.**
 
 ## RED: Write Failing Test
 
 1. Read task's micro acceptance criteria
 2. Write test asserting that behavior
-3. Run test - must fail
-4. Verify it fails for the right reason
+3. Run test - **MUST fail**
+4. Verify it fails for the **right reason** (not syntax error, not missing import)
 
 **Derive tests from plan**: Task's micro acceptance becomes your first test. Edge cases become additional tests.
 
 **Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria.
 
-## GREEN: Minimal Implementation
+**No implementation code exists yet.** If you're tempted to "just sketch out the class first" - don't. The test comes first. Always.
 
-Write the simplest code that passes:
-- No extra features
+## GREEN: Implementation
+
+Write complete, functional code that passes:
+- No extra features beyond what the test requires
 - No "while I'm here" improvements
 - No edge cases not yet tested
 
-If you think "I should also handle X" - stop. Write a test for X first.
+If you think "I should also handle X" - STOP. Write a test for X first.
 
-**One test at a time**: Write → Pass → Commit → Next
+**One test at a time**: Write test → Run (fails) → Implement → Run (passes) → Commit → Next
 
 ## REFACTOR: Only When Green
 
 **Do**: Remove duplication, improve naming, extract methods
 **Don't**: Touch code outside current task, optimize prematurely
 
-Run tests after. If they fail, undo.
+Run tests after. If they fail, undo the refactor.
 
 ## COMMIT: After Every Green
 
-Commit with descriptive message referencing the task.
+Commit with descriptive message referencing the task. This is non-negotiable - it creates recovery points.
 
 ## When Tests CAN Change
 
-- Genuine bug in test
-- Tests implementation not behavior
+- Genuine bug in test logic
+- Test asserts implementation details, not behavior
 - Missing setup/fixtures
 
 ## When Tests CANNOT Change
 
-- To make broken code pass (fix the code)
-- To avoid difficult work (the test is the requirement)
-- To skip temporarily (fix or escalate)
-
-## Red Flags
+- To make broken code pass → **fix the code**
+- To avoid difficult implementation → **the test IS the requirement**
+- To skip temporarily → **fix it now or escalate**
 
-- Wrote code before test → delete code, write test first
-- Multiple failing tests → work on one at a time
-- Test passes immediately → investigate
-- Changing tests frequently → design unclear, review plan
+Changing a test to pass is admitting the implementation is wrong and hiding it. Don't.