@leeovery/claude-technical-workflows 2.0.46 → 2.0.48

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

@@ -4,7 +4,13 @@
 
 ---
 
-This reference defines the principles, rules, and quality standards for creating implementation plans. It is loaded at the start of the planning process and stays in context throughout.
+These are the principles, rules, and quality standards that govern the planning process.
+
+## Your Role
+
+You are the **planner** — you coordinate the planning process and control a set of agents that do the analytical work alongside you. You invoke agents (for phase design, task design, and task authoring), present their output to the user, handle approval gates, and manage the Plan Index File.
+
+Analysis principles (`phase-design.md`, `task-design.md`) are loaded by the agents, not by you. You hold the planning artifacts (approved phases, task tables) — not the reasoning that produced them.
 
 ## Planning is a Gated Process
 
@@ -12,9 +18,35 @@ Planning translates the specification into actionable structure. This translatio
 
 ### Process Expectations
 
-**This is a step-by-step process with mandatory stop points.** You must work through each step sequentially. Steps end with **STOP** — you must present your work, wait for explicit user confirmation, and only then proceed to the next step.
+**This is a step-by-step process with mandatory stop points.** You must work through each step sequentially. Steps end with **STOP** — you must present your work, wait for explicit user approval, and only then proceed to the next step.
+
+**Never one-shot the plan.** Do not write the entire Plan Index File in a single operation. The plan is built incrementally — one phase at a time, with the user confirming the structure at each stage. A one-shot plan that misses requirements, hallucinates content, or structures tasks poorly wastes more time than a careful, step-by-step process. Go slow to go fast.
+
+### Explicit Approval Required
+
+At every stop point — phases, task lists, individual tasks, dependencies — the user must explicitly approve before you proceed or log content.
+
+**What counts as approval:** `y`/`yes` or equivalent explicit confirmation: "Approved", "That's good", "Looks right".
+
+**What does NOT count as approval:**
+- Silence
+- You presenting choices (that's you asking, not them approving)
+- The user asking a follow-up question
+- The user saying "What's next?" or "Continue"
+- The user making a comment or observation without explicit approval
+- ANY response that isn't explicit confirmation
+
+**If you are uncertain whether the user approved, ASK:** "Ready to proceed, or do you want to change something?"
+
+#### Self-Check Before Logging
+
+Before logging any task to the plan, ask yourself:
+
+1. **Did I present this specific content to the user?** If no → STOP. Present it first.
+2. **Did the user explicitly approve it?** If no → STOP. Wait for approval.
+3. **Am I writing exactly what was approved?** If adding or changing anything → STOP. Present the changes first.
 
-**Never one-shot the plan.** Do not write the entire plan document in a single operation. The plan is built incrementally — one phase at a time, with the user confirming the structure at each stage. A one-shot plan that misses requirements, hallucinates content, or structures tasks poorly wastes more time than a careful, step-by-step process. Go slow to go fast.
+### Collaboration and Judgment
 
 **Stop and ask when judgment is needed.** Planning is collaborative — not in the sense that every line needs approval, but in the sense that the user guides structural decisions and resolves ambiguity. You must stop and ask when:
 

package/skills/technical-planning/references/read-specification.md

@@ -0,0 +1,47 @@
+# Read Specification
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+This reference defines how planning agents must read the specification. It is passed to every agent alongside the specification path.
+
+**This is a full-ingestion protocol, not a summarisation guide.**
+
+---
+
+## Read the Entire Specification
+
+Read the specification file from top to bottom. Every section, every decision, every edge case, every constraint. If the file is large, read it in sequential chunks until you have consumed the entire document. Do not stop early. Do not skim.
+
+The specification is a verbatim, user-approved artifact. Every detail was explicitly agreed — treat nothing as filler or boilerplate.
+
+---
+
+## What to Absorb
+
+As you read, internalise:
+
+- **Decisions and rationale** — what was decided and why
+- **Architectural choices** — patterns, technologies, structures chosen
+- **Edge cases** — boundary conditions, unusual inputs, failure modes
+- **Acceptance boundaries** — what constitutes "done" for each requirement
+- **Constraints** — performance, compatibility, regulatory, or scope limits
+- **Dependencies** — what this feature needs from other systems or topics
+
+---
+
+## Cross-Cutting Specifications
+
+If cross-cutting specification paths are provided, read each one in full using the same protocol. Cross-cutting specs contain architectural decisions (caching, rate limiting, error handling) that influence how features are built — they inform implementation approach without adding scope.
+
+Note where cross-cutting decisions apply to the work you are designing.
+
+---
+
+## What NOT to Do
+
+- **Do not summarise** — your job is to use the spec directly, not to create a derivative
+- **Do not skip sections** — even sections that seem irrelevant may contain constraints or edge cases that affect your work
+- **Do not reinterpret decisions** — the spec contains validated decisions; translate them into plan structure, don't second-guess them
+- **Do not reference other source material** — the specification is the sole input; it already incorporates prior research and discussion

package/skills/technical-planning/references/spec-change-detection.md

@@ -0,0 +1,35 @@
+# Spec Change Detection
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+When resuming planning, check whether the specification or cross-cutting specifications have changed since planning started.
+
+The Plan Index File stores `spec_commit` — the git commit hash captured when planning began. This allows diffing any input file against that point in time.
+
+## Detection
+
+Run a git diff against the stored commit for all input files:
+
+```bash
+git diff {spec_commit} -- {specification-path} {cross-cutting-spec-paths...}
+```
+
+Also check for new cross-cutting specification files that didn't exist at that commit.
+
+## Reporting
+
+**If no changes detected:**
+
+> "Specification unchanged since planning started."
+
+**If changes detected:**
+
+Summarise the extent of changes:
+
+- **What files changed** (specification, cross-cutting specs, or both)
+- **Whether any cross-cutting specs are new** (didn't exist at the stored commit)
+- **Nature of changes** — formatting/cosmetic, minor additions/removals, or substantial restructuring
+
+Return the summary for use in the resume prompt.

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.