From 05437c8d41547b09da88d8f00e838c8309e58f43 Mon Sep 17 00:00:00 2001
From: jared <jared@swansoncloud.com>
Date: Tue, 30 Jun 2026 16:25:29 -0400
Subject: [PATCH] Document Forgejo/tea issue workflow

Add docs/issue-workflow.md covering token setup, listing, implementing, and
closing issues via tea on the self-hosted Forgejo tracker, plus a pointer
from CLAUDE.md. Captures the tea token-scope and --user gotchas discovered
while implementing SB Content Plan Phase 1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md              |  4 ++++
 docs/issue-workflow.md | 51 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 docs/issue-workflow.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 0bf43c8..eec4d85 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -102,6 +102,10 @@ to those two and fix the stale doc.
 
 **Remaining optional items:** SessionStart vault pull (multi-machine sync; push-only is the current design); additional project onboarding (one at a time, per ADR-013); bulk vault migration. All required build steps complete as of 2026-06-15.
 
+## Issue tracking
+
+Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md` for token setup, listing, implementing, and closing issues.
+
 ## OpenSpec workflow
 
 Changes are managed spec-driven via OpenSpec. Use the matching skills rather than editing spec
diff --git a/docs/issue-workflow.md b/docs/issue-workflow.md
new file mode 100644
index 0000000..34f653f
--- /dev/null
+++ b/docs/issue-workflow.md
@@ -0,0 +1,51 @@
+# Issue workflow (Forgejo + tea)
+
+_Last updated: 2026-06-30._
+
+How issues created by the `/to-issues` skill get tracked and implemented in this repo.
+
+## Tracker
+
+- Issues live on self-hosted **Forgejo**: https://forgejo.swansoncloud.com/jared/cc-os/issues
+- CLI: **`tea`** (`/home/jared/.local/bin/tea`), login name `forgejo`, user `jared`.
+- The repo remote is Forgejo, **not GitHub** — `gh` does not work here.
+
+## Token setup (one-time)
+
+`tea`'s token needs issue + repository scopes. Forgejo tokens are **immutable** — you cannot add scopes to an existing token, so generate a new one:
+
+1. https://forgejo.swansoncloud.com/user/settings/applications -> "Generate New Token".
+2. Select scopes: `read:issue`, `write:issue`, `read:repository`, `write:repository`.
+3. Register it with tea — **drop `--user`** (that flag forces the basic-auth path and fails with `Error: No password set`):
+   ```
+   tea login delete forgejo            # only if re-adding
+   tea logins add --name forgejo --url https://forgejo.swansoncloud.com --token <TOKEN>
+   ```
+
+`tea login delete` is local-only (edits `~/.config/tea/config.yml`); it does not revoke the server-side token. Git push/pull use SSH and are unaffected by API tokens.
+
+## List issues
+
+```
+tea issues list --repo jared/cc-os
+tea issues <N> --repo jared/cc-os     # view one issue's body
+```
+
+## Implement
+
+There is **no auto-trigger and no `/grab` command**. Issues from `/to-issues` are written as independently-grabbable tracer-bullet slices. To implement:
+
+1. Pick the next **unblocked** issue (check the "Blocked by" line in the body — slices often form a linear chain).
+2. Hand it to a coding session: _"implement issue #N from forgejo jared/cc-os"_.
+3. Work the dependency chain in order.
+
+## Close
+
+```
+tea comment <N> "summary of what was done" --repo jared/cc-os
+tea issues close <N> --repo jared/cc-os
+```
+
+## Caveat
+
+The Matt-Pocock `to-issues` / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.