@leeovery/claude-technical-workflows 2.0.54 → 2.1.0

package/README.md

@@ -14,6 +14,14 @@
 
 ---
 
+<p align="center">
+  <a href="https://leeovery.github.io/claude-technical-workflows/"><strong>Open the Interactive Workflow Explorer</strong></a>
+</p>
+
+> **Workflow Explorer** — A visual, interactive guide to every phase, skill, and command in this toolkit. See how commands route to skills, trace decision logic through flowcharts, and understand the full pipeline at a glance. No install required — runs in your browser.
+
+---
+
 ## What is this?
 
 A complete development workflow for Claude Code: explore ideas, capture decisions, build actionable plans, implement via strict TDD, and validate the result.
@@ -195,7 +203,7 @@ When using the full workflow, it progresses through six distinct phases:
 
 **Phase 3 - Specification:** Transforms discussion(s) into validated, standalone specifications. Automatically analyses multiple discussions for natural groupings, filters hallucinations and inaccuracies, enriches gaps, and builds documents that planning can execute against without referencing other sources.
 
-**Phase 4 - Planning:** Converts specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear, Backlog.md).
+**Phase 4 - Planning:** Converts specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear).
 
 **Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, with per-task approval gates (auto mode available).
 
@@ -235,6 +243,7 @@ skills/                              # Input-agnostic processors
 └── technical-review/                # Validate against artefacts
 
 commands/                            # Input layer (gather context → invoke skills)
+├── migrate.md                       # Keep workflow files in sync with system design
 ├── start-feature.md                 # Standalone: spec from inline context
 ├── link-dependencies.md             # Standalone: wire cross-topic deps
 └── workflow/                        # Sequential workflow commands
@@ -248,12 +257,24 @@ commands/                            # Input layer (gather context → invoke sk
     └── view-plan.md                 # View plan tasks
 
 agents/
-└── chain-verifier.md                # Parallel task verification for review
+├── review-task-verifier.md           # Verifies single task implementation for review
+├── implementation-task-executor.md  # TDD executor for single plan tasks
+├── implementation-task-reviewer.md  # Post-task review for spec conformance
+├── planning-phase-designer.md       # Design phases from specification
+├── planning-task-designer.md        # Break phases into task lists
+├── planning-task-author.md          # Write full task detail
+└── planning-dependency-grapher.md   # Analyze task dependencies and priorities
 
 scripts/                             # Helper scripts for commands
 ├── migrate.sh                       # Migration orchestrator
-├── specification-discovery.sh       # Discovery for specification command
+├── discovery-for-discussion.sh      # Discovery for discussion command
+├── discovery-for-specification.sh   # Discovery for specification command
+├── discovery-for-planning.sh        # Discovery for planning command
+├── discovery-for-implementation-and-review.sh  # Discovery for impl/review
 └── migrations/                      # Individual migration scripts (numbered)
