@leeovery/claude-technical-workflows 2.0.47 → 2.0.48

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

@@ -141,22 +141,30 @@ When creating issues, if something is unclear or missing from the specification:
 
 This allows iterative refinement. Create all issues, identify gaps, circle back to specification if needed, then update issues with missing detail. Plans don't have to be perfect on first pass.
 
-### 4. Create Local Plan File
+### 4. Create Plan Index File
 
 Create `docs/workflow/planning/{topic}.md`:
 
 ```markdown
 ---
+topic: {topic-name}
+status: planning
 format: linear
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
 plan_id: {PROJECT_NAME}
 project_id: {ID from MCP response}
 team: {TEAM_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
 
@@ -190,6 +198,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 |
+|----|------|------------|--------|
+| {issue-id} | {Task Name} | {list} | pending |
+
+---
+
+### Phase 2: {Name}
+status: draft
+label: phase-2
+
+...
+
 ## External Dependencies
 
 [Dependencies on other topics - copy from specification's Dependencies section]
@@ -202,14 +236,25 @@ The External Dependencies section tracks what this plan needs from other topics.
 
 ## Frontmatter
 
-The frontmatter contains all information needed to query Linear:
+The frontmatter contains all information needed to query Linear and tracks planning progress:
 
 ```yaml
 ---
+topic: {topic-name}
+status: planning | concluded
 format: linear
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
 plan_id: USER-AUTH-FEATURE
 project_id: abc123-def456
 team: Engineering
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 2
+  task: 3
 ---
 ```
 
@@ -267,6 +312,14 @@ Linear:
 - Update issue status in Linear via MCP after each task
 - User sees real-time progress in Linear UI
 
+### Cleanup (Restart)
+
+The official Linear MCP server does not support deletion. Ask the user to delete the Linear project manually via the Linear UI.
+
+> "The Linear project **{project name}** needs to be deleted before restarting. Please delete it in the Linear UI (Project Settings → Delete project), then confirm so I can proceed."
+
+**STOP.** Wait for the user to confirm.
+
 ### Fallback
 
 If Linear MCP is unavailable:

package/skills/technical-planning/references/output-formats/output-local-markdown.md

@@ -4,15 +4,15 @@
 
 ---
 
-Use this format for simple features or when you want everything in a single version-controlled file.
+Use this format for simple features or when you want everything in a single version-controlled file with detailed task files.
 
 ## Benefits
 
 - No external tools or dependencies required
-- Everything in a single version-controlled file
+- Plan Index File provides overview; task files provide detail
 - Human-readable and easy to edit
 - Works offline with any text editor
-- Simplest setup - just create a markdown file
+- Simplest setup - just create markdown files
 
 ## Setup
 
@@ -22,25 +22,34 @@ No external tools required. This format uses plain markdown files stored in the
 
 ```
 docs/workflow/planning/
-└── {topic}.md
+├── {topic}.md                    # Plan Index File
+└── {topic}/
+    └── {task-id}.md              # Task detail files
 ```
 
-This is a single file per topic in the planning directory.
+The Plan Index File contains phases and task tables. Each authored task gets its own file in the `{topic}/` directory. Task filename = task ID for easy lookup.
 
-## Template
+## Plan Index Template
 
 Create `{topic}.md` with this structure:
 
 ```markdown
 ---
 topic: {feature-name}
-status: in-progress
-date: YYYY-MM-DD
+status: planning
 format: local-markdown
-specification: {topic}.md
+specification: ../specification/{topic}.md
+cross_cutting_specs:              # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 1
+  task: ~
 ---
 
-# Implementation Plan: {Feature/Project Name}
+# Plan: {Feature/Project Name}
 
 ## Overview
 
@@ -65,98 +74,102 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 *Remove this section if no cross-cutting specifications apply.*
 
-## Architecture
-
-- Components
-- Data flow
-- Integration points
-
 ## Phases
 
-Each phase is independently testable with clear acceptance criteria.
-Each task is a single TDD cycle: write test → implement → commit.
-
----
-
 ### Phase 1: {Name}
+status: draft
 
 **Goal**: What this phase accomplishes
+**Why this order**: Why this comes at this position
 
 **Acceptance**:
 - [ ] Criterion 1
 - [ ] Criterion 2
 
-**Tasks**:
-
-1. **{Task Name}**
-   - **Do**: What to implement
-   - **Test**: `"it does expected behavior"`
-   - **Edge cases**: (if any)
-
-2. **{Task Name}**
-   - **Do**: What to implement
-   - **Test**: `"it does expected behavior"`
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| {topic}-1-1 | {Task Name} | {list} | pending |
+| {topic}-1-2 | {Task Name} | {list} | pending |
 
 ---
 
 ### Phase 2: {Name}
+status: draft
 
 **Goal**: What this phase accomplishes
+**Why this order**: Why this comes at this position
 
 **Acceptance**:
 - [ ] Criterion 1
 - [ ] Criterion 2
 
-**Tasks**:
-
-1. **{Task Name}**
-   - **Do**: What to implement
-   - **Test**: `"it does expected behavior"`
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
 
 (Continue pattern for remaining phases)
 
 ---
 
