100 lines
5.5 KiB
Markdown
100 lines
5.5 KiB
Markdown
---
|
|
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-issues` 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.
|