@leeovery/claude-technical-workflows 2.0.9 → 2.0.11

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/commands/start-discussion.md

@@ -1,36 +1,218 @@
 ---
-description: Start a technical discussion using the technical-discussion skill. Gathers information about the topic and creates discussion documentation in docs/workflow/discussion/
+description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
 
-Before beginning, ask the user these questions to properly set up the discussion:
+## Instructions
 
-## Essential Information
+Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
 
-1. **Discussion Topic**: What are we discussing? (This will be used as the filename in `docs/workflow/discussion/{topic}.md`)
+Before beginning, discover existing work and determine the best entry path.
 
-2. **Context & Background**:
-   - What sparked this discussion?
-   - What problem are we trying to solve?
-   - Why are we discussing this now?
+## Important
 
-3. **Foundational Knowledge**:
-   - Is there any background information I need to understand before we begin?
-   - Are there specific concepts, technologies, or architectures I should know about?
-   - Any constraints, requirements, or limitations I should be aware of?
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
-4. **Codebase Review**:
-   - Are there specific files in this repository I should read first?
-   - Should I explore any particular directories or components?
-   - Is there existing code related to this discussion?
+## Step 1: Discover Existing Work
 
-## After Gathering Information
+Scan the codebase for research and discussions:
 
-Once I have this information:
+1. **Find research**: Look in `docs/workflow/research/`
+   - Run `ls docs/workflow/research/` to list research files
+   - Note which files exist (may include `exploration.md` and semantic files like `market-landscape.md`)
+
+2. **Find discussions**: Look in `docs/workflow/discussion/`
+   - Run `ls docs/workflow/discussion/` to list discussion files
+   - Each file is named `{topic}.md`
+
+3. **Check discussion status**: For each discussion file
+   - Run `head -10 docs/workflow/discussion/{topic}.md` to extract the `Status:` field
+   - Status values: `Exploring`, `Deciding`, or `Concluded`
+   - Do NOT use bash loops - run separate commands for each file
+
+## Step 2: Present Workflow State and Options
+
+Present the workflow state and available options based on what was discovered.
+
+**Format:**
+```
+📂 Workflow state:
+  📚 Research: {count} files found / None found
+  💬 Discussions: {count} existing / None yet
+```
+
+Then present the appropriate options:
+
+**If research AND discussions exist:**
+```
+How would you like to proceed?
+
+1. **From research** - Analyze research and suggest undiscussed topics
+2. **Continue discussion** - Resume an existing discussion
+3. **Fresh topic** - Start a new discussion
+```
+
+**If ONLY research exists:**
+```
+How would you like to proceed?
+
+1. **From research** - Analyze research and suggest topics to discuss
+2. **Fresh topic** - Start a new discussion
+```
+
+**If ONLY discussions exist:**
+```
+How would you like to proceed?
+
+1. **Continue discussion** - Resume an existing discussion
+2. **Fresh topic** - Start a new discussion
+```
+
+**If NOTHING exists:**
+```
+Starting fresh - no prior research or discussions found.
+
+What topic would you like to discuss?
+```
+Then skip to Step 5 (Fresh topic path).
+
+Wait for the user to choose before proceeding.
+
+## Step 3A: "From research" Path
+
+Read each research file and analyze the content to extract key themes and potential discussion topics. For each theme:
+- Note the source file and relevant line numbers
+- Summarize what the theme is about in 1-2 sentences
+
+Cross-reference with existing discussions to identify what has and hasn't been discussed.
+
+**Present findings:**
+```
+🔍 Analyzing research documents...
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief 1-2 sentence summary of the theme and what needs deciding}"
+
+  ✨ {Another theme}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+  ✅ {Already discussed theme} → discussed in {topic}.md
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+Which topic would you like to discuss? (Or describe something else)
+```
+
+**Key:**
+- ✨ = Undiscussed topic (potential new discussion)
+- ✅ = Already has a corresponding discussion
+
+**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+
+Wait for the user to choose before proceeding to Step 4.
+
+## Step 3B: "Continue discussion" Path
+
+List existing discussions with their status:
+
+```
+💬 Existing discussions:
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description from context section}"
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description}"
+
+  ✅ {topic}.md — Concluded
+     "{Brief description}"
+
+Which discussion would you like to continue?
+```
+
+**Key:**
+- ⚡ = In progress (Exploring or Deciding)
+- ✅ = Concluded (can still be continued/reopened)
+
+Wait for the user to choose, then proceed to Step 4.
+
+## Step 3C: "Fresh topic" Path
+
+Proceed directly to Step 4.
+
+## Step 4: Gather Context
+
+Gather context based on the chosen path.
+
+**If starting new discussion (from research or fresh):**
+
+```
+## New discussion: {topic}
+
+Before we begin:
+
+1. What's the core problem or decision we need to work through?
+
+2. Any constraints or context I should know about?
+
+3. Are there specific files in the codebase I should review first?
+```
+
+Wait for responses before proceeding.
+
+**If continuing existing discussion:**
+
+Read the existing discussion document first, then ask:
+
+```
+## Continuing: {topic}
+
+I've read the existing discussion.
+
+What would you like to focus on in this session?
+```
+
+Wait for response before proceeding.
+
+## Step 5: Invoke Discussion Skill
+
+Begin the discussion session with appropriate context based on the path taken.
+
+**If from research:**
+```
+Discussion session for: {topic}
+Output: docs/workflow/discussion/{topic}.md
+
+## Research Reference
+Source: docs/workflow/research/{filename}.md (lines {start}-{end})
+Summary: {the 1-2 sentence summary from Step 3A}
+
+Begin discussion using the technical-discussion skill.
+```
+
+**If continuing or fresh:**
+```
+Discussion session for: {topic}
+Source: {existing discussion | fresh}
+Output: docs/workflow/discussion/{topic}.md
+
+Begin discussion using the technical-discussion skill.
+```
+
+**Setup:**
 - Ensure discussion directory exists: `docs/workflow/discussion/`
-- Start documenting the discussion following the technical-discussion skill structure
-- Create file: `docs/workflow/discussion/{topic}.md`
+- If new: Create file using the template structure
+- If continuing: Work with existing file
 - Commit frequently at natural discussion breaks
 
-Ask these questions clearly and wait for responses before proceeding with the discussion.
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- Discussion captures WHAT and WHY - don't jump to specifications or implementation
+- The goal is to work through edge cases, debates, and decisions before planning
+- Commit the discussion document frequently during the session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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.