@leeovery/claude-technical-workflows 2.0.47 → 2.0.48

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

@@ -4,58 +4,91 @@
 
 ---
 
-Load **[task-design.md](../task-design.md)** — the task design principles, template structure, and quality standards for writing task detail.
+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.
 
 ---
 
+## 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 — presenting the full detail, discussing if needed, and logging it to the plan once approved."
+> "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**.
 
-Work through the agreed task list **one task at a time**.
+### Invoke the Agent
 
-#### Present
+For each pending task, invoke `planning-task-author` with these file paths:
 
-Write the complete task using the task template — Problem, Solution, Outcome, Do, Acceptance Criteria, Tests, Context.
+1. **read-specification.md**: `.claude/skills/technical-planning/references/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**: `.claude/skills/technical-planning/references/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 adapter**: path to the loaded output format adapter
 
-Present it to the user **in the format it will be written to the plan**. The output format adapter determines the exact format. What the user sees is what gets logged — no changes between approval and writing.
+### Present the Output
+
+The agent returns complete task detail in the output format's structure. Present it to the user **exactly as it will be written** — what the user sees is what gets logged.
 
 After presenting, ask:
 
 > **Task {M} of {total}: {Task Name}**
 >
-> **To proceed, choose one:**
-> - **"Approve"** — Task is confirmed. I'll log it to the plan verbatim.
-> - **"Adjust"** — Tell me what to change.
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll log it to the plan verbatim.
+> - **Or tell me what to change.**
+> - **`skip to {X}`** — Navigate to different task/phase
 
 **STOP.** Wait for the user's response.
 
-#### If adjust
+#### 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
 
-The user may:
-- Request changes to the task content
-- Ask questions about scope, granularity, or approach
-- Flag that something doesn't match the specification
-- Identify missing edge cases or acceptance criteria
+Present the revised task in full. Ask the same choice again. Repeat until approved.
 
-Incorporate feedback and re-present the updated task **in full**. Then ask the same choice again. Repeat until approved.
+#### If approved (`y`/`yes`)
 
-#### If approved
+> **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.
 
-Log the task to the plan — verbatim, as presented. Do not modify content between approval and writing. The output format adapter determines how tasks are written (appending markdown, creating issues, etc.).
+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
+4. Commit: `planning({topic}): author task {task-id} ({task name})`
 
-After logging, confirm:
+Confirm:
 
-> "Task {M} of {total}: {Task Name} — logged."
+> "Task {M} of {total}: {Task Name} — authored."
 
 #### Next task or phase complete
 
-**If tasks remain in this phase:** → Return to the top of **Step 6** with the next task. Present it, ask, wait.
+**If 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:**
 
-**If all tasks in this phase are logged:**
+Update `planning:` block and commit: `planning({topic}): complete Phase {N} tasks`
 
 ```
-Phase {N}: {Phase Name} — complete ({M} tasks logged).
+Phase {N}: {Phase Name} — complete ({M} tasks authored).
 ```
 
 → Return to **Step 5** for the next phase.

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

@@ -4,37 +4,78 @@
 
 ---
 
-Load **[phase-design.md](../phase-design.md)** — the principles for structuring phases as independently valuable, testable increments built on a walking skeleton.
+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.
 
 ---
 
+## Check for Existing Phases
+
+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 with `status: draft`:**
+- Present the draft for review/approval
+- Continue the approval flow below
+
+**If no phases exist:**
+- Continue with fresh phase design below
+
+---
+
+## Fresh Phase Design
+
 Orient the user:
 
-> "I've read the full specification. I'm going to propose a phase structure — how we break this into independently testable stages. Once we agree on the phases, we'll take each one and break it into tasks."
+> "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."
 
-With the full specification understood, break it into logical phases. Understanding what tasks belong in each phase is necessary to determine the right ordering.
+### Invoke the Agent
 
-Present the proposed phase structure using this format:
+Invoke `planning-phase-designer` 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
+3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
+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:
+```yaml
+planning:
+  phase: 1
+  task: ~
 ```
