@leeovery/claude-technical-workflows 2.0.54 → 2.1.0

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

@@ -0,0 +1,68 @@
+# Linear: Task Graph
+
+Linear natively supports both priority levels and blocking relationships between issues. Both are used to determine execution order.
+
+This file is used by the graphing agent after all tasks have been authored. The agent receives the complete plan and establishes priority and dependencies across tasks.
+
+## Priority
+
+Linear uses fixed numeric priority values (0–4). The API normalises these to the workspace's display labels.
+
+| Value | Level |
+|-------|-------|
+| `1` | Urgent |
+| `2` | High |
+| `3` | Medium |
+| `4` | Low |
+| `0` | No priority |
+
+Lower number = higher priority. `0` means unset.
+
+### Setting Priority
+
+```
+linear_updateIssue(
+  issueId: "{issue_id}",
+  priority: {priority_level}
+)
+```
+
+### Removing Priority
+
+```
+linear_updateIssue(
+  issueId: "{issue_id}",
+  priority: 0
+)
+```
+
+## Dependencies
+
+### Adding a Dependency
+
+To declare that one task depends on another (is blocked by it):
+
+```
+linear_createIssueRelation(
+  issueId: "{dependent_issue_id}",
+  relatedIssueId: "{blocking_issue_id}",
+  type: "blocks"
+)
+```
+
+A task can have multiple dependencies. Call `linear_createIssueRelation` for each one.
+
+### Removing a Dependency
+
+Delete the issue relation via MCP:
+
+```
+linear_deleteIssueRelation(issueRelationId: "{relation_id}")
+```
+
+To find the relation ID, query the issue's relations first:
+
+```
+linear_getIssue(issueId: "{issue_id}")
+# Look for the relation in the issue's relations list
+```

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

@@ -0,0 +1,35 @@
+# Linear: Reading
+
+## Listing Tasks
+
+To retrieve all tasks for a plan:
+
+```
+linear_getIssues(projectId: "{project_id}")
+```
+
+Each issue in the response includes: id, title, state (status), priority, labels (phase grouping), and blocking relationships (`blockedByIssues`, `blockingIssues`).
+
+Use label filters to narrow by phase, or priority/state filters to scope the query further — Linear's API supports these natively.
+
+## Extracting a Task
+
+Query Linear MCP for the issue by ID:
+
+```
+linear_getIssue(issueId: "{issue_id}")
+```
+
+The response includes title, description, status, priority, labels, and blocking relationships.
+
+## Next Available Task
+
+To find the next task to implement:
+
+1. Query Linear MCP for project issues: `linear_getIssues(projectId: "{project_id}")`
+2. Filter to issues whose state is not "completed" or "cancelled"
+3. Exclude issues where any `blockedByIssues` entry has a state other than `completed`
+4. Filter by phase label — complete all `phase-1` issues before `phase-2`
+5. Within a phase, order by priority (Urgent > High > Medium > Low)
+6. The first match is the next task
+7. If no incomplete issues remain, all tasks are complete.

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

@@ -0,0 +1,25 @@
+# Linear: Updating
+
+## Status Transitions
+
+Update the issue state in Linear via MCP:
+
+| Transition | How |
+|------------|-----|
+| Complete | Set state to the team's "Done" workflow state |
+| Skipped | Set state to "Cancelled" + add comment explaining why |
+| Cancelled | Set state to "Cancelled" |
+| In Progress | Set state to "In Progress" |
+
+```
+linear_updateIssue(issueId: "{id}", stateId: "{state_id}")
+```
+
+## Updating Task Content
+
+Update issue properties via MCP:
+
+- **Title**: `linear_updateIssue(issueId: "{id}", title: "{new title}")`
+- **Description**: `linear_updateIssue(issueId: "{id}", description: "{new description}")`
+- **Priority**: `linear_updateIssue(issueId: "{id}", priority: {level})`
+- **Labels**: `linear_updateIssue(issueId: "{id}", labelIds: ["{label_id}", ...])`

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

