@leeovery/claude-technical-workflows 2.0.45 → 2.0.47

package/commands/link-dependencies.md

@@ -100,7 +100,7 @@ For each unresolved dependency:
 
 2. **If plan exists**: Load the output format reference file
    - Read `format:` from the dependency plan's frontmatter
-   - Load `skills/technical-planning/references/output-{format}.md`
+   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
    - Follow the "Querying Dependencies" section to search for matching tasks
 
 3. **Handle ambiguous matches**:
@@ -115,7 +115,7 @@ For each resolved match:
    - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
 
 2. **Create dependency in output format**:
-   - Load `skills/technical-planning/references/output-{format}.md`
+   - Load `skills/technical-planning/references/output-formats/output-{format}.md`
    - Follow the "Cross-Epic Dependencies" or equivalent section to create the blocking relationship
 
 ## Step 6: Bidirectional Check

package/commands/workflow/start-discussion.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-implementation.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-planning.md

@@ -1,5 +1,5 @@
 ---
-description: Start a planning session from an existing specification. Discovers available specifications, asks where to store the plan, and invokes the technical-planning skill.
+description: Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill.
 allowed-tools: Bash(.claude/scripts/discovery-for-planning.sh)
 ---
 
@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 
@@ -160,19 +164,7 @@ To proceed:
 
 ---
 
-## Step 4: Choose Output Destination
-
-Ask: **Where should this plan live?**
-
-Load **[output-formats.md](../../skills/technical-planning/references/output-formats.md)** and present the available formats to help the user choose. Then load the corresponding output adapter for that format's setup requirements.
-
-**STOP.** Wait for user response.
-
-→ Proceed to **Step 5**.
-
----
-
-## Step 5: Gather Additional Context
+## Step 4: Gather Additional Context
 
 Ask:
 - Any additional context or priorities to consider?
@@ -180,11 +172,11 @@ Ask:
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 6**.
+→ Proceed to **Step 5**.
 
 ---
 
-## Step 6: Surface Cross-Cutting Context
+## Step 5: Surface Cross-Cutting Context
 
 If any **concluded cross-cutting specifications** exist (from `specifications.crosscutting` in discovery), surface them as reference context for planning:
 
@@ -204,11 +196,11 @@ These specifications contain validated architectural decisions that should infor
 
 **If no cross-cutting specifications exist**: Skip this step.
 
-→ Proceed to **Step 7**.
+→ Proceed to **Step 6**.
 
 ---
 
-## Step 7: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -218,8 +210,7 @@ Invoke the [technical-planning](../../skills/technical-planning/SKILL.md) skill
 ```
 Planning session for: {topic}
 Specification: docs/workflow/specification/{topic}.md
-Output format: {format}
-Additional context: {summary of user's answers from Step 5}
+Additional context: {summary of user's answers from Step 4}
 Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
 
 Invoke the technical-planning skill.

package/commands/workflow/start-research.md

@@ -39,7 +39,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-review.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/start-specification.md

@@ -40,7 +40,11 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 
@@ -324,7 +328,12 @@ Then analyze coupling between discussions:
 - **Behavioral coupling**: Discussions where one's implementation requires another
 - **Conceptual coupling**: Discussions that address different facets of the same problem
 
-Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
+Group discussions into specifications where each grouping represents a **coherent feature or capability that can be independently planned and built** — with clear stages delivering incremental, testable value. Coupling tells you what's related; the grouping decision also requires that the result is the right shape:
+
+- **Tightly coupled discussions belong together** — their decisions are inseparable and would produce interleaved implementation work
+- **Don't group too broadly** — if a grouping mixes unrelated concerns, the resulting specification will produce incoherent stages and tasks that jump between disconnected areas
+- **Don't group too narrowly** — if a grouping is too thin, it may not warrant its own specification, planning, and implementation cycle
+- **Flag cross-cutting discussions** — discussions about patterns or policies (not features) should become cross-cutting specifications rather than being grouped with feature discussions
 
 #### Preserve Anchored Names
 

package/commands/workflow/status.md

@@ -8,7 +8,11 @@ Show the current state of the workflow for this project.
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+Invoke the `/migrate` command and assess its output.
+
+**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+
+**If no updates needed**: Proceed to Step 1.
 
 ---
 

package/commands/workflow/view-plan.md

@@ -4,14 +4,6 @@ description: View a plan's tasks and progress, regardless of output format.
 
 Display a readable summary of a plan's phases, tasks, and status.
 
-## Step 0: Run Migrations
-
-**This step is mandatory. You must complete it before proceeding.**
-
-Invoke the `/migrate` command and assess its output before proceeding to Step 1.
-
----
-
 ## Step 1: Identify the Plan
 
 If no topic is specified, list available plans:
@@ -31,7 +23,7 @@ Read the plan file from `docs/workflow/planning/{topic}.md` and check the `forma
 Load the corresponding output format reference:
 
 ```
-skills/technical-planning/references/output-{format}.md
+skills/technical-planning/references/output-formats/output-{format}.md
 ```
 
 This reference contains instructions for reading plans in that format.

