City-Lifeline-Cockpit/docs/agents/issue-tracker.md

Issue tracker: Local Markdown

Issues and specs for this repo live as markdown files in .scratch/.

Conventions

• One feature per directory: .scratch/<feature-slug>/
• The spec is .scratch/<feature-slug>/spec.md
• Implementation issues are one file per ticket at .scratch/<feature-slug>/issues/<NN>-<slug>.md, numbered from 01, never a single combined tickets file
• Triage state is recorded as a Status: line near the top of each issue file (see triage-labels.md for the role strings)
• Comments and conversation history append to the bottom of the file under a ## Comments heading

Field lines

The tracker panel matches these lines with a line-start pattern, so write them plain — no bolding, no list bullet, no blockquote:

Status: ready-for-agent
Type: research
Blocked by: 09, 13
Label: wayfinder:map

**Status:** … and the other bolded variants are not recognised. A ticket written that way is read as open, with no Blocked by edges and no assignee state, so the whole effort renders as a flat, all-open board. Field lines are the only lines held to this rule: **What to build:** and similar body lead-ins are free-form.

Blocked by: takes None or a comma-separated list of ticket numbers (09, 13). Any other number on that line is also read as a ticket reference, so keep prose and counts off it. Category: is free text and is not parsed.

Efforts the panel can see

The panel enumerates an effort only when .scratch/<effort>/map.md exists. A directory that holds spec.md and issues/ but no map.md is skipped entirely and none of its tickets are listed. Give an effort a map.md when it should be visible to the panel.

When a skill says "publish to the issue tracker"

Create a new file under .scratch/<feature-slug>/ (creating the directory if needed).

When a skill says "fetch the relevant ticket"

Read the file at the referenced path. The user will normally pass the path or the issue number directly.

Wayfinding operations

Used by /wayfinder. The map is a file with one child file per ticket.

• Map: .scratch/<effort>/map.md (the Notes / Decisions-so-far / Fog body).
• Child ticket: .scratch/<effort>/issues/NN-<slug>.md, numbered from 01, with the question in the body. A Type: line records the ticket type (research/prototype/grilling/task); a Status: line records claimed/resolved.
• Blocking: a Blocked by: NN, NN line near the top. A ticket is unblocked when every file it lists is resolved.
• Frontier: scan .scratch/<effort>/issues/ for files that are open, unblocked, and unclaimed; first by number wins.
• Claim: set Status: claimed and save before any work.
• Resolve: append the answer under an ## Answer heading, set Status: resolved, then append a context pointer (gist + link) to the map's Decisions-so-far in map.md.

Repo note

This working tree is a usable git checkout with an origin remote configured, and .scratch/ is tracked by git. The tracker in use is still this local Markdown backend. If that remote becomes the actual work tracker, re-run /setup-matt-pocock-skills to switch this configuration.