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.