package/package.json

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

package/skills/technical-discussion/SKILL.md

@@ -21,7 +21,13 @@ Either way: Capture decisions, rationale, competing approaches, and edge cases.
 - **Context** (optional) - Prior research, constraints, existing decisions
 - **Questions to explore** (optional) - Specific architectural questions to address
 
-**If missing:** Will ask user what topic they want to discuss.
+**Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.
+
+- **No topic provided?**
+  > "What topic would you like to discuss? This could be an architectural decision, a design problem, or edge cases to work through — anything that needs structured technical discussion."
+
+- **Topic is broad or ambiguous?**
+  > "You mentioned {topic}. To keep the discussion focused, is there a specific aspect or decision you want to work through first?"
 
 ## What to Capture
 

package/skills/technical-implementation/SKILL.md

@@ -25,7 +25,18 @@ Either way: Execute via strict TDD - tests first, implementation second.
 - **Environment setup** (optional) - First-time setup instructions
 - **Scope** (optional) - Specific phase/task to work on
 
-**If missing:** Will ask user for plan location. If no specification, plan becomes sole authority.
+**Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
+
+- **No plan provided?**
+  > "I need an implementation plan to execute. Could you point me to the plan file (e.g., `docs/workflow/planning/{topic}.md`)?"
+
+- **Plan has no `format` field in frontmatter?**
+  > "The plan at {path} doesn't specify an output format in its frontmatter. Which format does this plan use?"
+
+- **Plan status is not `concluded`?**
+  > "The plan at {path} has status '{status}' — it hasn't completed the review process. Should I proceed anyway, or should the plan be reviewed first?"
+
+If no specification is available, the plan becomes the sole authority for design decisions.
 
 ## Hard Rules
 
@@ -60,7 +71,7 @@ Complete ALL setup steps before proceeding to implementation work.
 
 2. **Read the plan** from the provided location (typically `docs/workflow/planning/{topic}.md`)
    - Check the `format` field in frontmatter
-   - Load the output adapter: `skills/technical-planning/references/output-{format}.md`
+   - Load the output adapter: `skills/technical-planning/references/output-formats/output-{format}.md`
    - If no format field, ask user which format the plan uses
    - Follow the **Implementation** section for how to read tasks and update progress
 

package/skills/technical-implementation/references/environment-setup.md

@@ -55,7 +55,7 @@ If the environment setup document contains only "No special setup required" (or
 Some plan formats require specific tools. Check the plan's `format` field and load the corresponding output adapter from the planning skill for setup instructions:
 
 ```
-skills/technical-planning/references/output-{format}.md
+skills/technical-planning/references/output-formats/output-{format}.md
 ```
 
 Each output adapter contains prerequisites and installation instructions for that format.

package/skills/technical-planning/SKILL.md

@@ -22,40 +22,103 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Specification content** (required) - The validated decisions and requirements to plan from
 - **Topic name** (optional) - Will derive from specification if not provided
 - **Output format preference** (optional) - Will ask if not specified
-- **Cross-cutting references** (optional) - List of cross-cutting specifications that inform this plan
+- **Cross-cutting references** (optional) - Cross-cutting specifications that inform technical decisions in this plan
 
-**If missing:** Will ask user for specification location or content.
+**Before proceeding**, verify the required input is available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
-### Cross-Cutting References
+- **No specification content provided?**
+  > "I need the specification content to plan from. Could you point me to the specification file (e.g., `docs/workflow/specification/{topic}.md`), or provide the content directly?"
 
-If cross-cutting specifications are provided (e.g., caching strategy, rate limiting policy), incorporate their decisions into the plan:
+- **Specification seems incomplete or not concluded?**
+  > "The specification at {path} appears to be {concern — e.g., 'still in-progress' or 'missing sections that are referenced elsewhere'}. Should I proceed with this, or is there a more complete version?"
 
-1. **Include a "Cross-Cutting References" section** in the plan linking to these specifications
-2. **Apply their patterns** when designing phases and tasks (e.g., if caching strategy says "cache API responses for 5 minutes", include that in relevant tasks)
-3. **Note where patterns apply** - when a task implements a cross-cutting pattern, reference it
+---
 
-Cross-cutting specifications are architectural decisions that inform HOW features are built. They don't have their own implementation plans - instead, their patterns are applied within feature plans.
+## The Process
 
-## Source Material
+Follow every step in sequence. No steps are optional.
 
-**The specification is your sole input.** Everything you need should be in the specification - do not request details from prior source material. If information is missing, ask for clarification on the specification itself.
+---
 
-## The Process
+## Step 1: Choose Output Format
+
+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.
+
+**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/)**.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Load Planning Principles
+
+Load **[planning-principles.md](references/planning-principles.md)** — this contains the planning principles, rules, and quality standards that apply throughout the process.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Read Specification Content
+
+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.
+
+The specification contains validated decisions. Your job is to translate it into an actionable plan, not to review or reinterpret it.
+
+**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)
 
