Work Tracker

Create and manage work items in a project's work/ directory. Also summarises sessions and searches past work. Sits on top of the project's vocabulary and architecture (in docs/) — work-tracker handles what you were doing recently and last time, what was on your mind, and what was bothering you. The vocabulary and architecture layer handles what the project is about and how it works.

Bootstrap

If work/ doesn't exist in the project root, create the full structure before doing anything else:

work/
  active/              → items being worked on (human + model)
  active/unsupervised/ → items an agent is working on autonomously
  done/                → completed items (moved here, not deleted)
  discussion/          → things you're not sure about — write them down, discuss with an agent or colleague
  backlog/             → prioritised queues of future work
  backlog/unsupervised/ → queued items for autonomous agent work
  .sessions/           → per-user session logs (user decides: commit or gitignore)

Backlog files

Single project: work/backlog/main.md
Monorepo / workspace: work/backlog/{package-name}.md — one file per package

On bootstrap, create work/backlog/main.md. If the project is a monorepo or workspace (multiple packages), create one file per package instead.

Each backlog file gets this header:

# Backlog

Items near the top get worked on first. Each item is an initial draft — improve wording and break out into individual files when ready to work on.

Grep-friendly: `grep -A 3 "^## " work/backlog/*.md` gives a quick index across all backlogs.

---

Work item format

Each work item is a markdown file with frontmatter:

---
id: SHORT_UPPER_SNAKE_CASE__WORK
status: active | done | discussion
created: YYYY-MM-DD
package: package-name (optional — omit for single-project repos, or for cross-cutting work use packages: [a, b])
summary: one-line summary
outcome: written when closing — what actually happened, what didn't, what was absorbed elsewhere
---

# type: Title

Body text — the initial proposal, plan, or discussion.

## Changes

Track important changes as they happen — decisions made, approaches tried, things learned. This is the ticket's own history. Use vocabulary terms where applicable. Each entry should be dated.

- **2026-03-20** — decided X because Y
- **2026-03-21** — switched approach from A to B; A didn't work because...

## Tasks

- [ ] First thing to do
- [ ] Second thing to do
- [x] Already done

## Housekeeping

Optional. Things to do in addition to the main work — cleanup, follow-ups, related chores that don't warrant their own ticket.

Fields

