cc-os/plugins/os-backlog/skills/route/SKILL.md

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:

   ${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).

   ${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:

     tea labels list --repo <owner>/<repo> -o json
     tea labels create --repo <owner>/<repo> --name <label> --color <hex>
     

   • GitHub:

     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.