-**Load**: [formal-planning.md](references/formal-planning.md)
+Do not present or summarize the specification back to the user — it has already been signed off.
 
-**Choose output format**: Ask user which format, then load the appropriate output adapter. See **[output-formats.md](references/output-formats.md)** for available formats.
+→ Proceed to **Step 4**.
 
-**Output**: Implementation plan in chosen format
+---
+
+## Step 4: Define Phases
+
+Load **[steps/define-phases.md](references/steps/define-phases.md)** and follow its instructions as written.
+
+---
+
+## Step 5: Define Tasks
+
+Load **[steps/define-tasks.md](references/steps/define-tasks.md)** and follow its instructions as written.
+
+---
+
+## Step 6: Author Tasks
 
-## Critical Rules
+Load **[steps/author-tasks.md](references/steps/author-tasks.md)** and follow its instructions as written.
 
-**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing.
+---
+
+## Step 7: Resolve External Dependencies
+
+Load **[steps/resolve-dependencies.md](references/steps/resolve-dependencies.md)** and follow its instructions as written.
+
+---
+
+## Step 8: Plan Review
+
+Load **[steps/plan-review.md](references/steps/plan-review.md)** and follow its instructions as written.
+
+---
 
-**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+## Step 9: Conclude the Plan
 
-**Never invent reasoning**: If it's not in the specification, ask again. The specification is the golden document - all plan content must trace back to it.
+After the review is complete:
 
-**Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation.
+1. **Update plan status** — Update the plan frontmatter to `status: concluded`
+2. **Final commit** — Commit the concluded plan
+3. **Present completion summary**:
 
-**Collaborate with the user**: Planning is iterative. Stop and ask when the specification is ambiguous, multiple valid approaches exist, or you're uncertain about task scope. The user expects collaboration - don't guess when you can ask.
+> "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."

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

@@ -1,6 +1,6 @@
 # Output: Backlog.md
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -94,8 +94,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -107,7 +107,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {task-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
 
 ### Task File Format
 

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

@@ -1,6 +1,6 @@
 # Output: Beads
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -275,8 +275,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -295,7 +295,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {task-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+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
 

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

@@ -1,6 +1,6 @@
 # Output: Linear
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -185,8 +185,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 
@@ -198,7 +198,7 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 - {topic}: {description} → {issue-id} (resolved)
 ```
 
-The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+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
 

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

@@ -1,6 +1,6 @@
 # Output: Local Markdown
 
-*Output adapter for **[technical-planning](../SKILL.md)***
+*Output adapter for **[technical-planning](../../SKILL.md)***
 
 ---
 
@@ -60,8 +60,8 @@ Architectural decisions from cross-cutting specifications that inform this plan:
 
 | Specification | Key Decisions | Applies To |
 |---------------|---------------|------------|
-| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
-| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
+| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
+| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
 
 *Remove this section if no cross-cutting specifications apply.*
 

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

@@ -4,13 +4,40 @@
 
 ---
 
-Plans can be stored in different formats. **Ask the user which format they prefer** - present the benefits from each adapter file and let them decide.
+Plans can be stored in different formats.
 
-**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding `output-*.md` files in this directory.
+**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.
 
 ## Available Formats
 
-- **[Local Markdown](output-local-markdown.md)** - Single markdown file, no external tools
-- **[Linear](output-linear.md)** - Linear project with labeled issues (requires MCP)
-- **[Backlog.md](output-backlog-md.md)** - Kanban board with task files
-- **[Beads](output-beads.md)** - Git-backed graph issue tracker for AI agents
+### [Local Markdown](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.
+
+- **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
+- **Best for**: Simple features, small plans, quick iterations
+
+### [Linear](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.
+
+- **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)
+
+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](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