-Phase {N}: {Phase Name}
-  Goal: {What this phase accomplishes}
-  Why this order: {Why this phase comes at this position in the sequence}
-  Acceptance criteria:
-    - [ ] {First verifiable criterion}
-    - [ ] {Second verifiable criterion}
-```
 
-**STOP.** Present your proposed phase structure and ask:
+Commit: `planning({topic}): draft phase structure`
+
+Present the phase structure to the user.
+
+**STOP.** Ask:
+
+> **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.
+
+#### If the user provides feedback
 
-> **To proceed, choose one:**
-> - **"Approve"** — Phase structure is confirmed. I'll proceed to task breakdown.
-> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove phases.
+Re-invoke `planning-phase-designer` with all original inputs PLUS:
+- **Previous output**: the current phase structure
+- **User feedback**: what the user wants changed
 
-#### If Adjust
+Update the Plan Index File with the revised output, re-present, and ask again. Repeat until approved.
 
-Incorporate feedback, re-present the updated phase structure, and ask again. Repeat until approved.
+#### If approved
 
-#### If Approved
+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`
 
 → Proceed to **Step 5**.

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

@@ -4,40 +4,76 @@
 
 ---
 
-Load **[task-design.md](../task-design.md)** — the principles for breaking phases into well-scoped, vertically-sliced tasks.
+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.
 
 ---
 
+## 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
+
 Orient the user:
 
-> "Taking Phase {N}: {Phase Name} and breaking it into tasks. Here's the overview — once we agree on the list, I'll write each task out in full detail."
+> "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."
 
-Take the first (or next) phase and break it into tasks. Present a high-level overview so the user can see the shape of the phase before committing to the detail of each task.
+### Invoke the Agent
 
-Present the task overview using this format:
+Invoke `planning-task-designer` with these file paths:
 
-```
-Phase {N}: {Phase Name}
+1. **read-specification.md**: `.claude/skills/technical-planning/references/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**: `.claude/skills/technical-planning/references/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
+
+### Present the Output
 
-  1. {Task Name} — {One-line summary}
-     Edge cases: {comma-separated list, or "none"}
+The agent returns a task overview and task table. Write the task table directly to the Plan Index File under the phase.
 
-  2. {Task Name} — {One-line summary}
-     Edge cases: {comma-separated list, or "none"}
+Update the frontmatter `planning:` block:
+```yaml
+planning:
+  phase: {N}
+  task: ~
 ```
 
-This overview establishes the scope and ordering. The user should be able to see whether the phase is well-structured, whether tasks are in the right order, and whether anything is missing or unnecessary — before investing time in writing out full task detail.
+Commit: `planning({topic}): draft Phase {N} task list`
+
+Present the task overview to the user.
+
+**STOP.** Ask:
+
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll begin writing full task detail.
+> - **Or tell me what to change** — reorder, split, merge, add, edit, or remove tasks.
 
-**STOP.** Present the phase task overview and ask:
+#### If the user provides feedback
 
-> **To proceed, choose one:**
-> - **"Approve"** — Task list is confirmed. I'll begin writing full task detail.
-> - **"Adjust"** — Tell me what to change: reorder, split, merge, add, or remove tasks.
+Re-invoke `planning-task-designer` with all original inputs PLUS:
+- **Previous output**: the current task list
+- **User feedback**: what the user wants changed
 
-#### If Adjust
+Update the Plan Index File with the revised task table, re-present, and ask again. Repeat until approved.
 
-Incorporate feedback, re-present the updated task overview, and ask again. Repeat until approved.
+#### If approved
 
-#### If Approved
+1. Update the `planning:` block to note task authoring is starting
+2. Commit: `planning({topic}): approve Phase {N} task list`
 
 → Proceed to **Step 6**.

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

@@ -12,7 +12,7 @@ After completing the plan, perform a comprehensive two-part review before handin
 
 To ensure analysis isn't lost during context refresh, create tracking files that capture findings. These files persist analysis so work can continue across sessions.
 
-**Location**: Store tracking files alongside the plan file:
+**Location**: Store tracking files alongside the Plan Index File:
 - `{topic}-review-traceability-tracking.md` — Traceability findings
 - `{topic}-review-integrity-tracking.md` — Integrity findings
 
@@ -20,7 +20,7 @@ To ensure analysis isn't lost during context refresh, create tracking files that
 ```markdown
 ---
 status: in-progress | complete
-created: YYYY-MM-DD
+created: YYYY-MM-DD  # Use today's actual date
 phase: Traceability Review | Plan Integrity Review
 topic: [Topic Name]
 ---

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