+
+tests/
+└── scripts/                         # Shell script tests for discovery and migrations
 ```
 
 ## Skills
@@ -282,7 +303,7 @@ Sequential commands in `commands/workflow/`. They expect files from previous pha
 | [**/start-research**](commands/workflow/start-research.md)                  | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
 | [**/start-discussion**](commands/workflow/start-discussion.md)              | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
 | [**/start-specification**](commands/workflow/start-specification.md)        | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
-| [**/start-planning**](commands/workflow/start-planning.md)                  | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (markdown, Linear, Backlog.md, Beads). |
+| [**/start-planning**](commands/workflow/start-planning.md)                  | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear). |
 | [**/start-implementation**](commands/workflow/start-implementation.md)      | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
 | [**/start-review**](commands/workflow/start-review.md)                      | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
 
@@ -318,9 +339,15 @@ See `/start-feature` as an example: it provides inline context to the specificat
 
 Subagents that skills can spawn for parallel task execution.
 
-| Agent                                          | Used By          | Description                                                                                                                                                                                              |
-|------------------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [**chain-verifier**](agents/chain-verifier.md) | technical-review | Verifies a single plan task was implemented correctly. Checks implementation, tests (not under/over-tested), and code quality. Multiple chain-verifiers run in parallel to verify ALL tasks efficiently. |
+| Agent | Used By | Description |
+|-------|---------|-------------|
+| [**review-task-verifier**](agents/review-task-verifier.md) | technical-review | Verifies a single plan task was implemented correctly. Checks implementation, tests, and code quality. Multiple run in parallel. |
+| [**implementation-task-executor**](agents/implementation-task-executor.md) | technical-implementation | Implements a single plan task via strict TDD. |
+| [**implementation-task-reviewer**](agents/implementation-task-reviewer.md) | technical-implementation | Reviews a completed task for spec conformance, acceptance criteria, and architectural quality. |
+| [**planning-phase-designer**](agents/planning-phase-designer.md) | technical-planning | Designs implementation phases from a specification. |
+| [**planning-task-designer**](agents/planning-task-designer.md) | technical-planning | Breaks a single phase into a task list with edge cases. |
+| [**planning-task-author**](agents/planning-task-author.md) | technical-planning | Writes full detail for a single plan task. |
+| [**planning-dependency-grapher**](agents/planning-dependency-grapher.md) | technical-planning | Analyzes authored tasks to establish internal dependencies and priorities. |
 
 ## Requirements
 

package/agents/implementation-task-executor.md

@@ -2,7 +2,7 @@
 name: implementation-task-executor
 description: Implements a single plan task via strict TDD. Invoked by technical-implementation skill for each task.
 tools: Read, Glob, Grep, Edit, Write, Bash
-model: inherit
+model: opus
 ---
 
 # Implementation Task Executor

package/agents/planning-dependency-grapher.md

@@ -0,0 +1,140 @@
+---
+name: planning-dependency-grapher
+description: Analyzes authored tasks to establish internal dependencies and priorities. Invoked by technical-planning skill after plan construction.
+tools: Read, Glob, Grep, Edit
+model: opus
+---
+
+# Planning Dependency Grapher
+
+Act as an **expert technical architect** analyzing a complete implementation plan to establish task dependencies and priorities.
+
+## Your Input
+
+You receive file paths via the orchestrator's prompt:
+
+1. **Plan Index File path** — The plan with phases, task tables, and frontmatter
+2. **reading.md** — The output format's reading reference (how to list and read tasks)
+3. **graph.md** — The output format's graph reference (priority + dependency CRUD instructions)
+
+On **re-invocation after feedback**, you also receive:
+- **Previous output** — Your prior dependency/priority analysis
+- **User feedback** — What to change
+
+## Your Process
+
+1. Read `reading.md` — understand how to list and read tasks for this format
+2. Read `graph.md` — understand how to record priorities and dependencies for this format
+3. Read the Plan Index File — understand phase structure and task tables
+4. List all authored task files using the method described in reading.md
+5. **Clear existing graph data** — using graph.md's removal instructions, remove all existing dependencies and priorities from every task. This ensures a clean slate on every invocation (first run, re-invocation after feedback, or `continue` of a previous session).
+6. Read every authored task file — absorb each task's Problem, Solution, Do steps, and Acceptance Criteria
+7. Analyze dependencies — follow the methodology in "Detecting Dependencies" below
+8. Assign priorities — follow the methodology in "Assigning Priorities" below
+9. Detect cycles — verify the dependency graph is acyclic (see "Cycle Detection" below)
+10. If no cycles: **apply all changes** — follow graph.md instructions to record dependencies and priorities on each task
+11. If cycles detected: **do not apply any changes** — report the cycle chain and stop
+
+If this is a **re-invocation after feedback**: read your previous output and the user's feedback, then revise accordingly. Step 5 (clearing) ensures previous analysis doesn't bias the new run.
+
+## Detecting Dependencies
+
+Dependencies and priorities are **optional**. In the absence of both, tasks execute in natural order — top to bottom by task ID. Only add dependencies or priorities when they change the execution order in a way that matters.
+
+Your job is to look at the complete plan from above and ask two questions about each task: **"What must exist before this task can start?"** and **"What does this task produce that other tasks need?"**
+
+### What constitutes a dependency
+
+A dependency exists when Task B **cannot start** until Task A is **complete**. The relationship is always finish-to-start: A must finish before B can begin. Specifically, look for:
+
+- **Data dependencies** — Task B reads, queries, or extends something that Task A creates. Example: a task that builds an API endpoint for a model depends on the task that creates that model and its migration.
+- **Capability dependencies** — Task B's tests require functionality that Task A implements. Example: a task testing error handling on an endpoint depends on the task that creates the working endpoint.
+- **Infrastructure dependencies** — Task B needs configuration, setup, or scaffolding that Task A provides. Example: tasks that use a service class depend on the task that creates the service class.
+
+### How to identify them
+
+For each task, read its **Do** steps and **Acceptance Criteria** carefully. Identify:
+
+1. **What it produces** — what files, classes, endpoints, configurations, or behaviours does this task create or modify?
+2. **What it requires** — what must already exist for this task's Do steps to be executable and its tests to be writable?
+
+Then match produces→requires across all tasks. If Task A produces something that Task B requires, and Task B would fail or be impossible to implement without it, that's a dependency.
+
+### When NOT to add a dependency
+
+- **Natural order already handles it.** If task 2 depends on task 1 and they're already in sequence, don't add an explicit dependency — the natural execution order already ensures the right sequence. Only wire dependencies that the natural order wouldn't catch.
+- **Same-phase sequential tasks.** Tasks within a phase are designed to flow foundation → happy path → errors → edge cases. If task 3 depends on task 2 depends on task 1 and they're already ordered that way, explicit dependencies add noise without value.
+- **Vague relatedness.** Two tasks being "in the same area" doesn't make one depend on the other. The question is: would Task B's implementation or tests literally fail if Task A hadn't been completed?
+- **Cross-phase implicit ordering.** Earlier phases complete before later phases by default. A task in Phase 2 doesn't need explicit dependencies on Phase 1 tasks unless it depends on a *specific* task that might not be obvious from phase ordering alone.
+
+### When dependencies ARE valuable
+
+- **Out-of-sequence dependencies.** Task 5 requires something that Task 6 produces. Without an explicit dependency, Task 5 would execute first and fail. The dependency corrects the execution order.
+- **Cross-phase specificity.** A task in Phase 3 depends on a specific task in Phase 1 (not the whole phase). Making this explicit ensures that if task ordering ever changes, the constraint survives.
+- **Convergence points.** A task that integrates work from multiple earlier tasks — it depends on all of them, not just the one immediately before it.
+
+## Assigning Priorities
+
+Priority determines execution order among tasks that are equally ready (not blocked by dependencies). Like dependencies, priority is optional — if natural task ID ordering produces the right sequence, skip it.
+
+### When to assign priority
+
+- **Bottleneck tasks** — If a task unblocks three or more other tasks, give it higher priority. It's a critical path node; delaying it delays everything downstream.
+- **Foundation tasks** — Tasks that set up infrastructure, models, or configuration that many other tasks build on. Higher priority ensures the foundation is laid early.
+- **Independent leaf tasks** — Tasks that nothing else depends on can receive lower priority. They can execute whenever capacity allows.
+
+### When NOT to assign priority
+
+- **Natural order is sufficient.** If the task table is already well-ordered and dependencies handle the necessary constraints, priorities add no value.
+- **Uniform importance.** If all tasks in a phase are roughly equal and should execute in sequence, don't assign priorities.
+- **Never use priority for "importance."** Priority controls execution order, not business value. A critical business feature doesn't get higher priority unless it also unblocks other tasks.
+
+### Priority based on graph position
+
+Count each task's **fan-out** — the number of tasks (directly or transitively) that depend on it. Tasks with higher fan-out get higher priority because they're bottlenecks. Tasks with zero fan-out (leaf nodes) get lower priority or no priority at all.
+
+## Cycle Detection
+
+After building the complete dependency graph, verify it contains no cycles. A cycle means Task A depends on B, B depends on C, and C depends on A — an impossible execution order.
+
+Use a topological sort: process tasks with no incoming dependencies first, remove them, repeat. If any tasks remain unprocessed, they form a cycle.
+
+If a cycle is detected: **do not apply any changes**. Report the cycle chain in your output so the orchestrator can present it to the user for resolution.
+
+## Your Output
+
+Return a structured summary:
+
+```
+STATUS: complete | blocked | no-changes
+DEPENDENCIES:
+- {task-id} depends on {task-id} — {one-line reason}
+- {task-id} depends on {task-id}, {task-id} — {one-line reason}
+
+PRIORITIES:
+- {task-id}: {priority-value} — {one-line reason}
+- {task-id}: {priority-value} — {one-line reason}
+
+CYCLES: none | {description of cycle chain}
+
+NOTES: {any observations — tasks with no dependencies, isolated tasks, etc.}
+```
+
+If STATUS is `blocked`, CYCLES must explain the circular chain. Do not apply any changes when a cycle is detected.
+
+If STATUS is `no-changes`, explain why — typically because the natural task order is already correct and no dependencies or priorities would improve execution order.
+
+DEPENDENCIES and PRIORITIES sections may be empty if none are needed. This is a valid outcome — not every plan needs explicit graph edges.
+
+## Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
+1. **Clean slate every time** — always clear all existing dependencies and priorities from all tasks before analyzing. This prevents previous runs from biasing the current analysis. Use graph.md's removal instructions.
+2. **Tasks are your source of truth** — determine dependencies from what tasks produce and consume. Each task is self-contained. Do not request or reference the specification.
+3. **graph.md is your recording interface** — follow its instructions for all writes and removals. Do not assume frontmatter fields, API calls, or file formats.
+4. **reading.md is your reading interface** — follow its instructions for listing and reading tasks. Do not assume file paths or API calls.
+5. **No cross-topic dependencies** — only wire dependencies between tasks in the same plan. Cross-topic dependencies are handled separately.
+6. **Cycle detection before writing** — detect cycles in your analysis before applying any changes. If a cycle exists, report it and stop.
+7. **Less is more** — only add dependencies and priorities that change execution order in a way that matters. An empty graph is a valid result.
+8. **Do not modify task content** — only add/update priority and dependency fields. Do not change titles, descriptions, acceptance criteria, or any other task content.

package/agents/planning-phase-designer.md

@@ -2,7 +2,7 @@
 name: planning-phase-designer
 description: Designs implementation phases from a specification. Invoked by technical-planning skill during plan construction.
 tools: Read, Glob, Grep
-model: inherit
+model: opus
 ---
 
 # Planning Phase Designer

package/agents/planning-task-author.md

@@ -2,7 +2,7 @@
 name: planning-task-author
 description: Writes full detail for a single plan task. Invoked by technical-planning skill during plan construction.
 tools: Read, Glob, Grep
-model: inherit
+model: opus
 ---
 
 # Planning Task Author

package/agents/planning-task-designer.md

@@ -2,7 +2,7 @@
 name: planning-task-designer
 description: Breaks a single phase into a task list with edge cases. Invoked by technical-planning skill during plan construction.
 tools: Read, Glob, Grep
-model: inherit
+model: opus
 ---
 
 # Planning Task Designer

package/agents/{chain-verifier.md → review-task-verifier.md}

@@ -1,11 +1,11 @@
 ---
-name: chain-verifier
+name: review-task-verifier
 description: Verifies a single plan task was implemented correctly. Checks implementation, tests, and code quality against the task's acceptance criteria and spec context. Invoked by technical-review to verify ALL plan tasks in PARALLEL.
 tools: Read, Glob, Grep
-model: haiku
+model: opus
 ---
 
-# Chain Verifier
+# Review Task Verifier
 
 Act as a **senior software architect** with deep experience in code review. You verify that ONE plan task was implemented correctly, tested adequately, and meets professional quality standards.
 

package/commands/link-dependencies.md

@@ -98,10 +98,10 @@ For each unresolved dependency:
 1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}.md` exist?
    - If no match: Mark as "no plan exists" - cannot resolve yet
 
