@leeovery/claude-technical-workflows 2.0.48 → 2.0.49

package/agents/planning-phase-designer.md

@@ -1,6 +1,6 @@
 ---
 name: planning-phase-designer
-description: Designs implementation phases from a specification. Invoked by technical-planning skill during phase design (Step 4).
+description: Designs implementation phases from a specification. Invoked by technical-planning skill during plan construction.
 tools: Read, Glob, Grep
 model: inherit
 ---

package/agents/planning-task-author.md

@@ -1,6 +1,6 @@
 ---
 name: planning-task-author
-description: Writes full detail for a single plan task. Invoked by technical-planning skill during task authoring (Step 6).
+description: Writes full detail for a single plan task. Invoked by technical-planning skill during plan construction.
 tools: Read, Glob, Grep
 model: inherit
 ---

package/agents/planning-task-designer.md

@@ -1,6 +1,6 @@
 ---
 name: planning-task-designer
-description: Breaks a single phase into a task list with edge cases. Invoked by technical-planning skill during task design (Step 5).
+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
 ---

package/package.json

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

package/skills/technical-planning/SKILL.md

@@ -65,7 +65,7 @@ Load **[spec-change-detection.md](references/spec-change-detection.md)** to chec
 >
 > {spec change summary from spec-change-detection.md}
 >
-> - **`continue`** — Walk through the plan from the start. You can review, amend, or skip to any point — including straight to the leading edge.
+> - **`continue`** — Walk through the plan from the start. You can review, amend, or navigate at any point — including straight to the leading edge.
 > - **`restart`** — Erase all planning work for this topic and start fresh. This deletes the Plan Index File and any Authored Tasks. Other topics are unaffected."
 
 **STOP.** Wait for user response.
@@ -144,39 +144,35 @@ Load **[planning-principles.md](references/planning-principles.md)** and follow
 
 Load **[steps/verify-source-material.md](references/steps/verify-source-material.md)** and follow its instructions as written.
 
----
-
-## Step 4: Define Phases
-
-Load **[steps/define-phases.md](references/steps/define-phases.md)** and follow its instructions as written.
+→ Proceed to **Step 4**.
 
 ---
 
-## Step 5: Define Tasks
-
-Load **[steps/define-tasks.md](references/steps/define-tasks.md)** and follow its instructions as written.
+## Step 4: Plan Construction
 
----
-
-## Step 6: Author Tasks
+Load **[steps/plan-construction.md](references/steps/plan-construction.md)** and follow its instructions as written.
 
-Load **[steps/author-tasks.md](references/steps/author-tasks.md)** and follow its instructions as written.
+→ Proceed to **Step 5**.
 
 ---
 
-## Step 7: Resolve External Dependencies
+## Step 5: Resolve External Dependencies
 
 Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
 
+→ Proceed to **Step 6**.
+
 ---
 
-## Step 8: Plan Review
+## Step 6: Plan Review
 
 Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
 
+→ Proceed to **Step 7**.
+
 ---
 
-## Step 9: Conclude the Plan
+## Step 7: Conclude the Plan
 
 After the review is complete:
 

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

@@ -4,35 +4,15 @@
 
 ---
 
