@leeovery/claude-technical-workflows 2.0.45 → 2.0.46

package/commands/link-dependencies.md

@@ -100,7 +100,7 @@ For each unresolved dependency:
 
 2. **If plan exists**: Load the output format reference file
    - Read `format:` from the dependency plan's frontmatter
-   - Load `skills/technical-planning/references/output-{format}.md`
+   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
    - Follow the "Querying Dependencies" section to search for matching tasks
 
 3. **Handle ambiguous matches**:
@@ -115,7 +115,7 @@ For each resolved match:
    - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
 
 2. **Create dependency in output format**:
-   - Load `skills/technical-planning/references/output-{format}.md`
+   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
    - Follow the "Cross-Epic Dependencies" or equivalent section to create the blocking relationship
 
 ## Step 6: Bidirectional Check

package/commands/workflow/start-discussion.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-implementation.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-planning.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-research.md

@@ -39,7 +39,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-review.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-specification.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 
@@ -324,7 +328,12 @@ Then analyze coupling between discussions:
 - **Behavioral coupling**: Discussions where one's implementation requires another
 - **Conceptual coupling**: Discussions that address different facets of the same problem
 
-Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
+Group discussions into specifications where each grouping represents a **coherent feature or capability that can be independently planned and built** — with clear stages delivering incremental, testable value. Coupling tells you what's related; the grouping decision also requires that the result is the right shape:
+
+- **Tightly coupled discussions belong together** — their decisions are inseparable and would produce interleaved implementation work
+- **Don't group too broadly** — if a grouping mixes unrelated concerns, the resulting specification will produce incoherent stages and tasks that jump between disconnected areas
+- **Don't group too narrowly** — if a grouping is too thin, it may not warrant its own specification, planning, and implementation cycle
+- **Flag cross-cutting discussions** — discussions about patterns or policies (not features) should become cross-cutting specifications rather than being grouped with feature discussions
 
 #### Preserve Anchored Names
 

package/commands/workflow/status.md

@@ -8,7 +8,11 @@ Show the current state of the workflow for this project.
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/view-plan.md

@@ -4,14 +4,6 @@ description: View a plan's tasks and progress, regardless of output format.
 
 Display a readable summary of a plan's phases, tasks, and status.
 
-## Step 0: Run Migrations
-
-**This step is mandatory. You must complete it before proceeding.**
-
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
-
----
-
 ## Step 1: Identify the Plan
 
 If no topic is specified, list available plans:
@@ -31,7 +23,7 @@ Read the plan file from `docs/workflow/planning/{topic}.md` and check the `forma
 Load the corresponding output format reference:
 
 ```
-skills/technical-planning/references/output-{format}.md
+skills/technical-planning/references/output-formats/output-{format}.md
 ```
 
 This reference contains instructions for reading plans in that format.

package/package.json

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

package/skills/technical-discussion/SKILL.md

@@ -21,7 +21,13 @@ Either way: Capture decisions, rationale, competing approaches, and edge cases.
 - **Context** (optional) - Prior research, constraints, existing decisions
 - **Questions to explore** (optional) - Specific architectural questions to address
 
-**If missing:** Will ask user what topic they want to discuss.
+**Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.
+
+- **No topic provided?**
+  > "What topic would you like to discuss? This could be an architectural decision, a design problem, or edge cases to work through — anything that needs structured technical discussion."
+
+- **Topic is broad or ambiguous?**
+  > "You mentioned {topic}. To keep the discussion focused, is there a specific aspect or decision you want to work through first?"
 
 ## What to Capture
 

package/skills/technical-implementation/SKILL.md

@@ -25,7 +25,18 @@ Either way: Execute via strict TDD - tests first, implementation second.
 - **Environment setup** (optional) - First-time setup instructions
 - **Scope** (optional) - Specific phase/task to work on
 
-**If missing:** Will ask user for plan location. If no specification, plan becomes sole authority.
+**Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
+
+- **No plan provided?**
+  > "I need an implementation plan to execute. Could you point me to the plan file (e.g., `docs/workflow/planning/{topic}.md`)?"
+
+- **Plan has no `format` field in frontmatter?**
+  > "The plan at {path} doesn't specify an output format in its frontmatter. Which format does this plan use?"
+
+- **Plan status is not `concluded`?**
+  > "The plan at {path} has status '{status}' — it hasn't completed the review process. Should I proceed anyway, or should the plan be reviewed first?"
+
+If no specification is available, the plan becomes the sole authority for design decisions.
 
 ## Hard Rules
 
@@ -60,7 +71,7 @@ Complete ALL setup steps before proceeding to implementation work.
 
 2. **Read the plan** from the provided location (typically `docs/workflow/planning/{topic}.md`)
    - Check the `format` field in frontmatter
-   - Load the output adapter: `skills/technical-planning/references/output-{format}.md`
+   - Load the output adapter: `skills/technical-planning/references/output-formats/output-{format}.md`
    - If no format field, ask user which format the plan uses
    - Follow the **Implementation** section for how to read tasks and update progress
 

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

@@ -55,7 +55,7 @@ If the environment setup document contains only "No special setup required" (or
 Some plan formats require specific tools. Check the plan's `format` field and load the corresponding output adapter from the planning skill for setup instructions:
 
 ```
