> ## 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.

# Relationships

> Typed connections between specs and issues for dependency modeling

## 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.

<Note>
  **Key Principle:** Relationships model how entities connect - what blocks what, what implements what, and how context flows through your project.
</Note>

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:

<CardGroup cols={2}>
  <Card title="blocks" icon="ban">
    **Hard blocker dependency**

    From entity cannot proceed until To entity is complete
  </Card>

  <Card title="implements" icon="code">
    **Implementation link**

    Issue implements requirements from a spec
  </Card>

  <Card title="depends-on" icon="arrow-right-to-arc">
    **Soft dependency**

    From entity needs To entity but not a hard blocker
  </Card>

  <Card title="references" icon="link">
    **General reference**

    Contextual link without specific semantics
  </Card>

  <Card title="related" icon="diagram-project">
    **Association**

    Entities share context or are related
  </Card>

  <Card title="discovered-from" icon="magnifying-glass">
    **Discovery tracking**

    Issue was discovered while working on another issue
  </Card>
</CardGroup>

### Detailed Relationship Semantics

<AccordionGroup>
  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    # 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
  </Accordion>
</AccordionGroup>

## Creating Relationships

### Using the CLI

The `link` command creates relationships between entities:

```bash theme={null}
sudocode link <from-id> <to-id> --type <relationship-type>
```

**Examples:**

```bash theme={null}
# 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
```

<Info>
  sudocode automatically determines entity types (spec or issue) by checking which exists in your database.
</Info>

### Using Markdown Syntax

You can embed relationships directly in markdown using extended Obsidian-style syntax:

<CodeGroup>
  ```markdown Basic Reference theme={null}
  See [[SPEC-010]] for API design patterns.

  This implements [[@ISSUE-001]] and [[@ISSUE-002]].
  ```

  ```markdown With Relationship Type (Shorthand) theme={null}
  This depends on [[SPEC-002]]{ depends-on } being finalized.

  Blocked by [[ISSUE-001]]{ blocks } completing first.

  Implements [[SPEC-001]]{ implements } requirements.
  ```

  ```markdown With Relationship Type (Explicit) theme={null}
  Related to [[ISSUE-005]]{ type: related } authentication work.

  Discovered from [[ISSUE-010]]{ type: discovered-from } during testing.
  ```

  ```markdown With Display Text and Type theme={null}
  See [[SPEC-001|Auth System Design]]{ implements } for requirements.

  Blocked by [[ISSUE-001|Database Schema]]{ blocks } completion.
  ```
</CodeGroup>

**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

<Check>
  When you use this syntax in markdown files, sudocode automatically creates the corresponding relationships in the database when syncing.
</Check>

## Hierarchical Relationships

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

### For Specs

```bash theme={null}
# 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

```bash theme={null}
# 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
```

<Info>
  Parent-child relationships are stored directly in the `parent_id` field, not in the relationships table. This enables efficient tree traversal and hierarchical queries.
</Info>

## Bidirectional Tracking

All relationships are automatically tracked in **both directions**:

```bash theme={null}
# Create a relationship
sudocode link ISSUE-001 SPEC-001 --type implements
```

Now you can query from either direction:

```bash theme={null}
# 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:

```mermaid theme={null}
graph TB
    A[ISSUE-001<br/>open] --> |blocks| B[ISSUE-002<br/>blocked]
    A --> |blocks| C[ISSUE-003<br/>blocked]
    B --> |blocks| D[ISSUE-004<br/>blocked]
    style A fill:#10B981
    style B fill:#EF4444
    style C fill:#EF4444
    style D fill:#EF4444
```

```bash theme={null}
sudocode ready
# Returns: ISSUE-001 (no blockers)
```

After ISSUE-001 closes:

```bash theme={null}
sudocode ready
# Returns: ISSUE-002, ISSUE-003 (blockers removed)
```

### Finding Blocked Work

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<Steps>
  <Step title="Is it a hard blocker?">
    Use `blocks` if From must complete before To can proceed
  </Step>

  <Step title="Is it implementing requirements?">
    Use `implements` for issue → spec implementation links
  </Step>

  <Step title="Is it informational context?">
    Use `depends-on` for soft dependencies or `references` for general links
  </Step>

  <Step title="Is it associative?">
    Use `related` for bidirectional associations without specific semantics
  </Step>

  <Step title="Was it discovered during work?">
    Use `discovered-from` to track issue genealogy
  </Step>
</Steps>

### Modeling Dependencies Effectively

<AccordionGroup>
  <Accordion title="✅ Good dependency modeling">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="❌ Avoid these patterns">
    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

### Using Relationships for Multi-Agent Workflows

<Steps>
  <Step title="Model clear dependencies">
    Use `blocks` to prevent agents from working on blocked tasks
  </Step>

  <Step title="Link issues to specs">
    Use `implements` so agents can read requirements
  </Step>

  <Step title="Track discovered work">
    Use `discovered-from` when agents find new issues during implementation
  </Step>

  <Step title="Query ready work">
    Agents use `sudocode ready` to find unblocked, high-priority work
  </Step>
</Steps>

## CLI Commands

Quick reference for relationship commands:

```bash theme={null}
# 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
```

<Card title="Link Command Reference" icon="terminal" href="/cli/link">
  See complete documentation for the link command
</Card>

## Database Schema

For reference, here's how relationships are stored:

```sql theme={null}
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

<CardGroup cols={2}>
  <Card title="Specs" icon="file-lines" href="/concepts/specs">
    Learn about specs - high-level requirements that issues implement
  </Card>

  <Card title="Issues" icon="list-check" href="/concepts/issues">
    Learn about issues - actionable work items that can be linked
  </Card>

  <Card title="Feedback System" icon="comments" href="/concepts/feedback">
    Provide anchored feedback from issues back to specs
  </Card>

  <Card title="Link Command" icon="terminal" href="/cli/link">
    Complete CLI reference for the link command
  </Card>
</CardGroup>