-This step uses the `planning-task-author` agent (`.claude/agents/planning-task-author.md`) to write full task detail. You invoke the agent per task, present its output, and handle the approval gate.
+This step uses the `planning-task-author` agent (`.claude/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.
 
 ---
 
-## Check for Existing Authored Tasks
-
-Read the Plan Index File. Check the task table under the current phase.
-
-**For each task:**
-- If `status: authored` → skip (already written to output format)
-- If `status: pending` → needs authoring
-
-Walk through tasks in order. Already-authored tasks are presented for quick review (user can approve or amend). Pending tasks need full authoring.
-
-**If all tasks in current phase are authored:** → Return to Step 5 for next phase, or Step 7 if all phases complete.
-
----
-
-## Author Tasks
-
-Orient the user:
-
-> "Task list for Phase {N} is agreed. I'll work through each task one at a time — delegating to a specialist agent that will read the full specification and write the complete task detail. You'll review each one before it's logged."
-
-Work through the task list **one task at a time**.
+## Author the Task
 
 ### Invoke the Agent
 
-For each pending task, invoke `planning-task-author` with these file paths:
+Invoke `planning-task-author` with these file paths:
 
 1. **read-specification.md**: `.claude/skills/technical-planning/references/read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
@@ -52,9 +32,9 @@ After presenting, ask:
 > **Task {M} of {total}: {Task Name}**
 >
 > **To proceed:**
-> - **`y`/`yes`** — Approved. I'll log it to the plan verbatim.
+> - **`y`/`yes`** — Approved. I'll log it to the plan.
 > - **Or tell me what to change.**
-> - **`skip to {X}`** — Navigate to different task/phase
+> - **Or navigate** — a different phase or task, or the leading edge.
 
 **STOP.** Wait for the user's response.
 
@@ -66,31 +46,21 @@ Re-invoke `planning-task-author` with all original inputs PLUS:
 
 Present the revised task in full. Ask the same choice again. Repeat until approved.
 
+#### If the user navigates
+
+→ Return to **Plan Construction**.
+
 #### If approved (`y`/`yes`)
 
 > **CHECKPOINT**: Before logging, verify: (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 output adapter)
 2. Update the task table in the Plan Index File: set `status: authored`
-3. Update the `planning:` block in frontmatter: note current phase and task
+3. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
 4. Commit: `planning({topic}): author task {task-id} ({task name})`
 
 Confirm:
 
 > "Task {M} of {total}: {Task Name} — authored."
 
-#### Next task or phase complete
-
-**If tasks remain in this phase:** → Return to the top with the next task. Present it, ask, wait.
-
-**If all tasks in this phase are authored:**
-
-Update `planning:` block and commit: `planning({topic}): complete Phase {N} tasks`
-
-```
-Phase {N}: {Phase Name} — complete ({M} tasks authored).
-```
-
-→ Return to **Step 5** for the next phase.
-
-**If all phases are complete:** → Proceed to **Step 7**.
+→ Return to **Plan Construction**.

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

@@ -4,34 +4,27 @@
 
 ---
 
-This step uses the `planning-phase-designer` agent (`.claude/agents/planning-phase-designer.md`) to design phases. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-phase-designer` agent (`.claude/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.
 
 ---
 
-## Check for Existing Phases
+## Determine Phase State
 
 Read the Plan Index File. Check if phases already exist in the body.
 
-**If phases exist with `status: approved`:**
-- Present them to the user for review (deterministic replay)
-- User can approve (`y`), amend, or navigate (`skip to {X}`)
-- If amended, re-invoke the agent with the existing phases + user feedback
-- Once approved (or skipped), proceed to Step 5
+#### If phases exist
 
-**If phases exist with `status: draft`:**
-- Present the draft for review/approval
-- Continue the approval flow below
+Orient the user:
 
-**If no phases exist:**
-- Continue with fresh phase design below
+> "Phase structure already exists. I'll present it for your review."
 
----
+Continue to **Review and Approve** below.
 
-## Fresh Phase Design
+#### If no phases exist
 
 Orient the user:
 
-> "I'm going to 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. Once we agree on the phases, we'll take each one and break it into tasks."
+> "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
 
@@ -43,8 +36,6 @@ Invoke `planning-phase-designer` with these file paths:
 4. **phase-design.md**: `.claude/skills/technical-planning/references/phase-design.md`
 5. **task-design.md**: `.claude/skills/technical-planning/references/task-design.md`
 
-### Present the Output
-
 The agent returns a complete phase structure. Write it directly to the Plan Index File body.
 
 Update the frontmatter `planning:` block:
@@ -56,13 +47,22 @@ planning:
 
 Commit: `planning({topic}): draft phase structure`
 
+Continue to **Review and Approve** below.
+
+---
+
+## Review and Approve
+
 Present the phase structure to the user.
 
 **STOP.** Ask:
 
+> **Phase Structure**
+>
 > **To proceed:**
 > - **`y`/`yes`** — Approved. I'll proceed to task breakdown.
 > - **Or tell me what to change** — reorder, split, merge, add, edit, or remove phases.
+> - **Or navigate** — a different phase or task, or the leading edge.
 
 #### If the user provides feedback
 
@@ -74,8 +74,9 @@ Update the Plan Index File with the revised output, re-present, and ask again. R
 
 #### If approved
 
+**If the phase structure is new or was amended:**
+
 1. Update each phase in the Plan Index File: set `status: approved` and `approved_at: YYYY-MM-DD` (use today's actual date)
-2. Update `planning:` block in frontmatter to note current position
-3. Commit: `planning({topic}): approve phase structure`
+2. Commit: `planning({topic}): approve phase structure`
 
-→ Proceed to **Step 5**.
+**If the phase structure was already approved and unchanged:** No updates needed.

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

@@ -4,32 +4,15 @@
 
 ---
 
-This step uses the `planning-task-designer` agent (`.claude/agents/planning-task-designer.md`) to break phases into task lists. You invoke the agent per phase, present its output, and handle the approval gate.
+This step uses the `planning-task-designer` agent (`.claude/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.
 
 ---
 
-## Check for Existing Task Tables
-
-Read the Plan Index File. Check the task table under each phase.
-
-**For each phase with an existing task table:**
-- If all tasks show `status: authored` → skip to next phase
-- If task table exists but not all approved → present for review (deterministic replay)
-- User can approve (`y`), amend, or navigate (`skip to {X}`)
-
-Walk through each phase in order, presenting existing task tables for review before moving to phases that need fresh work.
-
-**If all phases have approved task tables:** → Proceed to Step 6.
-
-**If no task table for current phase:** Continue with fresh task design below.
-
----
-
-## Fresh Task Design
+## Design the Task List
 
 Orient the user:
 
-> "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. Once we agree on the list, I'll write each task out in full detail."
+> "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
 
@@ -60,8 +43,9 @@ Present the task overview to the user.
 **STOP.** Ask:
 
 > **To proceed:**
-> - **`y`/`yes`** — Approved. I'll begin writing full task detail.
+> - **`y`/`yes`** — Approved.
 > - **Or tell me what to change** — reorder, split, merge, add, edit, or remove tasks.
+> - **Or navigate** — a different phase or task, or the leading edge.
 
 #### If the user provides feedback
 
@@ -73,7 +57,11 @@ Update the Plan Index File with the revised task table, re-present, and ask agai
 
 #### If approved
 
-1. Update the `planning:` block to note task authoring is starting
+**If the task list is new or was amended:**
+
+1. Advance the `planning:` block to the first task in this phase
 2. Commit: `planning({topic}): approve Phase {N} task list`
 
-→ Proceed to **Step 6**.
+**If the task list was already approved and unchanged:** No updates needed.
+
+→ Return to **Plan Construction**.

package/skills/technical-planning/references/steps/plan-construction.md

@@ -0,0 +1,131 @@
+# Plan Construction
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+This step constructs the complete plan — defining phases, designing task lists, and authoring every task. It operates as a nested structure:
+
+    ┌─────────────────────────────────────────────────────┐
+    │                                                     │
+    │  Phase Structure — define or review all phases      │
+    │                                                     │
+    │  ┌─────────────────────────────────────────────┐    │
+    │  │  For each phase:                            │    │
+    │  │                                             │    │
+    │  │    Step A → Define tasks for the phase      │    │
+    │  │                                             │    │
+    │  │      ┌─────────────────────────────────┐    │    │
+    │  │      │  For each task in the phase:    │    │    │
+    │  │      │                                 │    │    │
+    │  │      │    Step B → Author the task     │    │    │
+    │  │      └─────────────────────────────────┘    │    │
+    │  │                                             │    │
+    │  └─────────────────────────────────────────────┘    │
+    │                                                     │
+    └─────────────────────────────────────────────────────┘
+
+---
+
+## Navigation
+
+At any approval gate during plan construction, the user can navigate. They may describe where they want to go in their own words — a specific phase, a specific task, "the beginning", "the leading edge", or any point in the plan.
+
+The **leading edge** is where new work begins — the first phase, task list, or task that hasn't been completed yet. It is tracked by the `planning:` block in the Plan Index File frontmatter (`phase` and `task`). To find the leading edge, read those values. If all phases and tasks are complete, the leading edge is the end of plan construction.
+
+The `planning:` block always tracks the leading edge. It is only advanced when work is completed — never when the user navigates. Navigation moves the user's position, not the leading edge.
+
+Navigation stays within plan construction. It cannot skip past the end of this step.
+
+---
+
+## Phase Structure
+
+Load **[define-phases.md](define-phases.md)** and follow its instructions as written.
+
+After the phase structure is approved, continue to **Process Phases** below.
+
+---
+
+## Process Phases
+
+Work through each phase in order.
+
+Orient the user:
+
+> "I'll now work through each phase — presenting existing work for review and designing or authoring anything still pending. You'll approve at every stage."
+
+### For each phase, check its state:
+
+#### If the phase has no task table
+
+This phase needs task design.
+
+→ Go to **Step A** with this phase.
+
+After Step A returns with an approved task table, continue to **Author Tasks for the Phase** below.
+
+#### If the phase has a task table
+
+Present the task list to the user for review.
+
+> **Phase {N}: {Phase Name}** — {M} tasks.
+>
+> **To proceed:**
+> - **`y`/`yes`** — Confirmed.
+> - **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 wants changes:** → Go to **Step A** with this phase for revision.
+
+**If confirmed:** Continue to **Author Tasks for the Phase** below.
+
+---
+
+## Author Tasks for the Phase
+
+Work through each task in the phase's task table, in order.
+
+#### If the task status is `authored`
+
+Already written. Present a brief summary:
+
+> "Task {M} of {total}: {Task Name} — already authored."
+
+Continue to the next task.
+
+#### If the task status is `pending`
+
+→ Go to **Step B** with this task.
+
+After Step B returns, the task is authored. Continue to the next task.
+
+#### When all tasks in the phase are authored
+
+Advance the `planning:` block in frontmatter to the next phase. Commit: `planning({topic}): complete Phase {N} tasks`
+
+> Phase {N}: {Phase Name} — complete ({M} tasks authored).
+
+Continue to the next phase.
+
+---
+
+## Loop Complete
+
+When all phases have all tasks authored:
+
+> "All phases are complete. The plan has **{N} phases** with **{M} tasks** total."
+
+---
+
+## Step A: Define Tasks
+
+Load **[define-tasks.md](define-tasks.md)** and follow its instructions as written. This step designs and approves a task list for **one phase**.
+
+---
+
+## Step B: Author Tasks
+
+Load **[author-tasks.md](author-tasks.md)** and follow its instructions as written. This step authors **one task** and returns.

package/skills/technical-planning/references/steps/plan-review.md

@@ -92,5 +92,3 @@ After both reviews:
 > Review is complete."
 
 > **CHECKPOINT**: Do not confirm completion if tracking files still exist. They indicate incomplete review work.
-
-→ Proceed to **Step 9**.

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

@@ -52,5 +52,3 @@ Skip the resolution and reverse check — there is nothing to resolve against. D
 Incorporate feedback, re-present the updated dependency state, and ask again. Repeat until approved.
 
 #### If approved
-
-→ Proceed to **Step 8**.

package/skills/technical-planning/references/steps/verify-source-material.md

@@ -18,5 +18,3 @@ Verify that all source material exists and is accessible before entering agent-d
 ls docs/workflow/specification/{topic}.md
 ls docs/workflow/specification/{cross-cutting-spec}.md
 ```
-
-→ Proceed to **Step 4**.