@@ -0,0 +1,40 @@
+# Local Markdown
+
+*Output format adapter for **[technical-planning](../../../SKILL.md)***
+
+---
+
+Use this format for simple features or when you want everything in version-controlled markdown files.
+
+## Benefits
+
+- No external tools or dependencies required
+- Human-readable and easy to edit
+- Works offline with any text editor
+- Simplest setup — just create markdown files
+
+## Setup
+
+No external tools required. This format uses plain markdown files stored in the repository.
+
+## Structure Mapping
+
+| Concept | Local Markdown Entity |
+|---------|-----------------------|
+| Topic | Directory (`docs/workflow/planning/{topic}/`) |
+| Phase | Encoded in task ID (`{topic}-{phase}-{seq}`) |
+| Task | Markdown file (`{task-id}.md`) |
+| Dependency | Task ID reference in frontmatter (no native blocking) |
+
+## Output Location
+
+Tasks are stored as individual markdown files in a `{topic}/` subdirectory under the planning directory:
+
+```
+docs/workflow/planning/{topic}/
+├── {topic}-1-1.md              # Phase 1, task 1
+├── {topic}-1-2.md              # Phase 1, task 2
+└── {topic}-2-1.md              # Phase 2, task 1
+```
+
+Task filename = task ID for easy lookup.

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

@@ -0,0 +1,64 @@
+# Local Markdown: Authoring
+
+## Task Storage
+
+Each task is written to `docs/workflow/planning/{topic}/{task-id}.md` — a markdown file with frontmatter and a description body.
+
+```markdown
+---
+id: {topic}-{phase}-{seq}
+phase: {phase-number}
+status: pending
+created: YYYY-MM-DD
+---
+
+# {Task Title}
+
+{Task description content}
+```
+
+**Required**: title (`# {Task Title}`) and description (body content). Everything else supports the format's storage mechanics.
+
+## Task Properties
+
+### Status
+
+Stored in frontmatter. Defaults to `pending` if omitted.
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Task has been authored but not started |
+| `in-progress` | Task is currently being worked on |
+| `completed` | Task is done |
+| `skipped` | Task was deliberately skipped |
+| `cancelled` | Task is no longer needed |
+
+### Phase Grouping
+
+Phases are encoded in the task ID: `{topic}-{phase}-{seq}`. The `phase` frontmatter field also stores the phase number for querying.
+
+### Labels / Tags (optional)
+
+Add a `tags` field to frontmatter if additional categorisation is needed:
+
+```yaml
+tags: [edge-case, needs-info]
+```
+
+## Flagging
+
+In the task file, add a **Needs Clarification** section:
+
+```markdown
+**Needs Clarification**:
+- What's the rate limit threshold?
+- Per-user or per-IP?
+```
+
+## Cleanup (Restart)
+
+Delete the task detail directory for this topic:
+
+```bash
+rm -rf docs/workflow/planning/{topic}/
+```

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

@@ -0,0 +1,44 @@
+# Local Markdown: Task Graph
+
+Local markdown has no native dependency or priority engine. Both are stored as frontmatter fields on task files and used during task selection to determine execution order.
+
+This file is used by the graphing agent after all tasks have been authored. The agent receives the complete plan and establishes priority and dependencies across tasks.
+
+## Priority
+
+Any positive integer. Lower number = higher priority. `0` means no priority (unset).
+
+### Setting Priority
+
+Add or update the `priority` field in frontmatter:
+
+```yaml
+priority: 2
+```
+
+### Removing Priority
+
+Set `priority: 0` or remove the `priority` field from frontmatter entirely.
+
+## Dependencies
+
+### Adding a Dependency
+
+Add the blocking task's ID to the `depends_on` field in the dependent task's frontmatter:
+
+```yaml
+depends_on:
+  - {topic}-1-2
+```
+
+A task can depend on multiple tasks:
+
+```yaml
+depends_on:
+  - {topic}-1-2
+  - {topic}-1-3
+```
+
+### Removing a Dependency
+
+Remove the task ID from the `depends_on` field. If the field becomes empty, remove it entirely.

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

@@ -0,0 +1,29 @@
+# Local Markdown: Reading
+
+## Listing Tasks
+
+To retrieve all tasks for a plan:
+
+1. List all `.md` files in `docs/workflow/planning/{topic}/` (excluding the Plan Index)
+2. Read each file's frontmatter to extract: `id`, `phase`, `status`, `priority`, `depends_on`
+3. Read the first heading for the task title
+
+This provides the summary-level data needed for graphing, progress overview, or any operation that needs the full task set.
+
+## Extracting a Task
+
+To read a specific task, read the file at `docs/workflow/planning/{topic}/{task-id}.md`.
+
+The task file is self-contained — frontmatter holds id, phase, and status. The body contains the title and full description.
+
+## Next Available Task
+
+To find the next task to implement:
+
+1. List task files in `docs/workflow/planning/{topic}/`
+2. Filter to tasks where `status` is `pending` or `in-progress` (or missing — treat as `pending`)
+3. If any tasks have `depends_on`, check each referenced task's `status` — exclude the task unless all dependencies have `status: completed`
+4. Order by phase number (from task ID: `{topic}-{phase}-{seq}`) — complete all earlier phases first
+5. Within a phase, order by `priority` if present (lower number = higher priority), then by sequence number
+6. The first match is the next task
+7. If no incomplete tasks remain, all tasks are complete.

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

