@leeovery/claude-technical-workflows 2.0.44 → 2.0.46

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.

package/skills/technical-planning/references/planning-principles.md

@@ -0,0 +1,44 @@
+# Planning Principles
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines the principles, rules, and quality standards for creating implementation plans. It is loaded at the start of the planning process and stays in context throughout.
+
+## Planning is a Gated Process
+
+Planning translates the specification into actionable structure. This translation requires judgment, and the process is designed to ensure that judgment is exercised carefully and collaboratively — not rushed.
+
+### Process Expectations
+
+**This is a step-by-step process with mandatory stop points.** You must work through each step sequentially. Steps end with **STOP** — you must present your work, wait for explicit user confirmation, and only then proceed to the next step.
+
+**Never one-shot the plan.** Do not write the entire plan document in a single operation. The plan is built incrementally — one phase at a time, with the user confirming the structure at each stage. A one-shot plan that misses requirements, hallucinates content, or structures tasks poorly wastes more time than a careful, step-by-step process. Go slow to go fast.
+
+**Stop and ask when judgment is needed.** Planning is collaborative — not in the sense that every line needs approval, but in the sense that the user guides structural decisions and resolves ambiguity. You must stop and ask when:
+
+- The specification is ambiguous about implementation approach
+- Multiple valid ways to structure phases or tasks exist
+- You're uncertain whether a task is appropriately scoped
+- Edge cases aren't fully addressed in the specification
+- You need to make any decision the specification doesn't cover
+- Something doesn't add up or feels like a gap
+
+**Never invent to fill gaps.** If the specification doesn't address something, flag it with `[needs-info]` and ask the user. The specification is the golden document — everything in the plan must trace back to it. Assuming or guessing — even when it seems reasonable — is not acceptable. Surface the problem immediately rather than continuing and hoping to address it later.
+
+## Rules
+
+**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing.
+
+**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+
+**Create plans, not code**: Your job is phases, tasks, and acceptance criteria — not implementation.
+
+## Plan as Source of Truth
+
+The plan IS the source of truth. Every phase, every task must contain all information needed to execute it.
+
+- **Self-contained**: Each task executable without external context
+- **No assumptions**: Spell out the context, don't assume implementer knows it
+

package/skills/technical-planning/references/steps/author-tasks.md

@@ -0,0 +1,63 @@
+# Author Tasks
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[task-design.md](../task-design.md)** — the task design principles, template structure, and quality standards for writing task detail.
+
+---
+
+Orient the user:
+
+> "Task list for Phase {N} is agreed. I'll work through each task one at a time — presenting the full detail, discussing if needed, and logging it to the plan once approved."
+
+Work through the agreed task list **one task at a time**.
+
+#### Present
+
+Write the complete task using the task template — Problem, Solution, Outcome, Do, Acceptance Criteria, Tests, Context.
+
+Present it to the user **in the format it will be written to the plan**. The output format adapter determines the exact format. What the user sees is what gets logged — no changes between approval and writing.
+
+After presenting, ask:
+
+> **Task {M} of {total}: {Task Name}**
+>
+> **To proceed, choose one:**
+> - **"Approve"** — Task is confirmed. I'll log it to the plan verbatim.
+> - **"Adjust"** — Tell me what to change.
+
+**STOP.** Wait for the user's response.
+
+#### If adjust
+
+The user may:
+- Request changes to the task content
+- Ask questions about scope, granularity, or approach
+- Flag that something doesn't match the specification
+- Identify missing edge cases or acceptance criteria
+
+Incorporate feedback and re-present the updated task **in full**. Then ask the same choice again. Repeat until approved.
+
+#### If approved
+
+Log the task to the plan — verbatim, as presented. Do not modify content between approval and writing. The output format adapter determines how tasks are written (appending markdown, creating issues, etc.).
+
+After logging, confirm:
+
+> "Task {M} of {total}: {Task Name} — logged."
+
+#### Next task or phase complete
+
+**If tasks remain in this phase:** → Return to the top of **Step 6** with the next task. Present it, ask, wait.
+
+**If all tasks in this phase are logged:**
+
+```
+Phase {N}: {Phase Name} — complete ({M} tasks logged).
+```
+
+→ Return to **Step 5** for the next phase.
+
+**If all phases are complete:** → Proceed to **Step 7**.

package/skills/technical-planning/references/steps/define-phases.md

@@ -0,0 +1,40 @@
+# Define Phases
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[phase-design.md](../phase-design.md)** — the principles for structuring phases as independently valuable, testable increments built on a walking skeleton.
+
+---
+
+Orient the user:
+
+> "I've read the full specification. I'm going to propose a phase structure — how we break this into independently testable stages. Once we agree on the phases, we'll take each one and break it into tasks."
+
+With the full specification understood, break it into logical phases. Understanding what tasks belong in each phase is necessary to determine the right ordering.
+
+Present the proposed phase structure using this format:
+
+```
+Phase {N}: {Phase Name}
+  Goal: {What this phase accomplishes}
+  Why this order: {Why this phase comes at this position in the sequence}
+  Acceptance criteria:
+    - [ ] {First verifiable criterion}
+    - [ ] {Second verifiable criterion}
+```
+
+**STOP.** Present your proposed phase structure and ask:
+
+> **To proceed, choose one:**
+> - **"Approve"** — Phase structure is confirmed. I'll proceed to task breakdown.
+> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove phases.
+
+#### If Adjust
+
+Incorporate feedback, re-present the updated phase structure, and ask again. Repeat until approved.
+
+#### If Approved
+
+→ Proceed to **Step 5**.

package/skills/technical-planning/references/steps/define-tasks.md

@@ -0,0 +1,43 @@
+# Define Tasks
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Load **[task-design.md](../task-design.md)** — the principles for breaking phases into well-scoped, vertically-sliced tasks.
+
+---
+
+Orient the user:
+
+> "Taking Phase {N}: {Phase Name} and breaking it into tasks. Here's the overview — once we agree on the list, I'll write each task out in full detail."
+
+Take the first (or next) phase and break it into tasks. Present a high-level overview so the user can see the shape of the phase before committing to the detail of each task.
+
+Present the task overview using this format:
+
+```
+Phase {N}: {Phase Name}
+
+  1. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+
+  2. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+```
+
+This overview establishes the scope and ordering. The user should be able to see whether the phase is well-structured, whether tasks are in the right order, and whether anything is missing or unnecessary — before investing time in writing out full task detail.
+
+**STOP.** Present the phase task overview and ask:
+
+> **To proceed, choose one:**
+> - **"Approve"** — Task list is confirmed. I'll begin writing full task detail.
+> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove tasks.
+
+#### If Adjust
+
+Incorporate feedback, re-present the updated task overview, and ask again. Repeat until approved.
+
+#### If Approved
+
+→ Proceed to **Step 6**.