Relationships

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

AssociationEntities share context or are related

discovered-from

Discovery trackingIssue was discovered while working on another issue

Detailed Relationship Semantics

blocks - Hard Blocker

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

implements - Implementation Link

Direction: Issue → Spec (“Issue implements 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

depends-on - Soft Dependency

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

references - General Reference

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

related - Association

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

discovered-from - Discovery Tracking

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

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

Modeling Dependencies Effectively

✅ Good dependency modeling

# 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

❌ 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

Using Relationships for Multi-Agent Workflows

Model clear dependencies

Use blocks to prevent agents from working on blocked tasks

Link issues to specs

Use implements so agents can read requirements

Track discovered work

Use discovered-from when agents find new issues during implementation

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

Getting Started

Core Concepts

Examples & Tutorials

What Are Relationships?

Relationship Types

blocks

implements

depends-on

references

related

discovered-from

Detailed Relationship Semantics

Creating Relationships

Using the CLI

Using Markdown Syntax

Hierarchical Relationships

For Specs

For Issues

Bidirectional Tracking

Graph-Based Planning

Topological Ordering

Finding Blocked Work

Dependency Chains

Viewing Relationships

In Entity Details

In Graph Form

Best Practices

Choosing the Right Relationship Type

Modeling Dependencies Effectively

Using Relationships for Multi-Agent Workflows

CLI Commands

Link Command Reference

Database Schema

Next Steps

Specs

Issues

Feedback System

Link Command

Getting Started

Core Concepts

Examples & Tutorials

​What Are Relationships?

​Relationship Types

blocks

implements

depends-on

references

related

discovered-from

​Detailed Relationship Semantics

​Creating Relationships

​Using the CLI

​Using Markdown Syntax

​Hierarchical Relationships

​For Specs

​For Issues

​Bidirectional Tracking

​Graph-Based Planning

​Topological Ordering

​Finding Blocked Work

​Dependency Chains

​Viewing Relationships

​In Entity Details

​In Graph Form

​Best Practices

​Choosing the Right Relationship Type

​Modeling Dependencies Effectively

​Using Relationships for Multi-Agent Workflows

​CLI Commands

Link Command Reference

​Database Schema

​Next Steps

Specs

Issues

Feedback System

Link Command

What Are Relationships?

Relationship Types

Detailed Relationship Semantics

Creating Relationships

Using the CLI

Using Markdown Syntax

Hierarchical Relationships

For Specs

For Issues

Bidirectional Tracking

Graph-Based Planning

Topological Ordering

Finding Blocked Work

Dependency Chains

Viewing Relationships

In Entity Details

In Graph Form

Best Practices

Choosing the Right Relationship Type

Modeling Dependencies Effectively

Using Relationships for Multi-Agent Workflows

CLI Commands

Database Schema

Next Steps