@@ -0,0 +1,22 @@
+# Local Markdown: Updating
+
+## Status Transitions
+
+Update the `status` field in the task file frontmatter at `docs/workflow/planning/{topic}/{task-id}.md`:
+
+| Transition | Value |
+|------------|-------|
+| Complete | `status: completed` |
+| Skipped | `status: skipped` |
+| Cancelled | `status: cancelled` |
+| In Progress | `status: in-progress` |
+
+## Updating Task Content
+
+Edit the task file directly:
+
+- **Title**: Change the `# {Title}` heading in the body
+- **Description**: Edit the body content below the title
+- **Priority**: Set or change the `priority:` field in frontmatter
+- **Tags**: Set or change the `tags:` field in frontmatter
+- **Dependencies**: See [graph.md](graph.md)

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

@@ -4,28 +4,28 @@
 
 ---
 
-Plans can be stored in different formats.
+Plans can be stored in different formats. Each format is a directory of 5 files split by concern (about, authoring, reading, updating, graph).
 
-**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding `output-*.md` files in the [output-formats/](output-formats/) directory.
+**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding directories in the [output-formats/](output-formats/) directory.
 
 ## Available Formats
 
 ### Local Markdown
 format: `local-markdown`
 
-adapter: [output-local-markdown.md](output-formats/output-local-markdown.md)
+adapter: [local-markdown/](output-formats/local-markdown/)
 
 
-Single markdown file per topic containing all phases, tasks, and progress tracking inline. No external tools or setup required.
+Plan Index File with task detail stored as individual markdown files in a `{topic}/` subdirectory. No external tools or setup required.
 
 - **Pros**: Zero setup, works offline, human-readable, easy to edit in any text editor
-- **Cons**: No visual board, everything in one file can get long for complex features, no dependency graph
+- **Cons**: No visual board, everything in markdown can get long for complex features, no dependency graph
 - **Best for**: Simple features, small plans, quick iterations
 
 ### Linear
 format: `linear`
 
-adapter: [output-linear.md](output-formats/output-linear.md)
+adapter: [linear/](output-formats/linear/)
 
 
 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.
@@ -33,27 +33,3 @@ Tasks managed as Linear issues within a Linear project. A thin Plan Index File p
 - **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
-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.
-
-- **Pros**: Visual Kanban (terminal + web), individual task files for focused editing, version-controlled, MCP integration, auto-commit
-- **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
-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.
-
-- **Pros**: Native dependency graph, `bd ready` surfaces unblocked work, hierarchical task structure, multi-agent coordination, hash-based IDs prevent merge conflicts
-- **Cons**: Requires CLI install, JSONL not human-editable, learning curve, less familiar tooling
-- **Best for**: Complex multi-phase features with many dependencies, AI-agent-driven workflows

package/skills/technical-planning/references/steps/analyze-task-graph.md

