link-dependencies

name	link-dependencies
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.
disable-model-invocation	true
hooks	{"PreToolUse":[{"hooks":[{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh","once":true}]}]}

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 .workflows/planning/

   • Run ls .workflows/planning/ to list plan files
   • Each topic is a directory containing plan.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:

Output the next fenced block as a code block:

Dependency Linking

No plans found in .workflows/planning/

There are no plans to link. Create plans first.

STOP. Do not proceed — terminal condition.

If only one plan exists:

Output the next fenced block as a code block:

Dependency Linking

Only one plan found: {topic}

Cross-topic dependency linking requires at least two plans.

STOP. Do not proceed — terminal condition.

Step 2: Check Output Format Consistency

Compare the format: field across all discovered plans.

If plans use different output formats:

Output the next fenced block as a code block:

Dependency Linking

Mixed output formats detected:

  • {topic} ({format})
  • ...

Cross-topic dependencies can only be wired within the same output
format. Consolidate your plans to a single format before linking.

STOP. Do not proceed — terminal condition.

Step 3: Extract External Dependencies

For each plan, read the external_dependencies field from the frontmatter:

1. Read external_dependencies from each plan index file's frontmatter

2. Categorize each dependency by its state field:

   • Unresolved: state: unresolved (no task linked)
   • Resolved: state: resolved (has task_id)
   • Satisfied externally: state: satisfied_externally

3. Build a summary:

Output the next fenced block as a code block:

Dependency Summary

{N} plans found. {M} unresolved dependencies.

Plan: {topic:(titlecase)} (format: {format})
  • {dependency}: {description} ({state:[unresolved|resolved|satisfied externally]})

Plan: ...

Output the next fenced block as a code block:

Key:

  Dependency state:
    unresolved           — no task linked yet
    resolved             — linked to a task in another plan
    satisfied externally — implemented outside this workflow

Step 4: Match Dependencies to Plans

For each unresolved dependency:

1. Search for matching plan: Does .workflows/planning/{dependency-topic}/plan.md exist?

   • If no match: Mark as "no plan exists" - cannot resolve yet

2. If plan exists: Load the format's reading reference

   • Read format: from the dependency plan's frontmatter
   • Load ../technical-planning/references/output-formats/{format}/reading.md
   • Use the task extraction instructions 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's frontmatter:

   • Change the dependency's state: unresolved to state: resolved and add task_id: {task-id}

2. Create dependency in output format:

   • Load ../technical-planning/references/output-formats/{format}/graph.md
   • Follow the "Adding a Dependency" 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 frontmatter?"

Step 7: Report Results

Present a summary:

Output the next fenced block as a code block:

Dependency Linking Complete

Resolved (newly linked):
  • {source} → {target}: {task-id} ({description})

Already resolved (no action needed):
  • {source} → {target}: {task-id}

Satisfied externally (no action needed):
  • {source} → {target}

Unresolved (no matching plan exists):
  • {source} → {target}: {description}

Updated files:
  • .workflows/planning/{topic}/plan.md

If any dependencies remain unresolved:

Output the next fenced block as a code block:

Unresolved dependencies have no corresponding plan. Either:
  • Create a plan for the topic
  • Mark as "satisfied externally" if already implemented

Step 8: Commit Changes

If any files were updated:

Output the next fenced block as markdown (not a code block):

· · · · · · · · · · · ·
Shall I commit these dependency updates?
- **`y`/`yes`** — Commit the changes
- **`n`/`no`** — Skip
· · · · · · · · · · · ·

STOP. Wait for user response.

If yes, commit with message:

Link cross-topic dependencies

- {summary of what was linked}