@leeovery/claude-technical-workflows 2.1.26 → 2.1.28

package/skills/technical-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-planning
-description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from docs/workflow/specification/{topic}.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}.md that can be executed via strict TDD."
+description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from docs/workflow/specification/{topic}/specification.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}/plan.md that can be executed via strict TDD."
 user-invocable: false
 ---
 
@@ -28,11 +28,29 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 **Before proceeding**, verify the required input is available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
-- **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 no specification content provided
 
-- **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?"
+> *Output the next fenced block as a code block:*
+
+```
+I need the specification content to plan from. Could you point me to the
+specification file (e.g., docs/workflow/specification/{topic}/specification.md),
+or provide the content directly?
+```
+
+**STOP.** Wait for user response.
+
+#### If specification seems incomplete or not concluded
+
+> *Output the next fenced block as a code block:*
+
+```
+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?
+```
+
+**STOP.** Wait for user response.
 
 ---
 
@@ -44,6 +62,7 @@ Context refresh (compaction) summarizes the conversation, losing procedural deta
 2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
 3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
 4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+5. **Check `author_gate_mode` and `finding_gate_mode`** in the Plan Index File frontmatter — if `auto`, the user previously opted in during this session. Preserve these values.
 
 Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
 
@@ -53,7 +72,7 @@ Do not guess at progress or continue from memory. The files on disk and git hist
 
 This process constructs a plan from a specification. A plan consists of:
 
-- **Plan Index File** — `docs/workflow/planning/{topic}.md`. Contains frontmatter (topic, format, status, progress), phases with acceptance criteria, and task tables tracking status. This is the single source of truth for planning progress.
+- **Plan Index File** — `docs/workflow/planning/{topic}/plan.md`. Contains frontmatter (topic, format, status, progress), phases with acceptance criteria, and task tables tracking status. This is the single source of truth for planning progress.
 - **Authored Tasks** — Detailed task files written to the chosen **Output Format** (selected during planning). The output format determines where and how task detail is stored.
 
 Follow every step in sequence. No steps are optional.
@@ -66,7 +85,7 @@ When announcing a new step, output `── ── ── ── ──` on its o
 
 ## Step 0: Resume Detection
 
-Check if a Plan Index File already exists at `docs/workflow/planning/{topic}.md`.
+Check if a Plan Index File already exists at `docs/workflow/planning/{topic}/plan.md`.
 
 #### If no Plan Index File exists
 
@@ -99,6 +118,8 @@ Found existing plan for **{topic}** (previously reached phase {N}, task {M}).
 
 If the specification changed, update `spec_commit` in the Plan Index File frontmatter to the current commit hash.
 
+Reset `author_gate_mode` and `finding_gate_mode` to `gated` in the Plan Index File frontmatter (fresh invocation = fresh gates).
+
 → Proceed to **Step 1**.
 
 #### If `restart`
@@ -151,20 +172,22 @@ Once selected:
 
 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:
+3. Create the Plan Index File at `docs/workflow/planning/{topic}/plan.md` with the following frontmatter and title:
 
 ```yaml
 ---
 topic: {topic-name}
 status: planning
 format: {chosen-format}
-specification: ../specification/{topic}.md
+specification: ../specification/{topic}/specification.md
 cross_cutting_specs:              # Omit if none
-  - ../specification/{spec}.md
+  - ../specification/{spec}/specification.md
 spec_commit: {output of git rev-parse HEAD}
 created: YYYY-MM-DD  # Use today's actual date
 updated: YYYY-MM-DD  # Use today's actual date
 external_dependencies: []
+author_gate_mode: gated
+finding_gate_mode: gated
 planning:
   phase: 1
   task: ~
@@ -189,7 +212,7 @@ Load **[planning-principles.md](references/planning-principles.md)** and follow
 
 ## Step 3: Verify Source Material
 
-Load **[steps/verify-source-material.md](references/steps/verify-source-material.md)** and follow its instructions as written.
+Load **[verify-source-material.md](references/verify-source-material.md)** and follow its instructions as written.
 
 → Proceed to **Step 4**.
 
@@ -197,7 +220,7 @@ Load **[steps/verify-source-material.md](references/steps/verify-source-material
 
 ## Step 4: Plan Construction
 
-Load **[steps/plan-construction.md](references/steps/plan-construction.md)** and follow its instructions as written.
+Load **[plan-construction.md](references/plan-construction.md)** and follow its instructions as written.
 
 → Proceed to **Step 5**.
 
@@ -205,7 +228,7 @@ Load **[steps/plan-construction.md](references/steps/plan-construction.md)** and
 
 ## Step 5: Analyze Task Graph
 
-Load **[steps/analyze-task-graph.md](references/steps/analyze-task-graph.md)** and follow its instructions as written.
+Load **[analyze-task-graph.md](references/analyze-task-graph.md)** and follow its instructions as written.
 
 → Proceed to **Step 6**.
 
@@ -213,7 +236,7 @@ Load **[steps/analyze-task-graph.md](references/steps/analyze-task-graph.md)** a
 
 ## Step 6: Resolve External Dependencies
 
-Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
+Load **[resolve-dependencies.md](references/resolve-dependencies.md)** and follow its instructions as written.
 
 → Proceed to **Step 7**.
 
@@ -221,7 +244,7 @@ Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)
 
 ## Step 7: Plan Review
 
-Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
+Load **[plan-review.md](references/plan-review.md)** and follow its instructions as written.
 
 → Proceed to **Step 8**.
 
@@ -229,16 +252,35 @@ Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its
 
 ## Step 8: Conclude the Plan
 
-After the review is complete:
+> **CHECKPOINT**: Do not conclude if any tasks in the Plan Index File show `status: pending`. All tasks must be `authored` before concluding.
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Conclude plan and mark as concluded
+- **Comment** — Add context before concluding
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If comment
+
+Discuss the user's context. If additional work is needed, route back to **Step 6** or **Step 7** as appropriate. Otherwise, re-present the sign-off prompt above.
+
+#### If yes
 
 1. **Update plan status** — Set `status: concluded` in the Plan Index File frontmatter
-3. **Final commit** — Commit the concluded plan
-4. **Present completion summary**:
+2. **Final commit** — Commit the concluded plan: `planning({topic}): conclude plan`
+3. **Present completion summary**:
 
-"Planning is complete for **{topic}**.
+> *Output the next fenced block as markdown (not a code block):*
 
-The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceability against the specification and structural integrity.
+```
+Planning is complete for **{topic}**.
 
-Status has been marked as `concluded`. The plan is ready for implementation."
+The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceability against the specification and structural integrity.
 
-> **CHECKPOINT**: Do not conclude if any tasks in the Plan Index File show `status: pending`. All tasks must be `authored` before concluding.
+Status has been marked as `concluded`. The plan is ready for implementation.
+```

package/skills/technical-planning/references/{steps/analyze-task-graph.md → analyze-task-graph.md}

@@ -1,26 +1,29 @@
 # Analyze Task Graph
 
-*Reference for **[technical-planning](../../SKILL.md)***
+*Reference for **[technical-planning](../SKILL.md)***
 
 ---
 
-This step uses the `planning-dependency-grapher` agent (`../../../../agents/planning-dependency-grapher.md`) to analyze all authored tasks, establish internal dependencies, assign priorities, and detect cycles. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-dependency-grapher` agent (`../../../agents/planning-dependency-grapher.md`) to analyze all authored tasks, establish internal dependencies, assign priorities, and detect cycles. You invoke the agent, present its output, and handle the approval gate.
 
 ---
 
 ## Analyze Dependencies and Priorities
 
-Orient the user:
+> *Output the next fenced block as a code block:*
 
-"All tasks are authored. Now I'll analyze internal dependencies and priorities across the full plan."
+```
+All tasks are authored. Now I'll analyze internal dependencies and
+priorities across the full plan.
+```
 