@@ -43,14 +43,14 @@ Skip the resolution and reverse check — there is nothing to resolve against. D
 
 **STOP.** Present a summary of the dependency state: what was documented, what was resolved, what remains unresolved, and any reverse resolutions made.
 
-> **To proceed, choose one:**
-> - **"Approve"** — Dependency state is confirmed. Proceed to plan review.
-> - **"Adjust"** — Tell me what to change.
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll proceed to plan review.
+> - **Or tell me what to change.**
 
-#### If Adjust
+#### If the user provides feedback
 
 Incorporate feedback, re-present the updated dependency state, and ask again. Repeat until approved.
 
-#### If Approved
+#### If approved
 
 → Proceed to **Step 8**.

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

@@ -172,14 +172,14 @@ After presenting the finding and proposed fix, ask:
 
 > **Finding {N} of {total}: {Brief Title}**
 >
-> **To proceed, choose one:**
-> - **"Approve"** — Fix is confirmed. I'll apply it to the plan verbatim.
-> - **"Adjust"** — Tell me what to change about the proposed fix.
-> - **"Skip"** — Leave this as-is and move to the next finding.
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll apply it to the plan verbatim.
+> - **`skip`** — Leave this as-is and move to the next finding.
+> - **Or tell me what to change.**
 
 **STOP.** Wait for the user's response.
 
-### If Adjust
+### If the user provides feedback
 
 The user may:
 - Request changes to the proposed fix

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

@@ -149,14 +149,14 @@ After presenting the finding and proposed fix, ask:
 
 > **Finding {N} of {total}: {Brief Title}**
 >
-> **To proceed, choose one:**
-> - **"Approve"** — Fix is confirmed. I'll apply it to the plan verbatim.
-> - **"Adjust"** — Tell me what to change about the proposed fix.
-> - **"Skip"** — Leave this as-is and move to the next finding.
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll apply it to the plan verbatim.
+> - **`skip`** — Leave this as-is and move to the next finding.
+> - **Or tell me what to change.**
 
 **STOP.** Wait for the user's response.
 
-### If Adjust
+### If the user provides feedback
 
 The user may:
 - Request changes to the proposed fix

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

@@ -0,0 +1,22 @@
+# Verify Source Material
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+Verify that all source material exists and is accessible before entering agent-driven work. Agents will read these files — this step just confirms they are present.
+
+## Verification
+
+1. Read the Plan Index File's frontmatter to get the `specification:` path and any `cross_cutting_specs:` paths
+2. For each path, run `ls` to confirm the file exists — do not read the file contents
+3. If any file is missing, **STOP** — inform the user which file is missing and do not proceed
+
+### Example
+
+```bash
+ls docs/workflow/specification/{topic}.md
+ls docs/workflow/specification/{cross-cutting-spec}.md
+```
+
+→ Proceed to **Step 4**.

package/skills/technical-specification/SKILL.md

@@ -75,11 +75,11 @@ After user signs off:
 - **STOP and WAIT** for the user to explicitly approve before writing
 - Treat each write operation as requiring its own explicit approval
 
-**What counts as approval:** "Log it" (the standard choice you present) or equivalent: "Yes", "Approved", "Add it", "That's good".
+**What counts as approval:** `y`/`yes` (the standard choice you present) or equivalent: "Approved", "Add it", "That's good".
 
 **What does NOT count as approval:** Silence, you presenting choices, the user asking a follow-up question, the user saying "What's next?", or any response that isn't explicit confirmation.
 
-If you are uncertain whether the user approved, **ASK**: "Would you like me to log it, or do you want to adjust something?"
+If you are uncertain whether the user approved, **ASK**: "Ready to log it, or do you want to change something?"
 
 ---
 
@@ -103,7 +103,7 @@ The specification is the **golden document** - planning uses only this. If infor
 
 ## Critical Rules
 
-**STOP AND WAIT FOR APPROVAL**: You MUST NOT write to the specification until the user has explicitly approved. Presenting content is NOT approval. Presenting choices is NOT approval. You must receive explicit confirmation (e.g., "Log it") before ANY write operation. If uncertain, ASK.
+**STOP AND WAIT FOR APPROVAL**: You MUST NOT write to the specification until the user has explicitly approved. Presenting content is NOT approval. Presenting choices is NOT approval. You must receive explicit confirmation (e.g., `y`/`yes`) before ANY write operation. If uncertain, ASK.
 
 **Log verbatim**: When approved, write exactly what was presented - no silent modifications.
 

