@leeovery/claude-technical-workflows 2.0.15 → 2.0.16

package/commands/link-dependencies.md

@@ -0,0 +1,170 @@
+---
+description: Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format.
+---
+
+Link cross-topic dependencies across all existing plans.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+## Important
+
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+
+## Step 1: Discover All Plans
+
+Scan the codebase for existing plans:
+
+1. **Find plan files**: Look in `docs/workflow/planning/`
+   - Run `ls docs/workflow/planning/` to list plan files
+   - Each file is named `{topic}.md`
+
+2. **Extract plan metadata**: For each plan file
+   - Read the frontmatter to get the `format:` field
+   - Note the format used by each plan
+
+**If no plans exist:**
+
+```
+⚠️ No plans found in docs/workflow/planning/
+
+There are no plans to link. Create plans using /start-planning first.
+```
+
+Stop here.
+
+**If only one plan exists:**
+
+```
+⚠️ Only one plan found: {topic}
+
+Cross-topic dependency linking requires at least two plans. Create more plans using /start-planning first.
+```
+
+Stop here.
+
+## Step 2: Check Output Format Consistency
+
+Compare the `format:` field across all discovered plans.
+
+**If plans use different output formats:**
+
+```
+⚠️ Mixed output formats detected:
+
+- authentication: beads
+- billing-system: linear
+- notifications: beads
+
+Cross-topic dependencies can only be wired within the same output format.
+Please consolidate your plans to use a single output format before linking dependencies.
+```
+
+Stop here.
+
+## Step 3: Extract External Dependencies
+
+For each plan, find the External Dependencies section:
+
+1. **Read the External Dependencies section** from each plan index file
+2. **Categorize each dependency**:
+   - **Unresolved**: `- {topic}: {description}` (no arrow, no task ID)
+   - **Resolved**: `- {topic}: {description} → {task-id}` (has task ID)
+   - **Satisfied externally**: `- ~~{topic}: {description}~~ → satisfied externally`
+
+3. **Build a summary**:
+
+```
+📋 Dependency Summary
+
+Plan: authentication (format: beads)
+  - billing-system: Invoice generation (unresolved)
+  - user-management: User profiles → beads-7x2k (resolved)
+
+Plan: billing-system (format: beads)
+  - authentication: User context (unresolved)
+  - ~~payment-gateway: Payment processing~~ → satisfied externally
+
+Plan: notifications (format: beads)
+  - authentication: User lookup (unresolved)
+  - billing-system: Invoice events (unresolved)
+```
+
+## Step 4: Match Dependencies to Plans
+
+For each unresolved dependency:
+
+1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}.md` exist?
+   - If no match: Mark as "no plan exists" - cannot resolve yet
+
+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`
+   - Follow the "Querying Dependencies" section to search for matching tasks
+
+3. **Handle ambiguous matches**:
+   - If multiple tasks could satisfy the dependency, present options to user
+   - Allow selecting multiple if the dependency requires multiple tasks
+
+## Step 5: Wire Up Dependencies
+
+For each resolved match:
+
+1. **Update the plan index file**:
+   - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
+
+2. **Create dependency in output format**:
+   - Load `skills/technical-planning/references/output-{format}.md`
+   - Follow the "Cross-Epic Dependencies" or equivalent section to create the blocking relationship
+
+## Step 6: Bidirectional Check
+
+For each plan that was a dependency target (i.e., other plans depend on it):
+
+1. **Check reverse dependencies**: Are there other plans that should have this wired up?
+2. **Offer to update**: "Plan X depends on tasks you just linked. Update its External Dependencies section?"
+
+## Step 7: Report Results
+
+Present a summary:
+
+```
+✅ Dependency Linking Complete
+
+RESOLVED (newly linked):
+  - authentication → billing-system: beads-b7c2.1.1 (Invoice generation)
+  - notifications → authentication: beads-a3f8.1.2 (Session management)
+
+ALREADY RESOLVED (no action needed):
+  - authentication → user-management: beads-9m3p
+
+SATISFIED EXTERNALLY (no action needed):
+  - billing-system → payment-gateway
+
+UNRESOLVED (no matching plan exists):
+  - notifications → email-service: Email delivery
+
+  ⚠️ These dependencies have no corresponding plan. Either:
+  - Create a plan for the topic using /start-planning
+  - Mark as "satisfied externally" if already implemented
+
+UPDATED FILES:
+  - docs/workflow/planning/authentication.md
+  - docs/workflow/planning/notifications.md
+```
+
+## Step 8: Commit Changes
+
+If any files were updated:
+
+```
+Shall I commit these dependency updates? (y/n)
+```
+
+If yes, commit with message:
+```
+Link cross-topic dependencies
+
+- {summary of what was linked}
+```

