From 3491e8f483dd2e941c4794c56da5745d5f6a50da Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Dec 2025 08:02:28 +0000 Subject: [PATCH 1/4] Update README with four-phase workflow and new skills/commands - Update workflow diagram from 3 to 4 phases (adding Review) - Add technical-implementation skill (Phase 3: TDD execution) - Add technical-review skill (Phase 4: validation against artifacts) - Add /start-planning command for initiating planning sessions - Update descriptions to reflect current skill capabilities --- README.md | 82 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index beafaf592..e5c5d179b 100644 --- a/README.md +++ b/README.md @@ -31,33 +31,35 @@ composer require --dev leeovery/claude-technical-workflows That's it. The [Claude Manager](https://github.com/leeovery/claude-manager) handles everything else automatically. -## The Three-Phase Workflow +## The Four-Phase Workflow -This package enforces a deliberate progression through three distinct phases: +This package enforces a deliberate progression through four distinct phases: ``` -┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ Discussion │ ──▶ │ Planning │ ──▶ │ Implementation │ -│ (Phase 1) │ │ (Phase 2) │ │ (Phase 3) │ -├─────────────────┤ ├─────────────────┤ ├─────────────────┤ -│ WHAT and WHY │ │ HOW │ │ DOING │ -│ │ │ │ │ │ -│ • Architecture │ │ • Phases │ │ • Actual code │ -│ • Decisions │ │ • Structure │ │ • Tests │ -│ • Edge cases │ │ • Code examples │ │ • Integration │ -│ • Debates │ │ • Dependencies │ │ │ -│ • Rationale │ │ • Rollback plan │ │ │ -└─────────────────┘ └─────────────────┘ └─────────────────┘ - ▲ ▲ ▲ - │ │ │ -technical-discussion technical-planning (your workflow) +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Discussion │ ──▶ │ Planning │ ──▶ │ Implementation │ ──▶ │ Review │ +│ (Phase 1) │ │ (Phase 2) │ │ (Phase 3) │ │ (Phase 4) │ +├─────────────────┤ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ +│ WHAT and WHY │ │ HOW │ │ DOING │ │ VALIDATING │ +│ │ │ │ │ │ │ │ +│ • Architecture │ │ • Phases │ │ • Tests first │ │ • Plan check │ +│ • Decisions │ │ • Tasks │ │ • Then code │ │ • Decision check│ +│ • Edge cases │ │ • Acceptance │ │ • Commit often │ │ • Test quality │ +│ • Debates │ │ criteria │ │ • Phase gates │ │ • Code quality │ +│ • Rationale │ │ • Output format │ │ │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ + ▲ ▲ ▲ ▲ + │ │ │ │ + technical-discussion technical-planning technical-implementation technical-review ``` **Phase 1 - Discussion:** Captures the back-and-forth exploration of a problem. Documents competing solutions, why certain approaches won or lost, edge cases discovered, and the journey to decisions—not just the decisions themselves. -**Phase 2 - Planning:** Transforms discussion documentation into actionable implementation plans with phases, code examples, testing strategies, and rollback procedures. +**Phase 2 - Planning:** Transforms discussion documentation into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear, Backlog.md). -**Phase 3 - Implementation:** Actual coding (outside this package's scope). The plans from Phase 2 provide clear guidance for execution. +**Phase 3 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, and stops for user approval between phases. + +**Phase 4 - Review:** Validates completed work against discussion decisions and plan acceptance criteria. Provides structured feedback without fixing code directly. ## How It Works @@ -89,7 +91,9 @@ docs/specs/ | Skill | Phase | Description | |-------|-------|-------------| | [**technical-discussion**](skills/technical-discussion/) | 1 | Document technical discussions as expert architect and meeting assistant. Captures context, decisions, edge cases, competing solutions, debates, and rationale. | -| [**technical-planning**](skills/technical-planning/) | 2 | Transform discussion documents into actionable implementation plans with phases, code examples, testing strategies, and rollback procedures. | +| [**technical-planning**](skills/technical-planning/) | 2 | Transform discussion documents into actionable implementation plans with phases, tasks, and acceptance criteria. Supports draft and formal planning paths. | +| [**technical-implementation**](skills/technical-implementation/) | 3 | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval. | +| [**technical-review**](skills/technical-review/) | 4 | Review completed implementation against discussion decisions and plan acceptance criteria. Produces structured feedback without fixing code. | ### technical-discussion @@ -109,7 +113,7 @@ Acts as both **expert software architect** (participating in discussions) and ** ### technical-planning -Converts discussion documentation into structured implementation plans. +Converts discussion documentation into structured implementation plans. Offers two paths: draft planning (collaborative specification building) or formal planning (direct to phases and tasks). **Use when:** - Ready to plan implementation after discussions @@ -118,9 +122,38 @@ Converts discussion documentation into structured implementation plans. **What it produces:** - Phased implementation plans with specific tasks -- Code examples (pseudocode or actual code in plan docs) -- Testing strategies derived from edge cases -- Rollback procedures +- Acceptance criteria at phase and task levels +- Multiple output formats: local markdown, Linear, or Backlog.md + +### technical-implementation + +Executes plans through strict TDD. Acts as an expert senior developer who builds quality software through disciplined test-driven development. + +**Use when:** +- Implementing a plan from `docs/specs/plans/` +- Ad hoc coding that should follow TDD and quality standards +- Bug fixes or features benefiting from structured implementation + +**Hard rules:** +- No code before tests—write the failing test first +- No test changes to pass—fix the code, not the tests +- No scope expansion—if it's not in the plan, don't build it +- Commit after green—every passing test is a commit point + +### technical-review + +Reviews completed work with fresh perspective. Validates implementation against prior workflow artifacts without fixing code directly. + +**Use when:** +- Implementation phase is complete +- User wants validation before merging/shipping +- Quality gate check needed after implementation + +**What it checks:** +- Were discussion decisions followed? +- Were all plan acceptance criteria met? +- Do tests actually verify requirements? +- Does code follow project conventions? ## Commands @@ -129,6 +162,7 @@ Slash commands to quickly invoke the workflow. | Command | Description | |---------|-------------| | [**/start-discussion**](commands/start-discussion.md) | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation. | +| [**/start-planning**](commands/start-planning.md) | Start a planning session from an existing discussion. Discovers available discussions, offers draft vs formal planning paths, and supports multiple output formats (markdown, Linear, Backlog.md). | ## Requirements From 21c63e9beda657d4e7b6101e36b22f2865c96fe8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Dec 2025 08:04:17 +0000 Subject: [PATCH 2/4] Update About section and nav link for four-phase workflow - Fix workflow nav link to point to #the-four-phase-workflow - Update About paragraph to include review phase in workflow description --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e5c5d179b..a6d3f8c3f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

