Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
What Are Relationships?

Relationships are the connective tissue in sudocode’s context graph. They create typed, bidirectional links between specs and issues, enabling graph-based planning, dependency resolution, and intelligent work ordering.
Key Principle: Relationships model how entities connect - what blocks what, what implements what, and how context flows through your project.
A relationship is a directional, typed connection between two entities (specs or issues). Every relationship has:
  • From entity - The source (e.g., ISSUE-001)
  • To entity - The target (e.g., SPEC-001)
  • Relationship type - What kind of connection (e.g., implements)
Relationships are bidirectional - sudocode automatically tracks both directions, so you can traverse the graph from either end.

​
Relationship Types

sudocode supports six relationship types, each with specific semantics:

blocks

Hard blocker dependencyFrom entity cannot proceed until To entity is complete

implements

Implementation linkIssue implements requirements from a spec

depends-on

Soft dependencyFrom entity needs To entity but not a hard blocker

references

General referenceContextual link without specific semantics

related

AssociationEntities share context or are related

discovered-from

Discovery trackingIssue was discovered while working on another issue

​
Detailed Relationship Semantics

Direction: From → To (“From blocks To”)Meaning: To entity cannot start or complete until From entity is done.Use cases:
  • Sequential implementation tasks
  • Dependencies between infrastructure and features
  • Prerequisites that must be satisfied first
Example:
# ISSUE-002 cannot start until ISSUE-001 is complete
sudocode link ISSUE-001 ISSUE-002 --type blocks
Graph behavior:
  • Blocked entities won’t appear in sudocode ready query
  • Topological sorting uses blocks for execution order
  • Status of blocker affects what’s ready
