44 lines
2.7 KiB
Markdown
44 lines
2.7 KiB
Markdown
# 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`.
|