@@ -0,0 +1,89 @@
+# Analyze Task Graph
+
+*Reference for **[technical-planning](../../SKILL.md)***
+
+---
+
+This step uses the `planning-dependency-grapher` agent (`.claude/agents/planning-dependency-grapher.md`) to analyze all authored tasks, establish internal dependencies, assign priorities, and detect cycles. You invoke the agent, present its output, and handle the approval gate.
+
+---
+
+## Analyze Dependencies and Priorities
+
+Orient the user:
+
+> "All tasks are authored. Now I'll analyze internal dependencies and priorities across the full plan."
+
+Read **[output-formats.md](../output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[reading.md](../output-formats/{format}/reading.md)** and **[graph.md](../output-formats/{format}/graph.md)**.
+
+### Invoke the Agent
+
+Invoke `planning-dependency-grapher` with these file paths:
+
+1. **Plan Index File path**: `docs/workflow/planning/{topic}.md`
+2. **reading.md**: the format's reading reference loaded above
+3. **graph.md**: the format's graph reference loaded above
+
+The agent clears any existing dependencies/priorities, analyzes all tasks, and — if no cycles — applies the new graph data directly. It returns a structured summary of what was done.
+
+---
+
+## Review and Approve
+
+#### If the agent reports no changes needed (`STATUS: no-changes`)
+
+The natural task order is already correct. Present this to the user:
+
+> "I've analyzed all {M} tasks and the natural execution order is already correct — no explicit dependencies or priorities are needed.
+>
+> {notes from agent output}"
+
+> **To proceed:**
+> - **`y`/`yes`** — Confirmed.
+> - **Or tell me what to change.**
+
+**STOP.** Wait for the user's response.
+
+#### If the agent reports a cycle (`STATUS: blocked`)
+
+No changes were applied. Present the cycle to the user:
+
+> "The dependency analysis found a circular dependency:
+>
+> {cycle chain from agent output}
+>
+> This must be resolved before continuing. The cycle usually means two tasks each assume the other is done first — one needs to be restructured or the dependency removed."
+
+**STOP.** Wait for the user to decide how to resolve. Options include adjusting task scope, merging tasks, or removing a dependency. Re-invoke the agent after changes.
+
+#### If the agent applied changes successfully (`STATUS: complete`)
+
+Dependencies and priorities have already been written to the task files. Present the summary:
+
+> "I've analyzed and applied dependencies and priorities across all {M} tasks:
+>
+> **Dependencies** ({count} relationships):
+> {dependency list from agent output}
+>
+> **Priorities**:
+> {priority list from agent output}
+>
+> {any notes from agent output}"
+
+> **To proceed:**
+> - **`y`/`yes`** — Approved.
+> - **Or tell me what to change.**
+
+**STOP.** Wait for the user's response.
+
+#### If the user provides feedback
+
+Re-invoke `planning-dependency-grapher` with all original inputs PLUS:
+- **Previous output**: the current analysis
+- **User feedback**: what to change
+
+The agent will clear all existing graph data and re-analyze from scratch. Present the revised analysis in full. Ask the same choice again. Repeat until approved.
+
+#### If approved
+
+Commit: `planning({topic}): analyze task dependencies and priorities`

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

@@ -21,11 +21,11 @@ Invoke `planning-task-author` with these file paths:
 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
+8. **Output format authoring reference**: path to the format's `authoring.md` (e.g., `.claude/skills/technical-planning/references/output-formats/{format}/authoring.md`)
 
 ### 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.
+The agent returns complete task detail following the task template from task-design.md. Present it to the user **exactly as it will be written** — what the user sees is what gets logged.
 
 After presenting, ask:
 
@@ -54,7 +54,7 @@ Present the revised task in full. Ask the same choice again. Repeat until approv
 
 > **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.
 
-1. Write the task to the output format (format-specific — see output adapter)
+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. Commit: `planning({topic}): author task {task-id} ({task name})`

package/skills/technical-planning/references/steps/review-integrity.md

@@ -44,11 +44,10 @@ Read the plan end-to-end — carefully, as if you were about to implement it. Fo
    - Phase boundaries make sense (not arbitrary groupings)
 
 4. **Dependencies and Ordering**
-   - Phase ordering reflects actual dependencies
-   - Tasks within phases are ordered logically
-   - Cross-phase dependencies are explicit where they exist
-   - No circular dependencies
-   - An implementer can infer execution order from the plan structure
+   - Task dependencies are explicit and correct — each dependency reflects a genuine data or capability requirement
+   - No circular dependencies exist in the task graph
+   - Priority assignments reflect graph position — foundation tasks and tasks that unblock others are prioritised appropriately
+   - An implementer can determine execution order from the dependency graph and priorities alone
 
 5. **Task Self-Containment**
    - Each task contains all context needed for execution

package/skills/technical-planning/references/task-design.md

@@ -104,6 +104,8 @@ Ask: "Can I write a test for this task that passes without any other task being
 
 ## Task Template
 
+This is the canonical task format. The planning skill owns task content — output format adapters only define where/how this content is stored.
+
 Every task should follow this structure:
 
 ```markdown
@@ -130,9 +132,15 @@ Every task should follow this structure:
 - `"it handles edge case correctly"`
 - `"it fails appropriately for invalid input"`
 
+**Edge Cases**: (when relevant)
+- Boundary condition details
+- Unusual inputs or race conditions
+
 **Context**: (when relevant)
 > Relevant details from specification: code examples, architectural decisions,
 > data models, or constraints that inform implementation.
+
+**Spec Reference**: `docs/workflow/specification/{topic}.md` (if specification was provided)
 ```
 
 ### Field Requirements
@@ -145,7 +153,9 @@ Every task should follow this structure:
 | Do | Yes | At least one concrete action |
 | Acceptance Criteria | Yes | At least one pass/fail criterion |
 | Tests | Yes | At least one test name; include edge cases, not just happy path |
+| Edge Cases | When relevant | Boundary conditions, unusual inputs |
 | Context | When relevant | Only include when spec has details worth pulling forward |
+| Spec Reference | When provided | Path to specification for ambiguity resolution. Include when a specification file was provided as input. Omit if planning from inline context or other non-file sources. |
 
 ### The Template as Quality Gate
 

package/skills/technical-review/SKILL.md

@@ -74,7 +74,7 @@ Plan (tasks + acceptance criteria)
         → Check Code Quality (readable, conventions)
 ```
 
-**Use parallel `chain-verifier` subagents** to verify ALL plan tasks simultaneously. Each verifier checks one task for implementation, tests, and quality. This enables comprehensive review without sequential bottlenecks.
+**Use parallel `review-task-verifier` subagents** to verify ALL plan tasks simultaneously. Each verifier checks one task for implementation, tests, and quality. This enables comprehensive review without sequential bottlenecks.
 
 ## What You Verify (Per Task)
 
@@ -115,8 +115,8 @@ Review as a senior architect would:
 1. **Read the plan** - Understand all phases, tasks, and acceptance criteria
 2. **Read the specification** - Load context for the feature being reviewed
 3. **Extract all tasks** - List every task from every phase
-4. **Spawn chain-verifiers in parallel** - One subagent per task, all running simultaneously
-5. **Aggregate findings** - Collect reports from all chain-verifiers
+4. **Spawn review-task-verifiers in parallel** - One subagent per task, all running simultaneously
+5. **Aggregate findings** - Collect reports from all review-task-verifiers
 6. **Check project skills** - Framework/language conventions
 7. **Produce review** - Structured feedback covering all tasks
 

package/skills/technical-review/references/review-checklist.md

@@ -26,18 +26,18 @@ From the plan, list every task across all phases:
 
 ### Parallel Verification
 
-Spawn `chain-verifier` subagents **in parallel** for ALL tasks:
+Spawn `review-task-verifier` subagents **in parallel** for ALL tasks:
 
 ```
-Task 1 ──▶ [chain-verifier] ──▶ Findings
-Task 2 ──▶ [chain-verifier] ──▶ Findings
-Task 3 ──▶ [chain-verifier] ──▶ Findings  (all running in parallel)
-Task 4 ──▶ [chain-verifier] ──▶ Findings
+Task 1 ──▶ [review-task-verifier] ──▶ Findings
+Task 2 ──▶ [review-task-verifier] ──▶ Findings
+Task 3 ──▶ [review-task-verifier] ──▶ Findings  (all running in parallel)
+Task 4 ──▶ [review-task-verifier] ──▶ Findings
   ...
-Task N ──▶ [chain-verifier] ──▶ Findings
+Task N ──▶ [review-task-verifier] ──▶ Findings
 ```
 
-**How to invoke each chain-verifier:**
+**How to invoke each review-task-verifier:**
 
 Provide:
 - The specific task (with acceptance criteria)
@@ -45,14 +45,14 @@ Provide:
 - Path to plan (for phase context)
 - Implementation scope (files/directories changed)
 
-**Each chain-verifier checks:**
+**Each review-task-verifier checks:**
 1. Implementation exists and matches acceptance criteria
 2. Tests are adequate (not under-tested, not over-tested)
 3. Code quality is acceptable
 
 **Aggregate the findings:**
 
-Once all chain-verifiers complete, synthesize their reports:
+Once all review-task-verifiers complete, synthesize their reports:
 - Collect all incomplete/failed tasks as blocking issues
 - Collect all test issues (under/over-tested)
 - Collect all code quality concerns
@@ -60,7 +60,7 @@ Once all chain-verifiers complete, synthesize their reports:
 
 ## Per-Task Verification Details
 
-For each task, the chain-verifier checks:
+For each task, the review-task-verifier checks:
 
 ### Implementation