-skills/technical-planning/references/output-{format}.md
+skills/technical-planning/references/output-formats/output-{format}.md
 ```
 
 Each output adapter contains prerequisites and installation instructions for that format.

package/skills/technical-planning/SKILL.md

@@ -22,40 +22,103 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Specification content** (required) - The validated decisions and requirements to plan from
 - **Topic name** (optional) - Will derive from specification if not provided
 - **Output format preference** (optional) - Will ask if not specified
-- **Cross-cutting references** (optional) - List of cross-cutting specifications that inform this plan
+- **Cross-cutting references** (optional) - Cross-cutting specifications that inform technical decisions in this plan
 
-**If missing:** Will ask user for specification location or content.
+**Before proceeding**, verify the required input is available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
-### Cross-Cutting References
+- **No specification content provided?**
+  > "I need the specification content to plan from. Could you point me to the specification file (e.g., `docs/workflow/specification/{topic}.md`), or provide the content directly?"
 
-If cross-cutting specifications are provided (e.g., caching strategy, rate limiting policy), incorporate their decisions into the plan:
+- **Specification seems incomplete or not concluded?**
+  > "The specification at {path} appears to be {concern — e.g., 'still in-progress' or 'missing sections that are referenced elsewhere'}. Should I proceed with this, or is there a more complete version?"
 
-1. **Include a "Cross-Cutting References" section** in the plan linking to these specifications
-2. **Apply their patterns** when designing phases and tasks (e.g., if caching strategy says "cache API responses for 5 minutes", include that in relevant tasks)
-3. **Note where patterns apply** - when a task implements a cross-cutting pattern, reference it
+---
 
-Cross-cutting specifications are architectural decisions that inform HOW features are built. They don't have their own implementation plans - instead, their patterns are applied within feature plans.
+## The Process
 
-## Source Material
+Follow every step in sequence. No steps are optional.
 
-**The specification is your sole input.** Everything you need should be in the specification - do not request details from prior source material. If information is missing, ask for clarification on the specification itself.
+---
 
-## The Process
+## Step 1: Choose Output Format
+
+Present the formats from **[output-formats.md](references/output-formats.md)** to the user as written — including description, pros, cons, and "best for" — so they can make an informed choice. Number each format and ask the user to pick a number.
+
+**STOP.** Wait for the user to choose. After they pick, confirm the choice and load the corresponding `output-{format}.md` adapter from **[output-formats/](references/output-formats/)**.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Load Planning Principles
+
+Load **[planning-principles.md](references/planning-principles.md)** — this contains the planning principles, rules, and quality standards that apply throughout the process.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Read Specification Content
+
+Now read the specification content **in full**. Not a scan, not a summary — read every section, every decision, every edge case. The specification must be fully digested before any structural decisions are made. If a document is too large for a single read, read it in sequential chunks until you have consumed the entire file. Never summarise or skip sections to fit within tool limits.
+
+The specification contains validated decisions. Your job is to translate it into an actionable plan, not to review or reinterpret it.
+
+**The specification is your sole input.** Everything you need is in the specification — do not reference other documents or prior source materials. If cross-cutting specifications are provided, read them alongside the specification so their patterns are available during planning.
+
+From the specification, absorb:
+- Key decisions and rationale
+- Architectural choices
+- Edge cases identified
+- Constraints and requirements
+- Whether a Dependencies section exists (you will handle these in Step 7)
 
-**Load**: [formal-planning.md](references/formal-planning.md)
+Do not present or summarize the specification back to the user — it has already been signed off.
 
-**Choose output format**: Ask user which format, then load the appropriate output adapter. See **[output-formats.md](references/output-formats.md)** for available formats.
+→ Proceed to **Step 4**.
 
-**Output**: Implementation plan in chosen format
+---
+
+## Step 4: Define Phases
+
+Load **[steps/define-phases.md](references/steps/define-phases.md)** and follow its instructions as written.
+
+---
+
+## Step 5: Define Tasks
+
+Load **[steps/define-tasks.md](references/steps/define-tasks.md)** and follow its instructions as written.
+
+---
+
+## Step 6: Author Tasks
 
-## Critical Rules
+Load **[steps/author-tasks.md](references/steps/author-tasks.md)** and follow its instructions as written.
 
-**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing.
+---
+
+## Step 7: Resolve External Dependencies
+
+Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
+
+---
+
+## Step 8: Plan Review
+
+Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
+
+---
 
-**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+## Step 9: Conclude the Plan
 
-**Never invent reasoning**: If it's not in the specification, ask again. The specification is the golden document - all plan content must trace back to it.
+After the review is complete:
 
-**Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation.
+1. **Update plan status** — Update the plan frontmatter to `status: concluded`
+2. **Final commit** — Commit the concluded plan
+3. **Present completion summary**:
 
-**Collaborate with the user**: Planning is iterative. Stop and ask when the specification is ambiguous, multiple valid approaches exist, or you're uncertain about task scope. The user expects collaboration - don't guess when you can ask.
+> "Planning is complete for **{topic}**.
+>
+> The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceability against the specification and structural integrity.
+>
+> Status has been marked as `concluded`. The plan is ready for implementation."

package/skills/technical-planning/references/{output-backlog-md.md → output-formats/output-backlog-md.md}

@@ -1,6 +1,6 @@
 # Output: Backlog.md
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -94,8 +94,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -107,7 +107,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {task-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
 
 ### Task File Format
 

package/skills/technical-planning/references/{output-beads.md → output-formats/output-beads.md}

@@ -1,6 +1,6 @@
 # Output: Beads
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -275,8 +275,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -295,7 +295,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {task-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
 
 ## Frontmatter
 

package/skills/technical-planning/references/{output-linear.md → output-formats/output-linear.md}

@@ -1,6 +1,6 @@
 # Output: Linear
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -185,8 +185,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -198,7 +198,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {issue-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
 
 ## Frontmatter
 

package/skills/technical-planning/references/{output-local-markdown.md → output-formats/output-local-markdown.md}

@@ -1,6 +1,6 @@
 # Output: Local Markdown
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -60,8 +60,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 

package/skills/technical-planning/references/output-formats.md

@@ -4,13 +4,40 @@
 
 ---
 
-Plans can be stored in different formats. **Ask the user which format they prefer** - present the benefits from each adapter file and let them decide.
+Plans can be stored in different formats.
 
-**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding `output-*.md` files in this directory.
+**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding `output-*.md` files in the [output-formats/](output-formats/) directory.
 
 ## Available Formats
 
-- **[Local Markdown](output-local-markdown.md)** - Single markdown file, no external tools
-- **[Linear](output-linear.md)** - Linear project with labeled issues (requires MCP)
-- **[Backlog.md](output-backlog-md.md)** - Kanban board with task files
-- **[Beads](output-beads.md)** - Git-backed graph issue tracker for AI agents
+### [Local Markdown](output-formats/output-local-markdown.md)
+
+Single markdown file per topic containing all phases, tasks, and progress tracking inline. No external tools or setup required.
+
+- **Pros**: Zero setup, works offline, human-readable, easy to edit in any text editor
+- **Cons**: No visual board, everything in one file can get long for complex features, no dependency graph
+- **Best for**: Simple features, small plans, quick iterations
+
+### [Linear](output-formats/output-linear.md)
+
+Tasks managed as Linear issues within a Linear project. A thin local plan file points to the Linear project; Linear is the source of truth.
+
+- **Pros**: Visual tracking, team collaboration, real-time updates, integrates with existing Linear workflows
+- **Cons**: Requires Linear account and MCP server, external dependency, not fully local
+- **Best for**: Teams already using Linear, collaborative projects needing shared visibility
+
+### [Backlog.md](output-formats/output-backlog-md.md)
+
+Individual task files in a `backlog/` directory with a local Kanban board. Each task is a self-contained markdown file with frontmatter for status, priority, labels, and dependencies.
+
+- **Pros**: Visual Kanban (terminal + web), individual task files for focused editing, version-controlled, MCP integration, auto-commit
+- **Cons**: Requires npm install, flat directory (phases via labels not folders), external tool dependency
+- **Best for**: Solo developers wanting a local Kanban board with per-task files
+
+### [Beads](output-formats/output-beads.md)
+
+Git-backed graph issue tracker with hierarchical tasks (epics → phases → tasks) and native dependency management. Uses JSONL storage with a CLI interface.
+
+- **Pros**: Native dependency graph, `bd ready` surfaces unblocked work, hierarchical task structure, multi-agent coordination, hash-based IDs prevent merge conflicts
+- **Cons**: Requires CLI install, JSONL not human-editable, learning curve, less familiar tooling
+- **Best for**: Complex multi-phase features with many dependencies, AI-agent-driven workflows

package/skills/technical-planning/references/phase-design.md

@@ -0,0 +1,146 @@
+# Phase Design
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines the principles for breaking specifications into implementation phases. It is loaded when phases are first proposed and stays in context through phase approval.
+
+## What Makes a Good Phase
+
+Each phase should:
+
+- **Deliver a working increment** — not a technical layer, but functionality that can be used or tested end-to-end
+- **Have clear acceptance criteria** — checkboxes that are pass/fail verifiable
+- **Follow natural boundaries** — domain, feature, or capability boundaries, not architectural layers
+- **Leave the system working** — every phase ends with a green test suite and deployable code
+- **Be independently valuable** — if the project stopped after this phase, something useful would exist
+
+---
+
+## The Walking Skeleton
+
+Phase 1 is always a **walking skeleton** — the thinnest possible end-to-end slice that threads through all system layers and proves the architecture works.
+
+The walking skeleton:
+
+- Touches every architectural component the system needs (database, API, UI, external services)
+- Delivers one complete flow, however minimal
+- Establishes the patterns subsequent phases will follow
+- Is production code, not throwaway — it becomes the foundation
+
+**Example** (Slack clone):
+
+> Phase 1: "Any unauthenticated person can post messages in a hardcoded #general room. Messages persist through page refreshes."
+>
+> No auth, no accounts, no multiple rooms. Just the thinnest thread through the entire stack.
+
+**Example** (Calendar app):
+
+> Phase 1: "A single event can be created with title, start, and end time, persisted, and retrieved by ID."
+>
+> No recurrence, no sharing, no notifications. Just one thing working end-to-end.
+
+The skeleton validates architecture assumptions at the cheapest possible moment. If the end-to-end flow doesn't work, you discover it in Phase 1 — not after building three phases of isolated components.
+
+This is the **steel thread** principle: never have big-bang integration. By threading through all layers immediately, integration is the first thing you solve, not the last.
+
+---
+
+## Vertical Phases
+
+After the walking skeleton, each subsequent phase adds complete functionality — a vertical slice through the relevant layers.
+
+**Vertical (prefer):**
+
+```
+Phase 1: Walking skeleton — single event CRUD, end-to-end
+Phase 2: Recurring events — rules, instance generation, single-instance editing
+Phase 3: Sharing and permissions — invite users, permission levels, shared calendars
+Phase 4: Notifications — email and push notifications for event changes
+```
+
+Each phase delivers something a user or test suite can validate independently.
+
+**Horizontal (avoid):**
+
+```
+Phase 1: All database models and migrations
+Phase 2: All service classes and business logic
+Phase 3: All API endpoints
+Phase 4: All UI components
+Phase 5: Wire everything together
+```
+
+Nothing works until Phase 5. No phase is independently testable. Integration risk concentrates at the end.
+
+A phase may touch multiple architectural layers — that's expected. The test is: **does this phase deliver working functionality, or does it deliver infrastructure that only becomes useful later?**
+
+### Progression
+
+**Skeleton → Core features → Edge cases → Refinement**
+
+- **Skeleton** (Phase 1): Thinnest end-to-end slice proving the architecture
+- **Core features**: Each phase adds a complete capability, building on what exists
+- **Edge cases**: Handling boundary conditions, error scenarios, unusual inputs
+- **Refinement**: Performance optimisation, UX polish, hardening
+
+This ordering means each phase builds on a working system. The skeleton establishes the pattern; core features flesh it out; edge cases harden it; refinement polishes it.
+
+---
+
+## Phase Boundaries
+
+A phase boundary belongs where:
+
+- **A meaningful state change occurs** — the system gains a new capability
+- **Human validation is needed** — the approach should be confirmed before building more
+- **The risk profile shifts** — different concerns, different complexity, different unknowns
+- **The work's nature changes** — from core functionality to edge cases, from features to optimisation
+
+### When to split
+
+- The combined work exceeds what can be reasoned about in a single focused session
+- An intermediate state is independently valuable or testable
+- You need a checkpoint to validate before investing further
+- Different parts have different risk or uncertainty levels
+
+### When to keep together
+
+- High cohesion — changes to one part directly affect the other
+- The intermediate state has no independent value
+- Splitting would create phases that aren't meaningful milestones
+- The overhead of phase management exceeds the benefit
+
+### Granularity check
+
+If a phase has only 1-2 trivial tasks, it's probably too thin — merge it. If a phase has 8+ tasks spanning multiple concerns, it's probably too thick — split it. Most phases land at 3-6 focused tasks.
+
+---
+
+## Cross-Phase Coupling
+
+**Maximize cohesion within a phase, minimize dependencies between phases.**
+
+A well-bounded phase could theoretically be reordered or dropped without cascading failures across other phases. In practice, phases have a natural sequence (the skeleton must come first), but each phase should be as self-contained as possible.
+
+Strategies:
+
+- **Walking skeleton first** — subsequent phases add to a working system rather than depending on future phases
+- **Clear interfaces between phases** — each phase produces defined contracts (API shapes, data models, test suites) that subsequent phases consume
+- **Shared infrastructure in Phase 1** — if multiple phases need the same foundation, it belongs in the skeleton
+- **No forward references** — a phase should never depend on something that hasn't been built yet
+
+---
+
+## Anti-Patterns
+
+**Horizontal phases** — organising by technical layer ("all models, then all services, then all controllers"). Defers integration risk, produces phases that aren't independently valuable. The walking skeleton eliminates this by integrating from the start.
+
+**God phase** — one massive phase covering too many concerns. Results in unclear success criteria, inability to track progress, and cognitive overload. If you can't summarise a phase's goal in one sentence, it needs splitting.
+
+**Trivial phases** — phases so small they're just individual tasks wearing a trenchcoat. Phase management has overhead; don't pay it for work that doesn't warrant a checkpoint.
+
+**Infrastructure-only phases** (after Phase 1) — phases that deliver tooling, configuration, or refactoring with no user-facing value. These should be folded into the phase that needs them, unless they're genuinely cross-cutting prerequisites.
+
+**Speculative phases** — phases planned for hypothetical future requirements. Plan what the specification defines, not what might be needed later.