Work Tracking

Project-specific tracker instructions the planner actually follows

The problem tracking.md solves

Every project tracks work differently:

  • Some use Linear. Some use Jira. Some use a plain markdown file. Some use nothing.
  • Status transitions, comment conventions, QA handoffs, branch naming - all project-specific.
  • Baking a single flow into the protocol would force every team to agree - they won't.
  • Baking nothing in means every session re-explains "how do we track work here?"
.agentic/tracking.md is the protocol's pressure release: project-level, free-form instructions the orchestration-planner reads and follows verbatim.

Where it lives and who reads it

File: .agentic/tracking.md at the project root (legacy path .claude/tracking.md also recognized as fallback).

Reader: the orchestration-planner agent, during step 7 of its planning process:

Check for .agentic/tracking.md first, then .claude/tracking.md (legacy fallback).
If it exists at either path, read it and follow its instructions.

The planner is otherwise strictly read-only. tracking.md is the one file that can instruct it to run commands (curl a ticket API, update a status, post a comment).

Two newer mechanisms complete the tracker picture. .agentic/tracker.yml (via bin/ds-tracker) is a local overlay for resolving TRACKER - sole source when AGENTS.md declares no tracker, field-merged when it declares the same one; it refuses to write any path git tracks. The Tracker Writeback Helper (content/references/tracker-writeback.md) is the reusable subagent pattern behind every state transition - gated on TRACKER != none, forward-only so a ticket never moves backward.

No file = no tracker actions. The protocol degrades cleanly for projects that don't care.

What goes in it

The file is free-form, but a good one tells the planner things like:

  • Where the ticket lives - Linear team, Jira project, Notion doc, markdown file
  • How to fetch it - exact CLI command, MCP call, or file path to read
  • How to record planning decisions - a comment on the ticket, a log file, nothing at all
  • Which status transitions to make and when - "move to In Progress when architect starts", "move to In QA after Skeptic passes"
  • Who to assign for QA - user ID, team, or "skip - no QA assignee"
  • What NOT to do - e.g. "never close a ticket automatically, the PM does that"
Treat it as a runbook the planner will literally execute. Vague instructions produce vague behavior.

Example - a Linear project

# Work Tracking

This project uses Linear. Ticket IDs look like ENG-1234.

## At planning start
1. Fetch the ticket: mcp__linear__get_issue with the ticket ID
2. Read the Implementation, Files, and QA sections from the description
3. Note blockedBy tickets - confirm they are Done before continuing
4. Transition the ticket to "In Progress" (state ID: abc-123)

## At plan completion (before engineer spawn)
- Post a comment on the ticket with the final phase list and estimated phases

## At Skeptic pass
- Transition the ticket to "In QA"
- Assign QA to user 789-xyz

## Never
- Close the ticket. The PM decides when Done is Done.

Example - a project with no external tracker

Not every project has Linear or Jira. tracking.md can point at anything:

# Work Tracking

No external tracker. Work is captured in docs/worklog.md.

## At planning start
- Append a new section to docs/worklog.md with today's date and the goal.

## At plan completion
- Under that section, write the phase list as a checklist.

## As phases complete
- The engineer will check items off as part of its DONE report.
  The planner does not need to touch the file again after planning.

How it composes with the rest of the protocol

  • /ds-init-project can seed the file during project setup - you edit it to match your tracker
  • The orchestration-planner reads it every time it plans a task - no caching, no staleness
  • Every other agent ignores it - engineer, skeptic, qa-engineer, investigator never touch it
  • Version control it - same as AGENTS.md, decisions.md, and other tool-agnostic config in .agentic/
  • Scales down cleanly - no file means no tracker actions, and the planner plans the same way otherwise
One file, one reader, one job: give the planner project-specific tracker instructions it can execute during any orchestration. That is the whole surface area.

One file. Project-specific. Planner-executed.

Tracker flexibility without protocol bloat.

github.com/Space-Dinosaurs/DinoStack