Living Context System

Co-located documentation that stays synchronized with code. No more archaeological digs through outdated wikis. Context lives where the code lives.

Overview

Living Context provides a structured approach to keeping documentation synchronized with code through:

1. System-level context - Each system has its own

   .ctx/

   directory with standardized files
2. Global context - Project-wide knowledge database and dependency graph
3. Validation engine - Automated freshness checking and health validation
4. ADR tracking - Architecture Decision Records with full lifecycle management

Commands Reference

All commands use the

uv run cctx

Initialize Project Context

uv run cctx init [PATH]

Create

.ctx/

Options:

• --ctx-dir, -c

  - Override context directory name (default: .ctx)

• --json

  - Output as JSON

• --quiet, -q

  - Minimal output for CI

Check Context Health

uv run cctx health [--deep]

Run health checks on Living Context documentation. Validates file presence, formatting, and synchronization.

Validators run:

• Snapshot validator - Checks file existence and dependencies
• ADR validator - Validates ADR consistency and indexing
• Debt auditor - Audits technical debt tracking
• Freshness checker - Detects stale documentation

Options:

• --deep, -d

  - Include constraint checking in health validation

• --json

  - Output as JSON

• --quiet, -q

  - Minimal output for CI

Show Status Summary

uv run cctx status

Display overview of documented systems, ADR count and status breakdown, technical debt items, and last sync timestamp.

Sync Documentation

uv run cctx sync [--dry-run]

Analyze codebase for changes requiring documentation updates. Uses freshness checker to identify stale documentation.

Options:

• --dry-run, -n

  - Preview changes without applying them

Pre-commit Validation

uv run cctx validate

Run validation suitable for pre-commit hooks. Checks context file integrity, ADR format, required fields, and system registrations. Exits with code 2 if validation fails.

Add System Context

uv run cctx add-system <PATH> [--name NAME]

Create

.ctx/

• snapshot.md - System overview and public API
• constraints.md - System invariants and boundaries
• decisions.md - Index of ADRs for this system
• debt.md - Technical debt tracking
• adr/ - Directory for Architecture Decision Records

Options:

• --name, -n

  - Human-readable system name (defaults to directory name)

Create ADR

uv run cctx adr <TITLE> [--system PATH]

Create a new Architecture Decision Record from template with next available number. Creates in system's

.ctx/adr/

.ctx/adr/

Options:

• --system, -s

  - System path to create ADR in

List Entities

uv run cctx list [systems|adrs|debt]

List registered entities. Defaults to systems if no entity type specified.

Context File Structure

Global Context (project-wide)

.ctx/
├── knowledge.db    # SQLite - ADRs, systems, dependencies
├── graph.json      # Generated dependency graph
├── schema.sql      # Database schema
├── templates/      # Documentation templates
└── README.md       # System documentation

System-level Context (per system)

src/systems/<name>/.ctx/
├── snapshot.md     # Purpose, public API, dependencies
├── constraints.md  # Invariants and boundaries
├── decisions.md    # Index of ADRs for this system
├── debt.md         # Known technical debt
└── adr/            # Architecture Decision Records
    └── ADR-NNN.md

Workflow Guidance

When to Use Each Command

uv run cctx init

uv run cctx add-system src/systems/auth

uv run cctx health

uv run cctx health --deep

uv run cctx status

uv run cctx sync --dry-run

uv run cctx validate

uv run cctx adr "Use PostgreSQL"

uv run cctx list systems

uv run cctx list adrs

uv run cctx list debt

File Update Guidelines

snapshot.md

constraints.md

decisions.md

debt.md

adr/*.md

Agent Behavior Rules

These rules define how AI agents should interact with Living Context.

Before Modifying a System

1. Read

   src/systems/<name>/.ctx/snapshot.md

   to understand purpose, API, and constraints
2. Check

   constraints.md

   for invariants that must not be violated
3. Review

   debt.md

   for known issues that might affect the work

After Modifying a System's Public API

1. Update

   snapshot.md

   with new/changed/removed exports
2. If a dependency was added, update the Dependencies section

When Making Architectural Decisions

1. Create an ADR in

   .ctx/adr/

   explaining context, options, and rationale
2. Update

   decisions.md

   to index the new ADR
3. Register in

   knowledge.db

When Introducing Technical Debt

1. Document it in

   debt.md

   with description and rationale
2. Never leave undocumented shortcuts

Before Completing Work on a System

1. Run

   uv run cctx health

   to verify documentation is current
2. Fix any issues before considering work complete

Common Workflows

Creating a New System with Context

# Create system directory
mkdir -p src/systems/auth

# Add context structure
uv run cctx add-system src/systems/auth --name "Authentication System"

# Fill in snapshot.md with purpose, API, dependencies
# Add constraints to constraints.md
# Document any initial debt in debt.md

Adding an Architecture Decision Record

# Create ADR for a system
uv run cctx adr "Use JWT for session tokens" --system src/systems/auth

# Or create global ADR
uv run cctx adr "Adopt monorepo structure"

# Update decisions.md to index the new ADR
# Register in knowledge.db

Pre-commit Workflow

# Quick validation
uv run cctx validate

# If issues found, check health for details
uv run cctx health

# Find what needs updating
uv run cctx sync --dry-run