#346

docs/issue-workflow.md

@@ -0,0 +1,80 @@
+# 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:
+
+```txt
+fix: prevent preview SSRF
+
+Refs: #123
+```
+or
+```
+fix: prevent preview SSRF
+
+Closes: #123
+```
+depending on whether the change fully resolves the issue.