AI assistants scrape through TODO files, commit messages, and scattered notes, trying to piece together what blocks a feature. They guess. They miss critical dependencies and recent decisions.

The fix: let agents query project knowledge like a database instead of parsing human prose.

Before: Context scattered across files

# “What’s blocking the auth feature?”
# AI scrapes TODO.md, commit messages, Slack. Guesses. You verify manually.

After: Query the graph

code-hq query 'FIND ?b WHERE urn:task:auth-123 dependsOn* ?b AND ?b.taskStatus != "Done"'
# → urn:task:db-456  (Setup database, assigned to Bob)

The core problems#

Missing relationships: TODO lists describe tasks in isolation. Real work is about dependencies, ownership, and ripple effects.
Context brittleness: Rephrase a comment or move a task, and the AI’s understanding breaks. No stable way to reference project state.
Translation overhead: Humans use Markdown. Agents need structured data.

Solution: maintain two layers - one for humans (Markdown, UIs) and one for machines (structured graph). Keep them synchronized.

The approach#

1) Everything as a graph#

Projects aren’t lists - they’re webs of relationships. Represent everything as JSON-LD entities with clear connections:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@id": "urn:task:auth-123",
      "@type": "Task",
      "name": "Fix authentication bug",
      "taskStatus": "InProgress",
      "priority": "high",
      "assignee": { "@id": "urn:person:alice" },
      "dependsOn": [{ "@id": "urn:task:db-456" }],
      "dateModified": "2025-10-24T04:12:00Z"
    },
    {
      "@id": "urn:task:db-456",
      "@type": "Task",
      "name": "Setup database",
      "taskStatus": "Blocked",
      "assignee": { "@id": "urn:person:bob" }
    }
  ]
}

2) A query language for exploring relationships#

A simple query language that traverses relationships and filters results:

FIND ?t
WHERE
  ?t a Task ;
     dependsOn* ?b .
  ?b taskStatus != "Done" .
FILTER (?t = urn:task:auth-123)

3) CLI for humans#

A CLI that handles the tedious parts:

code-hq init
code-hq create task "Fix auth bug" --priority high --assignee trent
code-hq tasks --status blocked
code-hq people --role developer
code-hq show --view kanban

4) Generated views#

Generate human-readable views from the structured data:

# Tasks (Generated)

## In Progress
- Fix authentication bug (@trent, high)

## Blocked
- Setup database (@trent)

Humans use Markdown. Agents get structured data. Both stay synchronized through the CLI.

Migration#

# Parse TODO.md → tasks with inferred priority/assignee/dependencies
code-hq import todo ./TODO.md

# Import GitHub issues (PLACEHOLDER: add repo)
code-hq import github --repo org/repo

# Keep files in sync (graph → Markdown views)
code-hq render --views kanban,timeline

Trade-offs#

Authoring cost → CLI verbs (create, link, set) and smart importers make structured data feel natural
Schema drift → JSON-LD contexts with validation on write
Review friction → Small, machine-stable diffs in .code-hq/
Team adoption → Humans keep Markdown, agents get structure
VSCode only → Visualization layer depends on VSCode extension for now (web client coming soon): code-hq-vscode

Getting started#

# Start with a simple graph
code-hq init

# Add a few tasks with relationships
code-hq create task "Test semantic workflows" --priority medium

# Query to understand the current state
code-hq query 'FIND ?t WHERE ?t a Task ; priority "high"'

# See it from a human perspective
code-hq show --view kanban

Architecture#

┌─────────────────────────┐
│  CLI (Human Interface)  │  Simple commands that update understanding
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│  Semantic Graph Layer   │  JSON-LD with clear relationships
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│     Query Engine        │  TQL for exploring connections
└────────────┬────────────┘
             │
┌────────────▼────────────┐
│     Agent Workflows     │  Standup summaries, PR reviews, planning
└─────────────────────────┘

IDE Integration#

Cursor#

Add to .cursorrules:

This project uses code-hq for task management.
Reference .code-hq/prompts/task-management.md for commands.
Always check existing tasks before creating duplicates.
Update task status when starting/finishing work.

Windsurf#

Create .windsurf/workflows/codehq.md:

---
description: code-hq commands reference
---
Read `.code-hq/prompts/_index.md` for overview.
See `.code-hq/prompts/task-management.md` for details.

Claude Code#

Automatically sees .code-hq/prompts/ as context. Ask: “How do I manage tasks in this project?”

What’s next#

code-hq solves developer workflows. The next step is specialized AI agents for marketing, finance, and ops, all sharing the same knowledge graph. One source of truth for the entire company.