---
description: Onboard a project's issue tracker — inspect what tracking already exists, propose a destination (forgejo/github/repo), write it to .cc-os/config, and ensure the ten canonical labels exist. Use unprompted WHEN a project has no tracker key configured and process/backlog work surfaces, or when the user explicitly asks to set up or change how a repo's issues are tracked. Invoked by `/os-backlog:route`.
---

Register a project's issue tracker: figure out what already exists, propose the single
destination where its state and specs both live, and — with the human's confirmation —
write it and ensure its labels exist.

## One tracker, both jobs

Per ADR-0042 there is exactly one tracker per project. It holds both task state (labels)
and durable specs (issue bodies, `/to-tickets` slices, PRDs) — there is no second surface.
Valid tracker key formats (exactly one, written to `.cc-os/config`'s `tracker` key):
`forgejo:<owner>/<repo>` | `github:<owner>/<repo>` | `repo:<path>`. `planka:<board>` is
rejected — `config-write` and the os-status `tracker-configured` check both reject it with
a one-line message citing ADR-0042, fail-soft.

## Procedure

All commands use the plugin CLI at `${CLAUDE_PLUGIN_ROOT}/bin/os-backlog`.

1. **Inspect (autonomous, mechanical).** Run:
   ```bash
   ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog inspect
   ```
   Read-only, safe without asking. It reports `tracker_configured` (existing key, if any —
   if set, confirm re-routing with the user before continuing; re-routing is itself a
   decision gate), `git_remote` (parsed `git remote -v`, classified `forgejo`/`github`/
   `unknown`, plus open-issue count via `tea`/`gh` if available — fail-soft, not blocking),
   and `in_repo_issue_files` (`docs/issues/` and/or `ISSUES.md` if present).

2. **Propose a destination (NAMED DECISION GATE).** Pick one:
   - Git remote is `forgejo` → propose `forgejo:<owner>/<repo>`.
   - Git remote is `github` → propose `github:<owner>/<repo>`.
   - No git-host remote, but `in_repo_issue_files` exist → propose `repo:<path>` naming
     that location.
   - Neither → ask the user which of the three they want; do not guess.
   **Stop here and wait for the user to confirm or override before writing or migrating
   anything.**

3. **Migrate existing items if the tracker type is changing (SECOND NAMED DECISION GATE).**
   Only applies when open items currently live somewhere other than the confirmed
   destination (e.g. `ISSUES.md` entries moving to Forgejo, or switching from GitHub to
   Forgejo). Before touching any live project history:
   - Tell the user exactly what will move (list the items) and get explicit go-ahead —
     separate from the destination confirmation in step 2.
   - Once confirmed, migrate mechanically using existing machinery: `tea issues create` /
     `gh issue create` for items moving onto a git-host tracker; append to the target file
     for items moving into `repo:<path>`. Do not invent bespoke migration scripts.
   - Back-link both ways: the old item gets a pointer to its new home, the new item's body
     links back to the source. Close/archive the old item once the back-link is in place.

4. **Write the tracker key (autonomous, mechanical, once destination is confirmed).**
   ```bash
   ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog config-write <tracker-value>
   ```
   This validates the format, rejects anything malformed (including `planka:`, citing
   ADR-0042), writes `.cc-os/config`, and upserts the global project index
   (`~/.cc-os/projects.json`) so cross-project filing can find this project later.

5. **Ensure the ten canonical labels exist (forgejo/github only, idempotent).** Skip for
   `repo:` trackers — they carry no label mechanism. List what's already there, then create
   only what's missing:
   - Forgejo:
     ```bash
     tea labels list --repo <owner>/<repo> -o json
     tea labels create --repo <owner>/<repo> --name <label> --color <hex>
     ```
   - GitHub:
     ```bash
     gh label list --repo <owner>/<repo> --json name
     gh label create <label> --repo <owner>/<repo> --color <hex>
     ```
   The ten labels: priority `P0` `P1` `P2` `P3`; autonomy `hitl` `semi` `afk-ready`; state
   `next` `waiting` `review`. Pick any consistent color scheme (e.g. red-to-green for
   priority) — the color itself isn't contractual, only that all ten exist. Re-running
   `/os-backlog:route` on an already-labeled repo creates nothing new.

6. **Close out.** Tell the user the tracker is set, which labels were created (if any), and
   that the os-status tracker warning goes silent starting next session.

## Decision gates (non-negotiable)

- **Destination gate (step 2):** never call `config-write` before the human has confirmed
  which tracker to use.
- **Migration gate (step 3):** even after the destination is confirmed, migrating existing
  open items needs its own explicit go-ahead — a destination choice for new work is not
  consent to move old work.
- Inspection (step 1), `config-write` (step 4), and label creation (step 5) are mechanical
  and run without a gate — they don't change or move anything you haven't already been told
  to.

## Failure behavior

Fail soft. `inspect`'s individual checks (`tea`/`gh`) degrade gracefully and are reported as
unavailable rather than aborting the whole command — relay those as informational unless
the missing signal is the only way to make the destination decision, in which case say
what's missing and ask the human directly. `config-write` fails loudly on an invalid
tracker value — relay the CLI's error verbatim.