sudocode link - sudocode

Syntax

sudocode link <from-id> <to-id> --type <relationship-type>

Description

The link command creates a typed relationship between two entities (specs or issues). Relationships are:

Typed - Each relationship has a specific meaning (blocks, implements, depends-on, etc.)
Bidirectional - Automatically tracked in both directions for graph traversal
Permanent - Persist across updates to entity properties
Graph-enabling - Power dependency resolution, planning, and visualization

Relationships are the foundation of sudocode’s graph-based planning system.

sudocode automatically detects entity types (spec or issue) by checking which exists in the database. You don’t need to specify types explicitly.

Arguments

string

required

Source entity IDExample: ISSUE-001 or SPEC-001The entity creating the relationship. sudocode automatically determines if this is a spec or issue.

string

required

Target entity IDExample: SPEC-001 or ISSUE-002The entity being referenced. sudocode automatically determines if this is a spec or issue.

Options

string

required

Relationship typeExample: --type implementsValid relationship types:

blocks - Hard blocker dependency
implements - Issue implements spec
depends-on - Soft dependency
references - General reference
related - General association
discovered-from - Issue discovered during implementation

See Relationship Types section for detailed explanations.

Relationship Types

blocks

Direction: FROM blocks TO Meaning: TO entity cannot proceed until FROM entity is complete. Use cases:

Sequential implementation tasks
Hard dependencies between features
Prerequisites that must be satisfied first

Example:

# ISSUE-002 cannot start until ISSUE-001 is done
sudocode link ISSUE-001 ISSUE-002 --type blocks

Graph behavior:

Blocked entities won’t appear in sudocode ready
Topological sorting uses blocks for execution order
Status of blocker affects what’s ready to work on

Example scenario

# Database schema must be done before API endpoints
sudocode link ISSUE-001 ISSUE-002 --type blocks
# Frontend can't proceed until API is done
sudocode link ISSUE-002 ISSUE-003 --type blocks

# Now ISSUE-001 is ready, but ISSUE-002 and ISSUE-003 are blocked
sudocode ready
# Returns: ISSUE-001

# After closing ISSUE-001, ISSUE-002 becomes ready
sudocode issue close ISSUE-001
sudocode ready
# Returns: ISSUE-002

implements

Direction: Issue → Spec Meaning: The issue implements requirements or design from the spec. Use cases:

Linking implementation tasks to requirements
Tracing code changes back to specs
Understanding what’s been implemented

Example:

# ISSUE-001 implements SPEC-001
sudocode link ISSUE-001 SPEC-001 --type implements

Graph behavior:

Specs show which issues implement them
Issues show which specs they fulfill
Enables traceability from requirement to implementation

Example scenario

# Create a spec
sudocode spec create "Authentication System" --priority 1

# Create implementation issues
sudocode issue create "Implement login endpoint"
sudocode issue create "Implement registration endpoint"

# Link issues to spec
sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-002 SPEC-001 --type implements

# Now SPEC-001 shows both issues implement it
sudocode spec show SPEC-001
# Incoming Relationships:
#   ISSUE-001 → implements
#   ISSUE-002 → implements

depends-on

Direction: FROM depends on TO Meaning: FROM entity needs context/output from TO entity, but it’s not a hard blocker. Use cases:

Informational dependencies
Context that should be read but doesn’t block work
Related work that informs implementation

Example:

# ISSUE-003 depends on SPEC-002 for guidance
sudocode link ISSUE-003 SPEC-002 --type depends-on

Graph behavior:

Doesn’t block execution (entity still appears in ready queue)
Provides context for agents working on the issue
Can be used for soft ordering hints

Example scenario

# Frontend issue depends on API spec for context, but can start work
sudocode link ISSUE-005 SPEC-010 --type depends-on

# ISSUE-005 is still ready (not blocked)
sudocode ready
# Returns: ISSUE-005 (even though it depends on SPEC-010)

# Agent can read SPEC-010 for guidance while implementing ISSUE-005

references

Direction: FROM references TO Meaning: General contextual link without specific blocking or implementation semantics. Use cases:

Cross-referencing related entities
Creating links between documentation
Default type for [[ID]] syntax without explicit type

Example:

# SPEC-001 references SPEC-010 for context
sudocode link SPEC-001 SPEC-010 --type references

Graph behavior:

No blocking or ordering implications
Purely for navigation and context
Automatic type for cross-references without explicit type

Example scenario

# Authentication spec references API design patterns
sudocode link SPEC-001 SPEC-010 --type references

# Issue references another related issue for context
sudocode link ISSUE-005 ISSUE-020 --type references

# Helps developers understand related work and context

Direction: Bidirectional (FROM and TO are related) Meaning: Entities share context or are associated without a specific directional relationship. Use cases:

Parallel work on related features
Entities in the same domain
Context grouping without direction

Example:

# ISSUE-005 and ISSUE-006 are related (both auth work)
sudocode link ISSUE-005 ISSUE-006 --type related

Graph behavior:

No blocking or ordering
Useful for finding peripheral context
Can group related work for visualization

