@leeovery/claude-technical-workflows 2.1.28 → 2.1.30

package/agents/implementation-analysis-task-writer.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Plan path** — the implementation plan path
 4. **Plan format reading adapter path** — how to read tasks from the plan (for determining next phase number)
 5. **Plan format authoring adapter path** — how to create tasks in the plan
+6. **plan-index-schema.md** — Canonical plan index structure
 
 ## Your Process
 
@@ -32,25 +33,17 @@ You receive via the orchestrator's prompt:
 
 The Plan Index File (`docs/workflow/planning/{topic}/plan.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
 
-Append at the end of the Plan Index File body:
+Append at the end of the Plan Index File body, following the **Phase Entry** and **Task Table** templates from plan-index-schema:
 
-```markdown
-### Phase {N}: Analysis ({cycle description})
-status: approved
-
-**Goal**: Address findings from implementation analysis cycle {N}.
-
-#### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| {topic}-{phase}-1 | {Task Title} | — | authored |
-| {topic}-{phase}-2 | {Task Title} | — | authored |
-```
-
-- Use `status: approved` for the phase (it's pre-approved by the user in the approval gate)
-- Use `authored` for each task status (the task files are fully written)
-- Use `—` for edge cases (analysis tasks don't have separate edge case annotations)
+- Phase heading: `### Phase {N}: Analysis ({cycle description})`
+- Phase `status`: `approved` (pre-approved by user in approval gate)
+- Phase `ext_id`: external identifier for the phase from the output format
+- Phase goal: `Address findings from implementation analysis cycle {N}.`
+- Omit `approved_at` and acceptance criteria (analysis phases don't use them)
+- Task `Status`: `authored` (task files are fully written)
+- Task `Ext ID`: external identifier for the task from the output format
 - Task IDs must match the IDs used in the created task files
+- If the Plan Index File frontmatter `ext_id` is empty, set it to the external identifier for the plan from the output format
 
 ## Hard Rules
 

package/agents/planning-phase-designer.md

@@ -18,6 +18,7 @@ You receive file paths via the orchestrator's prompt:
 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)
+6. **plan-index-schema.md** — Canonical plan index structure
 
 On **amendment**, you also receive:
 - **Previous output** — Your prior phase structure
@@ -30,7 +31,8 @@ On **amendment**, you also receive:
 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
+6. Read `plan-index-schema.md` — understand the plan index structure
+7. Design the phase structure
 
 If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
 
@@ -51,29 +53,7 @@ Phase {N}: {Phase Name}
 
 **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}
-```
+Begin with a `## Phases` heading, then follow the **Phase Entry** template from plan-index-schema for each phase. Set `status: draft`. Leave `ext_id` empty. Omit `approved_at`.
 
 Continue for all phases.
 

package/agents/planning-task-designer.md

@@ -19,6 +19,7 @@ You receive file paths via the orchestrator's prompt:
 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
+7. **plan-index-schema.md** — Canonical plan index structure
 
 On **amendment**, you also receive:
 - **Previous output** — Your prior task list
@@ -31,7 +32,8 @@ On **amendment**, you also receive:
 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
+6. Read `plan-index-schema.md` — understand the plan index structure
+7. 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.
 
@@ -53,15 +55,9 @@ Phase {N}: {Phase Name}
 
 **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 |
-```
+Follow the **Task Table** template from plan-index-schema. Use placeholder IDs `{topic}-{phase}-{seq}`. Set `Status` to `pending`. Leave `Ext ID` empty.
 
-Use placeholder IDs in the format `{topic}-{phase}-{seq}`. The orchestrator will use the topic name from the Plan Index File.
+The orchestrator will use the topic name from the Plan Index File.
 
 ## Rules
 

package/package.json

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

package/skills/technical-implementation/references/invoke-task-writer.md

@@ -19,6 +19,7 @@ Pass via the orchestrator's prompt:
 3. **Plan path** — the implementation plan path
 4. **Plan format reading adapter path** — `../../technical-planning/references/output-formats/{format}/reading.md`
 5. **Plan format authoring adapter path** — `../../technical-planning/references/output-formats/{format}/authoring.md`
+6. **plan-index-schema.md** — `../../technical-planning/references/plan-index-schema.md`
 
 ---
 

package/skills/technical-planning/SKILL.md

@@ -172,29 +172,7 @@ Once selected:
 
 1. Read **[output-formats.md](references/output-formats.md)**, find the chosen format entry, and load the format's **[about.md](references/output-formats/{format}/about.md)** and **[authoring.md](references/output-formats/{format}/authoring.md)**
 2. Capture the current git commit hash: `git rev-parse HEAD`
-3. Create the Plan Index File at `docs/workflow/planning/{topic}/plan.md` with the following frontmatter and title:
-
-```yaml
----
-topic: {topic-name}
-status: planning
-format: {chosen-format}
-specification: ../specification/{topic}/specification.md
-cross_cutting_specs:              # Omit if none
-  - ../specification/{spec}/specification.md
-spec_commit: {output of git rev-parse HEAD}
-created: YYYY-MM-DD  # Use today's actual date
-updated: YYYY-MM-DD  # Use today's actual date
-external_dependencies: []
-author_gate_mode: gated
-finding_gate_mode: gated
-planning:
-  phase: 1
-  task: ~
----
-
-# Plan: {Topic Name}
-```
+3. Create the Plan Index File at `docs/workflow/planning/{topic}/plan.md` using the **Frontmatter** and **Title** templates from **[plan-index-schema.md](references/plan-index-schema.md)**. Set `status: planning`, `spec_commit` to the captured git hash, and today's actual date for `created` and `updated`.
 
 3. Commit: `planning({topic}): initialize plan`
 

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

@@ -85,11 +85,15 @@ Note that `author_gate_mode` should be updated to `auto` during the commit step
 
 > **CHECKPOINT**: If `author_gate_mode: gated`, verify before logging: (1) You presented this exact content, (2) The user explicitly approved with `y`/`yes` or equivalent — not a question, comment, or "okay" in passing, (3) You are writing exactly what was approved with no modifications.
 
+See **[plan-index-schema.md](plan-index-schema.md)** for field definitions and lifecycle.
+
 1. Write the task to the output format (format-specific — see authoring.md)
-2. Update the task table in the Plan Index File: set `status: authored`
-3. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
-4. If user chose `auto` at this gate: update `author_gate_mode: auto` in the Plan Index File frontmatter
-5. Commit: `planning({topic}): author task {task-id} ({task name})`
+2. If the Plan Index File frontmatter `ext_id` is empty, set it to the external identifier for the plan as exposed by the output format.
+3. If the current phase's `ext_id` is empty, set it to the external identifier for the phase as exposed by the output format.
+4. Update the task table in the Plan Index File: set `status: authored` and set `Ext ID` to the external identifier for the task as exposed by the output format.
+5. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
+6. If user chose `auto` at this gate: update `author_gate_mode: auto` in the Plan Index File frontmatter
+7. Commit: `planning({topic}): author task {task-id} ({task name})`
 
 > *Output the next fenced block as a code block:*
 

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

@@ -41,6 +41,7 @@ Invoke `planning-phase-designer` with these file paths:
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
 4. **phase-design.md**: `phase-design.md`
 5. **task-design.md**: `task-design.md`
+6. **plan-index-schema.md**: `plan-index-schema.md`
 
 The agent returns a complete phase structure. Write it directly to the Plan Index File body.
 
@@ -88,7 +89,7 @@ Update the Plan Index File with the revised output, re-present, and ask again. R
 
 **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)
+1. Update each phase in the Plan Index File: set `status: approved` and `approved_at: YYYY-MM-DD` (use today's actual date). See **Phase Entry** in plan-index-schema for field definitions.
 2. Commit: `planning({topic}): approve phase structure`
 
 **If the phase structure was already approved and unchanged:** No updates needed.

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

@@ -28,6 +28,7 @@ Invoke `planning-task-designer` with these file paths:
 4. **task-design.md**: `task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
 6. **Target phase number**: the phase being broken into tasks