id — short, unique, UPPER_SNAKE_CASE with __WORK suffix (double underscore to visually separate). Used for cross-referencing between items (e.g. "see SHARED_UNDERSTANDING__WORK"). Keep it descriptive but brief.
status — matches the directory it lives in: active, done, or discussion
created — date the item was created
summary — one line, used for scanning
package — (optional) which package this work belongs to. Omit entirely for single-project repos. For work spanning multiple packages, use packages: [a, b] instead. Scannable via grep "^package" work/active/*.md.
outcome — written when closing the ticket. What actually happened, what didn't, what was absorbed elsewhere. A future reader should be able to read summary: (the intent) and outcome: (the result) and understand the full arc.

Title prefix

Use conventional commit style prefixes: feat:, refactor:, fix:, chore:, docs:. If the type isn't obvious, leave it unclassified.

File naming

YYYYMMDD.<type>.<slug>.md

Examples:

20260320.feat.entry-point-questions.md
20260320.chore.explore-pi-harness.md

Package scope lives in frontmatter (package: / packages:), not the filename.

Discussion items (`work/discussion/`)

The primary purpose of work/discussion/ is to put down things you're not sure about so you can discuss them with someone — another human, an agent, or your future self. Writing it down is the first step; the discussion that follows is what produces clarity.

Discussion items serve two purposes:

Capturing uncertainty for discussion — when you have an idea, concern, or question that isn't resolved yet, write it down here. The act of writing crystallises the issue; having it in a file means you can point an agent (or a colleague) at it and say "what do you think about this?" This is the primary use case — it's a place for things you're unsure about that benefit from another perspective.
Ongoing high-level thinking — some discussions are never "done" in the way a ticket is. They capture thematic, strategic ways of thinking that evolve over time and inform other work without being work items themselves.

Discussion items use the same format as other work items (frontmatter, status, changes) but with status: discussion. They don't need tasks or a clear endpoint. When a discussion crystallises into something actionable, create a new item in active/ or the relevant backlog file and reference the discussion.

Unsupervised items (`backlog/unsupervised/` → `active/unsupervised/`)

Unsupervised items are tickets designed for an agent to pick up and work on autonomously with minimal human supervision. The human queues them in work/backlog/unsupervised/ and an agent moves them to work/active/unsupervised/ when starting work.

The key distinction: items directly in work/active/ are for the human working with a model. Items in work/active/unsupervised/ are for an agent working alone.

Creating unsupervised items

When the human says "create an unsupervised ticket", "queue this for an agent", "let an agent handle this", or similar — or when creating a regular ticket and additionally asking for an unsupervised version:

Create a file in work/backlog/unsupervised/ using the standard work item format
Add mode: unsupervised to the frontmatter
The body must contain clear, self-contained instructions — everything the agent needs to understand the goal, constraints, and definition of done. The agent won't have the human available to clarify, so:
- State the objective concretely
- Specify any constraints (files to touch, patterns to follow, things to avoid)
- Define what "done" looks like
- Reference relevant vocabulary, docs, or other tickets by id if context is needed
Include a ## Acceptance criteria section with checkable items

Agent workflow

When an agent picks up an unsupervised item:

Move the file from work/backlog/unsupervised/ to work/active/unsupervised/
Update status: active in frontmatter
Work through the instructions, checking off tasks as completed
Log decisions and changes in the ## Changes section as with any ticket
When done, leave the item in work/active/unsupervised/ with tasks checked off — the human reviews and moves to work/done/

Example

---
id: UPDATE_VOCAB_EXAMPLES__WORK
status: backlog
mode: unsupervised
created: 2026-03-25
summary: Add usage examples to each term in docs/vocab/coding.md
---

# chore: Add vocab examples

Each term in `docs/vocab/coding.md` should have a short code example showing the pattern. Currently they have definitions only.

## Instructions

- For each term in `docs/vocab/coding.md`, add a 3-5 line code example beneath the definition
- Use TypeScript
- Examples should be minimal and self-contained — a reader should understand the term from definition + example alone
- Don't modify definitions, only add examples
- Follow existing formatting conventions in the file

## Acceptance criteria

- [ ] Every term has a code example
- [ ] Examples are TypeScript
- [ ] Existing definitions unchanged
- [ ] File still renders cleanly as markdown

Session log

Each user has a session log at work/.sessions/$USER.md (e.g. work/.sessions/danb.md). Determine $USER from the system environment or ask on first use.

The session log has a different focus from work items. Work items track what's being built — changes, decisions, tasks. The session log tracks where the human's head is at — what they were thinking about, what's bothering them, what concerns cut across tickets or don't belong to any ticket. It may reference work items but doesn't have to.

Format

## YYYY-MM-DD

### What happened
- Brief summary of the session — what was discussed, explored, decided
- Can reference work items but doesn't need to mirror their Changes sections

### On my mind
- What the human was thinking about, concerned with, or mulling over
- Open questions, unresolved tensions, things that feel off
- Cross-cutting concerns that span multiple tickets or no ticket at all
- This is the headspace that work items don't capture

### Open threads
- TICKET_ID__WORK — brief note (optional, only if relevant)

Rotation

Rotate by month: work/.sessions/danb.2026-03.md. When a new month starts, begin a new file. The agent should only read the current month's file (and optionally the tail of the previous month if the session is near the boundary). This keeps context usage bounded.

When to write

Append to the session log at the end of a session — when the human says "summarise", "write up what we did", or when the conversation is clearly wrapping up. The session log and work item updates can happen in the same operation.

Operations

Start / continue a session

When the human says "let's continue", "where were we", "what was I working on", or starts a new session:

Read the summary: frontmatter from the project's theme docs (e.g. docs/discussion-driven-development.md, docs/themes.md) if they exist. Briefly remind the human what the project is about.
Read the last entry in work/.sessions/$USER.md — this tells you what happened, what was on their mind, and which threads were open.
Scan work/active/ — read the Status section and checked/unchecked Tasks from each active item. This tells you the factual state of work across recent sessions.
Present a summary that covers:
- Last session: what happened and what was on the human's mind
- Current state of work: which active items have progress, which are stalled, what's next
Offer options:
- Pick up a thread (if multiple are active)
- Review the backlog? — grep -A 3 "^## " work/backlog/*.md for a quick index
- Dive into the themes? — read the full theme docs and walk through them

The session log gives you the feel of where they left off. The work items give you the facts.

Create a work item

When the human says "create a ticket", "let's track this", "create a work item", or similar:

If it's future work (not something to start now), add it to a backlog file. Otherwise, create a file in work/active/.
- Which backlog? If there's only main.md, use it. If multiple backlogs exist, infer the package from context (file being discussed, directory, etc.) or ask.
- Unsupervised? If the human asks to create an unsupervised ticket (or asks for one alongside a regular ticket), create a file in work/backlog/unsupervised/ with self-contained instructions. See the "Unsupervised items" section above.
Draft the item with frontmatter, a title, and body from what the human described.
If it belongs in the backlog:

## type: Title
- id: THE_ID
- drafted: YYYY-MM-DD
- summary: one-line summary

Body text.

Move an item

When the human says "this is done", "close the ticket", "promote this to active", or similar:

Update the status: in frontmatter
Move the file to the matching directory (work/active/ or work/done/)

When closing a ticket (moving to done):

Draft an outcome: line for the frontmatter — what actually happened, what didn't, what was absorbed elsewhere
Present the draft outcome to the human for review before writing it
Once confirmed, add the outcome: field, update status: done, and move to work/done/

When promoting a backlog item to active:

Remove it from its backlog file (glob work/backlog/*.md to find it if needed)
Create a file in work/active/

Scan / review

When the human says "what's active", "what's in flight", "show me the backlog", or similar:

Active items: list files in work/active/ (human+model) and work/active/unsupervised/ (autonomous), show id + summary from frontmatter. Distinguish which are unsupervised.
Backlog: run grep -A 3 "^## " work/backlog/*.md for a quick index across all backlogs. Also list files in work/backlog/unsupervised/ if any exist. If the human asks about a specific package, target that file.
All statuses: scan all directories

Cross-referencing

Items can reference each other by id (e.g. "relates to SHARED_UNDERSTANDING__WORK"). When creating an item that relates to another, mention the id in the body. Don't over-formalise this — a mention is enough.

Summarise a session

When the human says "summarise this session", "write up what we did", "capture this", or at the end of a session, do two things:

1. Update work items — for each active ticket that was worked on:

Update the Status section to reflect current state
Check off completed Tasks
Update the frontmatter summary: if it's shifted
If no ticket exists for this work, create one in work/active/

2. Append to session log — add an entry to work/.sessions/$USER.md with:

What happened — conceptual changes, grouped by theme. Use vocabulary terms (UPPER_SNAKE_CASE) from docs/vocab/ when they apply.
On my mind — what the human was thinking about, concerned with, open questions. Capture the headspace, not just the deliverables.
Open threads — which work items are active and where they stand.

Keep both concise. Focus on decisions and the why; the what is in the code. The frontmatter summary: on work items is the most important line — optimise it for scanning.

Search past work

When the human says "remember when we...", "what did we do with...", or asks about previous sessions, past decisions, or earlier implementations:

Glob for files across work/done/, work/active/, and work/backlog/.
Match the query against filenames first (fast path) — the filename scheme encodes type and topic.
If filename matches are found, read their frontmatter summaries. Present matches with status, date, and summary so the human can pick which to dive into.
If no filename matches, grep the files for the query term in their content, including vocabulary terms (UPPER_SNAKE_CASE).
Only read the full body if the human asks to go deeper. If multiple matches, list them and let the human choose.

Conventions

Keep items concise. The initial version is a draft — it gets refined as work progresses.
Don't delete items. Move to work/done/ when complete.
The backlog is ordered by priority — items near the top get worked on first.
When an item is too big, break it into smaller items and link them via id references.

work-tracker