From d4dd5c1a2108dfd5a205f3595ff8a52f3028b11a Mon Sep 17 00:00:00 2001
From: Calmcacil <Calmcacil@Raion>
Date: Mon, 12 Jan 2026 16:15:25 +0100
Subject: [PATCH] Add Gitea issue workflow documentation

---
 AGENTS.md       | 18 ++++++++++++++-
 GITEA_ISSUES.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 GITEA_ISSUES.md

diff --git a/AGENTS.md b/AGENTS.md
index df7a4af..a2f03ae 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,22 @@
 # Agent Instructions
 
-This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+This project uses **bd** (beads) for issue tracking and **Gitea** for external issue tracking.
+
+## Gitea Issues Workflow
+
+When asked to work on Gitea issues:
+1. Read issue via API: `curl -s "https://gitea.calmcacil.dev/api/v1/repos/{owner}/{repo}/issues/{number}"`
+2. Analyze requirements and scope
+3. Create task list with `todowrite` for multi-step work
+4. Implement fix following existing patterns
+5. Commit with `Closes #{number}` in message (auto-closes issue)
+6. Push to remote
+
+See `GITEA_ISSUES.md` for detailed workflow.
+
+## Beads Workflow
+
+Run `bd onboard` to get started with beads.
 
 ## Quick Reference
 
diff --git a/GITEA_ISSUES.md b/GITEA_ISSUES.md
new file mode 100644
index 0000000..9088225
--- /dev/null
+++ b/GITEA_ISSUES.md
@@ -0,0 +1,60 @@
+# Gitea Issue Workflow
+
+## Process for Working with Gitea Issues
+
+### 1. Read Issue
+```bash
+# Get all issues
+curl -s "https://gitea.calmcacil.dev/api/v1/repos/{owner}/{repo}/issues?state=open" | jq '.'
+
+# Get specific issue
+curl -s "https://gitea.calmcacil.dev/api/v1/repos/{owner}/{repo}/issues/{number}" | jq '.'
+```
+
+### 2. Analyze Issue
+- Read title and body
+- Check labels, assignee, milestone
+- Identify blocking dependencies
+- Determine if actionable
+
+### 3. Create Task List
+- Use `todowrite` for multi-step issues
+- Break down into actionable steps
+- Mark first step `in_progress`
+
+### 4. Implement Fix
+- Follow existing code patterns
+- Make minimal changes
+- Update relevant documentation
+
+### 5. Verify Fix
+- Run any available tests
+- Manual verification of functionality
+- Check for side effects
+
+### 6. Commit Changes
+```bash
+git add -A
+git commit -m "Brief description
+
+Details about what was fixed.
+
+Closes #{issue_number}"
+```
+
+### 7. Push and Close
+```bash
+bd sync
+git push
+```
+
+The `Closes #{issue_number}` in commit message will automatically close the issue via Gitea API.
+
+## Guidelines
+
+- Always read the full issue before starting work
+- If issue is unclear, ask for clarification
+- Create todos for 2+ step tasks
+- Reference issue in commit message with `Closes #`
+- Verify the fix actually resolves the issue
+- Update documentation if behavior changes