feature-tracker-mcp — "oz"

A project-agnostic tracker for the case where one person directs several AI coding sessions at once and has become the bottleneck.

The problem is not "track features." It is: several tracks are in flight, each session is blind to the others, decisions surface constantly, and reading everything is the job. Most of those decisions are mundane and delegable. A few are genuinely yours. Nothing separates them, so you read all of it.

Each project gets its own Postgres instance in a .oz folder — the project owns its tracker outright.

Table of Contents

• The model
• Commands
• Agents
• Install
• Design notes
• What is not built

The model

Goals are objectives, not filing labels. Each carries what is being achieved, what done means, what is deliberately excluded, and what constrains it. A worker reads its goal before starting and declines work that falls inside the non-goals — that is the difference between executing a queue and pursuing an objective.

Features belong to exactly one goal. Ids are allocated atomically (DIP-17, GLG-4) and never change, so anything citing one in a commit message keeps resolving. They carry acceptance criteria, dependencies, and a parity record.

Gates are decisions a session must not take alone — architectural, install, spend, irreversible. Raising one banks the question and moves on; the principal answers a round of them in one sitting.

Parity is tracked across eight dimensions, because work is only done when it is done in all of them: code, unit tests, functional tests, documentation, screens, builds, infrastructure, features.

Studies are investigations whose deliverable is a document and a decision. Pre-registered, and allowed to conclude "do not build this".

Commands

Driven through the /oz skill.

Working

Command	Does
/oz next [goal]	What can be worked now — not done, nothing it depends on outstanding
/oz blocked [goal]	What is waiting, and on what
/oz task <goal>	Drive a goal's features to done, here
/oz start	Spawn the backlog maintainer and a worker per goal, each in its own worktree
/oz standup	Cross-track state, including uncommitted work per worktree
/oz pause · /oz resume · /oz stop	Broadcast to every worker, including ones not yet running
/oz workers	Who is alive, how long since each was heard from, what each holds

Shaping the work

Command	Does
/oz refine goals	Draft and record every unrefined goal in one pass; gate what the docs cannot settle
/oz refine features	Give every open feature acceptance criteria in one pass
/oz goal	Define a new goal — the conversation produces the name
/oz review [id]	Work through a derived checklist a page at a time
/oz boundaries	What the project is not
/oz design <goal|feature>	Invention, ending in one checkpoint
/oz study <question>	Investigate; deliverable is a document and a recommendation
/oz add [text]	Record something that would otherwise be lost
/oz link <id> <depends-on>	Record a dependency

Decisions and reporting

Command	Does
/oz questions	The question round — every pending decision, answered in one sitting
/oz watch	Alert this session when a question is raised
/oz gates · /oz approve · /oz reject	The gate queue
/oz status · /oz table · /oz history	Counts, items, the append-only record
/oz parity [goal] · /oz scan <dimension>	Coverage, and the cheap probe that populates it
/oz goals · /oz prune	Goals and hygiene

Agents

Agent	Does
oz-worker	One per goal, own worktree. Claims, builds, evidences, releases. Refines its own items and gates only genuine forks
oz-backlog	What a worker structurally cannot: dependencies across goals, cross-goal duplication, staleness
oz-capture	Per turn, cheap model. Records what a turn implied that would otherwise be lost
oz-triage	Dedups; splits what peers can settle from what only the principal can
oz-study	Investigates, writes it up, links what it spawned and killed

No agent may call gate_decide. An agent approving its own gate makes the mechanism theatre.

Install

git clone https://github.com/spe-investigator/feature-tracker-mcp.git
cd feature-tracker-mcp
.\install.ps1

Builds, copies the /oz skill and the agents into ~/.claude, and registers the server. Requires Node 18+ and Docker; the database is created in the project's .oz folder on first use, and Docker is started automatically if it is not running.

Design notes

The database is the state, and the bus. Sessions cannot see each other, so coordination goes through Postgres rather than messages: a message is lost if its recipient is not running, and unauditable afterwards. Messaging is at most a doorbell.

Ids are allocated atomically. Two sessions reading a file, seeing the next free number and both taking it is how duplicate migration numbers happen. A counter incremented inside the inserting transaction makes it impossible.

Claims are leases, not flags. A worker that dies holding a flag blocks its feature forever; a lease expires and the work returns to the pool.

Counts are two numbers, never a ratio. The numerator is what converged; a growing denominator means real work was found. 12/16 → 12/20 reads as 75% → 60% — a drop — when nothing regressed and two genuine issues were named.

Standup reads working trees, not just commits. Measured here: every worktree reported zero commits ahead while two held real uncommitted work — a new crate in one, four untracked files in another. A standup built on git history calls active tracks idle.

Rejection means two things. "Not for this goal" is a routing error and the feature is moved; "not wanted" is a decision about the project. Only the second suppresses re-derivation. Every refusal keeps its rationale, and accumulated they define what the project is not — the difference between "no" and "no, because we decided X".

Drafting is derivable; decisions are not. Refinement is a batch pass over everything, with gates raised only for what the documents cannot settle. A flow that asks a question per item spends attention on the part that needed no input.

Studies are pre-registered. Method, decisive evidence and falsifier are recorded before execution, because a method chosen after seeing the data can be selected for the answer it produces. Revisions are counted rather than silent.

Thresholds are measured, not guessed. Duplicate detection uses trigram similarity at 0.30 — real restatements score 0.45–0.63, unrelated titles under 0.10, and an initial guess of 0.45 let a genuine duplicate through at 0.449.

What is not built

• /oz start has never been executed. The spawn line is documented but background spawning is untested here. Try /oz task on one goal first.
• The interactive flows are unrun. /oz refine, /oz design, /oz study and /oz goal are written and their tools are tested individually; the conversations are not.
• Parity probes exist for documentation and code only. builds and infrastructure need a real check — a build, an applied migration — and a reference search would only pretend to answer them. screens is switched off.
• No tests. The server is load-bearing and has none.
• The markdown renderer that would regenerate a human-readable tracker from the database does not exist, so a migrated markdown tracker cannot be diffed against the database to prove nothing was lost.