Installation • - Workflow • + Workflow • Skills • Commands • How It Works • @@ -17,7 +17,7 @@ ## About -A structured approach to technical discussions and implementation planning with Claude Code. These skills enforce a deliberate **discuss-then-plan-then-implement** workflow that captures context, decisions, and rationale before any code is written. +A structured approach to technical discussions and implementation planning with Claude Code. These skills enforce a deliberate **discuss-then-plan-then-implement-then-review** workflow that captures context, decisions, and rationale before any code is written—then validates the work against those artifacts. **Why this matters:** Complex features benefit from thorough discussion before implementation. These skills help you document the *what* and *why* before diving into the *how*—preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost. From 0f60c76000f49b76efb3eade2e0022e5c98b4326 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Dec 2025 08:09:12 +0000 Subject: [PATCH 3/4] Update start-planning emoji indicators for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ⏳ for concluded discussions awaiting planning - ✅ for concluded discussions with plans already created - ⚠️ remains for exploring discussions (may not be ready) --- commands/start-planning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/commands/start-planning.md b/commands/start-planning.md index 76bd3bb45..d94b86e65 100644 --- a/commands/start-planning.md +++ b/commands/start-planning.md @@ -25,10 +25,10 @@ Show what you found: ``` 📂 Discussions found: - ✅ {topic-1} - Concluded (no plan yet) - ✅ {topic-2} - Concluded (no plan yet) + ⏳ {topic-1} - Concluded (no plan yet) + ⏳ {topic-2} - Concluded (no plan yet) ⚠️ {topic-3} - Exploring (may not be ready) - ✓ {topic-4} - Concluded (plan exists) + ✅ {topic-4} - Concluded (plan exists) Which discussion would you like to create a plan for? ``` From 4f0c716aab63d24566e825939835e9d5a33e68d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Dec 2025 08:10:32 +0000 Subject: [PATCH 4/4] Improve start-planning status labels and add flexibility note - Clearer status text: "ready for planning", "not ready", "plan exists" - Add legend explaining each emoji indicator - Note that users can pick any option or start without a discussion --- commands/start-planning.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/commands/start-planning.md b/commands/start-planning.md index d94b86e65..db4798684 100644 --- a/commands/start-planning.md +++ b/commands/start-planning.md @@ -25,17 +25,19 @@ Show what you found: ``` 📂 Discussions found: - ⏳ {topic-1} - Concluded (no plan yet) - ⏳ {topic-2} - Concluded (no plan yet) - ⚠️ {topic-3} - Exploring (may not be ready) + ⏳ {topic-1} - Concluded (ready for planning) + ⏳ {topic-2} - Concluded (ready for planning) + ⚠️ {topic-3} - Exploring (not ready) ✅ {topic-4} - Concluded (plan exists) Which discussion would you like to create a plan for? ``` -- Highlight "Concluded" discussions without plans as ready -- Warn about "Exploring" discussions (may not be ready for planning) -- Note discussions that already have plans +- ⏳ Concluded discussions without plans are ready for planning +- ⚠️ Exploring discussions may not be ready yet +- ✅ Discussions with existing plans can be extended or revised + +**Note:** You can pick any option—continue an exploring discussion, extend an existing plan, or even start a plan without a prior discussion. Ask: **Which discussion would you like to plan?**