package/commands/start-implementation.md

@@ -5,7 +5,7 @@ description: Start an implementation session from an existing plan. Discovers av
 ## IMPORTANT: Follow these steps EXACTLY. Do not skip steps.
 
 - Ask each question and WAIT for a response before proceeding
-- Do NOT install anything or invoke tools until Step 5
+- Do NOT install anything or invoke tools until Step 6
 - Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
 - Do NOT make assumptions about what the user wants
 - Complete each step fully before moving to the next
@@ -49,7 +49,66 @@ Plans found:
 Which plan would you like to implement?
 ```
 
-## Step 3: Check Environment Setup
+## Step 3: Check External Dependencies
+
+**This step is a gate.** Implementation cannot proceed if dependencies are not satisfied.
+
+See **[dependencies.md](../skills/technical-planning/references/dependencies.md)** for dependency format and states.
+
+After the user selects a plan:
+
+1. **Read the External Dependencies section** from the plan index file
+2. **Check each dependency** according to its state:
+   - **Unresolved**: Block
+   - **Resolved**: Check if task is complete (load output format reference, follow "Querying Dependencies" section)
+   - **Satisfied externally**: Proceed
+
+### Blocking Behavior
+
+If ANY dependency is unresolved or incomplete, **stop and present**:
+
+```
+⚠️ Implementation blocked. Missing dependencies:
+
+UNRESOLVED (not yet planned):
+- billing-system: Invoice generation for order completion
+  → No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
+
+INCOMPLETE (planned but not implemented):
+- beads-7x2k (authentication): User context retrieval
+  → Status: in_progress. This task must be completed first.
+
+These dependencies must be completed before this plan can be implemented.
+
+OPTIONS:
+1. Implement the blocking dependencies first
+2. Mark a dependency as "satisfied externally" if it was implemented outside this workflow
+3. Run /link-dependencies to wire up any recently completed plans
+```
+
+### Escape Hatch
+
+If the user says a dependency has been implemented outside the workflow:
+
+1. Ask which dependency to mark as satisfied
+2. Update the plan index file:
+   - Change `- {topic}: {description}` to `- ~~{topic}: {description}~~ → satisfied externally`
+3. Commit the change
+4. Re-check dependencies
+
+### All Dependencies Satisfied
+
+If all dependencies are resolved and complete (or satisfied externally), proceed to Step 4.
+
+```
+✅ External dependencies satisfied:
+- billing-system: Invoice generation → beads-b7c2.1.1 (complete)
+- authentication: User context → beads-a3f8.1.2 (complete)
+
+Proceeding with environment setup...
+```
+
+## Step 4: Check Environment Setup
 
 > **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The technical-implementation skill will handle execution when invoked.
 
@@ -62,7 +121,7 @@ After the user selects a plan:
    - If the user says no, create `docs/workflow/environment-setup.md` with "No special setup required." and commit. This prevents asking again in future sessions.
    - See `skills/technical-implementation/references/environment-setup.md` for format guidance
 
-## Step 4: Ask About Scope
+## Step 5: Ask About Scope
 
 Ask the user about implementation scope:
 
@@ -81,7 +140,7 @@ If they choose a specific phase or task, ask them to specify which one.
 
 > **Note:** Do NOT verify that the phase or task exists. Accept the user's answer and pass it to the skill. Validation happens during the implementation phase.
 
-## Step 5: Invoke Implementation Skill
+## Step 6: Invoke Implementation Skill
 
 Invoke the **technical-implementation** skill for this conversation.
 
@@ -89,6 +148,7 @@ Pass to the technical-implementation skill:
 - Plan: `docs/workflow/planning/{topic}.md`
 - Format: (from frontmatter)
 - Scope: (all phases | specific phase | specific task | next-available)
+- Dependencies: (all satisfied - verified in Step 3)
 - Environment setup: (completed | not needed)
 
 **Example handoff:**
@@ -98,6 +158,7 @@ Plan: docs/workflow/planning/{topic}.md
 Format: {format}
 Scope: All phases
 
+Dependencies: All satisfied ✓
 Environment setup: Completed (or: Not needed)
 
 Begin implementation using the technical-implementation skill.

package/package.json

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

package/skills/technical-planning/references/dependencies.md

@@ -0,0 +1,69 @@
+# Dependencies
+
+*Reference for dependency handling across the technical workflow*
+
+---
+
+## Internal Dependencies
+
+Internal dependencies are dependencies within a single topic/epic - where one task depends on another task in the same plan. These are handled by the planning output format's native dependency system.
+
+During planning, structure tasks in the correct order with appropriate dependencies so work proceeds logically. The output format manages these relationships and ensures tasks are worked in the right sequence.
+
+See the relevant output format reference for how to create and query internal dependencies.
+
+## External Dependencies
+
+External dependencies are things a feature needs from other topics or systems that are outside the current plan's scope. They come from the specification's Dependencies section.
+
+## Format
+
+In plan index files, external dependencies appear in a dedicated section:
+
+```markdown
+## External Dependencies
+
+- billing-system: Invoice generation for order completion
+- user-authentication: User context for permissions → beads-9m3p (resolved)
+- ~~payment-gateway: Payment processing~~ → satisfied externally
+```
+
+If there are no external dependencies, still include the section:
+
+```markdown
+## External Dependencies
+
+No external dependencies.
+```
+
+This makes it explicit for downstream stages that dependencies were considered and none exist.
+
+## States
+
+| State | Format | Meaning |
+|-------|--------|---------|
+| Unresolved | `- {topic}: {description}` | Dependency exists but not yet linked to a task |
+| Resolved | `- {topic}: {description} → {task-id}` | Linked to specific task in another plan |
+| Satisfied externally | `- ~~{topic}: {description}~~ → satisfied externally` | Implemented outside workflow |
+
+## Lifecycle
+
+```
+SPECIFICATION                    PLANNING
+───────────────────────────────────────────────────────────────────
+Dependencies section    →    Copied to plan index as unresolved
+(natural language)                      ↓
+                             Resolved when linked to specific task ID
+                             (via planning or /link-dependencies)
+```
+
+## Resolution
+
+Dependencies move from unresolved → resolved when:
+- The dependency topic is planned and you identify the specific task
+- The `/link-dependencies` command finds and wires the match
+
+Dependencies become "satisfied externally" when:
+- The user confirms it was implemented outside the workflow
+- It already exists in the codebase
+- It's a third-party system that's already available

package/skills/technical-planning/references/formal-planning.md

@@ -19,9 +19,29 @@ From the specification (`docs/workflow/specification/{topic}.md`), extract:
 - Architectural choices
 - Edge cases identified
 - Constraints and requirements
+- **External dependencies** (from the Dependencies section)
 
 **The specification is your sole input.** Discussion documents and other source materials have already been validated, filtered, and enriched during the specification phase. Everything you need is in the specification - do not reference other documents.
 
+#### Extract External Dependencies
+
+The specification's Dependencies section lists things this feature needs from other topics/systems. These are **external dependencies** - things outside this plan's scope that must exist for implementation to proceed.
+
+Copy these into the plan index file (see "External Dependencies Section" below). During planning:
+
+1. **Check for existing plans**: For each dependency, search `docs/workflow/planning/` for a matching topic
+2. **If plan exists**: Try to identify specific tasks that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply.
+3. **If no plan exists**: Record the dependency in natural language - it will be linked later via `/link-dependencies` or when that topic is planned.
+
+**Optional reverse check**: Ask the user: "Would you like me to check if any existing plans depend on this topic?"
+
+If yes:
+1. Scan other plan indexes for External Dependencies that reference this topic
+2. For each match, identify which task(s) in the current plan satisfy that dependency
+3. Update the other plan's dependency entry with the task ID (unresolved → resolved)
+
+Alternatively, the user can run `/link-dependencies` later to resolve dependencies across all plans in bulk.
+
 ### 2. Define Phases
 
 Break into logical phases:
@@ -106,6 +126,11 @@ Before handing off to implementation:
 - [ ] Each task has micro acceptance (test name)
 - [ ] All edge cases mapped to tasks
 - [ ] Gaps flagged with `[needs-info]`
+- [ ] External dependencies documented in plan index
+
+## External Dependencies Section
+
+The plan index file must include an External Dependencies section. See **[dependencies.md](dependencies.md)** for the format, states, and how they affect implementation.
 
 ## Commit Frequently
 

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

@@ -71,9 +71,10 @@ This plan is managed via Backlog.md. Tasks are stored in the `backlog/` director
 
 **Implementation will**:
 1. Read this file to identify the plan
-2. Query backlog via MCP or read task files directly
-3. Work through tasks by status/priority
-4. Update task status as work completes
+2. Check External Dependencies below
+3. Query backlog via MCP or read task files directly
+4. Work through tasks by status/priority
+5. Update task status as work completes
 
 **To add tasks**: Run `backlog add "Task title"` or create task files directly.
 
@@ -86,8 +87,17 @@ Tasks are organized with labels/priorities:
 ## Key Decisions
 
 [Summary of key decisions from specification]
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {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).
+
 ### Task File Format
 
 Each task is a separate file: `backlog/task-{id} - {title}.md`
@@ -138,7 +148,68 @@ Specification reference: `docs/workflow/specification/{topic}.md` (for ambiguity
 | `priority` | Importance | high, medium, low |
 | `labels` | Categories | `[phase-1, api, edge-case, needs-info]` |
 | `assignee` | Who's working on it | (optional) |
-| `dependencies` | Blocking tasks | `[task-1, task-3]` |
+| `dependencies` | Blocking tasks (internal) | `[task-1, task-3]` |
+| `external_deps` | Cross-topic dependencies | `[billing-system#task-5]` |
+
+## Cross-Topic Dependencies
+
+Cross-topic dependencies link tasks between different plan topics. This is how you express "this task depends on the billing system being implemented."
+
+### In Task Frontmatter
+
+Use the `external_deps` field with the format `{topic}#{task-id}`:
+
+```yaml
+---
+status: To Do
+priority: high
+labels: [phase-1]
+external_deps: [billing-system#task-5, authentication#task-3]
+---
+```
+
+### In Plan Reference File
+
+The plan reference file at `docs/workflow/planning/{topic}.md` tracks external dependencies in a dedicated section (see template below).
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Find Tasks With External Dependencies
+
+```bash
+# Find all tasks with external dependencies
+grep -l "external_deps:" backlog/*.md
+
+# Find tasks depending on a specific topic
+grep -l "billing-system#" backlog/*.md
+```
+
+### Check Internal Dependencies
+
+```bash
+# Find tasks with dependencies
+grep -l "dependencies:" backlog/*.md
+
+# Show dependency values
+grep "dependencies:" backlog/*.md
+```
+
+### Check if a Dependency is Complete
+
+Read the task file and check the frontmatter:
+- `status: Done` means the dependency is met
+- Any other status means it's still blocking
+
+### Parse Frontmatter Programmatically
+
+For more complex queries, parse the YAML frontmatter:
+
+```bash
+# Extract frontmatter from a task file
+sed -n '/^---$/,/^---$/p' backlog/task-5*.md
+```
 
 ### Using `needs-info` Label
 

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

@@ -78,10 +78,13 @@ This creates `.beads/config.yaml` with the appropriate `no-db` setting.
 
 | Planning Concept | Beads Entity |
 |------------------|--------------|
-| Plan | Epic issue |
+| Specification/Topic | Epic issue |
 | Phase | Sub-issue under epic |
 | Task | Sub-task under phase |
-| Dependency | `bd dep add` relationship |
+| Internal dependency | `bd dep add` within same epic |
+| Cross-topic dependency | `bd dep add` across epics |
+
+Each specification topic becomes its own epic. All epics live in one beads database, enabling cross-topic dependencies.
 
 Example hierarchy:
 ```
@@ -91,8 +94,85 @@ bd-a3f8        (Epic: User Authentication)
 │   └── bd-a3f8.1.2  (Task: Session management)
 └── bd-a3f8.2  (Phase 2: OAuth)
     └── bd-a3f8.2.1  (Task: Google provider)
+
+bd-b7c2        (Epic: Billing System)  ← Different topic, same database
+├── bd-b7c2.1  (Phase 1: Invoicing)
+│   └── bd-b7c2.1.1  (Task: Invoice generation)
+```
+
+## Cross-Epic Dependencies
+
+Cross-topic dependencies link tasks between different epics (different specifications/topics). This is how you express "billing depends on authentication being complete."
+
+### Creating Cross-Epic Dependencies
+
+Use the same `bd dep add` command - it works across epics:
+
+```bash
+# Invoice generation (in billing epic) depends on user authentication (in auth epic)
+bd dep add bd-b7c2.1.1 bd-a3f8.1.1
+```
+
+After adding, `bd ready` will not show `bd-b7c2.1.1` until `bd-a3f8.1.1` is closed.
+
+### Viewing Cross-Epic Dependencies
+
+```bash
+# Show what a task depends on
+bd show bd-b7c2.1.1
+
+# Show what depends on a task
+bd show bd-a3f8.1.1 --deps
+```
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Find Ready Tasks (No Open Blockers)
+
+```bash
+bd ready
 ```
 
+Returns tasks with no incomplete dependencies - these are safe to implement.
+
+### Find All Tasks Blocked By a Specific Task
+
+```bash
+bd show bd-a3f8.1.1 --deps
+```
+
+Shows what will be unblocked when this task completes.
+
+### Find What a Task Depends On
+
+```bash
+bd show bd-b7c2.1.1
+```
+
+The output includes a "Blocked by" section listing dependencies.
+
+### Query Via JSONL (Advanced)
+
+For programmatic queries, read `.beads/issues.jsonl` directly:
+
+```bash
+# Find all dependencies (grep for blocked_by field)
+grep -o '"blocked_by":\[[^]]*\]' .beads/issues.jsonl
+
+# Find tasks depending on a specific ID
+grep '"bd-a3f8.1.1"' .beads/issues.jsonl | grep blocked_by
+```
+
+### Check if a Task is Complete
+
+```bash
+bd show bd-a3f8.1.1
+```
+
+Look for `status: closed` in the output. A dependency is "met" when the task is closed.
+
 ## Output Process
 
 ### 1. Create Epic for Plan
@@ -180,9 +260,10 @@ This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a d
 
 **Implementation will**:
 1. Read this file to identify the epic
-2. Query `bd ready` for unblocked tasks
-3. Work through tasks respecting dependencies
-4. Close tasks with `bd close bd-{id} "reason"`
+2. Check External Dependencies below
+3. Query `bd ready` for unblocked tasks
+4. Work through tasks respecting dependencies
+5. Close tasks with `bd close bd-{id} "reason"`
 
 ## Key Decisions
 
@@ -194,8 +275,17 @@ This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a d
 |-------|------|---------|
 | Phase 1 | {Goal} | bd-{id}.1 |
 | Phase 2 | {Goal} | bd-{id}.2 |
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {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).
+
 ## Frontmatter
 
 The `format: beads` frontmatter tells implementation to use beads CLI:

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

@@ -18,9 +18,52 @@ Ask the user: **Which team should own this project?**
 
 | Planning Concept | Linear Entity |
 |------------------|---------------|
-| Plan | Project |
+| Specification/Topic | Project |
 | Phase | Label (e.g., `phase-1`, `phase-2`) |
 | Task | Issue |
+| Internal dependency | Issue blocking relationship (within project) |
+| Cross-topic dependency | Issue blocking relationship (across projects) |
+
+Each specification topic becomes its own Linear project. Cross-topic dependencies link issues between projects.
+
+## Cross-Project Dependencies
+
+Cross-topic dependencies link issues between different Linear projects (different specifications/topics). This is how you express "billing depends on authentication being complete."
+
+### Creating Cross-Project Dependencies
+
+Linear supports blocking relationships between issues, even across projects. Via MCP or the Linear UI:
+
+1. Open the dependent issue (the one that's blocked)
+2. Add a "Blocked by" relationship to the issue in the other project
+3. Linear will show this issue as blocked until the dependency is complete
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Via MCP
+
+Query Linear for issues with blocking relationships:
+
+```
+# Get all issues in a project
+linear_getIssues(projectId: "{project_id}")
+
+# Check if an issue has blockers
+linear_getIssue(issueId: "{issue_id}")
+# Look for blockedByIssues in the response
+```
+
+### Check if a Dependency is Complete
+
+Query the blocking issue and check its state:
+- `state.type === "completed"` means the dependency is met
+- Any other state means it's still blocking
+
+### Find Issues Blocked by a Specific Issue
+
+Via the Linear API or MCP, query for issues where `blockedByIssues` contains the issue ID.
 
 ## Output Process
 
@@ -125,17 +168,27 @@ This plan is managed in Linear. The source of truth for tasks and progress is th
 
 **Implementation will**:
 1. Read this file to find the Linear project
-2. Query Linear for project issues
-3. Work through tasks in phase order (by label)
-4. Update issue status as tasks complete
+2. Check External Dependencies below
+3. Query Linear for project issues
+4. Work through tasks in phase order (by label)
+5. Update issue status as tasks complete
 
 **To add tasks**: Create issues in the Linear project. They'll be picked up automatically.
 
 ## Key Decisions
 
 [Summary of key decisions from specification - for quick reference]
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {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).
+
 ## Frontmatter
 
 The frontmatter contains all information needed to query Linear:

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

@@ -124,11 +124,18 @@ Map edge cases from specification to specific tasks:
 
 Tables, schemas, API contracts
 
-## Dependencies
+## Internal Dependencies
 
 - Prerequisites for Phase 1
-- Phase dependencies
-- External blockers
+- Phase dependencies (Phase 2 depends on Phase 1, etc.)
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {topic}: {description} → {task-reference} (resolved)
+- ~~{topic}: {description}~~ → satisfied externally
 
 ## Rollback (if applicable)
 
@@ -141,6 +148,67 @@ Triggers and steps
 | YYYY-MM-DD | Created from specification |
 ```
 
+## Cross-Topic Dependencies
+
+Cross-topic dependencies link tasks between different plan files. This is how you express "this feature depends on the billing system being implemented."
+
+### In the External Dependencies Section
+
+Use the format `{topic}: {description} → {task-reference}` where task-reference points to a specific task in another plan file:
+
+```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)
+- 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
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Find Plans With External Dependencies
+
+```bash
+# Find all plans with external dependencies
+grep -l "## External Dependencies" docs/workflow/planning/*.md
+
+# Find unresolved dependencies (no arrow →)
+grep -A 10 "## External Dependencies" docs/workflow/planning/*.md | grep "^- " | grep -v "→"
+```
+
+### Find Dependencies on a Specific Topic
+
+```bash
+# Find plans that depend on billing-system
+grep -l "billing-system:" docs/workflow/planning/*.md
+```
+
+### Check if a Dependency Task Exists
+
+Read the referenced plan file and verify the task exists:
+
+```bash
+# Check if a task exists in another plan
+grep "Phase 1.*Task 2" docs/workflow/planning/billing-system.md
+```
+
+### Check if a Dependency is Complete
+
+For local markdown, check if the task's acceptance criteria are checked off:
+
+```bash
+# Look for completed acceptance criteria
+grep -A 5 "### Phase 1" docs/workflow/planning/billing-system.md | grep "\[x\]"
+```
+
 ## Frontmatter
 
 The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file.