Sudocode

Sudocode uses a SQLite database to manage project state, including specifications, issues, and their relationships. The schema is designed to support a graph-like structure for entities and an audit trail for changes.

Core Entities

• Specs: Represents technical specifications (e.g., architecture, api, feature).
• Issues: Represents actionable items (e.g., bug, task, epic).
• Relationships: A polymorphic table that links any two entities (spec-to-spec, spec-to-issue, etc.) using types like blocks, related, or implements.
• Tags: A shared table for categorizing both specs and issues.
• Events: An audit trail recording changes to entities, including snapshots of old and new values.

-- Example of the core relationship structure
CREATE TABLE relationships (
    from_id TEXT NOT NULL,
    from_type TEXT NOT NULL,               -- spec|issue
    to_id TEXT NOT NULL,
    to_type TEXT NOT NULL,                 -- spec|issue
    relationship_type TEXT NOT NULL,       -- blocks|related|parent-child|discovered-from|implements
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    created_by TEXT NOT NULL,
    metadata TEXT,                          -- Optional JSON metadata
    PRIMARY KEY (from_id, from_type, to_id, to_type, relationship_type)
);

Sudocode uses a git-native approach where project management data lives alongside your code in the .sudocode/ directory. This allows you to branch, merge, and version your requirements and issues just like your source code.

File Structure

• .sudocode/meta.json: Configuration and ID counters (tracked in git).
• .sudocode/specs.jsonl: All specifications (tracked in git). Each line is a complete entity.
• .sudocode/issues.jsonl: All issues (tracked in git). Each line is a complete entity.
• .sudocode/cache.db: SQLite cache (gitignored).
• .sudocode/specs/: Generated markdown files for editing (gitignored).
• .sudocode/issues/: Generated markdown files for editing (gitignored).

Key Benefits

• Branching: Create specs/issues for specific feature branches.
• Merging: Merge requirements and task updates via standard git workflows.
• Reverting: Revert task changes alongside code changes.
• Review: Review specifications and issue updates directly in Pull Requests.

An Issue captures actionable work items derived from specs, assigned to agents or humans.

Storage Locations:

• Markdown: .sudocode/issues/{id}.md
• JSONL: .sudocode/issues/issues.jsonl

Status Lifecycle:

• open → in_progress → closed
• open → blocked → in_progress → closed
• closed can be reopened to open.

Frontmatter Schema:

id: string                    # Unique identifier (issue-NNN)
title: string                 # Short description (max 500 chars)
description: string           # Detailed problem statement
status: enum                  # open | in_progress | blocked | needs_review | closed
priority: int                 # 0-4 (0=highest, 2=default)
issue_type: enum              # bug | feature | task | epic | chore
assignee: string?            # Agent ID or username
estimated_minutes: int?       # Estimated effort
created_at: timestamp         # ISO 8601 format
updated_at: timestamp         # ISO 8601 format
closed_at: timestamp?        # When closed (null if open)
created_by: string            # Who created (user or agent)
spec_refs: [string]           # Specs this issue relates to
parent: string?               # Parent issue (for epics)
blocks: [string]              # Issues this blocks
blocked_by: [string]          # Issues blocking this (computed)
related: [string]             # Related issues
tags: [string]                # Free-form labels for organization

---
id: issue-001
title: Implement OAuth 2.0 token endpoint
description: Create REST endpoint for OAuth token exchange
status: open
priority: 1
issue_type: task
assignee: agent-backend-dev
estimated_minutes: 120
created_at: 2025-10-16T10:00:00Z
updated_at: 2025-10-16T15:30:00Z
closed_at: null
created_by: agent-planner
spec_refs: [spec-001]
parent: null
blocks: [issue-002]
blocked_by: []
related: [issue-010]
tags: [auth, backend, api]
---

# Implement OAuth 2.0 token endpoint

## Description
Create REST endpoint for OAuth token exchange following RFC 6749.

Sudocode supports two primary architectural modes for managing entity data. This allows teams to choose between a machine-first or human-first workflow:

1. JSONL Mode (Current Default): The JSONL files (e.g., specs.jsonl, issues.jsonl) act as the authoritative source of truth. Markdown files in .sudocode/specs/*.md are synchronized with these files via a watcher using timestamp-based conflict resolution. This mode is optimized for machine-driven data management.

2. Markdown Mode (Proposed/New): Markdown files become the authoritative source of truth. In this mode, JSONL files are treated as derived artifacts used for caching or exporting. This is ideal for teams that prefer managing data through human-readable, wiki-style documentation.

In both modes, a SQLite Cache (cache.db) is used as the underlying query engine, but it is typically gitignored and treated as a transient layer.

Current Architecture (JSONL-first):
Markdown Files (.sudocode/specs/*.md) <-> JSONL Files (specs.jsonl, issues.jsonl) <-> SQLite Cache (cache.db)

Proposed Architecture (Markdown-first):
Markdown Files (Source of Truth) -> JSONL Files (derived) -> SQLite Cache