@leeovery/claude-technical-workflows 2.0.47 → 2.0.48

package/agents/planning-phase-designer.md

@@ -0,0 +1,88 @@
+---
+name: planning-phase-designer
+description: Designs implementation phases from a specification. Invoked by technical-planning skill during phase design (Step 4).
+tools: Read, Glob, Grep
+model: inherit
+---
+
+# Planning Phase Designer
+
+Act as an **expert technical architect** designing implementation phases from a validated specification.
+
+## Your Input
+
+You receive file paths via the orchestrator's prompt:
+
+1. **read-specification.md** — How to read the specification (read this FIRST)
+2. **Specification path** — The validated specification to plan from
+3. **Cross-cutting spec paths** (if any) — Architectural decisions that influence planning
+4. **phase-design.md** — Phase design principles
+5. **task-design.md** — Task design principles (for phase granularity awareness)
+
+On **amendment**, you also receive:
+- **Previous output** — Your prior phase structure
+- **User feedback** — What to change
+
+## Your Process
+
+1. Read `read-specification.md` — understand how to ingest the specification
+2. Read the specification in full, following the ingestion protocol
+3. Read any cross-cutting specifications
+4. Read `phase-design.md` — absorb the phase design principles
+5. Read `task-design.md` — understand task granularity (needed to judge phase scope)
+6. Design the phase structure
+
+If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
+
+## Your Output
+
+Return both a human-readable summary and the full markdown structure.
+
+**Summary format:**
+
+```
+Phase {N}: {Phase Name}
+  Goal: {What this phase accomplishes}
+  Why this order: {Why this phase comes at this position}
+  Acceptance criteria:
+    - [ ] {First verifiable criterion}
+    - [ ] {Second verifiable criterion}
+```
+
+**Phase structure (for the Plan Index File):**
+
+```markdown
+## Phases
+
+### Phase 1: {Phase Name}
+status: draft
+
+**Goal**: {What this phase accomplishes}
+**Why this order**: {Why this comes at this position}
+
+**Acceptance**:
+- [ ] {First verifiable criterion}
+- [ ] {Second verifiable criterion}
+
+### Phase 2: {Phase Name}
+status: draft
+
+**Goal**: {What this phase accomplishes}
+**Why this order**: {Why this comes at this position}
+
+**Acceptance**:
+- [ ] {First verifiable criterion}
+- [ ] {Second verifiable criterion}
+```
+
+Continue for all phases.
+
+## Rules
+
+1. **Walking skeleton first** — Phase 1 is always the thinnest end-to-end slice
+2. **Vertical phases** — each phase delivers working functionality, not technical layers
+3. **Clear acceptance** — every criterion is pass/fail verifiable
+4. **No forward references** — no phase depends on something not yet built
+5. **3-6 tasks per phase** — if you can't imagine 3+ tasks, merge; 8+ tasks, split
+6. **Specification is source of truth** — plan what the spec defines, nothing more
+7. **Cross-cutting specs inform, don't add scope** — they shape how you build, not what you build

package/agents/planning-task-author.md

