zopu-code/docs/agents/issue-tracker.md

Issue tracker: Gitea + local markdown

This repo uses a hybrid workflow: issues are drafted and triaged locally as markdown files under .scratch/, then published as polished issues to Gitea (git.openputer.com:2222/puter/zopu-code) when they are ready for the public tracker.

Local markdown conventions

• One feature per directory: .scratch/<feature-slug>/
• The spec/PRD 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

Gitea conventions

Use the Gitea web UI or API at https://git.openputer.com/puter/zopu-code/issues.

• Create a polished issue from a local draft: copy the title and body from the final local file, then create the issue in Gitea.
• Read an issue: open the issue in the Gitea UI or fetch it via the API.
• List issues: use the Gitea UI or API with label/state filters.
• Comment on an issue: add a comment through the Gitea UI or API.
• Apply / remove labels: edit labels through the Gitea UI or API.
• Close an issue: close through the Gitea UI or API.

When a skill says "publish to the issue tracker"

1. If the output is a draft, spec, or work-in-progress, write it under .scratch/<feature-slug>/.
2. If the output is a final, polished issue, create it in Gitea and, if helpful, archive the local draft with a link to the Gitea issue number.

When a skill says "fetch the relevant ticket"

• For local drafts: read the file at the referenced path.
• For Gitea issues: open or fetch the issue by its Gitea number.

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.