-## Edge Cases
+## External Dependencies
 
-Map edge cases from specification to specific tasks:
+[Dependencies on other topics - copy from specification's Dependencies section]
 
-| Edge Case | Solution | Phase.Task | Test |
-|-----------|----------|------------|------|
-| {From specification} | How handled | 1.2 | `"it handles X"` |
+- {topic}: {description}
+- {topic}: {description} → {task-reference} (resolved)
+- ~~{topic}: {description}~~ → satisfied externally
 
-## Testing Strategy
+## Log
 
-**Unit**: What to test per component
-**Integration**: What flows to verify
-**Manual**: (if needed)
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD *(use today's actual date)* | Created from specification |
+```
 
-## Data Models (if applicable)
+## Task File Template
 
-Tables, schemas, API contracts
+Each authored task is written to `{topic}/{task-id}.md`:
 
-## Internal Dependencies
+```markdown
+---
+id: {topic}-{phase}-{seq}
+phase: {phase-number}
+status: pending
+created: YYYY-MM-DD  # Use today's actual date
+---
 
-- Prerequisites for Phase 1
-- Phase dependencies (Phase 2 depends on Phase 1, etc.)
+# {Task Name}
 
-## External Dependencies
+## Goal
 
-[Dependencies on other topics - copy from specification's Dependencies section]
+{What this task accomplishes and why — include rationale from specification}
 
-- {topic}: {description}
-- {topic}: {description} → {task-reference} (resolved)
-- ~~{topic}: {description}~~ → satisfied externally
+## Implementation
 
-## Rollback (if applicable)
+{The "Do" — specific files, methods, approach}
 
-Triggers and steps
+## Tests
 
-## Log
+- `it does expected behavior`
+- `it handles edge case`
 
-| Date | Change |
-|------|--------|
-| YYYY-MM-DD *(use today's actual date)* | Created from specification |
+## Edge Cases
+
+{Specific edge cases for this task}
+
+## Acceptance Criteria
+
+- [ ] Test written and failing
+- [ ] Implementation complete
+- [ ] Tests passing
+- [ ] Committed
+
+## Context
+
+{Relevant decisions and constraints from specification}
+
+Specification reference: `docs/workflow/specification/{topic}.md` (for ambiguity resolution)
 ```
 
 ## Cross-Topic Dependencies
@@ -165,21 +178,19 @@ Cross-topic dependencies link tasks between different plan files. This is how yo
 
 ### In the External Dependencies Section
 
-Use the format `{topic}: {description} → {task-reference}` where task-reference points to a specific task in another plan file:
+Use the format `{topic}: {description} → {task-id}` where task-id points to a specific task:
 
 ```markdown
 ## External Dependencies
 
-- billing-system: Invoice generation → billing-system.md#phase-1-task-2 (resolved)
-- authentication: User context → authentication.md#phase-2-task-1 (resolved)
+- billing-system: Invoice generation → billing-1-2 (resolved)
+- authentication: User context → auth-2-1 (resolved)
 - payment-gateway: Payment processing (unresolved - not yet planned)
 ```
 
 ### Task References
 
-For local markdown plans, reference tasks using:
-- `{topic}.md#phase-{n}-task-{m}` - references a specific task by phase and number
-- Consider adding nano IDs to task headers for more stable references
+For local markdown plans, reference tasks using the task ID (e.g., `billing-1-2`). The task file is at `{topic}/{task-id}.md`.
 
 ## Querying Dependencies
 
@@ -202,51 +213,60 @@ grep -A 10 "## External Dependencies" docs/workflow/planning/*.md | grep "^- " |
 grep -l "billing-system:" docs/workflow/planning/*.md
 ```
 
-### Check if a Dependency Task Exists
-
-Read the referenced plan file and verify the task exists:
+### Check if a Task Exists
 
 ```bash
-# Check if a task exists in another plan
-grep "Phase 1.*Task 2" docs/workflow/planning/billing-system.md
+# Check if task file exists
+ls docs/workflow/planning/billing-system/billing-1-2.md
 ```
 
-### Check if a Dependency is Complete
+### Check if a Task is Complete
 
-For local markdown, check if the task's acceptance criteria are checked off:
+Read the task file and check the status in frontmatter:
 
 ```bash
-# Look for completed acceptance criteria
-grep -A 5 "### Phase 1" docs/workflow/planning/billing-system.md | grep "\[x\]"
+# Check task status
+grep "status:" docs/workflow/planning/billing-system/billing-1-2.md
 ```
 
 ## Frontmatter
 
-Plan documents use YAML frontmatter for metadata:
+Plan Index Files use YAML frontmatter for metadata:
 
 ```yaml
 ---
-topic: {feature-name}        # Matches filename (without .md)
-status: in-progress          # in-progress | concluded
-date: YYYY-MM-DD             # Creation date
-format: local-markdown       # Output format used
-specification: {topic}.md    # Source specification filename
+topic: {feature-name}                    # Matches filename (without .md)
+status: planning | concluded             # Planning status
+format: local-markdown                   # Output format used
+specification: ../specification/{topic}.md
+cross_cutting_specs:                     # Omit if none
+  - ../specification/{spec}.md
+spec_commit: {git-commit-hash}        # Git commit when planning started
+created: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+planning:
+  phase: 2
+  task: 3
 ---
 ```
 
-The `format` field tells implementation which output adapter to use for reading/updating the plan.
+The `planning:` block tracks current progress position. It persists after the plan is concluded — `status:` indicates whether the plan is active or concluded.
 
 ## Flagging Incomplete Tasks
 
-When information is missing, mark clearly with `[needs-info]`:
+When information is missing, mark in the task table:
 
 ```markdown
-### Task 3: Configure rate limiting [needs-info]
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| auth-1-3 | Configure rate limiting | [needs-info] threshold, per-user vs per-IP | pending |
+```
 
-**Do**: Set up rate limiting for the API endpoint
-**Test**: `it throttles requests exceeding limit`
+And in the task file, add a "Needs Clarification" section:
+
+```markdown
+## Needs Clarification
 
-**Needs clarification**:
 - What's the rate limit threshold?
 - Per-user or per-IP?
 ```
@@ -257,20 +277,42 @@ After planning:
 
 ```
 docs/workflow/
-├── discussion/{topic}.md      # Discussion output
-├── specification/{topic}.md   # Specification output
-└── planning/{topic}.md        # Planning output (format: local-markdown)
+├── discussion/{topic}.md           # Discussion output
+├── specification/{topic}.md        # Specification output
+└── planning/
+    ├── {topic}.md                  # Plan Index File (format: local-markdown)
+    └── {topic}/
+        ├── {topic}-1-1.md          # Task detail files
+        ├── {topic}-1-2.md
+        └── {topic}-2-1.md
 ```
 
 ## Implementation
 
 ### Reading Plans
 
-1. Read the plan file - all content is inline
-2. Phases and tasks are in the document
-3. Follow phase order as written
+1. Read the Plan Index File to get overview and task tables
+2. For each task to implement, read `{topic}/{task-id}.md`
+3. Follow phase order as written in the index
+4. Check task status in the index table
 
 ### Updating Progress
 
-- Check off acceptance criteria in the plan file
-- Update phase status as phases complete
+- Update task file frontmatter `status: completed` when done
+- Update the task table in the Plan Index File
+- Check off phase acceptance criteria when all phase tasks complete
+
+### Authoring Tasks (During Planning)
+
+When a task is approved:
+1. Create `{topic}/{task-id}.md` with the task content
+2. Update the task table: set `status: authored`
+3. Update the `planning:` block in frontmatter
+
+### Cleanup (Restart)
+
+Delete the task detail directory for this topic:
+
+```bash
+rm -rf docs/workflow/planning/{topic}/
+```

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

@@ -10,7 +10,11 @@ Plans can be stored in different formats.
 
 ## Available Formats
 
-### [Local Markdown](output-formats/output-local-markdown.md)
+### Local Markdown
+format: `local-markdown`
+
+adapter: [output-local-markdown.md](output-formats/output-local-markdown.md)
+
 
 Single markdown file per topic containing all phases, tasks, and progress tracking inline. No external tools or setup required.
 
@@ -18,15 +22,23 @@ Single markdown file per topic containing all phases, tasks, and progress tracki
 - **Cons**: No visual board, everything in one file can get long for complex features, no dependency graph
 - **Best for**: Simple features, small plans, quick iterations
 
-### [Linear](output-formats/output-linear.md)
+### Linear
+format: `linear`
+
+adapter: [output-linear.md](output-formats/output-linear.md)
+
 
-Tasks managed as Linear issues within a Linear project. A thin local plan file points to the Linear project; Linear is the source of truth.
+Tasks managed as Linear issues within a Linear project. A thin Plan Index File points to the Linear project; Linear is the source of truth.
 
 - **Pros**: Visual tracking, team collaboration, real-time updates, integrates with existing Linear workflows
 - **Cons**: Requires Linear account and MCP server, external dependency, not fully local
 - **Best for**: Teams already using Linear, collaborative projects needing shared visibility
 
-### [Backlog.md](output-formats/output-backlog-md.md)
+### Backlog.md
+format: `backlog-md`
+
+adapter: [output-backlog-md.md](output-formats/output-backlog-md.md)
+
 
 Individual task files in a `backlog/` directory with a local Kanban board. Each task is a self-contained markdown file with frontmatter for status, priority, labels, and dependencies.
 
@@ -34,7 +46,11 @@ Individual task files in a `backlog/` directory with a local Kanban board. Each
 - **Cons**: Requires npm install, flat directory (phases via labels not folders), external tool dependency
 - **Best for**: Solo developers wanting a local Kanban board with per-task files
 
-### [Beads](output-formats/output-beads.md)
+### Beads
+format: `beads`
+
+adapter: [output-beads.md](output-formats/output-beads.md)
+
 
 Git-backed graph issue tracker with hierarchical tasks (epics → phases → tasks) and native dependency management. Uses JSONL storage with a CLI interface.
 

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.