cc-os/docs/issue-workflow.md

Issue workflow (Forgejo + tea)

Last updated: 2026-07-16.

Note (2026-07-16): the /to-issues skill was renamed to /to-tickets in Matt Pocock's v1.1 skill set.

How issues created by the /to-tickets 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-tickets 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-tickets (formerly 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.