@leeovery/claude-technical-workflows 2.1.27 → 2.1.29

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">Claude Technical Workflows</h1>
 
 <p align="center">
-  <strong>From Idea to Implementation: Software Engineering Workflows for Claude Code</strong>
+  <strong>From Idea to Implementation: Agentic Engineering Workflows for Claude Code</strong>
 </p>
 
 <p align="center">
@@ -36,6 +36,8 @@ Research → Discussion → Specification → Planning → Implementation → Re
 
 **Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Entry-point skills gather context and feed it to processing skills.
 
+**Engineered like software.** This isn't a collection of prompts — it's built with the same discipline you'd apply to code. Processing skills follow the single responsibility principle. Entry-point skills compose with them, keeping input gathering DRY. Output formats implement a [5-file adapter contract](#output-formats), so planning works identically regardless of where tasks end up. Agents handle isolated concerns. The result is a natural language workflow that's modular, extensible, and maintainable — software engineering principles applied to agentic workflows.
+
 > [!NOTE]
 > **Work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
 
@@ -52,53 +54,76 @@ See [Installation](#installation) for details.
 
 ## How do I use it?
 
-### Two Ways to Use the Skills
+### Where to Start
+
+Pick your entry point based on where you are:
+
+- **Seeds of an idea?** → Start with `/start-research` *(recommended)*
+  You have a rough idea but haven't explored feasibility, alternatives, or scope yet. Research lets you think freely before committing to anything.
+
+- **Know what you're building?** → Start with `/start-discussion`
+  You've moved past exploration and want to capture architecture decisions, edge cases, and rationale for specific topics.
+
+- **Clear feature, ready to spec?** → Use `/start-feature`
+  You already know the what and why. Jump straight to building a specification from inline context — no prior documents needed.
+
+**Why research is the recommended default:** When you move from research to discussion, the discussion skill analyses your research document and automatically breaks it into focused discussion topics. Skip research and you manage topic structure yourself.
 
-**1. Full Workflow** - Sequential phases that build on each other:
+### The Workflow
 
 ```
-Research → Discussion → Specification → Planning → Implementation → Review
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│   Research    │──▶│  Discussion   │──▶│ Specification │
+│   (Phase 1)   │   │   (Phase 2)   │   │   (Phase 3)   │
+├───────────────┤   ├───────────────┤   ├───────────────┤
+│ EXPLORING     │   │ WHAT & WHY    │   │ REFINING      │
+│               │   │               │   │               │
+│ • Ideas       │   │ • Architecture│   │ • Validate    │
+│ • Market      │   │ • Decisions   │   │ • Filter      │
+│ • Viability   │   │ • Edge cases  │   │ • Enrich      │
+│               │   │ • Rationale   │   │ • Standalone  │
+└───────────────┘   └───────────────┘   └───────────────┘
+                                                │
+                                                ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│    Review     │◀──│Implementation │◀──│   Planning    │
+│   (Phase 6)   │   │   (Phase 5)   │   │   (Phase 4)   │
+├───────────────┤   ├───────────────┤   ├───────────────┤
+│ VALIDATING    │   │ DOING         │   │ HOW           │
+│               │   │               │   │               │
+│ • Plan check  │   │ • Tests first │   │ • Phases      │
+│ • Specs check │   │ • Then code   │   │ • Tasks       │
+│ • Test quality│   │ • Commit often│   │ • Criteria    │
+│ • Code quality│   │ • Task gates  │   │ • Outputs     │
+└───────────────┘   └───────────────┘   └───────────────┘
 ```
 
-Start with `/start-research` or `/start-discussion` and follow the flow. Each phase outputs files that the next phase consumes.
+Each phase produces documents that feed the next. Here's the journey:
 
-**2. Standalone Skills** - Jump directly to a processing skill with flexible inputs:
+**Research** — Free-form exploration. Investigate ideas, market fit, technical feasibility, business viability. The output is a research document capturing everything you've explored. The key benefit: when you move to discussion, the skill analyses this document and breaks it into focused topics automatically.
 
-| Skill | What it does |
-|-------|-------------|
-| `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
+**Discussion** — Per-topic deep dives into architecture, edge cases, competing approaches, and rationale. Each topic gets its own document. This captures not just decisions, but *why* you made them — the alternatives considered, the trade-offs weighed, the journey to the decision. Conclude each topic when its decisions are made.
 
-*More standalone skills coming soon.*
+**Specification** — This is where the magic happens. The skill analyses *all* your discussions and creates intelligent groupings — 10 discussions might become 3–5 specifications, or you can unify everything into one. It filters hallucinations, enriches gaps, and validates decisions against each other. The spec becomes the golden document: planning only references this, not earlier phases.
 
-### The Two-Tier Skill Architecture
+**Planning** — Converts each specification into phased implementation plans with tasks, acceptance criteria, and dependency ordering. Supports [multiple output formats](#output-formats) — from local markdown files to CLI tools with native dependency graphs. Task authoring has per-item approval gates (with auto-mode for faster flow).
 
-**Processing skills** (`technical-*`) are input-agnostic. They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
+**Implementation** — Executes plans via strict TDD. Tests first, then code, commit after each task. Per-task approval gates keep you in control, with auto-mode available when you trust the flow.
 
-**Entry-point skills** (`/start-*`, `/status`, etc.) are the input layer. They gather context (from files, prompts, or inline) and pass it to processing skills. This separation means:
+**Review** — Validates the implementation against spec and plan. Catches drift, missing requirements, and quality issues. The spec is the source of truth here — earlier phases may contain rejected ideas that were intentionally filtered out. Produces structured feedback without fixing code directly.
 
-- The same processing skill can be invoked from different entry points
-- You can create custom entry-point skills that feed processing skills in new ways
-- Processing skills remain reusable without coupling to specific workflows
+### Standalone Skills
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    ENTRY-POINT SKILLS                        │
-│  (gather inputs from files, prompts, inline context)         │
-├─────────────────────────────────────────────────────────────┤
-│  /start-specification   /start-feature   (your custom)      │
-│         │                       │                 │          │
-│         └───────────┬───────────┘                 │          │
-│                     ▼                             ▼          │
-├─────────────────────────────────────────────────────────────┤
-│                    PROCESSING SKILLS                         │
-│  (process inputs without knowing their source)               │
-├─────────────────────────────────────────────────────────────┤
-│           technical-specification skill                      │
-│           technical-planning skill                           │
-│           technical-implementation skill                     │
-│           etc.                                               │
-└─────────────────────────────────────────────────────────────┘
-```
+Not every task needs the full workflow. These skills gather inputs flexibly and invoke processing skills directly:
+
+| Skill | What it does |
+|-------|-------------|
+| `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
+| `/link-dependencies` | Wire cross-topic dependencies across plans |
+
+### Under the Hood
+
+Skills are organised in two tiers. **Entry-point skills** (`/start-*`, `/status`, etc.) gather context from files, prompts, or inline input. **Processing skills** (`technical-*`) receive those inputs and do the work — they don't know or care where inputs came from. This separation means the same processing skill can be invoked from different entry points: `/start-specification` and `/start-feature` both feed `technical-specification` with different inputs. You can create custom entry-point skills that feed processing skills in new ways.
 
 ### Workflow Skills
 
@@ -113,19 +138,25 @@ Start with `/start-research` or `/start-discussion` and follow the flow. Each ph
 
 Run the skill directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the processing skill.
 
-## Installation
+### Output Formats
+
+Planning supports multiple output formats through an adapter pattern. Each format implements a 5-file contract — about, authoring, reading, updating, and graph — so the planning workflow works identically regardless of where tasks are stored.
 
-| Method  | Where files live           | Best for                                        |
-|---------|----------------------------|-------------------------------------------------|
-| **npm** | `.claude/` in your project | Ownership, version control, Claude Code for Web |
+| Format | Best for | Setup | |
+|--------|----------|-------|-|
+| **Tick** | AI-driven workflows, native dependencies, token-efficient | `brew install leeovery/tools/tick` | Recommended |
+| **Local Markdown** | Simple features, offline, quick iterations | None | |
+| **Linear** | Team collaboration, visual tracking | Linear account + MCP server | |
 
-### npm
+Choose a format when planning begins. New formats can be scaffolded with `/create-output-format`.
+
+## Installation
 
 ```bash
 npm install -D @leeovery/claude-technical-workflows
 ```
 
-Skills are copied to `.claude/` and can be committed, giving you ownership and making them available everywhere including Claude Code for Web.
+Skills are copied to `.claude/` in your project and can be committed, giving you ownership and making them available everywhere including Claude Code for Web.
 
 <details>
 <summary>pnpm users</summary>
@@ -149,70 +180,37 @@ npx claude-manager remove @leeovery/claude-technical-workflows && npm rm @leeove
 ```
 </details>
 
-## The Six-Phase Workflow
-
-When using the full workflow, it progresses through six distinct phases:
-
-```
-┌───────────────┐   ┌───────────────┐   ┌───────────────┐
-│   Research    │──▶│  Discussion   │──▶│ Specification │
-│   (Phase 1)   │   │   (Phase 2)   │   │   (Phase 3)   │
-├───────────────┤   ├───────────────┤   ├───────────────┤
-│ EXPLORING     │   │ WHAT & WHY    │   │ REFINING      │
-│               │   │               │   │               │
-│ • Ideas       │   │ • Architecture│   │ • Validate    │
-│ • Market      │   │ • Decisions   │   │ • Filter      │
-│ • Viability   │   │ • Edge cases  │   │ • Enrich      │
-│               │   │ • Rationale   │   │ • Standalone  │
-└───────────────┘   └───────────────┘   └───────────────┘
-                                                │
-                                                ▼
-┌───────────────┐   ┌───────────────┐   ┌───────────────┐
-│    Review     │◀──│Implementation │◀──│   Planning    │
-│   (Phase 6)   │   │   (Phase 5)   │   │   (Phase 4)   │
-├───────────────┤   ├───────────────┤   ├───────────────┤
-│ VALIDATING    │   │ DOING         │   │ HOW           │
-│               │   │               │   │               │
-│ • Plan check  │   │ • Tests first │   │ • Phases      │
-│ • Specs check │   │ • Then code   │   │ • Tasks       │
-│ • Test quality│   │ • Commit often│   │ • Criteria    │
-│ • Code quality│   │ • Task gates  │   │ • Outputs     │
-└───────────────┘   └───────────────┘   └───────────────┘
-```
-
-**Phase 1 - Research:** Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration that may or may not lead to building something.
-
-**Phase 2 - Discussion:** Captures the back-and-forth exploration of a problem. Documents competing solutions, why certain approaches won or lost, edge cases discovered, and the journey to decisions, not just the decisions themselves.
-
-**Phase 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).
-
-**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).
-
-**Phase 6 - Review:** Validates completed work against specification requirements and plan acceptance criteria. The specification is the validated source of truth; earlier phases may contain rejected ideas that were intentionally filtered out. Provides structured feedback without fixing code directly.
-
 ## Project Structure
 
 ### Output Files
 