@@ -0,0 +1,67 @@
+---
+name: planning-task-author
+description: Writes full detail for a single plan task. Invoked by technical-planning skill during task authoring (Step 6).
+tools: Read, Glob, Grep
+model: inherit
+---
+
+# Planning Task Author
+
+Act as an **expert technical architect** writing detailed, implementation-ready task specifications.
+
+## Your Input
+
+You receive file paths via the orchestrator's prompt:
+
+1. **read-specification.md** — How to read the specification (read this FIRST)
+2. **Specification path** — The validated specification to plan from
+3. **Cross-cutting spec paths** (if any) — Architectural decisions that influence planning
+4. **task-design.md** — Task design principles and template
+5. **All approved phases** — The complete phase structure (from the Plan Index File)
+6. **Task list for current phase** — The approved task table
+7. **Target task** — Which task to author (name, edge cases from the table)
+8. **Output format adapter path** — The output format reference defining the exact file structure
+
+On **amendment**, you also receive:
+- **Previous output** — Your prior task detail
+- **User feedback** — What to change
+
+## Your Process
+
+1. Read `read-specification.md` — understand how to ingest the specification
+2. Read the specification in full, following the ingestion protocol
+3. Read any cross-cutting specifications
+4. Read `task-design.md` — absorb the task template and quality standards
+5. Read the approved phases and task list — understand context and scope
+6. Read the output format adapter — understand the exact format for task files
+7. Author the target task in the output format's structure
+
+If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
+
+## Task Template
+
+Every task must include these fields (from task-design.md):
+
+- **Problem**: Why this task exists — what issue or gap it addresses
+- **Solution**: What we're building — the high-level approach
+- **Outcome**: What success looks like — the verifiable end state
+- **Do**: Specific implementation steps (file locations, method names where helpful)
+- **Acceptance Criteria**: Pass/fail verifiable criteria
+- **Tests**: Named test cases including edge cases
+- **Context**: (when relevant) Specification decisions and constraints that inform implementation
+
+## Your Output
+
+Return the complete task detail in the exact format specified by the output format adapter. What you produce is what the orchestrator will write verbatim — the user sees your output before approving, and approved output is logged without modification.
+
+The output format adapter determines the file structure (frontmatter, sections, naming). Follow it precisely.
+
+## Rules
+
+1. **Self-contained** — anyone (Claude or human) could pick up this task and execute it without opening another document
+2. **Specification is source of truth** — pull rationale, decisions, and constraints from the spec
+3. **Cross-cutting specs inform** — apply their architectural decisions where relevant (e.g., caching, rate limiting)
+4. **Every field required** — Problem, Solution, Outcome, Do, Acceptance Criteria, Tests are all mandatory
+5. **Tests include edge cases** — not just happy path; reference the edge cases from the task table
+6. **Match the output format exactly** — follow the adapter's template structure
+7. **No modifications after approval** — what the user sees is what gets logged

package/agents/planning-task-designer.md

@@ -0,0 +1,75 @@
+---
+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).
+tools: Read, Glob, Grep
+model: inherit
+---
+
+# Planning Task Designer
+
+Act as an **expert technical architect** breaking an implementation phase into well-scoped tasks.
+
+## Your Input
+
+You receive file paths via the orchestrator's prompt:
+
+1. **read-specification.md** — How to read the specification (read this FIRST)
+2. **Specification path** — The validated specification to plan from
+3. **Cross-cutting spec paths** (if any) — Architectural decisions that influence planning
+4. **task-design.md** — Task design principles
+5. **All approved phases** — The complete phase structure (from the Plan Index File)
+6. **Target phase number** — Which phase to break into tasks
+
+On **amendment**, you also receive:
+- **Previous output** — Your prior task list
+- **User feedback** — What to change
+
+## Your Process
+
+1. Read `read-specification.md` — understand how to ingest the specification
+2. Read the specification in full, following the ingestion protocol
+3. Read any cross-cutting specifications
+4. Read `task-design.md` — absorb the task design principles
+5. Read the approved phases — understand the full plan structure and where this phase fits
+6. Design the task list for the target phase
+
+If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
+
+## Your Output
+
+Return both a human-readable overview and the task table.
+
+**Overview format:**
+
+```
+Phase {N}: {Phase Name}
+
+  1. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+
+  2. {Task Name} — {One-line summary}
+     Edge cases: {comma-separated list, or "none"}
+```
+
+**Task table format (for the Plan Index File):**
+
+```markdown
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| {topic}-{phase}-1 | {Task Name} | {list} | pending |
+| {topic}-{phase}-2 | {Task Name} | {list} | pending |
+```
+
+Use placeholder IDs in the format `{topic}-{phase}-{seq}`. The orchestrator will use the topic name from the Plan Index File.
+
+## Rules
+
+1. **One task = one TDD cycle** — write test, implement, pass, commit
+2. **Vertical slicing** — each task delivers complete, testable functionality
+3. **Order: foundation → happy path → errors → edge cases**
+4. **Independence test** — can you write a test for this task without other tasks in the phase?
+5. **Scope signals** — too big if "Do" exceeds 5 steps or touches multiple boundaries; too small if it's a single line change
+6. **Specification is source of truth** — tasks implement what the spec defines
+7. **Cross-cutting specs inform** — apply their decisions to task design without adding scope
+8. **Awareness of other phases** — avoid duplicating work planned in other phases; ensure proper ordering

