Projects vs. Domain Todos

Tier 2 · Building 6 min read

Before this, read:

Files as state, not chat memory — the file conventions this article extends

Not every task deserves a directory. Scaffolding a full project for a one-time errand (“register the car,” “clear the stale Skylight chores”) is overhead that makes the project registry noisier without adding value. But tracking a months-long build as a loose Markdown bullet in a task list means losing the history of what shipped and what’s still open.

The decision rule is simple enough to apply in under ten seconds.

The decision rule

Scaffold a project when:

It has a goal with an identifiable end-state (“launched,” “deployed,” “first sale made”)
It produces a durable artifact (code, a deployed app, a report, a published piece)
It will take more than one session to complete
You’ll want to look back at what shipped and in what order

Use a domain todo when:

It’s a single action (“buy milk,” “register the car,” “email the professor”)
It has no artifact — just a thing that gets done
It doesn’t benefit from a WORKPLAN or CHANGELOG

When in doubt: domain todo. Create a project when the scope becomes real, not when you’re speculating about whether it might.

What a project gets

A scaffolded project lives at ~/clawd/projects/<slug>/ and gets:

README.md       ← what this is and why it exists
WORKPLAN.md     ← current tasks, status, and open questions
CHANGELOG.md    ← what shipped, dated, in plain English
LINKS.md        ← external URLs, deploys, repos

It’s also registered in ~/clawd/state/project-registry.yaml with a slug, domain, status (idea/planning/active/complete), and a one-line description.

The scaffolding command:

bash ~/agent-system/scripts/clawd-new-project.sh <slug> \
  --name "Human-readable name" \
  --domain <domain> \
  --status active

This creates the directory structure and adds the registry entry atomically. Don’t scaffold a project by hand — the registry will drift.

What a domain todo gets

A domain todo is a YAML entry in ~/clawd/domains/<domain>/state/tasks.yaml:

- id: T-042
  title: "Register the car"
  status: open
  priority: medium
  domain: family
  project_slug: null   # no project attachment

project_slug: null (or the field omitted) is the signal that this is a standalone todo, not part of a project. Domain todos sync to the Supabase tasks table every 30 minutes and surface in the Nerve Center task view.

A domain todo can optionally attach to a project:

  project_slug: openbudget

This is useful when a task is part of a project but small enough that it doesn’t need its own WORKPLAN tracking.

The logging rule

After shipping anything material on a project, log it:

bash ~/agent-system/scripts/clawd-log.sh <slug> "shipped X — what changed, what it does"

This appends to ~/clawd/projects/<slug>/CHANGELOG.md and, with --task ID, updates the WORKPLAN task status. The entry is also picked up by the master CHANGELOG at ~/clawd/CHANGELOG.md.

“Material” means anything that changes system state: a script written, a file edited, a migration run, a bug fixed, a decision made. Not for pure reading or research. If you wrote code or edited state, you log it.

Skipping the log makes the work invisible to the next session. The next agent to pick up the project reads the CHANGELOG to restore context. If the CHANGELOG is blank, the agent has no context and will either duplicate work or make decisions that conflict with what’s already built.

The registry as a single source of truth

The project registry (~/clawd/state/project-registry.yaml) is the canonical list of what exists. As of June 2026 it holds approximately 80 entries — ranging from status: active shipping products to status: archived experiments.

An honest registry acknowledges that most entries are experiments or tools, not shipped products. The May 2026 self-audit explicitly reclassified ~30 “ghost” projects — things that existed in the registry but had no real code or had been abandoned. An inflated registry is worse than a small one: it creates false confidence about how much is actually running.

When you finish a project (artifact shipped, no more open tasks), mark it status: complete. When you abandon a project (the idea didn’t pan out), mark it status: archived. The registry should tell the truth about what’s actually active.

A real example: openbudget

The openbudget project was scaffolded when JD decided to build a self-hosted YNAB on free-tier Supabase and Vercel. That decision produced a clear artifact (a deployed app), had an end-state (“public on GitHub, PII-scrubbed”), and would take multiple sessions.

The sequence:

bash ~/agent-system/scripts/clawd-new-project.sh openbudget --domain family --status active
WORKPLAN populated with tasks (SimpleFIN sync, envelope categories, Vercel deploy)
Each shipping session ran clawd-log.sh openbudget "..." to record what shipped
When the app went public (2026-06-05), status was updated to complete

The comparison: “register the car” is a domain todo in family/tasks.yaml. It needs no directory, no WORKPLAN, no CHANGELOG. It just needs to get done and be marked done.

You’ve finished Tier 2. You can design specialist agents, spawn and isolate parallel workers, orchestrate a hierarchy, schedule a heartbeat, wire future obligations to the right primitives, turn Telegram into a control plane, enforce root-cause discipline, and ship to prod without punting review to a human.

Tier 3 is the gallery: every real piece of this system, written up as a learning artifact with the full honest context — what worked, what broke, and what was quietly wrong for longer than it should have been.