-Documents are stored in your project using a **phase-first** organisation:
+Documents are stored in your project using a **phase-first** organisation. Early phases use flat files; later phases use topic directories with multiple files for tracking and analysis.
 
 ```
 docs/workflow/
-├── research/              # Phase 1 - flat, semantically named files
+├── research/                          # Phase 1 — flat, semantically named
 │   ├── exploration.md
 │   ├── competitor-analysis.md
 │   └── pricing-models.md
-├── discussion/            # Phase 2 - one file per topic
-│   └── {topic}.md
-├── specification/         # Phase 3 - one file per topic
+├── discussion/                        # Phase 2 — one file per topic
 │   └── {topic}.md
-└── planning/              # Phase 4 - one file per topic
+├── specification/                     # Phase 3 — directory per topic
+│   └── {topic}/
+│       └── specification.md
+├── planning/                          # Phase 4 — directory per topic
+│   └── {topic}/
+│       ├── plan.md                    #   Plan index (phases, metadata)
+│       └── tasks/                     #   Task files (local-markdown format)
+│           ├── {topic}-1-1.md
+│           └── {topic}-1-2.md
+├── implementation/                    # Phase 5 — directory per topic
+│   └── {topic}/
+│       └── tracking.md               #   Progress, gates, current task
+└── review/                            # Phase 6 — one file per review
     └── {topic}.md
 ```
 