package/skills/technical-specification/references/specification-guide.md

@@ -35,7 +35,7 @@ Before starting any topic, identify ALL available reference material:
 
 This is a collaborative dialogue, not an autonomous task. The user validates every piece before it's logged.
 
-> **CHECKPOINT**: If you are about to write to the specification file and haven't received explicit approval (e.g., "Log it") for this specific content, **STOP**. You are violating the workflow. Go back and present the choices first.
+> **CHECKPOINT**: If you are about to write to the specification file and haven't received explicit approval (e.g., `y`/`yes`) for this specific content, **STOP**. You are violating the workflow. Go back and present the choices first.
 
 ---
 
@@ -78,9 +78,9 @@ Present your understanding to the user **in the format it would appear in the sp
 
 Then present two explicit choices:
 
-> **To proceed, choose one:**
-> - **"Log it"** - I'll add the above to the specification **verbatim** (exactly as shown, no modifications)
-> - **"Adjust"** - Tell me which part to change and what you want it to say instead
+> **To proceed:**
+> - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim** (exactly as shown, no modifications).
+> - **Or tell me what to change.**
 
 **Do not paraphrase these choices.** Present them exactly as written so users always know what to expect.
 
@@ -101,8 +101,8 @@ This is a **human-level conversation**, not form-filling. The user brings contex
 **DO NOT PROCEED TO LOGGING WITHOUT EXPLICIT USER APPROVAL.**
 
 **What counts as approval:**
-- **"Log it"** - the standard confirmation you present as a choice
-- Or equivalent explicit confirmation: "Yes", "Approved", "Add it", "That's good"
+- **`y`/`yes`** - the standard confirmation you present as a choice
+- Or equivalent explicit confirmation: "Approved", "Add it", "That's good"
 
 **What does NOT count as approval:**
 - Silence
@@ -112,7 +112,7 @@ This is a **human-level conversation**, not form-filling. The user brings contex
 - The user making a minor comment without explicit approval
 - ANY response that isn't explicit confirmation
 
-**If you are uncertain, ASK:** "Would you like me to log it, or do you want to adjust something?"
+**If you are uncertain, ASK:** "Ready to log it, or do you want to change something?"
 
 > **CHECKPOINT**: If you are about to write to the specification and the user's last message was not explicit approval, **STOP**. You are violating the workflow. Present the choices again.
 
@@ -522,11 +522,11 @@ For each item, follow the **same workflow as the main specification process**:
    >
    > [content exactly as it would appear]
    >
-   > **To proceed, choose one:**
-   > - **"Log it"** - I'll add the above to the specification **verbatim**
-   > - **"Adjust"** - Tell me which part to change
+   > **To proceed:**
+   > - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
+   > - **Or tell me what to change.**
 
-4. **Wait for explicit approval** - same rules as always: "Log it" or equivalent before writing
+4. **Wait for explicit approval** - same rules as always: `y`/`yes` or equivalent before writing
 5. **Log verbatim** when approved
 6. **Update tracking file** - Mark the item's resolution (Approved/Adjusted/Skipped) and add any notes
 7. **Move to the next item**: "Moving to #2: [Brief title]..."
@@ -652,9 +652,9 @@ For each item:
    >
    > [content exactly as it would appear]
    >
-   > **To proceed, choose one:**
-   > - **"Log it"** - I'll add the above to the specification **verbatim**
-   > - **"Adjust"** - Tell me which part to change
+   > **To proceed:**
+   > - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
+   > - **Or tell me what to change.**
 
 4. **Wait for explicit approval**
 5. **Log verbatim** when approved
@@ -764,7 +764,7 @@ Before ANY write operation to the specification file, verify:
 | Question | If No... |
 |----------|----------|
 | Did I present this specific content to the user? | **STOP**. Present it first. |
-| Did the user explicitly approve? (e.g., "Log it") | **STOP**. Wait for approval or ask. |
+| Did the user explicitly approve? (e.g., `y`/`yes`) | **STOP**. Wait for approval or ask. |
 | Am I writing exactly what was approved, with no additions? | **STOP**. Present any changes first. |
 
 > **FINAL CHECK**: If you have written to the specification file and cannot answer "yes" to all three questions above for that content, you have violated the workflow. Every piece of content requires explicit user approval before logging.