Example scenario

# Two issues working on related authentication features
sudocode link ISSUE-010 ISSUE-011 --type related

# Specs covering related architectural domains
sudocode link SPEC-005 SPEC-006 --type related

# Helps discover related work in same area

discovered-from

Direction: New Issue → Source Issue Meaning: A new issue was discovered while working on another issue. Use cases:

Tracking scope creep
Understanding how issues spawn new work
Tracing problem discovery during implementation

Example:

# ISSUE-010 was discovered while working on ISSUE-005
sudocode link ISSUE-010 ISSUE-005 --type discovered-from

Graph behavior:

Shows issue genealogy
Helps understand how work expands
Can identify issues that frequently spawn new issues

Example scenario

# While implementing login, discover password reset is also needed
sudocode issue create "Add password reset flow"
sudocode link ISSUE-010 ISSUE-005 --type discovered-from

# Shows ISSUE-010 was discovered from ISSUE-005
sudocode issue show ISSUE-010
# Outgoing Relationships:
#   discovered-from → ISSUE-005

Examples

Basic Link Creation

Create a simple relationship:

sudocode link ISSUE-001 SPEC-001 --type implements

Expected output

✓ Created relationship
ISSUE-001 implements → SPEC-001

Block an Issue

Prevent work until dependency is done:

sudocode link ISSUE-001 ISSUE-002 --type blocks

Expected output

✓ Created relationship
ISSUE-001 blocks → ISSUE-002

Interpretation: ISSUE-002 is blocked by ISSUE-001. ISSUE-002 cannot proceed until ISSUE-001 is closed.

Link Multiple Issues to a Spec

Connect implementation tasks to requirements:

sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-002 SPEC-001 --type implements
sudocode link ISSUE-003 SPEC-001 --type implements

Expected output

✓ Created relationship
ISSUE-001 implements → SPEC-001
✓ Created relationship
ISSUE-002 implements → SPEC-001
✓ Created relationship
ISSUE-003 implements → SPEC-001

Create Dependency Chain

Model sequential dependencies:

# Database schema first
sudocode link ISSUE-001 ISSUE-002 --type blocks

# Then API endpoints
sudocode link ISSUE-002 ISSUE-003 --type blocks

# Then frontend

This creates: ISSUE-001 → ISSUE-002 → ISSUE-003

Cross-Reference Specs

Link related specifications:

sudocode link SPEC-001 SPEC-010 --type references

Expected output

✓ Created relationship
SPEC-001 references → SPEC-010

Track Issue Discovery

Document when issues are discovered:

sudocode link ISSUE-020 ISSUE-015 --type discovered-from

Expected output

✓ Created relationship
ISSUE-020 discovered-from → ISSUE-015

JSON Output

Get machine-readable output:

sudocode --json link ISSUE-001 SPEC-001 --type implements

JSON output

{
  "from": "ISSUE-001",
  "to": "SPEC-001",
  "type": "implements",
  "success": true
}

Viewing Relationships

After creating relationships, view them with show commands:

# View issue relationships
sudocode issue show ISSUE-001

# View spec relationships
sudocode spec show SPEC-001

The output includes:

Outgoing Relationships - From this entity to others
Incoming Relationships - From others to this entity

Choosing the Right Relationship Type

Use this decision matrix:

Is it a hard blocker?

Use blocks if FROM must complete before TO can proceed

Is it implementing requirements?

Use implements for issue → spec implementation links

Is it informational context?

Use depends-on for soft dependencies or references for general links

Is it associative?

Use related for bidirectional associations without specific semantics

Was it discovered during work?

Use discovered-from to track issue genealogy

Common Workflows

Spec-Driven Development

Create a spec

sudocode spec create "User Dashboard" --priority 1

Create implementation issues

sudocode issue create "Build dashboard layout"
sudocode issue create "Add data visualizations"
sudocode issue create "Implement filters"

Link issues to spec

sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-002 SPEC-001 --type implements
sudocode link ISSUE-003 SPEC-001 --type implements

Model dependencies

# Layout must be done before visualizations
sudocode link ISSUE-001 ISSUE-002 --type blocks

Modeling Complex Dependencies

Create all issues

sudocode issue create "Database schema"      # ISSUE-001
sudocode issue create "API endpoints"        # ISSUE-002
sudocode issue create "Frontend components"  # ISSUE-003
sudocode issue create "Integration tests"    # ISSUE-004

Model blockers

sudocode link ISSUE-001 ISSUE-002 --type blocks
sudocode link ISSUE-002 ISSUE-003 --type blocks
sudocode link ISSUE-003 ISSUE-004 --type blocks

Find ready work

sudocode ready
# Returns: ISSUE-001 (only unblocked issue)

Discovering and Linking New Work

Start work on issue

sudocode issue update ISSUE-005 --status in_progress

Discover new requirement

While implementing, realize password reset is needed

Create new issue

sudocode issue create "Add password reset flow"

Link as discovered

sudocode link ISSUE-010 ISSUE-005 --type discovered-from