-2. **If plan exists**: Load the output format reference file
+2. **If plan exists**: Load the format's reading reference
    - Read `format:` from the dependency plan's frontmatter
-   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
-   - Follow the "Querying Dependencies" section to search for matching tasks
+   - Load `.claude/skills/technical-planning/references/output-formats/{format}/reading.md`
+   - Use the task extraction instructions to search for matching tasks
 
 3. **Handle ambiguous matches**:
    - If multiple tasks could satisfy the dependency, present options to user
@@ -115,8 +115,8 @@ For each resolved match:
    - Change the dependency's `state: unresolved` to `state: resolved` and add `task_id: {task-id}`
 
 2. **Create dependency in output format**:
-   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
-   - Follow the "Cross-Epic Dependencies" or equivalent section to create the blocking relationship
+   - Load `.claude/skills/technical-planning/references/output-formats/{format}/graph.md`
+   - Follow the "Adding a Dependency" section to create the blocking relationship
 
 ## Step 6: Bidirectional Check
 

package/commands/workflow/view-plan.md

@@ -18,19 +18,19 @@ Ask the user which plan to view.
 
 Read the plan file from `docs/workflow/planning/{topic}.md` and check the `format:` field in the frontmatter.
 
-## Step 3: Load Format Reference
+## Step 3: Load Format Reading Reference
 