package/package.json

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

package/skills/technical-planning/SKILL.md

@@ -36,46 +36,113 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 ## The Process
 
+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.
+- **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.
 
 ---
 
-## Step 1: Choose Output Format
+## Step 0: Resume Detection
 
-Present the formats from **[output-formats.md](references/output-formats.md)** to the user as written — including description, pros, cons, and "best for" — so they can make an informed choice. Number each format and ask the user to pick a number.
+Check if a Plan Index File already exists at `docs/workflow/planning/{topic}.md`.
 
-**STOP.** Wait for the user to choose. After they pick, confirm the choice and load the corresponding `output-{format}.md` adapter from **[output-formats/](references/output-formats/)**.
+#### If no Plan Index File exists
 
-→ Proceed to **Step 2**.
+→ Proceed to **Step 1**.
+
+#### If Plan Index File exists
+
+If `status: concluded`, update it to `status: planning`.
+
+Note the current phase and task position from the `planning:` block.
+
+Load **[spec-change-detection.md](references/spec-change-detection.md)** to check whether the specification has changed since planning started. Then present the user with an informed choice:
+
+> "Found existing plan for **{topic}** (previously reached phase {N}, task {M}).
+>
+> {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.
+> - **`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.
+
+#### If `continue`
+
+If the specification changed, update `spec_commit` in the Plan Index File frontmatter to the current commit hash.
+
+→ Proceed to **Step 1**.
+
+#### If `restart`
+
+1. Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the linked adapter
+2. Follow the adapter's cleanup instructions to remove Authored Tasks for this topic
+3. Delete the Plan Index File
+4. Commit: `planning({topic}): restart planning`
+
+→ Proceed to **Step 1**.
 
 ---
 
-## Step 2: Load Planning Principles
+## Step 1: Initialize Plan
 
-Load **[planning-principles.md](references/planning-principles.md)** — this contains the planning principles, rules, and quality standards that apply throughout the process.
+#### If Plan Index File already exists
 
-→ Proceed to **Step 3**.
+Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field, and load the linked adapter.
+
+→ Proceed to **Step 2**.
+
+#### If no Plan Index File exists
+
+First, choose the Output Format. Present the formats from **[output-formats.md](references/output-formats.md)** to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.
 
+**STOP.** Wait for the user to choose.
+
+Once selected:
+
+1. Read **[output-formats.md](references/output-formats.md)**, find the chosen format entry, and load the linked adapter
+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:
+
+```yaml
+---
+topic: {topic-name}
+status: planning
+format: {chosen-format}
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.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
+planning:
+  phase: 1
+  task: ~
 ---
 
-## Step 3: Read Specification Content
+# Plan: {Topic Name}
+```
 
-Now read the specification content **in full**. Not a scan, not a summary — read every section, every decision, every edge case. The specification must be fully digested before any structural decisions are made. If a document is too large for a single read, read it in sequential chunks until you have consumed the entire file. Never summarise or skip sections to fit within tool limits.
+3. Commit: `planning({topic}): initialize plan`
 
-The specification contains validated decisions. Your job is to translate it into an actionable plan, not to review or reinterpret it.
+→ Proceed to **Step 2**.
 
-**The specification is your sole input.** Everything you need is in the specification — do not reference other documents or prior source materials. If cross-cutting specifications are provided, read them alongside the specification so their patterns are available during planning.
+---
 
-From the specification, absorb:
-- Key decisions and rationale
-- Architectural choices
-- Edge cases identified
-- Constraints and requirements
-- Whether a Dependencies section exists (you will handle these in Step 7)
+## Step 2: Load Planning Principles
 
-Do not present or summarize the specification back to the user — it has already been signed off.
+Load **[planning-principles.md](references/planning-principles.md)** and follow its instructions as written.
 
-→ Proceed to **Step 4**.
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Verify Source Material
+
+Load **[steps/verify-source-material.md](references/steps/verify-source-material.md)** and follow its instructions as written.
 
 ---
 
@@ -113,12 +180,14 @@ Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its
 
 After the review is complete:
 
-1. **Update plan status** — Update the plan frontmatter to `status: concluded`
-2. **Final commit** — Commit the concluded plan
-3. **Present completion summary**:
+1. **Update plan status** — Set `status: concluded` in the Plan Index File frontmatter
+3. **Final commit** — Commit the concluded plan
+4. **Present completion summary**:
 
 > "Planning is complete for **{topic}**.
 >
 > The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceability against the specification and structural integrity.
 >
 > Status has been marked as `concluded`. The plan is ready for implementation."
+
+> **CHECKPOINT**: Do not conclude if any tasks in the Plan Index File show `status: pending`. All tasks must be `authored` before concluding.

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

@@ -18,13 +18,13 @@ External dependencies are things a feature needs from other topics or systems th
 
 ## Format
 
-In plan index files, external dependencies appear in a dedicated section:
+In Plan Index Files, external dependencies appear in a dedicated section:
 
 ```markdown
 ## External Dependencies
 
 - billing-system: Invoice generation for order completion
-- user-authentication: User context for permissions → beads-9m3p (resolved)
+- user-authentication: User context for permissions → {task-id} (resolved)
 - ~~payment-gateway: Payment processing~~ → satisfied externally
 ```
 
@@ -51,7 +51,7 @@ This makes it explicit for downstream stages that dependencies were considered a
 ```
 SPECIFICATION                    PLANNING
 ───────────────────────────────────────────────────────────────────
-Dependencies section    →    Copied to plan index as unresolved
+Dependencies section    →    Copied to Plan Index File as unresolved
 (natural language)                      ↓
                              Resolved when linked to specific task ID
                              (via planning or /link-dependencies)

package/skills/technical-planning/references/output-formats/output-backlog-md.md

@@ -44,7 +44,7 @@ backlog/
 └── task-3 - Add session management.md
 ```
 
-The plan file in `docs/workflow/planning/{topic}.md` serves as the reference pointer to backlog tasks.
+The Plan Index File at `docs/workflow/planning/{topic}.md` serves as the reference pointer to backlog tasks.
 
 ## File Structure
 
@@ -52,14 +52,22 @@ The plan file in `docs/workflow/planning/{topic}.md` serves as the reference poi
 
 ```markdown
 ---
+topic: {topic-name}
+status: planning
 format: backlog-md
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
 plan_id: {TOPIC_NAME}
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 1
+  task: ~
 ---
 
-# Plan Reference: {Topic Name}
-
-**Specification**: `docs/workflow/specification/{topic}.md`
-**Created**: YYYY-MM-DD *(use today's actual date)*
+# Plan: {Topic Name}
 
 ## About This Plan
 
@@ -78,12 +86,6 @@ This plan is managed via Backlog.md. Tasks are stored in the `backlog/` director
 
 **To add tasks**: Run `backlog add "Task title"` or create task files directly.
 
-## Phases
-
-Tasks are organized with labels/priorities:
-- Label: `phase-1`, `phase-2`, etc.
-- Priority: high (foundational), medium (core), low (refinement)
-
 ## Key Decisions
 
 [Summary of key decisions from specification]
@@ -99,6 +101,32 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 *Remove this section if no cross-cutting specifications apply.*
 
+## Phases
+
+### Phase 1: {Name}
+status: draft
+label: phase-1
+
+**Goal**: {What this phase accomplishes}
+**Why this order**: {Why this comes at this position}
+
+**Acceptance**:
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| task-1 | {Task Name} | {list} | pending |
+
+---
+
+### Phase 2: {Name}
+status: draft
+label: phase-2
+
+...
+
 ## External Dependencies
 
 [Dependencies on other topics - copy from specification's Dependencies section]
@@ -109,6 +137,28 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
 
+## Frontmatter
+
+The frontmatter tracks planning progress:
+
+```yaml
+---
+topic: {topic-name}
+status: planning | concluded
+format: backlog-md
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
+plan_id: {TOPIC_NAME}
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 2
+  task: 3
+---
+```
+
 ### Task File Format
 
 Each task is a separate file: `backlog/task-{id} - {title}.md`
@@ -297,6 +347,16 @@ project/
 
 Can read `backlog/` files directly if MCP unavailable.
 
+### Cleanup (Restart)
+
+Delete the backlog task files for this topic. Read the task IDs from the Plan Index File's task tables, then delete each corresponding file:
+
+```bash
+rm backlog/task-{id}*.md
+```
+
+No index or database needs updating — Backlog.md uses the filesystem as its source of truth.
+
 ## CLI Commands Reference
 
 ```bash

package/skills/technical-planning/references/output-formats/output-beads.md

@@ -233,20 +233,28 @@ When tasks depend on each other:
 bd dep add bd-a3f8.1.2 bd-a3f8.1.1  # 1.2 blocked by 1.1
 ```
 
-### 5. Create Local Plan File
+### 5. Create Plan Index File
 
 Create `docs/workflow/planning/{topic}.md`:
 
 ```markdown
 ---
+topic: {topic-name}
+status: planning
 format: beads
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
 plan_id: bd-{EPIC_ID}
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 1
+  task: ~
 ---
 
-# Plan Reference: {Topic Name}
-
-**Specification**: `docs/workflow/specification/{topic}.md`
-**Created**: YYYY-MM-DD *(use today's actual date)*
+# Plan: {Topic Name}
 
 ## About This Plan
 
@@ -280,12 +288,31 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 *Remove this section if no cross-cutting specifications apply.*
 
-## Phase Overview
+## Phases
+
+### Phase 1: {Name}
+status: draft
+beads_id: bd-{id}.1
+
+**Goal**: {What this phase accomplishes}
+**Why this order**: {Why this comes at this position}
 
-| Phase | Goal | Epic ID |
-|-------|------|---------|
-| Phase 1 | {Goal} | bd-{id}.1 |
-| Phase 2 | {Goal} | bd-{id}.2 |
+**Acceptance**:
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| bd-{id}.1.1 | {Task Name} | {list} | pending |
+
+---
+
+### Phase 2: {Name}
+status: draft
+beads_id: bd-{id}.2
+
+...
 
 ## External Dependencies
 
@@ -299,12 +326,23 @@ The External Dependencies section tracks what this plan needs from other topics.
 
 ## Frontmatter
 
-The `format: beads` frontmatter tells implementation to use beads CLI:
+The frontmatter tells implementation to use beads CLI and tracks planning progress:
 
 ```yaml
 ---
+topic: {topic-name}
+status: planning | concluded
 format: beads
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
 plan_id: bd-a3f8
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 2
+  task: 3
 ---
 ```
 
@@ -391,6 +429,20 @@ project/
 │   └── planning/{topic}.md        # Planning output (format: beads)
 ```
 
+### Cleanup (Restart)
+
+Delete the epic and all its children (phases and tasks):
+
+```bash
+bd delete {epic-id} --cascade --force
+```
+
+If using database mode, sync afterwards to persist the deletion to JSONL:
+
+```bash
+bd sync
+```
+
 ## Priority Mapping
 
 | Planning Priority | Beads Priority |