Direction: From → To (“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
Direction: From → To (“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
Direction: New Issue → Source Issue (“New was discovered from Source”)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

​
Creating Relationships

​
Using the CLI

The link command creates relationships between entities: 
sudocode link <from-id> <to-id> --type <relationship-type>
Examples: 
# Block a task until prerequisite is done
sudocode link ISSUE-001 ISSUE-002 --type blocks

# Link issue to spec it implements
sudocode link ISSUE-003 SPEC-001 --type implements

# Create soft dependency
sudocode link ISSUE-004 SPEC-002 --type depends-on

# General reference
sudocode link SPEC-001 SPEC-010 --type references

# Mark related work
sudocode link ISSUE-005 ISSUE-006 --type related

# Track discovery
sudocode link ISSUE-020 ISSUE-015 --type discovered-from
sudocode automatically determines entity types (spec or issue) by checking which exists in your database.

​
Using Markdown Syntax

You can embed relationships directly in markdown using extended Obsidian-style syntax: 
See [[SPEC-010]] for API design patterns.

This implements [[@ISSUE-001]] and [[@ISSUE-002]].
Syntax Rules:
  • [[ID]] - Basic reference (defaults to references type)
  • [[ID|Display Text]] - Reference with custom display text
  • [[ID]]{ type } - Reference with relationship type (shorthand)
  • [[ID]]{ type: typename } - Reference with relationship type (explicit)
  • [[ID|Display]]{ type } - Combination of display text and type
When you use this syntax in markdown files, sudocode automatically creates the corresponding relationships in the database when syncing.

​
Hierarchical Relationships

While not a relationship type in the table, specs and issues support parent-child hierarchies through the parent_id field:

​
For Specs

# Create parent spec
sudocode spec create "Authentication System" --priority 0

# Create child specs
sudocode spec create "OAuth 2.0" --parent SPEC-001
sudocode spec create "Session Management" --parent SPEC-001

​
For Issues

# Create epic
sudocode issue create "Build Auth System" --priority 0

# Create subtasks
sudocode issue create "Implement login" --parent ISSUE-001
sudocode issue create "Implement logout" --parent ISSUE-001
Parent-child relationships are stored directly in the parent_id field, not in the relationships table. This enables efficient tree traversal and hierarchical queries.

​
Bidirectional Tracking

All relationships are automatically tracked in both directions: 
# Create a relationship
sudocode link ISSUE-001 SPEC-001 --type implements
Now you can query from either direction: 
# From the issue: what does this implement?
sudocode issue show ISSUE-001
# Shows: implements → SPEC-001

# From the spec: what implements this?
sudocode spec show SPEC-001
# Shows: implemented by ← ISSUE-001
This bidirectional tracking 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?

​
Graph-Based Planning

Relationships enable sudocode’s graph-based planning and execution:

​
Topological Ordering

The ready command uses blocks relationships to determine execution order: 
sudocode ready
# Returns: ISSUE-001 (no blockers)
After ISSUE-001 closes: 
sudocode ready
# Returns: ISSUE-002, ISSUE-003 (blockers removed)

​
Finding Blocked Work

# See what's blocked and why
sudocode blocked

# Output:
# ISSUE-002 blocked by:
#   - ISSUE-001 (in_progress)
#
# ISSUE-004 blocked by:
#   - ISSUE-002 (blocked)
#   - ISSUE-003 (open)

​
Dependency Chains

Relationships create dependency chains that agents can traverse: 
SPEC-001 (Auth System)
  ← implements ← ISSUE-001 (Login endpoint)
  ← implements ← ISSUE-002 (Registration endpoint)
                    ↑ blocks ↑
                 ISSUE-001
Agents can:
  • Start with a spec
  • Find unblocked issues that implement it
  • Work through issues in topological order
  • Provide feedback back to the spec

​
Viewing Relationships

​
In Entity Details

# View issue relationships
sudocode issue show ISSUE-001

# Output includes:
# Relationships:
#   implements → SPEC-001 (Auth System)
#   blocks → ISSUE-002 (Registration endpoint)
#   related → ISSUE-005 (Password reset)

​
In Graph Form

# View spec with implementation graph
sudocode spec show SPEC-001

# Output includes:
# Implemented by:
#   - ISSUE-001: Login endpoint
#   - ISSUE-002: Registration endpoint (blocked)
#   - ISSUE-003: Password reset

​
Best Practices

​
Choosing the Right Relationship Type

1

Is it a hard blocker?

Use blocks if From must complete before To can proceed
2

Is it implementing requirements?

Use implements for issue → spec implementation links
3

Is it informational context?

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

Is it associative?

Use related for bidirectional associations without specific semantics
5

Was it discovered during work?

Use discovered-from to track issue genealogy

​
Modeling Dependencies Effectively

# Clear sequential dependencies
sudocode link ISSUE-001 ISSUE-002 --type blocks  # DB schema blocks API
sudocode link ISSUE-002 ISSUE-003 --type blocks  # API blocks UI

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

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

# 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

​
Using Relationships for Multi-Agent Workflows

1

Model clear dependencies

Use blocks to prevent agents from working on blocked tasks
2

Link issues to specs

Use implements so agents can read requirements
3

Track discovered work

Use discovered-from when agents find new issues during implementation
4

Query ready work

Agents use sudocode ready to find unblocked, high-priority work

​
CLI Commands

Quick reference for relationship commands: 
# Create relationship
sudocode link <from> <to> --type <type>

# View entity relationships
sudocode spec show <spec-id>
sudocode issue show <issue-id>

# Find ready work (respects blocks)
sudocode ready

# Find blocked work
sudocode blocked

# Create hierarchical relationships
sudocode spec create "Child" --parent SPEC-001
sudocode issue create "Subtask" --parent ISSUE-001

Link Command Reference

See complete documentation for the link command

​
Database Schema

For reference, here’s how relationships are stored: 
CREATE TABLE relationships (
    from_id TEXT NOT NULL,           -- Source entity ID
    from_type TEXT NOT NULL,         -- 'spec' | 'issue'
    to_id TEXT NOT NULL,             -- Target entity ID
    to_type TEXT NOT NULL,           -- 'spec' | 'issue'
    relationship_type TEXT NOT NULL, -- Type of relationship
    created_at DATETIME NOT NULL,    -- When created
    metadata TEXT,                   -- Optional JSON metadata
    PRIMARY KEY (from_id, from_type, to_id, to_type, relationship_type)
);
The composite primary key ensures:
  • No duplicate relationships
  • Same entities can have multiple relationship types
  • Efficient bidirectional queries

​
Next Steps

Specs

Learn about specs - high-level requirements that issues implement

Issues

Learn about issues - actionable work items that can be linked

Feedback System

Provide anchored feedback from issues back to specs

Link Command

Complete CLI reference for the link command