-Load the corresponding output format reference:
+Load the format's reading reference:
 
 ```
-skills/technical-planning/references/output-formats/output-{format}.md
+.claude/skills/technical-planning/references/output-formats/{format}/reading.md
 ```
 
-This reference contains instructions for reading plans in that format.
+This file contains instructions for reading plans in that format.
 
 ## Step 4: Read Plan Content
 
-Follow the "Reading" or "Implementation" section in the format reference to locate and read the actual plan content.
+Follow the reading reference to locate and read the actual plan content.
 
 ## Step 5: Present Summary
 

package/package.json

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

package/skills/technical-implementation/SKILL.md

@@ -100,9 +100,11 @@ Save their instructions to `docs/workflow/environment-setup.md` (or "No special
 
 1. Read the plan from the provided location (typically `docs/workflow/planning/{topic}.md`)
 2. Plans can be stored in various formats. The `format` field in the plan's frontmatter identifies which format this plan uses.
-3. Load the corresponding adapter file: `skills/technical-planning/references/output-formats/output-{format}.md` — this document provides instructions for reading tasks from and writing progress to the plan. Hereafter referred to as the **plan adapter**.
+3. Load the format's per-concern adapter files from `.claude/skills/technical-planning/references/output-formats/{format}/`:
+   - **reading.md** — how to read tasks from the plan
+   - **updating.md** — how to write progress to the plan
 4. If no `format` field exists, ask the user which format the plan uses.
-5. Read the plan adapter's **Implementation** section to understand the instructions — they apply during Step 5.
+5. These adapter files apply during Step 5 (task loop).
 
 → Proceed to **Step 3**.
 

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

@@ -52,13 +52,13 @@ If the environment setup document contains only "No special setup required" (or
 
 ## Plan Format Setup
 
-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:
+Some plan formats require specific tools. Check the plan's `format` field and load the format's about file for setup instructions:
 
 ```
-skills/technical-planning/references/output-formats/output-{format}.md
+.claude/skills/technical-planning/references/output-formats/{format}/about.md
 ```
 
-Each output adapter contains prerequisites and installation instructions for that format.
+Each format's about.md contains prerequisites and installation instructions.
 
 ## Example Setup Document
 

package/skills/technical-implementation/references/steps/task-loop.md

@@ -23,7 +23,7 @@ E. Update progress + commit
 
 ## A. Retrieve Next Task
 
-1. Follow the plan adapter's Reading instructions to determine the next available task.
+1. Follow the format's **reading.md** instructions to determine the next available task.
 2. If no available tasks remain → skip to **When All Tasks Are Complete**.
 3. Normalise the task content following **[task-normalisation.md](../task-normalisation.md)**.
 
@@ -132,7 +132,7 @@ Announce the result (one line, no stop):
 
 ## E. Update Progress and Commit
 
-**Update task progress in the plan** — follow the plan adapter's Implementation section for instructions on how to mark the task complete.
+**Update task progress in the plan** — follow the format's **updating.md** instructions to mark the task complete.
 
 **Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}.md`):
 - Append the task ID to `completed_tasks`

package/skills/technical-planning/SKILL.md

@@ -92,8 +92,8 @@ If the specification changed, update `spec_commit` in the Plan Index File frontm
 
 #### If `restart`
 
-1. Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the linked adapter
-2. Follow the adapter's cleanup instructions to remove Authored Tasks for this topic
+1. Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[authoring.md](references/output-formats/{format}/authoring.md)**
+2. Follow the authoring file's cleanup instructions to remove Authored Tasks for this topic
 3. Delete the Plan Index File
 4. Commit: `planning({topic}): restart planning`
 
@@ -105,7 +105,7 @@ If the specification changed, update `spec_commit` in the Plan Index File frontm
 
 #### If Plan Index File already exists
 
-Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field, and load the linked adapter.
+Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field, and load the format's **[about.md](references/output-formats/{format}/about.md)** and **[authoring.md](references/output-formats/{format}/authoring.md)**.
 
 → Proceed to **Step 2**.
 
@@ -131,7 +131,7 @@ Present the formats from **[output-formats.md](references/output-formats.md)** t
 
 Once selected:
 
-1. Read **[output-formats.md](references/output-formats.md)**, find the chosen format entry, and load the linked adapter
+1. Read **[output-formats.md](references/output-formats.md)**, find the chosen format entry, and load the format's **[about.md](references/output-formats/{format}/about.md)** and **[authoring.md](references/output-formats/{format}/authoring.md)**
 2. Capture the current git commit hash: `git rev-parse HEAD`
 3. Create the Plan Index File at `docs/workflow/planning/{topic}.md` with the following frontmatter and title:
 
@@ -185,23 +185,31 @@ Load **[steps/plan-construction.md](references/steps/plan-construction.md)** and
 
 ---
 
-## Step 5: Resolve External Dependencies
+## Step 5: Analyze Task Graph
 
-Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
+Load **[steps/analyze-task-graph.md](references/steps/analyze-task-graph.md)** and follow its instructions as written.
 
 → Proceed to **Step 6**.
 
 ---
 
-## Step 6: Plan Review
+## Step 6: Resolve External Dependencies
 
-Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
+Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
 
 → Proceed to **Step 7**.
 
 ---
 
-## Step 7: Conclude the Plan
+## Step 7: Plan Review
+
+Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
+
+→ Proceed to **Step 8**.
+
+---
+
+## Step 8: Conclude the Plan
 
 After the review is complete:
 

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

@@ -6,11 +6,11 @@
 
 ## Internal Dependencies
 
-Internal dependencies are dependencies within a single topic/epic - where one task depends on another task in the same plan. These are handled by the planning output format's native dependency system.
+Internal dependencies are dependencies within a single topic/epic — where one task depends on another task in the same plan.
 
-During planning, structure tasks in the correct order with appropriate dependencies so work proceeds logically. The output format manages these relationships and ensures tasks are worked in the right sequence.
+These are established during planning by the **Analyze Task Graph** step. After all tasks are authored, a dedicated agent analyzes the full plan, determines which tasks depend on which, assigns priorities based on graph position, and records both via the output format's `graph.md` instructions.
 
-See the relevant output format reference for how to create and query internal dependencies.
+The output format's `graph.md` reference documents how dependencies and priorities are stored and queried for each format.
 
 ## External Dependencies
 

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

@@ -0,0 +1,48 @@
+# Linear
+
+*Output format adapter for **[technical-planning](../../../SKILL.md)***
+
+---
+
+Use this output format when you want **Linear as the source of truth** for task management. Tasks are stored as Linear issues and can be updated directly in Linear's UI.
+
+## Benefits
+
+- Visual tracking with real-time progress updates
+- Team collaboration with shared visibility
+- Native priority, estimation, and dependency support
+- Update tasks directly in Linear UI without editing markdown
+- Integrates with existing Linear workflows
+
+## Setup
+
+Requires the Linear MCP server to be configured in Claude Code.
+
+Check if Linear MCP is available by looking for Linear tools. If not configured, inform the user that Linear MCP is required for this format.
+
+Ask the user: **Which team should own this project?**
+
+## Structure Mapping
+
+| Concept | Linear Entity |
+|---------|---------------|
+| Topic | Project |
+| Phase | Label (e.g., `phase-1`, `phase-2`) |
+| Task | Issue |
+| Dependency | Issue blocking relationship |
+
+Each topic becomes its own Linear project. Phases are represented as labels on issues.
+
+## Output Location
+
+Tasks are stored as issues in a Linear project:
+
+```
+Linear:
+└── Project: {topic}
+    ├── Issue: Task 1 [label: phase-1, priority: urgent]
+    ├── Issue: Task 2 [label: phase-1, priority: normal]
+    └── Issue: Task 3 [label: phase-2, priority: high]
+```
+
+Linear is the source of truth for task detail and status.

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

@@ -0,0 +1,82 @@
+# Linear: Authoring
+
+## Project Setup
+
+Via MCP, create a project with:
+
+- **Name**: Match the topic name
+- **Description**: Brief summary + link to specification file
+- **Team**: As specified by user
+
+## Phase Labels
+
+Create labels to denote phases (if they don't already exist):
+
+- `phase-1`
+- `phase-2`
+- etc.
+
+## Task Storage
+
+For each task, create a Linear issue via MCP:
+
+```
+linear_createIssue(
+  teamId: "{team_id}",
+  projectId: "{project_id}",
+  title: "{Task title}",
+  description: "{Task description content}",
+  labelIds: ["{phase_label_id}", ...]
+)
+```
+
+## Task Properties
+
+### Status
+
+Linear uses workflow states. Map to these states:
+
+| Status | Linear State |
+|--------|-------------|
+| Pending | Todo (or Backlog) |
+| In Progress | In Progress |
+| Completed | Done |
+| Skipped | Cancelled (add comment explaining why) |
+| Cancelled | Cancelled |
+
+### Phase Grouping
+
+Apply phase labels to issues: `phase-1`, `phase-2`, etc. All issues in a phase share the same label.
+
+### Labels / Tags
+
+Beyond phase labels, apply optional labels for categorisation:
+
+- `needs-info` — task requires additional information
+- `edge-case` — edge case handling task
+- `foundation` — setup/infrastructure task
+- `refactor` — cleanup task
+
+## Flagging
+
+When creating issues, if something is unclear:
+
+1. **Create the issue anyway** — don't block planning
+2. **Apply `needs-info` label** — makes gaps visible
+3. **Note what's missing** in description — add a **Needs Clarification** section
+4. **Continue planning** — circle back later
+
+## Cleanup (Restart)
+
+The official Linear MCP server does not support deletion. Ask the user to delete the Linear project manually via the Linear UI.
+
+> "The Linear project **{project name}** needs to be deleted before restarting. Please delete it in the Linear UI (Project Settings → Delete project), then confirm so I can proceed."
+
+**STOP.** Wait for the user to confirm.
+
+### Fallback
+
+If Linear MCP is unavailable:
+- Inform the user
+- Cannot proceed without MCP access
+- Suggest checking MCP configuration or switching to local markdown