Skip to content

Update README with four-phase workflow and new skills/commands #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leeovery merged 4 commits into from
Dec 11, 2025
Merged

Update README with four-phase workflow and new skills/commands #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3491e8f
Update README with four-phase workflow and new skills/commands
claude Dec 11, 2025
21c63e9
Update About section and nav link for four-phase workflow
claude Dec 11, 2025
0f60c76
Update start-planning emoji indicators for clarity
claude Dec 11, 2025
4f0c716
Improve start-planning status labels and add flexibility note
claude Dec 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 60 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<p align="center">
<a href="#installation">Installation</a> •
<a href="#the-three-phase-workflow">Workflow</a> •
<a href="#the-four-phase-workflow">Workflow</a> •
<a href="#skills">Skills</a> •
<a href="#commands">Commands</a> •
<a href="#how-it-works">How It Works</a> •
Expand All @@ -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.

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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

Expand Down
16 changes: 9 additions & 7 deletions commands/start-planning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-4} - Concluded (plan exists)
⏳ {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?**

Expand Down