btrc-hub/docs/issue-workflow.md

Issue workflow

Source of truth

Gitea Issues are the source of truth for tasks, discussions, labels, milestones, and status.

Do not copy the full backlog into git.

Repository documents may define:

• issue templates
• triage rules
• Codex task format
• verification rules
• release checklist

Labels

Recommended labels:

• P0
• P1
• P2
• P3
• security
• data-integrity
• backend
• frontend
• wiki
• tags
• materials
• theatre
• codex-ready
• needs-design
• blocked
• good-first-codex-task

Codex-ready criteria

An issue can be labeled codex-ready only when it has:

• clear background
• target area
• concrete tasks
• acceptance criteria
• verification commands
• explicit non-goals
• no unresolved architecture decision

Workflow

1. Create or refine the issue in Gitea.
2. Add labels and milestone.
3. If design is unclear, label needs-design.
4. Discuss design before implementation.
5. When scoped enough, label codex-ready.
6. Give Codex the issue URL or copied issue body.
7. Codex creates a branch.
8. Codex implements a small patch.
9. Codex runs verification commands.
10. Human reviews the diff.
11. Merge.
12. Close the issue from the PR/commit message.

Commit message

Use issue references when possible:

fix: prevent preview SSRF

Refs: #123

or

fix: prevent preview SSRF

Closes: #123

depending on whether the change fully resolves the issue.