+7. **plan-index-schema.md**: `plan-index-schema.md`
 
 ### Present the Output
 

package/skills/technical-planning/references/plan-index-schema.md

@@ -0,0 +1,101 @@
+# Plan Index Schema
+
+*Reference for **[technical-planning](../SKILL.md)** and its agents*
+
+---
+
+This file defines the canonical structure for Plan Index Files (`docs/workflow/planning/{topic}/plan.md`). All agents and references that create or update plan index content **must** follow these templates.
+
+---
+
+## Frontmatter
+
+```yaml
+---
+topic: {topic-name}
+status: {status}
+format: {chosen-format}
+ext_id:
+specification: ../specification/{topic}/specification.md
+cross_cutting_specs:
+  - ../specification/{spec}/specification.md
+spec_commit: {commit-hash}
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+external_dependencies: []
+author_gate_mode: gated
+finding_gate_mode: gated
+planning:
+  phase: 1
+  task: ~
+---
+```
+
+| Field | Set when |
+|-------|----------|
+| `topic` | Plan creation (Step 1) |
+| `status` | Plan creation → `planning`; conclusion → `concluded` |
+| `format` | Plan creation — user-chosen output format |
+| `ext_id` | First task authored — external identifier for the plan |
+| `specification` | Plan creation — relative path to source specification |
+| `cross_cutting_specs` | Plan creation — relative paths to cross-cutting specs (omit key if none) |
+| `spec_commit` | Plan creation — `git rev-parse HEAD`; updated on continue if spec changed |
+| `created` | Plan creation — today's date |
+| `updated` | Plan creation — today's date; update on each commit |
+| `external_dependencies` | Dependency resolution (Step 6) |
+| `author_gate_mode` | Plan creation → `gated`; user opts in → `auto` |
+| `finding_gate_mode` | Plan creation → `gated`; user opts in → `auto` |
+| `planning.phase` | Tracks current phase position |
+| `planning.task` | Tracks current task position (`~` when between tasks) |
+| `review_cycle` | Added by plan-review when review cycle begins |
+
+---
+
+## Title
+
+```markdown
+# Plan: {Topic Name}
+```
+
+---
+
+## Phase Entry
+
+```markdown
+### Phase {N}: {Phase Name}
+status: {status}
+ext_id:
+approved_at: {YYYY-MM-DD}
+
+**Goal**: {What this phase accomplishes}
+
+**Why this order**: {Why this comes at this position}
+
+**Acceptance**:
+- [ ] {First verifiable criterion}
+- [ ] {Second verifiable criterion}
+```
+
+| Field | Set when |
+|-------|----------|
+| `status` | Phase design → `draft`; approval → `approved` |
+| `ext_id` | First task in phase authored — external identifier for the phase |
+| `approved_at` | Phase approval — today's date. Omit while `draft`. |
+
+---
+
+## Task Table
+
+```markdown
+#### Tasks
+| ID | Name | Status | Ext ID |
+|----|------|--------|--------|
+| {topic}-{phase}-{seq} | {Task Name} | {status} | |
+```
+
+| Field | Set when |
+|-------|----------|
+| `ID` | Task design — format: `{topic}-{phase}-{seq}` |
+| `Name` | Task design — descriptive task name |
+| `Status` | Task design → `pending`; authoring → `authored` |
+| `Ext ID` | Task authored — external identifier for the task |