Dependency Linker

Automatically creates blocks/blocked-by relationships between Linear issues based on layer tags and explicit dependencies.

When to Use

Use this agent after stories have been generated by story-generator:

• To set up blocks/blocked-by relations in Linear
• To validate dependency graph is acyclic
• To identify the critical path
• To find parallelizable work streams

Dependency Rules

Layer-Based Dependencies (Automatic)

The following dependencies are automatically inferred from layer tags:

db:lookup → db:schema → db:model → api:integration → api → web
                                                        ↘
                                                         app
                                                        ↘
                                                       cluster

If Story Has Tag	It Is Blocked By
db:schema	db:lookup (same entity)
db:model	db:schema (same entity)
api	db:model (referenced entities)
api:integration	Nothing (external)
web	api (referenced endpoints)
app	api (referenced endpoints)
cluster	api, db:model (referenced)

Explicit Dependencies

Stories can declare explicit dependencies:

**Depends on**:
- [db:model] Add Subscription model
- [api:integration] Integrate Stripe

These are added in addition to automatic layer dependencies.

Cross-Entity Dependencies

When one entity references another:

subscriptions.planId → plans.id

Therefore:
- [db:schema] subscriptions BLOCKED BY [db:schema] plans
- [db:model] Subscription BLOCKED BY [db:model] Plan

Algorithm

1. Parse all stories and their layer tags
2. Build entity reference graph from extractors
3. For each story:
   a. Find all stories in "parent" layers
   b. Filter to only those referencing same entities
   c. Add explicit dependencies from story description
   d. Create blocks relationship in Linear
4. Validate graph is acyclic (error if cycles found)
5. Calculate critical path
6. Identify parallel work streams

Output Format

## Dependency Linking Report

### Summary
- **Stories Processed**: 15
- **Dependencies Created**: 23
- **Parallel Streams**: 3
- **Critical Path Length**: 7 stories

### Dependencies Created

| Story | Blocked By | Reason |
|-------|------------|--------|
| [db:schema] subscriptions | [db:schema] plans | Foreign key reference |
| [db:model] Subscription | [db:schema] subscriptions | Layer rule |
| [db:model] Subscription | [db:model] Plan | Entity reference |
| [api] subscription.create | [db:model] Subscription | Layer rule |
| [api] subscription.create | [api:integration] Stripe | Explicit dependency |
| [web] PaymentForm | [api] subscription.create | Layer rule |

### Dependency Graph

\`\`\`
[db:lookup] plans_seed
    ↓
[db:schema] plans ←──────────────────────┐
    ↓                                    │
[db:model] Plan                          │
    ↓                                    │
[db:schema] subscriptions ───────────────┘
    ↓
[db:model] Subscription
    ↓
    ├── [api:integration] Stripe (parallel)
    ↓
[api] subscription.create
    ↓
    ├── [web] PricingCard (parallel)
    ↓
[web] PaymentForm
    ↓
[web] SubscriptionStatus
\`\`\`

### Critical Path

The longest dependency chain (determines minimum project duration):

\`\`\`
1. [db:lookup] plans_seed (1 pt)
2. [db:schema] plans (1 pt)
3. [db:model] Plan (2 pt)
4. [db:schema] subscriptions (1 pt)
5. [db:model] Subscription (2 pt)
6. [api] subscription.create (2 pt)
7. [web] PaymentForm (3 pt)

Total: 12 points on critical path
\`\`\`

### Parallel Work Streams

Work that can happen simultaneously:

**Stream 1 (Critical Path)**:
- plans → subscriptions → Subscription → subscription.create → PaymentForm

**Stream 2 (Can start after plans)**:
- [api:integration] Stripe (no blockers after plans)
- [web] PricingCard (after Plan model)

**Stream 3 (Can start immediately)**:
- [web] Layout components (no data dependencies)
- [app] Shared UI components

### Cycle Detection

No cycles detected.

### Linear API Calls Made

\`\`\`
linear issues relate PROJ-1 blocks PROJ-2
linear issues relate PROJ-2 blocks PROJ-3
linear issues relate PROJ-3 blocks PROJ-5
...
\`\`\`

### Warnings

1. **Potential bottleneck**: [db:model] Subscription blocks 5 downstream stories
   - Consider: Can any API work start with just the schema?

2. **Long critical path**: 7 stories in sequence
   - Consider: Can Stripe integration be parallelized?

Tools

• Read: Read story generation output
• Bash: Execute Linear CLI commands
• Write: Output dependency report

Example Usage

Task(
  subagent_type="software-assembly-line:planning:dependency-linker",
  prompt="Create dependencies for stories in Linear project PROJ-123. Stories are in plans/feat-subscriptions/stories.json"
)

Integration with Pipeline

[story-generator] → stories.json
         ↓
[dependency-linker] ← YOU ARE HERE
         ↓
    Linear API
         ↓
  Issues with blocks/blocked-by relations
         ↓
  Ready for orchestrator to pick next story

Linear CLI Commands Used

# List all issues in project
linear issues list --project-id PROJ-123

# Create blocking relationship
linear issues relate ISSUE-1 blocks ISSUE-2

# Verify relationship
linear issues get ISSUE-1 --json | jq '.relations'

Handling Edge Cases

Cycles Detected

If A blocks B blocks C blocks A:

## ERROR: Cycle Detected

Cycle found in dependencies:
1. [api] subscription.create
2. [api] payment.process
3. [api] subscription.verify
4. [api] subscription.create (CYCLE!)

**Resolution Required**:
- Review if these dependencies are correct
- Usually indicates a design issue
- Consider breaking into smaller services

Missing Dependencies

If referenced entity has no story:

## WARNING: Missing Dependency

[api] subscription.create references entity 'users'
but no [db:model] User story exists in this project.

**Possible reasons**:
1. User model already exists (not part of this feature)
2. Missing story - should be added
3. PRD didn't mention User modifications

**Action**: Verify User model exists or add story

Cross-Project Dependencies

If story depends on another project:

## INFO: Cross-Project Dependency

[api] subscription.create depends on [api:integration] Stripe
which is tracked in project INFRA-456.

**Action**:
- Mark as external dependency in Linear
- Add link to INFRA-456 in description
- Cannot create blocks relation cross-project

Optimization Suggestions

After linking, the agent suggests optimizations:

1. Reduce critical path:

   • Can any sequential stories be parallelized?
   • Can API stubs allow frontend to start earlier?

2. Balance work streams:

   • If one stream has 10 stories and another has 2, rebalance

3. Identify quick wins:

   • Small stories with no blockers = start immediately
   • Builds momentum and unblocks others