-Read **[output-formats.md](../output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[reading.md](../output-formats/{format}/reading.md)** and **[graph.md](../output-formats/{format}/graph.md)**.
+Read **[output-formats.md](output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[reading.md](output-formats/{format}/reading.md)** and **[graph.md](output-formats/{format}/graph.md)**.
 
 ### Invoke the Agent
 
 Invoke `planning-dependency-grapher` with these file paths:
 
-1. **Plan Index File path**: `docs/workflow/planning/{topic}.md`
+1. **Plan Index File path**: `docs/workflow/planning/{topic}/plan.md`
 2. **reading.md**: the format's reading reference loaded above
 3. **graph.md**: the format's graph reference loaded above
 
@@ -32,11 +35,15 @@ The agent clears any existing dependencies/priorities, analyzes all tasks, and
 
 #### If the agent reports no changes needed (`STATUS: no-changes`)
 
-The natural task order is already correct. Present as rendered markdown (not in a code block):
+The natural task order is already correct.
+
+> *Output the next fenced block as markdown (not a code block):*
 
-"I've analyzed all {M} tasks and the natural execution order is already correct — no explicit dependencies or priorities are needed.
+```
+I've analyzed all {M} tasks and the natural execution order is already correct — no explicit dependencies or priorities are needed.
 
-{notes from agent output}"
+{notes from agent output}
+```
 
 > *Output the next fenced block as markdown (not a code block):*
 
@@ -52,21 +59,30 @@ The natural task order is already correct. Present as rendered markdown (not in
 
 #### If the agent reports a cycle (`STATUS: blocked`)
 
-No changes were applied. Present the cycle to the user:
+No changes were applied.
 
-"The dependency analysis found a circular dependency:
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+The dependency analysis found a circular dependency:
 
 {cycle chain from agent output}
 
-This must be resolved before continuing. The cycle usually means two tasks each assume the other is done first — one needs to be restructured or the dependency removed."
+This must be resolved before continuing. The cycle usually means two tasks each assume the other is done first — one needs to be restructured or the dependency removed.
+```
+
+**STOP.** Wait for the user to decide how to resolve.
 
-**STOP.** Wait for the user to decide how to resolve. Options include adjusting task scope, merging tasks, or removing a dependency. Re-invoke the agent after changes.
+Options include adjusting task scope, merging tasks, or removing a dependency. Re-invoke the agent after changes.
 
 #### If the agent applied changes successfully (`STATUS: complete`)
 
-Dependencies and priorities have already been written to the task files. Present as rendered markdown (not in a code block):
+Dependencies and priorities have already been written to the task files.
 
-"I've analyzed and applied dependencies and priorities across all {M} tasks:
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+I've analyzed and applied dependencies and priorities across all {M} tasks:
 
 **Dependencies** ({count} relationships):
 {dependency list from agent output}
@@ -74,7 +90,8 @@ Dependencies and priorities have already been written to the task files. Present
 **Priorities**:
 {priority list from agent output}
 
-{any notes from agent output}"
+{any notes from agent output}
+```
 
 > *Output the next fenced block as markdown (not a code block):*
 

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

@@ -0,0 +1,100 @@
+# Author Tasks
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This step uses the `planning-task-author` agent (`../../../agents/planning-task-author.md`) to write full detail for a single task. You invoke the agent, present its output, and handle the approval gate.
+
+---
+
+## Author the Task
+
+### Invoke the Agent
+
+Invoke `planning-task-author` with these file paths:
+
+1. **read-specification.md**: `read-specification.md`
+2. **Specification**: path from the Plan Index File's `specification:` field
+3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
+4. **task-design.md**: `task-design.md`
+5. **All approved phases**: the complete phase structure from the Plan Index File body
+6. **Task list for current phase**: the approved task table
+7. **Target task**: the task name, edge cases, and ID from the table
+8. **Output format authoring reference**: path to the format's `authoring.md` (e.g., `output-formats/{format}/authoring.md`)
+
+### Check Gate Mode
+
+The agent returns complete task detail following the task template from task-design.md. What the user sees is what gets logged.
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+{task detail from planning-task-author agent}
+```
+
+Check `author_gate_mode` in the Plan Index File frontmatter.
+
+#### If `author_gate_mode: auto`
+
+> *Output the next fenced block as a code block:*
+
+```
+Task {M} of {total}: {Task Name} — authored. Logging to plan.
+```
+
+→ Skip to **If approved** below.
+
+#### If `author_gate_mode: gated`
+
+**Task {M} of {total}: {Task Name}**
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+**To proceed:**
+- **`y`/`yes`** — Approved. I'll log it to the plan.
+- **`a`/`auto`** — Approve this and all remaining tasks automatically
+- **Or tell me what to change.**
+- **Or navigate** — a different phase or task, or the leading edge.
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for the user's response.
+
+#### If the user provides feedback
+
+Re-invoke `planning-task-author` with all original inputs PLUS:
+- **Previous output**: the current task detail
+- **User feedback**: what the user wants changed
+
+Present the revised task in full. Ask the same choice again. Repeat until approved.
+
+#### If the user navigates
+
+→ Return to **Plan Construction**.
+
+#### If `auto`
+
+Note that `author_gate_mode` should be updated to `auto` during the commit step below.
+
+→ Proceed to **If approved** below.
+
+#### If approved (`y`/`yes` or `auto`)
+
+> **CHECKPOINT**: If `author_gate_mode: gated`, verify before logging: (1) You presented this exact content, (2) The user explicitly approved with `y`/`yes` or equivalent — not a question, comment, or "okay" in passing, (3) You are writing exactly what was approved with no modifications.
+
+1. Write the task to the output format (format-specific — see authoring.md)
+2. Update the task table in the Plan Index File: set `status: authored`
+3. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
+4. If user chose `auto` at this gate: update `author_gate_mode: auto` in the Plan Index File frontmatter
+5. Commit: `planning({topic}): author task {task-id} ({task name})`
+
+> *Output the next fenced block as a code block:*
+
+```
+Task {M} of {total}: {Task Name} — authored.
+```
+
+→ Return to **Plan Construction**.

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

@@ -1,10 +1,10 @@
 # Define Phases
 
-*Reference for **[technical-planning](../../SKILL.md)***
+*Reference for **[technical-planning](../SKILL.md)***
 
 ---
 
-This step uses the `planning-phase-designer` agent (`../../../../agents/planning-phase-designer.md`) to define or review the phase structure. Whether phases are being designed for the first time or reviewed from a previous session, the process converges on the same approval gate.
+This step uses the `planning-phase-designer` agent (`../../../agents/planning-phase-designer.md`) to define or review the phase structure. Whether phases are being designed for the first time or reviewed from a previous session, the process converges on the same approval gate.
 
 ---
 
@@ -14,27 +14,33 @@ Read the Plan Index File. Check if phases already exist in the body.
 
 #### If phases exist
 
-Orient the user:
+> *Output the next fenced block as a code block:*
 
-"Phase structure already exists. I'll present it for your review."
+```
+Phase structure already exists. I'll present it for your review.
+```
 
 Continue to **Review and Approve** below.
 
 #### If no phases exist
 
-Orient the user:
+> *Output the next fenced block as a code block:*
 
-"I'll delegate phase design to a specialist agent. It will read the full specification and propose a phase structure — how we break this into independently testable stages."
+```
+I'll delegate phase design to a specialist agent. It will read the full
+specification and propose a phase structure — how we break this into
+independently testable stages.
+```
 
 ### Invoke the Agent
 
 Invoke `planning-phase-designer` with these file paths:
 
-1. **read-specification.md**: `../read-specification.md`
+1. **read-specification.md**: `read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
-4. **phase-design.md**: `../phase-design.md`
-5. **task-design.md**: `../task-design.md`
+4. **phase-design.md**: `phase-design.md`
+5. **task-design.md**: `task-design.md`
 
 The agent returns a complete phase structure. Write it directly to the Plan Index File body.
 

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

@@ -1,27 +1,31 @@
 # Define Tasks
 
-*Reference for **[technical-planning](../../SKILL.md)***
+*Reference for **[technical-planning](../SKILL.md)***
 
 ---
 
-This step uses the `planning-task-designer` agent (`../../../../agents/planning-task-designer.md`) to design a task list for a single phase. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-task-designer` agent (`../../../agents/planning-task-designer.md`) to design a task list for a single phase. You invoke the agent, present its output, and handle the approval gate.
 
 ---
 
 ## Design the Task List
 
-Orient the user:
+> *Output the next fenced block as a code block:*
 
-"Taking Phase {N}: {Phase Name} and breaking it into tasks. I'll delegate this to a specialist agent that will read the full specification and propose a task list."
+```
+Taking Phase {N}: {Phase Name} and breaking it into tasks. I'll delegate
+this to a specialist agent that will read the full specification and
+propose a task list.
+```
 
 ### Invoke the Agent
 
 Invoke `planning-task-designer` with these file paths:
 
-1. **read-specification.md**: `../read-specification.md`
+1. **read-specification.md**: `read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
-4. **task-design.md**: `../task-design.md`
+4. **task-design.md**: `task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
 6. **Target phase number**: the phase being broken into tasks
 

package/skills/technical-planning/references/invoke-review-integrity.md

@@ -0,0 +1,36 @@
+# Invoke Integrity Review
+
+*Reference for **[plan-review](plan-review.md)***
+
+---
+
+This step invokes the `planning-review-integrity` agent (`../../../agents/planning-review-integrity.md`) to review plan structural quality and implementation readiness.
+
+---
+
+## Invoke the Agent
+
+Invoke `planning-review-integrity` with:
+
+1. **Review criteria path**: `review-integrity.md` (in this directory)
+2. **Plan path**: `docs/workflow/planning/{topic}/plan.md`
+3. **Format reading.md path**: load **[output-formats.md](output-formats.md)**, find the entry matching the plan's `format:` field, and pass the format's `reading.md` path
+4. **Cycle number**: current `review_cycle` from the Plan Index File frontmatter
+5. **Topic name**: from the plan's `topic` frontmatter field
+6. **Task design path**: `task-design.md`
+
+---
+
+## Expected Result
+
+The agent returns a brief status:
+
+```
+STATUS: findings | clean
+CYCLE: {N}
+TRACKING_FILE: {path to tracking file}
+FINDING_COUNT: {N}
+```
+
+- `clean`: plan meets structural quality standards. No findings to process.
+- `findings`: tracking file contains findings with full fix content for the orchestrator to present to the user.

package/skills/technical-planning/references/invoke-review-traceability.md

@@ -0,0 +1,37 @@
+# Invoke Traceability Review
+
+*Reference for **[plan-review](plan-review.md)***
+
+---
+
+This step invokes the `planning-review-traceability` agent (`../../../agents/planning-review-traceability.md`) to analyze plan traceability against the specification.
+
+---
+
+## Invoke the Agent
+
+Invoke `planning-review-traceability` with:
+
+1. **Review criteria path**: `review-traceability.md` (in this directory)
+2. **Specification path**: from the plan's `specification` frontmatter field (resolved relative to the plan directory)
+3. **Plan path**: `docs/workflow/planning/{topic}/plan.md`
+4. **Format reading.md path**: load **[output-formats.md](output-formats.md)**, find the entry matching the plan's `format:` field, and pass the format's `reading.md` path
+5. **Cycle number**: current `review_cycle` from the Plan Index File frontmatter
+6. **Topic name**: from the plan's `topic` frontmatter field
+7. **Task design path**: `task-design.md`
+
+---
+
+## Expected Result
+
+The agent returns a brief status:
+
+```
+STATUS: findings | clean
+CYCLE: {N}
+TRACKING_FILE: {path to tracking file}
+FINDING_COUNT: {N}
+```
+
+- `clean`: plan is a faithful, complete translation of the specification. No findings to process.
+- `findings`: tracking file contains findings with full fix content for the orchestrator to present to the user.

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

@@ -28,13 +28,15 @@ No external tools required. This format uses plain markdown files stored in the
 
 ## Output Location
 
-Tasks are stored as individual markdown files in a `{topic}/` subdirectory under the planning directory:
+Tasks are stored as individual markdown files in a `tasks/` subdirectory under the topic directory:
 
 ```
 docs/workflow/planning/{topic}/
-├── {topic}-1-1.md              # Phase 1, task 1
-├── {topic}-1-2.md              # Phase 1, task 2
-└── {topic}-2-1.md              # Phase 2, task 1
+├── plan.md                     # Plan Index File (not a task)
+└── tasks/                      # Task files
+    ├── {topic}-1-1.md          # Phase 1, task 1
+    ├── {topic}-1-2.md          # Phase 1, task 2
+    └── {topic}-2-1.md          # Phase 2, task 1
 ```
 
 Task filename = task ID for easy lookup.

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

@@ -2,7 +2,7 @@
 
 ## Task Storage
 
-Each task is written to `docs/workflow/planning/{topic}/{task-id}.md` — a markdown file with frontmatter and a description body.
+Each task is written to `docs/workflow/planning/{topic}/tasks/{task-id}.md` — a markdown file with frontmatter and a description body.
 
 ```markdown
 ---
@@ -57,8 +57,8 @@ In the task file, add a **Needs Clarification** section:
 
 ## Cleanup (Restart)
 
-Delete the task detail directory for this topic:
+Delete the tasks directory — preserves `plan.md` (the Plan Index) and any review tracking files:
 
 ```bash
-rm -rf docs/workflow/planning/{topic}/
+rm -rf docs/workflow/planning/{topic}/tasks/
 ```

package/skills/technical-planning/references/output-formats/local-markdown/reading.md

@@ -4,7 +4,7 @@
 
 To retrieve all tasks for a plan:
 
-1. List all `.md` files in `docs/workflow/planning/{topic}/` (excluding the Plan Index)
+1. List all `.md` files in `docs/workflow/planning/{topic}/tasks/` — every file in this directory is a task file, no filtering needed
 2. Read each file's frontmatter to extract: `id`, `phase`, `status`, `priority`, `depends_on`
 3. Read the first heading for the task title
 
@@ -12,7 +12,7 @@ This provides the summary-level data needed for graphing, progress overview, or
 
 ## Extracting a Task
 
-To read a specific task, read the file at `docs/workflow/planning/{topic}/{task-id}.md`.
+To read a specific task, read the file at `docs/workflow/planning/{topic}/tasks/{task-id}.md`.
 
 The task file is self-contained — frontmatter holds id, phase, and status. The body contains the title and full description.
 
@@ -20,7 +20,7 @@ The task file is self-contained — frontmatter holds id, phase, and status. The
 
 To find the next task to implement:
 
-1. List task files in `docs/workflow/planning/{topic}/`
+1. List all `.md` files in `docs/workflow/planning/{topic}/tasks/`
 2. Filter to tasks where `status` is `pending` or `in-progress` (or missing — treat as `pending`)
 3. If any tasks have `depends_on`, check each referenced task's `status` — exclude the task unless all dependencies have `status: completed`
 4. Order by phase number (from task ID: `{topic}-{phase}-{seq}`) — complete all earlier phases first

package/skills/technical-planning/references/output-formats/local-markdown/updating.md

@@ -2,7 +2,7 @@
 
 ## Status Transitions
 
-Update the `status` field in the task file frontmatter at `docs/workflow/planning/{topic}/{task-id}.md`:
+Update the `status` field in the task file frontmatter at `docs/workflow/planning/{topic}/tasks/{task-id}.md`:
 
 | Transition | Value |
 |------------|-------|