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

description

Onboard a project's issue tracker — inspect what tracking already exists, propose a destination per the Planka-state/git-issues-spec boundary rule, migrate existing open items with back-links, and write the tracker key to .cc-os/config. 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/backlog are tracked. Invoked by `/os-backlog:route`.

Register a project's issue tracker: figure out what already exists, propose where issue/backlog tracking should live, and — with the human's confirmation at each decision gate — migrate and record it.

The boundary rule (what you're deciding between)

• Planka = state. Cards track what's happening now — backlog/next/doing/review/done. Use planka:<board> when the project's work is mostly ephemeral tasks, small fixes, or process/coordination — nothing that needs a durable written spec.
• Git issues = specs only. Use forgejo:<owner>/<repo> or github:<owner>/<repo> when work is specified as text that needs to survive and be referenced (features, migrations, architecture-level changes) — tracer-bullet slices from /to-issues, PRDs from /to-prd.
• repo:<path> is the escape hatch for a project that already tracks issues in-repo (docs/issues/, ISSUES.md) and wants to keep doing so without moving to Planka or a git host's issue tracker.
• Card-as-pointer + issue-chain-as-spec, for code efforts: when a body of work needs both — ongoing state tracking AND a durable spec — the Planka card is a pointer (title + link) into a chain of git issues that hold the actual spec. Don't duplicate the spec text into the card description.
• Promotion rule: if a Planka-tracked effort accretes significant code/design decisions in card comments, that's a signal to promote it — open a git issue (or issue chain) holding the durable spec, and turn the Planka card into a pointer per the rule above. Flag this to the user when you see it happening; don't do it silently.

Valid tracker key formats (exactly one, written to .cc-os/config's tracker key): planka:<board> | forgejo:<owner>/<repo> | github:<owner>/<repo> | repo:<path>.

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
   

   This is read-only and safe to run without asking. It reports, as JSON:

   • tracker_configured — an existing tracker key in .cc-os/config, if any. If this is already set, tell the user the project is already routed to it and confirm they want to re-route before continuing (re-routing is itself a decision gate — treat it as step 2).
   • planka — whether a Planka board already resolves for this repo (via the same resolver /os-backlog:capture uses), or why that check couldn't run (gem/credentials unavailable — fail-soft, not blocking).
   • git_remote — the parsed git remote -v, classified as forgejo (the user's self-hosted instance) / github / unknown, plus the open-issue count via tea or gh if that CLI is available (null with a reason if not — fail-soft, not blocking).
   • in_repo_issue_files — docs/issues/ and/or ISSUES.md if present.

2. Synthesize and propose (NAMED DECISION GATE). Given the findings, propose exactly ONE destination tracker key with a short rationale grounded in the boundary rule above — e.g. "this repo has an active Forgejo remote with 11 open issues and no Planka board; issues already carry specs, so forgejo:jared/cc-os fits git-issues-as-spec" or "no existing tracking found, work here is small ad hoc fixes; planka:<repo-name> fits Planka-as-state; a board will be created on first capture, not by this skill." Stop here and wait for the user to confirm or override the destination before writing anything or moving anything. If findings are ambiguous (e.g. both a live Planka board AND an active issue tracker with open items, and it's unclear which is authoritative), say so plainly and ask rather than guessing.

3. If migration is needed (SECOND NAMED DECISION GATE). Only applies when the confirmed destination differs from where open items currently live (e.g. moving from ad hoc ISSUES.md entries to Planka, or from an unrouted Planka board to git issues). Before touching any live project history:

   • Tell the user exactly what will move (list the items) and ask for explicit go-ahead. This gate is separate from the destination gate in step 2 — confirming the destination is not confirming the migration.
   • Once confirmed, migrate mechanically using existing machinery, not new code paths: card-add/cards (via /os-backlog:capture's CLI calls) for items moving into Planka; tea/gh issue-create commands for items moving into git issues. Do not invent bespoke migration scripts.
   • Back-link both ways so nothing is double-tracked: the old item (closed Planka card comment, closed in-repo issue entry, or a note in the git-host issue if migrating away from it) gets a pointer to its new home; the new item (card description or issue body) links back to the source. Close/archive the old item once the back-link is in place — don't leave both open.

4. Write the tracker key (autonomous, mechanical, once destination is confirmed).

   ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog config-write <tracker-value>
   

   The CLI validates the format and rejects anything malformed — if it fails, relay the error verbatim and re-ask rather than hand-editing .cc-os/config.

5. Close out. Tell the user the tracker is set and that the os-status tracker warning (ADR-022/ADR-026) goes silent starting next session.

Decision gates (non-negotiable)

• Destination gate (step 2): never call config-write or move anything before the human has confirmed which tracker to use.
• Migration gate (step 3): even after the destination is confirmed, migrating existing open items (live project history) needs its own explicit go-ahead — a destination choice for new work is not consent to move old work.
• Inspection (step 1) and the final config-write (step 4) 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, per the plugin convention. inspect's individual checks (Planka, tea/gh) degrade gracefully and are reported as unavailable rather than aborting the whole command — relay those as informational, not blocking, 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.