-Research starts with `exploration.md` and splits into topic files as themes emerge. From discussion onwards, each topic gets its own file per phase.
+Research starts with `exploration.md` and splits into topic files as themes emerge. From specification onwards, each topic gets its own directory. Planning task storage varies by [output format](#output-formats) — the tree above shows local-markdown; Tick and Linear store tasks externally.
 
 ### Package Structure
 
@@ -280,7 +278,7 @@ Sequential skills that expect files from previous phases and pass content to pro
 | [**/start-research**](skills/start-research/)                                | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
 | [**/start-discussion**](skills/start-discussion/)                            | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
 | [**/start-specification**](skills/start-specification/)                      | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
-| [**/start-planning**](skills/start-planning/)                                | 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-planning**](skills/start-planning/)                                | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats. |
 | [**/start-implementation**](skills/start-implementation/)                    | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
 | [**/start-review**](skills/start-review/)                                    | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
 

package/agents/implementation-analysis-task-writer.md

@@ -30,7 +30,7 @@ You receive via the orchestrator's prompt:
 
 ## Update the Plan Index File
 
-The Plan Index File (`docs/workflow/planning/{topic}.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
+The Plan Index File (`docs/workflow/planning/{topic}/plan.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
 
 Append at the end of the Plan Index File body:
 
@@ -41,16 +41,17 @@ status: approved
 **Goal**: Address findings from implementation analysis cycle {N}.
 
 #### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| {topic}-{phase}-1 | {Task Title} | — | authored |
-| {topic}-{phase}-2 | {Task Title} | — | authored |
+| ID | Name | Edge Cases | Status | Ext ID |
+|----|------|------------|--------|--------|
+| {topic}-{phase}-1 | {Task Title} | — | authored | {ext-id} |
+| {topic}-{phase}-2 | {Task Title} | — | authored | {ext-id} |
 ```
 
 - Use `status: approved` for the phase (it's pre-approved by the user in the approval gate)
 - Use `authored` for each task status (the task files are fully written)
 - Use `—` for edge cases (analysis tasks don't have separate edge case annotations)
 - Task IDs must match the IDs used in the created task files
+- `Ext ID` must contain the external identifier for the task as exposed by the output format.
 
 ## Hard Rules
 

package/agents/planning-review-integrity.md

@@ -0,0 +1,71 @@
+---
+name: planning-review-integrity
+description: Reviews plan structural quality, implementation readiness, and standards adherence. Invoked by technical-planning skill during plan review.
+tools: Read, Glob, Grep, Write, Bash
+model: opus
+---
+
+# Planning Review: Integrity
+
+Perform an **integrity review** of the plan as a standalone document — checking structural quality, implementation readiness, and adherence to planning standards.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **Review criteria path** — `review-integrity.md` with detailed review criteria and tracking file format
+2. **Plan path** — the Plan Index File
+3. **Format reading.md path** — the output format's reading instructions for locating task files
+4. **Cycle number** — current review cycle (for tracking file naming)
+5. **Topic name** — for file naming and paths
+6. **Task design path** — `task-design.md` with the canonical task template and field requirements
+
+## Your Process
+
+1. **Read the review criteria** (`review-integrity.md`) — absorb all review dimensions before starting
+2. **Read the Plan Index File** for structure and phase overview
+3. **Locate and read all task files** following the format's reading.md instructions
+4. **Evaluate all review criteria** as defined in the review criteria file
+5. **Create the tracking file** — write findings to `review-integrity-tracking-c{N}.md` in the plan topic directory, using the format defined in the review criteria file
+6. **Commit the tracking file**: `planning({topic}): integrity review cycle {N}`
+7. **Return status**
+
+## Writing Full Fix Content
+
+For each finding, the tracking file must contain the **exact content** that would be written to the plan if the fix is approved. The orchestrator presents this content to the user as-is — what the user sees is what gets applied.
+
+- **Current**: Copy the existing content verbatim from the plan/task file. This shows the user exactly what's there now.
+- **Proposed**: Write the replacement content in full plan format. This is what will replace the current content if approved.
+
+For `add-task` or `add-phase`, omit **Current** and write the complete new content in **Proposed**.
+For `remove-task` or `remove-phase`, include **Current** for reference and omit **Proposed**.
+
+**Task structure**: Read `task-design.md` before writing any proposed content. All task content — whether new tasks (`add-task`) or modifications to existing tasks (`update-task`, `add-to-task`) — must follow the canonical task template and field requirements defined there. This is the same template the planning agents used to create the plan.
+
+**Do not write summaries or descriptions** like "restructure the acceptance criteria". Write the actual restructured criteria as they should appear in the plan.
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **Read everything** — plan and all tasks. Do not skip or skim.
+2. **Write only the tracking file** — do not modify the plan or tasks
+3. **Commit the tracking file** — ensures it survives context refresh
+4. **No user interaction** — return status to the orchestrator
+5. **Full fix content** — every finding must include complete Current/Proposed content in plan format. No summaries.
+6. **Proportional** — prioritize by impact. Don't nitpick style when architecture is wrong.
+7. **Task scope only** — check the plan as built; don't redesign it
+
+## Your Output
+
+Return a brief status:
+
+```
+STATUS: findings | clean
+CYCLE: {N}
+TRACKING_FILE: {path to tracking file}
+FINDING_COUNT: {N}
+```
+
+- `clean`: No findings. The plan meets structural quality standards.
+- `findings`: Tracking file contains findings for the orchestrator to present to the user.

package/agents/planning-review-traceability.md

@@ -0,0 +1,74 @@
+---
+name: planning-review-traceability
+description: Analyzes plan traceability against specification in both directions. Invoked by technical-planning skill during plan review.
+tools: Read, Glob, Grep, Write, Bash
+model: opus
+---
+
+# Planning Review: Traceability
+
+Perform a **traceability analysis** comparing the plan against its specification in both directions — verifying that everything from the spec is in the plan, and everything in the plan traces back to the spec.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **Review criteria path** — `review-traceability.md` with detailed analysis criteria and tracking file format
+2. **Specification path** — the validated specification to trace against
+3. **Plan path** — the Plan Index File
+4. **Format reading.md path** — the output format's reading instructions for locating task files
+5. **Cycle number** — current review cycle (for tracking file naming)
+6. **Topic name** — for file naming and paths
+7. **Task design path** — `task-design.md` with the canonical task template and field requirements
+
+## Your Process
+
+1. **Read the review criteria** (`review-traceability.md`) — absorb the full analysis criteria before starting
+2. **Read the specification** in full — do not rely on summaries or memory
+3. **Read the Plan Index File** for structure and phase overview
+4. **Locate and read all task files** following the format's reading.md instructions
+5. **Perform Direction 1** (Spec → Plan): verify every spec element has plan coverage
+6. **Perform Direction 2** (Plan → Spec): verify every plan element traces to the spec
+7. **Create the tracking file** — write findings to `review-traceability-tracking-c{N}.md` in the plan topic directory, using the format defined in the review criteria file
+8. **Commit the tracking file**: `planning({topic}): traceability review cycle {N}`
+9. **Return status**
+
+## Writing Full Fix Content
+
+For each finding, the tracking file must contain the **exact content** that would be written to the plan if the fix is approved. The orchestrator presents this content to the user as-is — what the user sees is what gets applied.
+
+- **Current**: Copy the existing content verbatim from the plan/task file. This shows the user exactly what's there now.
+- **Proposed**: Write the replacement content in full plan format. This is what will replace the current content if approved.
+
+For `add-task` or `add-phase`, omit **Current** and write the complete new content in **Proposed**.
+For `remove-task` or `remove-phase`, include **Current** for reference and omit **Proposed**.
+
+**Task structure**: Read `task-design.md` before writing any proposed content. All task content — whether new tasks (`add-task`) or modifications to existing tasks (`update-task`, `add-to-task`) — must follow the canonical task template and field requirements defined there.
+
+**Do not write summaries or descriptions** like "add missing acceptance criteria for edge case X". Write the actual acceptance criteria as they should appear in the plan.
+
+## Hard Rules
+
+**MANDATORY. No exceptions.**
+
+1. **Read everything** — spec, plan, and all tasks. Do not skip or skim.
+2. **Write only the tracking file** — do not modify the plan, tasks, or specification
+3. **Commit the tracking file** — ensures it survives context refresh
+4. **No user interaction** — return status to the orchestrator. The orchestrator handles presentation and approval.
+5. **Full fix content** — every finding must include complete Current/Proposed content in plan format. No summaries.
+6. **Trace, don't invent** — if content can't be traced to the spec, flag it. Don't justify it.
+7. **Spec-grounded fixes** — proposed content must come from the specification. Do not hallucinate plan content.
+
+## Your Output
+
+Return a brief status:
+
+```
+STATUS: findings | clean
+CYCLE: {N}
+TRACKING_FILE: {path to tracking file}
+FINDING_COUNT: {N}
+```
+
+- `clean`: No findings. The plan is a faithful translation of the specification.
+- `findings`: Tracking file contains findings for the orchestrator to present to the user.

package/agents/planning-task-designer.md

@@ -55,10 +55,10 @@ Phase {N}: {Phase Name}
 
 ```markdown
 #### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| {topic}-{phase}-1 | {Task Name} | {list} | pending |
-| {topic}-{phase}-2 | {Task Name} | {list} | pending |
+| ID | Name | Edge Cases | Status | Ext ID |
+|----|------|------------|--------|--------|
+| {topic}-{phase}-1 | {Task Name} | {list} | pending | |
+| {topic}-{phase}-2 | {Task Name} | {list} | pending | |
 ```
 
 Use placeholder IDs in the format `{topic}-{phase}-{seq}`. The orchestrator will use the topic name from the Plan Index File.

package/package.json

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

package/skills/link-dependencies/SKILL.md

@@ -20,7 +20,7 @@ Scan the codebase for existing plans:
 
 1. **Find plan files**: Look in `docs/workflow/planning/`
    - Run `ls docs/workflow/planning/` to list plan files
-   - Each file is named `{topic}.md`
+   - Each topic is a directory containing `plan.md`
 
 2. **Extract plan metadata**: For each plan file
    - Read the frontmatter to get the `format:` field
@@ -116,7 +116,7 @@ Key:
 
 For each unresolved dependency:
 
-1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}.md` exist?
+1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}/plan.md` exist?
    - If no match: Mark as "no plan exists" - cannot resolve yet
 
 2. **If plan exists**: Load the format's reading reference
@@ -168,7 +168,7 @@ Unresolved (no matching plan exists):
   • {source} → {target}: {description}
 
 Updated files:
-  • docs/workflow/planning/{topic}.md
+  • docs/workflow/planning/{topic}/plan.md
 ```
 
 If any dependencies remain unresolved:

package/skills/migrate/scripts/migrations/002-specification-frontmatter.sh

@@ -52,6 +52,11 @@ fi
 for file in "$SPEC_DIR"/*.md; do
     [ -f "$file" ] || continue
 
+    # Skip tracking/review files — only process specification documents
+    case "$(basename "$file")" in
+        *-review-*|*-tracking*) continue ;;
+    esac
+
     # Check if already migrated via tracking
     if is_migrated "$file" "$MIGRATION_ID"; then
         report_skip "$file"

package/skills/migrate/scripts/migrations/003-planning-frontmatter.sh

@@ -50,6 +50,11 @@ fi
 for file in "$PLAN_DIR"/*.md; do
     [ -f "$file" ] || continue
 
+    # Skip tracking/review files — only process plan documents
+    case "$(basename "$file")" in
+        *-review-*|*-tracking*) continue ;;
+    esac
+
     # Check if already migrated via tracking
     if is_migrated "$file" "$MIGRATION_ID"; then
         report_skip "$file"

package/skills/migrate/scripts/migrations/004-sources-object-format.sh

@@ -87,6 +87,11 @@ extract_simple_sources() {
 for file in "$SPEC_DIR"/*.md; do
     [ -f "$file" ] || continue
 
+    # Skip tracking/review files — only process specification documents
+    case "$(basename "$file")" in
+        *-review-*|*-tracking*) continue ;;
+    esac
+
     # Check if already migrated via tracking
     if is_migrated "$file" "$MIGRATION_ID"; then
         report_skip "$file"

package/skills/migrate/scripts/migrations/005-plan-external-deps-frontmatter.sh

@@ -117,6 +117,11 @@ parse_dep_line() {
 for file in "$PLAN_DIR"/*.md; do
     [ -f "$file" ] || continue
 
+    # Skip tracking/review files — only process plan documents
+    case "$(basename "$file")" in
+        *-review-*|*-tracking*) continue ;;
+    esac
+
     # Check if already migrated via tracking
     if is_migrated "$file" "$MIGRATION_ID"; then
         report_skip "$file"