Wire this workspace up to an external issue tracker. The tracker becomes the source of truth for all work items; the workspace does not maintain a local mirror.
For (2) and (3): tell the user the adapter isn't shipped and exit. To add one, write a module at .claude/scripts/trackers/{type}.mjs that implements the contract in .claude/scripts/trackers/interface.mjs.
For (4): exit — no changes.
-
Verify gh auth. Run gh auth status. If not authenticated, walk the user through gh auth login. Do not proceed until authenticated.
-
Resolve the target repo. Default to the workspace's own git remote:
git -C {workspace-root} remote get-url origin
Parse the GitHub slug. Ask: "Use {slug} for issues, or a different repo?" If the user wants a different repo, accept any owner/name slug.
-
Verify issues are enabled:
gh repo view {slug} --json hasIssuesEnabled
If hasIssuesEnabled is false, offer: "Issues are disabled on {slug}. Enable? [Y/n]" → gh api repos/{slug} -X PATCH -f has_issues=true.
-
Write workspace.json:
{
"workspace": {
"tracker": {
"type": "github-issues",
"repo": "{slug}"
}
}
}
Preserve all other fields. Commit:
git add workspace.json
git commit -m "chore: configure github-issues tracker on {slug}"
-
Initialize labels by calling the adapter's ensureLabels() from a shell one-liner:
node --input-type=module -e "
import { createTracker } from './.claude/scripts/trackers/interface.mjs';
import { readFileSync } from 'node:fs';
const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
const t = createTracker(ws.workspace.tracker);
await t.ensureLabels();
console.log('Labels initialized.');
"
Creates the six standard labels: bug, feat, chore, P1, P2, P3.
-
Optional: create milestones. Ask if the user wants a starter milestone list (e.g., Backlog, v0.1 — Alpha, v1.0 — Launch). If yes, call the adapter for each — idempotent, so re-running setup won't duplicate:
node --input-type=module -e "
import { createTracker } from './.claude/scripts/trackers/interface.mjs';
import { readFileSync } from 'node:fs';
const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
const t = createTracker(ws.workspace.tracker);
await t.ensureMilestone({ title: 'Backlog', description: 'Triage later' });
await t.ensureMilestone({ title: 'v0.1 — Alpha' });
await t.ensureMilestone({ title: 'v1.0 — Launch' });
"
Skip if the user declines — milestones can be added anytime by calling tracker.ensureMilestone(...) or via the GitHub UI.
-
Verify:
gh issue list --repo {slug} --limit 5
Expected: empty list (no tickets yet) or the existing ones if the repo already had issues.