Relationship Best Practices

✅ Good relationship modeling

# Clear sequential dependencies
sudocode link ISSUE-001 ISSUE-002 --type blocks

# Implementation links to specs
sudocode link ISSUE-001 SPEC-001 --type implements

# Soft context dependencies
sudocode link ISSUE-005 SPEC-002 --type depends-on

❌ Avoid these patterns

# Don't create circular dependencies
sudocode link ISSUE-001 ISSUE-002 --type blocks
sudocode link ISSUE-002 ISSUE-001 --type blocks  # ❌ Circular!

# Don't use 'blocks' for soft context
sudocode link ISSUE-003 SPEC-005 --type blocks  # ❌ Use depends-on

# Don't over-link everything as 'related'
# Only link when there's actual shared context

Understanding Bidirectional Tracking

All relationships are automatically tracked in both directions:

# Create a relationship
sudocode link ISSUE-001 SPEC-001 --type implements

From ISSUE-001 perspective:

sudocode issue show ISSUE-001
# Outgoing Relationships:
#   implements → SPEC-001 (spec)

From SPEC-001 perspective:

sudocode spec show SPEC-001
# Incoming Relationships:
#   ISSUE-001 (issue) → implements

This enables:

Forward traversal - What does this entity depend on/reference?
Backward traversal - What depends on/references this entity?
Graph queries - Find all connected entities
Impact analysis - What’s affected if this changes?

Common Questions

Can I create multiple relationships between the same entities?

Yes! Entities can have multiple relationship types between them:

sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-001 SPEC-001 --type depends-on

Both relationships are tracked independently.

What's the difference between 'blocks' and 'depends-on'?

blocks - Hard dependency, prevents work from starting (affects ready query)
depends-on - Soft dependency, provides context but doesn’t prevent work

Use blocks for technical prerequisites, depends-on for informational context.

Can I link a spec to another spec?

Yes! All relationship types work between any entities:

sudocode link SPEC-001 SPEC-010 --type references
sudocode link SPEC-005 SPEC-006 --type related

How do I remove a relationship?

There’s currently no unlink command in the CLI. To remove relationships:

Edit the JSONL file directly
Run sudocode sync to update the database
Or update the database directly using SQL

Can I create a relationship to a non-existent entity?

No, sudocode validates that both entities exist before creating the relationship. You’ll get an error if either ID doesn’t exist.

What happens to relationships when I delete an entity?

Relationships are not automatically deleted. They become orphaned, which can cause broken links. Best practice: clean up relationships before deleting entities.

Troubleshooting

Error: Entity not found

Cause: One or both entity IDs don’t existSolution: Verify both IDs exist:

sudocode spec list
sudocode issue list

Error: Invalid relationship type

Cause: The relationship type isn’t validSolution: Use one of: blocks, implements, depends-on, references, related, discovered-from

sudocode link ISSUE-001 SPEC-001 --type implements

Relationship created but doesn't appear in show

Cause: Sync or cache issueSolution: Run sync:

sudocode sync
sudocode issue show ISSUE-001

Circular dependency warning

Cause: Created circular blocks relationshipsSolution: Review your dependency chain. Use depends-on for soft dependencies that don’t need strict ordering.

spec show

View spec relationships

issue show

View issue relationships

ready

Find unblocked work

blocked

View blocked issues

add-ref

Add inline references

Next Steps

Create entities

sudocode spec create "My Feature"
sudocode issue create "Implement X"

Link them

sudocode link ISSUE-001 SPEC-001 --type implements

View relationships

sudocode spec show SPEC-001
sudocode issue show ISSUE-001

Find ready work

sudocode ready

Relationships Concept Guide

Learn more about relationships and graph-based planning

​Syntax

​Description

​Arguments

​Options

​Relationship Types

​blocks

​implements

​depends-on

​references

​related

​discovered-from

​Examples

​Basic Link Creation

​Block an Issue

​Link Multiple Issues to a Spec

​Create Dependency Chain

​Cross-Reference Specs

​Track Issue Discovery

​JSON Output

​Viewing Relationships

​Choosing the Right Relationship Type

​Common Workflows

​Spec-Driven Development

​Modeling Complex Dependencies

​Discovering and Linking New Work

​Relationship Best Practices

​Understanding Bidirectional Tracking

​Common Questions

​Troubleshooting

​Related Commands

spec show

issue show

ready

blocked

add-ref

​Next Steps

Relationships Concept Guide

Syntax

Description

Arguments

Options

Relationship Types

blocks

implements

depends-on

references

related

discovered-from

Examples

Basic Link Creation

Block an Issue

Link Multiple Issues to a Spec

Create Dependency Chain

Cross-Reference Specs

Track Issue Discovery

JSON Output

Viewing Relationships

Choosing the Right Relationship Type

Common Workflows

Spec-Driven Development

Modeling Complex Dependencies

Discovering and Linking New Work

Relationship Best Practices

Understanding Bidirectional Tracking

Common Questions

Troubleshooting

Related Commands

Next Steps