@leeovery/claude-technical-workflows 2.0.47 → 2.0.49

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 |

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.