@backburner/cli 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Backburner is a local GitHub-driven agent orchestration CLI. It uses GitHub labels, issues, and pull requests as the control plane, keeps configuration and state as readable JSON on your machine, and dispatches eligible work to provider CLIs that you already have installed locally.
 
-Backburner currently supports:
+Backburner supports:
 
 - `backburner init` for interactive or non-interactive local setup
 - `backburner run` for one orchestration cycle
@@ -75,7 +75,7 @@ npm run install:local -- --prefix "$env:TEMP\backburner-local"
 & "$env:TEMP\backburner-local\backburner.cmd" journal --json
 ```
 
-Once the current package is published:
+Install from npm:
 
 ```sh
 npm install -g @backburner/cli
@@ -117,14 +117,16 @@ Useful `init` flags:
 --yes, -y                Accept defaults without prompts
 ```
 
-`backburner init` checks local requirements, confirms `gh auth status`, discovers repositories, detects provider CLIs, attempts model-list discovery when supported by those CLIs, and writes these files into the management directory:
+`backburner init` checks local requirements, confirms `gh auth status`, discovers repositories, detects provider CLIs, attempts model-list discovery when supported by those CLIs, writes configuration, and creates the configured Backburner labels on each selected repository.
 
 - `repos.json`
 - `agents.json`
 
-If either file already exists, onboarding asks before overwriting it. With `--yes`, defaults are accepted non-interactively, including selecting existing discovered repositories, enabling every discovered provider, and creating strong and cheap agents for each one. `--yes` does not create a private demo repository.
+If either file already exists, onboarding asks before overwriting it. With `--yes`, defaults are accepted non-interactively, including selecting existing discovered repositories, enabling every discovered provider, creating strong and cheap agents for each one, and creating or updating labels on selected repositories. `--yes` does not create a private demo repository.
 
-Repository setup first asks whether to select existing repositories, create a private Backburner demo repository, or skip repository setup for now. In an interactive terminal, repository and provider selection use a checkbox picker: arrow keys move, space toggles, and enter confirms. Non-TTY sessions fall back to text input and accept comma-separated numbers. If you are authenticated with GitHub but do not want to onboard an existing local clone yet, onboarding can explicitly create a private `backburner-demo` repository and clone it under the configured code root.
+Repository setup first asks whether to create a private Backburner demo repository, select existing repositories, or skip repository setup for now. When GitHub authentication is available, the private demo repository is the interactive default. Before choosing existing repositories, onboarding tells you that Backburner will create or update its labels on those repositories. In an interactive terminal, repository and provider selection use a checkbox picker: arrow keys move, space toggles, and enter confirms. Non-TTY sessions fall back to text input and accept comma-separated numbers. If you are authenticated with GitHub but do not want to onboard an existing local clone yet, onboarding can explicitly create a private `backburner-demo` repository and clone it under the configured code root.
+
+Label creation is best-effort. If GitHub rejects a label write because of permissions or repository policy, onboarding continues and prints the repository labels URL plus the exact label names to create manually. The final summary prints the next `backburner run` command, a prefilled GitHub issue URL for the first configured repository, and a terminal QR code for opening that repository's issues page from a phone.
 
 ## Default Directories
 
@@ -160,13 +162,13 @@ Minimal `repos.json`:
       "localPath": "your-github-user/example-repo",
       "enabled": true,
       "labels": {
-        "agentInProgress": "agent-in-progress",
-        "agentProductApproved": "agent-product-approved",
-        "agentPlanApproved": "agent-plan-approved",
-        "agentReview": "agent-review",
-        "planBreakdownNeeded": "plan-breakdown-needed",
-        "agentSyncParentBranch": "agent-sync-parent-branch",
-        "prepareForMerge": "prepare-for-merge"
+        "agentInProgress": "backburner:in-progress",
+        "agentProductApproved": "backburner:product-approved",
+        "agentPlanApproved": "backburner:plan-approved",
+        "agentReview": "backburner:review",
+        "planBreakdownNeeded": "backburner:plan-breakdown-needed",
+        "agentSyncParentBranch": "backburner:sync-parent-branch",
+        "prepareForMerge": "backburner:prepare-for-merge"
       }
     }
   ]
@@ -215,14 +217,14 @@ Agent selection filters enabled agents by required role and `modelClass`, then b
 
 ## Label Control Plane
 
-Configure labels per repository in `repos.json`. The common defaults are:
+Configure labels per repository in `repos.json`. The workflow labels are:
 
-- `agent-product-approved`: approves product discovery and allows Backburner to create the implementation PR/worktree flow for an issue
-- `agent-plan-approved`: approves an implementation plan and allows implementation tasks to run
-- `agent-review`: requests an explicit code review; review tasks are dispatched when the PR has this label and its head SHA changed since the last review
-- `agent-sync-parent-branch`: authorizes Backburner to sync a blocked parent implementation branch from the repository default branch
+- `agentProductApproved`: approves product discovery and allows Backburner to create the implementation PR/worktree flow for an issue
+- `agentPlanApproved`: approves an implementation plan and allows implementation tasks to run
+- `agentReview`: requests an explicit code review; review tasks are dispatched when the PR has this label and its head SHA changed since the last review
+- `agentSyncParentBranch`: authorizes Backburner to sync a blocked parent implementation branch from the repository default branch
 
-Backburner also uses `agent-in-progress`, `plan-breakdown-needed`, and `prepare-for-merge` when those labels are configured.
+Backburner also uses `agentInProgress`, `planBreakdownNeeded`, and `prepareForMerge` when those labels are configured. Onboarding writes `repos.json` with these label values by default: `backburner:product-approved`, `backburner:plan-approved`, `backburner:review`, `backburner:in-progress`, `backburner:plan-breakdown-needed`, `backburner:sync-parent-branch`, and `backburner:prepare-for-merge`. It creates or updates the configured labels through `gh label create --force`. Custom label names, including older unprefixed names, are supported when configured in `repos.json`.
 
 ## Commands
 
@@ -315,7 +317,7 @@ Generated files are readable JSON. Control-plane state is written under `<output
 
 ## Platform Support
 
-Backburner is intended to run on macOS, Linux, and Windows with Node.js 20 or newer. The current CI workflow in this checkout runs on Ubuntu, macOS, and Windows with Node 20 and 22, and includes build, typecheck, tests, package dry-run, and local package install smoke checks.
+Backburner is intended to run on macOS, Linux, and Windows with Node.js 20 or newer. The CI workflow runs on Ubuntu, macOS, and Windows with Node 20 and 22, and includes build, typecheck, tests, package dry-run, and local package install smoke checks.
 
 ## Verification
 

package/dist/src/cli/commands/broker-smoke.js

@@ -1,4 +1,3 @@
-import * as path from "node:path";
 import { ExecFileCommandRunner } from "../../utils/command-runner.js";
 import { loadConfig } from "../../config/loader.js";
 import { GhCliGitHubGateway } from "../../github/gateway.js";
@@ -9,11 +8,11 @@ import { PlanBreakdownSessionStore } from "../../workstreams/plan-breakdown-gene
 import { PlanBreakdownToolService } from "../../workstreams/plan-breakdown-generator/tools.js";
 import { WaveAssessmentSessionStore } from "../../workstreams/wave-assessment/store.js";
 import { WaveAssessmentToolService } from "../../workstreams/wave-assessment/tools.js";
-import { defaultBackburnerManagementRoot } from "../../utils/paths.js";
+import { defaultBackburnerManagementRoot, resolveUserPath } from "../../utils/paths.js";
 import { defaultStderrLogger } from "../../utils/logger.js";
 import { DEFAULT_GITHUB_BROKER_PORT, readOptionalNumberFlag, readOptionalStringFlag, readStringFlag } from "../options.js";
 export async function runBrokerSmokeCli(argv, logger = defaultStderrLogger) {
-    const managementDir = path.resolve(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
+    const managementDir = resolveUserPath(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
     const host = "127.0.0.1";
     const config = await loadConfig(managementDir);
     const commandRunner = new ExecFileCommandRunner();

package/dist/src/cli/commands/broker.js

@@ -1,4 +1,3 @@
-import * as path from "node:path";
 import { ExecFileCommandRunner } from "../../utils/command-runner.js";
 import { loadConfig } from "../../config/loader.js";
 import { GhCliGitHubGateway } from "../../github/gateway.js";
@@ -9,11 +8,11 @@ import { PlanBreakdownSessionStore } from "../../workstreams/plan-breakdown-gene
 import { PlanBreakdownToolService } from "../../workstreams/plan-breakdown-generator/tools.js";
 import { WaveAssessmentSessionStore } from "../../workstreams/wave-assessment/store.js";
 import { WaveAssessmentToolService } from "../../workstreams/wave-assessment/tools.js";
-import { defaultBackburnerManagementRoot } from "../../utils/paths.js";
+import { defaultBackburnerManagementRoot, resolveUserPath } from "../../utils/paths.js";
 import { defaultStderrLogger } from "../../utils/logger.js";
 import { DEFAULT_GITHUB_BROKER_PORT, readNumberFlag, readStringFlag } from "../options.js";
 export async function runBrokerCli(argv, logger = defaultStderrLogger) {
-    const managementDir = path.resolve(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
+    const managementDir = resolveUserPath(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
     const port = readNumberFlag(argv, "--port", DEFAULT_GITHUB_BROKER_PORT);
     const host = readStringFlag(argv, "--host", "127.0.0.1");
     const config = await loadConfig(managementDir);

package/dist/src/cli/commands/journal.js

@@ -1,11 +1,10 @@
-import * as path from "node:path";
 import { JournalReader } from "../../journal/index.js";
 import { renderJournalEntries } from "../../journal/renderer.js";
-import { defaultBackburnerOutputsRoot, resolveOutputsJournalRoot } from "../../utils/paths.js";
+import { defaultBackburnerOutputsRoot, resolveOutputsJournalRoot, resolveUserPath } from "../../utils/paths.js";
 import { CliUsageError } from "../errors.js";
 import { readOptionalStringFlag, readStringFlag } from "../options.js";
 export async function runJournalCli(argv, injectedJournal) {
-    const outputsDir = path.resolve(readStringFlag(argv, "--outputs-dir", defaultBackburnerOutputsRoot()));
+    const outputsDir = resolveUserPath(readStringFlag(argv, "--outputs-dir", defaultBackburnerOutputsRoot()));
     const journalDir = resolveOutputsJournalRoot(outputsDir);
     const reader = injectedJournal ? injectedJournal.reader : new JournalReader(journalDir);
     const repoId = readOptionalStringFlag(argv, "--repo");

package/dist/src/cli/commands/tui.js

@@ -1,7 +1,6 @@
-import * as path from "node:path";
 import { loadConfig } from "../../config/loader.js";
 import { StateStore } from "../../state/loader.js";
-import { defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, resolveOutputsLogsRoot, resolveOutputsStateRoot } from "../../utils/paths.js";
+import { defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, resolveOutputsLogsRoot, resolveOutputsStateRoot, resolveUserPath } from "../../utils/paths.js";
 import { RuntimeStatusTracker, TuiScreen } from "../tui/index.js";
 import { readIntervalMs, readOptionalStringFlag, readStringFlag } from "../options.js";
 import { runCli } from "./run.js";
@@ -73,7 +72,7 @@ export class SerializedCycleRunner {
 }
 export async function runInteractiveTui(argv) {
     const rest = argv.filter((arg) => arg !== "run");
-    const managementDir = path.resolve(readStringFlag(rest, "--management-dir", defaultBackburnerManagementRoot()));
+    const managementDir = resolveUserPath(readStringFlag(rest, "--management-dir", defaultBackburnerManagementRoot()));
     let repoCount = 0;
     let initialConfig = null;
     try {
@@ -91,9 +90,9 @@ export async function runInteractiveTui(argv) {
     tracker.setIntervalMs(intervalMs);
     // Load initial state for the explorer immediately on start
     try {
-        const outputsDir = path.resolve(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
-        const stateDir = path.resolve(resolveOutputsStateRoot(outputsDir));
-        const logDir = path.resolve(resolveOutputsLogsRoot(outputsDir));
+        const outputsDir = resolveUserPath(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
+        const stateDir = resolveUserPath(resolveOutputsStateRoot(outputsDir));
+        const logDir = resolveUserPath(resolveOutputsLogsRoot(outputsDir));
         const stateStore = new StateStore({ stateDir, executionDir: logDir });
         const state = await stateStore.load();
         tracker.setState(state);
@@ -114,9 +113,9 @@ export async function runInteractiveTui(argv) {
                 logger: silentLogger,
                 cycleNo: currentCycleNo
             });
-            const outputsDir = path.resolve(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
-            const stateDir = path.resolve(resolveOutputsStateRoot(outputsDir));
-            const logDir = path.resolve(resolveOutputsLogsRoot(outputsDir));
+            const outputsDir = resolveUserPath(readOptionalStringFlag(rest, "--outputs-dir") ?? defaultBackburnerOutputsRoot());
+            const stateDir = resolveUserPath(resolveOutputsStateRoot(outputsDir));
+            const logDir = resolveUserPath(resolveOutputsLogsRoot(outputsDir));
             const stateStore = new StateStore({ stateDir, executionDir: logDir });
             const state = await stateStore.load();
             try {

package/dist/src/cli/init.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { ExecFileCommandRunner } from "../utils/command-runner.js";
-import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, defaultWorkspacesRootForCodeRoot } from "../utils/paths.js";
+import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, defaultWorkspacesRootForCodeRoot, resolveUserPath } from "../utils/paths.js";
 import { OnboardingEngine } from "../onboarding/engine.js";
 import { NodeReadlinePrompter, NonInteractivePrompter } from "../onboarding/prompt.js";
 import { WelcomeStep } from "../onboarding/steps/welcome.js";
@@ -12,6 +12,7 @@ import { ConfigurePathsStep } from "../onboarding/steps/configure-paths.js";
 import { DiscoverProvidersStep } from "../onboarding/steps/discover-providers.js";
 import { ConfigureModelsStep } from "../onboarding/steps/configure-models.js";
 import { GenerateConfigStep } from "../onboarding/steps/generate-config.js";
+import { ProvisionLabelsStep } from "../onboarding/steps/provision-labels.js";
 import { ReadinessValidationStep } from "../onboarding/steps/readiness-validation.js";
 import { ShowSummaryStep } from "../onboarding/steps/show-summary.js";
 import { DemoRepoCreator } from "../onboarding/services/demo-repo.js";
@@ -38,14 +39,14 @@ export async function runInitCli(argv) {
 export async function runInit(options) {
     const commandRunner = new ExecFileCommandRunner();
     const { codeRoot, nonInteractive = false } = options;
-    const resolvedCodeRoot = path.resolve(codeRoot);
-    const resolvedOutputsDir = path.resolve(options.outputsDir ?? defaultBackburnerOutputsRoot());
+    const resolvedCodeRoot = resolveUserPath(codeRoot);
+    const resolvedOutputsDir = resolveUserPath(options.outputsDir ?? defaultBackburnerOutputsRoot());
     const ctx = {
         codeRoot: resolvedCodeRoot,
-        managementDir: path.resolve(options.managementDir ?? defaultBackburnerManagementRoot()),
+        managementDir: resolveUserPath(options.managementDir ?? defaultBackburnerManagementRoot()),
         outputsDir: resolvedOutputsDir,
-        logDir: path.resolve(options.logDir ?? path.join(resolvedOutputsDir, "logs")),
-        workspacesDir: path.resolve(options.workspacesDir ?? defaultWorkspacesRootForCodeRoot(resolvedCodeRoot)),
+        logDir: resolveUserPath(options.logDir ?? path.join(resolvedOutputsDir, "logs")),
+        workspacesDir: resolveUserPath(options.workspacesDir ?? defaultWorkspacesRootForCodeRoot(resolvedCodeRoot)),
         discoveredRepos: [],
         selectedRepos: [],
         discoveredProviders: [],
@@ -57,11 +58,12 @@ export async function runInit(options) {
         new CheckRequirementsStep(commandRunner),
         new CheckGitHubAuthStep(commandRunner),
         new DiscoverReposStep(commandRunner, ctx.codeRoot),
-        new SelectReposStep(new DemoRepoCreator(commandRunner)),
+        new SelectReposStep(new DemoRepoCreator(commandRunner), nonInteractive ? "existing" : "demo"),
         new ConfigurePathsStep(),
         new DiscoverProvidersStep(commandRunner),
         new ConfigureModelsStep(),
         new GenerateConfigStep(),
+        new ProvisionLabelsStep(commandRunner),
         new ReadinessValidationStep(commandRunner),
         new ShowSummaryStep()
     ];

package/dist/src/cli/runtime/run-context.js

@@ -15,19 +15,19 @@ import { createSmitheryMcpResolverFromEnv, reconcileMcpStatus } from "../../mcps
 import { StateStore } from "../../state/loader.js";
 import { ExecFileCommandRunner } from "../../utils/command-runner.js";
 import { defaultStderrLogger } from "../../utils/logger.js";
-import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, resolveOutputsStateRoot, resolveOutputsLogsRoot, resolveOutputsJournalRoot } from "../../utils/paths.js";
+import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, resolveOutputsStateRoot, resolveOutputsLogsRoot, resolveOutputsJournalRoot, resolveUserPath } from "../../utils/paths.js";
 import { TriageFollowUpService } from "../../workflows/triage.js";
 import { ImplementationWorkflowService } from "../../worktrees/service.js";
 import { WorkspaceRecoveryService } from "../../worktrees/workspace-recovery.js";
 import { DEFAULT_GITHUB_BROKER_PORT as CLI_DEFAULT_GITHUB_BROKER_PORT, readNumberFlag, readOptionalStringFlag, readStringFlag } from "../options.js";
 export async function createRunContext(input) {
     const { rest, options } = input;
-    const managementDir = path.resolve(options.managementDir ?? readStringFlag(rest, "--management-dir", defaultBackburnerManagementRoot()));
+    const managementDir = resolveUserPath(options.managementDir ?? readStringFlag(rest, "--management-dir", defaultBackburnerManagementRoot()));
     const configuredOutputsDir = options.outputsDir ?? readOptionalStringFlag(rest, "--outputs-dir");
-    const outputsDir = path.resolve(configuredOutputsDir ?? defaultBackburnerOutputsRoot());
+    const outputsDir = resolveUserPath(configuredOutputsDir ?? defaultBackburnerOutputsRoot());
     const useLegacyStateDirWithoutOutputs = options.stateDir !== undefined && configuredOutputsDir === undefined;
     const logger = options.logger ?? defaultStderrLogger;
-    const codeRoot = path.resolve(readOptionalStringFlag(rest, "--code-root") ?? defaultBackburnerCodeRoot());
+    const codeRoot = resolveUserPath(readOptionalStringFlag(rest, "--code-root") ?? defaultBackburnerCodeRoot());
     const brokerPort = readNumberFlag(rest, "--broker-port", CLI_DEFAULT_GITHUB_BROKER_PORT);
     const commandRunner = options.commandRunner ?? new ExecFileCommandRunner();
     const gitGateway = options.gitGateway ?? new GitCliGateway(commandRunner);
@@ -48,9 +48,9 @@ export async function createRunContext(input) {
         logger.info(`Preparing outputs root ${outputsDir}`);
         outputsGitOpsPrepared = await gitOpsLifecycle.prepareOutputsRoot(outputsDir);
     }
-    const stateDir = path.resolve(options.stateDir ?? resolveOutputsStateRoot(outputsDir));
+    const stateDir = resolveUserPath(options.stateDir ?? resolveOutputsStateRoot(outputsDir));
     const defaultLogDir = options.stateDir !== undefined ? stateDir : resolveOutputsLogsRoot(outputsDir);
-    const logDir = path.resolve(options.logDir ?? readStringFlag(rest, "--log-dir", defaultLogDir));
+    const logDir = resolveUserPath(options.logDir ?? readStringFlag(rest, "--log-dir", defaultLogDir));
     let managementRepo;
     try {
         const remoteResult = await commandRunner.run("git", ["remote", "get-url", "origin"], { cwd: managementDir });

package/dist/src/onboarding/config-writer.js

@@ -1,6 +1,15 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { writeJsonFileAtomic } from "../utils/json.js";
+export const DEFAULT_BACKBURNER_LABELS = {
+    agentInProgress: "backburner:in-progress",
+    agentPlanApproved: "backburner:plan-approved",
+    agentProductApproved: "backburner:product-approved",
+    agentReview: "backburner:review",
+    planBreakdownNeeded: "backburner:plan-breakdown-needed",
+    agentSyncParentBranch: "backburner:sync-parent-branch",
+    prepareForMerge: "backburner:prepare-for-merge"
+};
 export class ConfigWriter {
     async detectExisting(managementDir) {
         const reposFile = path.join(managementDir, "repos.json");
@@ -55,15 +64,7 @@ function buildRepoEntry(repo) {
         defaultBranch: repo.defaultBranch,
         localPath: repo.localPath,
         enabled: repo.enabled,
-        labels: {
-            agentInProgress: "agent-in-progress",
-            agentPlanApproved: "agent-plan-approved",
-            agentProductApproved: "agent-product-approved",
-            agentReview: "agent-review",
-            planBreakdownNeeded: "plan-breakdown-needed",
-            agentSyncParentBranch: "agent-sync-parent-branch",
-            prepareForMerge: "prepare-for-merge"
-        }
+        labels: repo.labels
     };
 }
 function buildAgentsJson(draft) {

package/dist/src/onboarding/services/label-provisioner.js

@@ -0,0 +1,39 @@
+const LABEL_TIMEOUT_MS = 30_000;
+export class GitHubLabelProvisioner {
+    commandRunner;
+    constructor(commandRunner) {
+        this.commandRunner = commandRunner;
+    }
+    async provisionLabels(targets) {
+        const results = [];
+        for (const target of targets) {
+            const repoSlug = `${target.owner}/${target.name}`;
+            for (const label of target.labels) {
+                try {
+                    await this.commandRunner.run("gh", [
+                        "label",
+                        "create",
+                        label.name,
+                        "--repo",
+                        repoSlug,
+                        "--description",
+                        label.description,
+                        "--color",
+                        label.color,
+                        "--force"
+                    ], { timeoutMs: LABEL_TIMEOUT_MS });
+                    results.push({ repoSlug, labelName: label.name, status: "created_or_updated" });
+                }
+                catch (err) {
+                    results.push({
+                        repoSlug,
+                        labelName: label.name,
+                        status: "failed",
+                        message: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            }
+        }
+        return results;
+    }
+}

package/dist/src/onboarding/steps/configure-paths.js

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, defaultWorkspacesRootForCodeRoot } from "../../utils/paths.js";
+import { defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot, defaultWorkspacesRootForCodeRoot, resolveUserPath } from "../../utils/paths.js";
 export class ConfigurePathsStep {
     name = "configure-paths";
     description = "Configure directories";
@@ -15,10 +15,10 @@ export class ConfigurePathsStep {
         const outputsDir = await prompter.ask("Outputs directory (state, logs):", defaultOutputs);
         const logDir = await prompter.ask("Log directory:", ctx.logDir || path.join(outputsDir || defaultOutputs, "logs"));
         const workspacesDir = await prompter.ask("Local workspaces directory (where Backburner creates git worktrees):", defaultWorkspaces);
-        ctx.managementDir = managementDir || defaultManagement;
-        ctx.outputsDir = outputsDir || defaultOutputs;
-        ctx.logDir = logDir || path.join(ctx.outputsDir, "logs");
-        ctx.workspacesDir = workspacesDir || defaultWorkspaces;
+        ctx.managementDir = resolveUserPath(managementDir || defaultManagement);
+        ctx.outputsDir = resolveUserPath(outputsDir || defaultOutputs);
+        ctx.logDir = resolveUserPath(logDir || path.join(ctx.outputsDir, "logs"));
+        ctx.workspacesDir = resolveUserPath(workspacesDir || defaultWorkspaces);
         return {
             status: "passed",
             message: "Directories configured",

package/dist/src/onboarding/steps/generate-config.js

@@ -1,5 +1,6 @@
 import * as path from "node:path";
 import { ConfigWriter } from "../config-writer.js";
+import { DEFAULT_BACKBURNER_LABELS } from "../config-writer.js";
 export class GenerateConfigStep {
     name = "generate-config";
     description = "Generating configuration";
@@ -101,6 +102,7 @@ function buildRepoDraft(repo, codeRoot) {
         name: repo.name,
         localPath,
         defaultBranch: repo.defaultBranch || "main",
-        enabled: true
+        enabled: true,
+        labels: { ...DEFAULT_BACKBURNER_LABELS }
     };
 }

package/dist/src/onboarding/steps/provision-labels.js

@@ -0,0 +1,104 @@
+import { GitHubLabelProvisioner } from "../services/label-provisioner.js";
+const LABEL_DEFINITIONS = {
+    agentInProgress: {
+        description: "Backburner is actively working on this item.",
+        color: "6F42C1"
+    },
+    agentProductApproved: {
+        description: "Approve Backburner to start product discovery from this issue.",
+        color: "2DA44E"
+    },
+    agentPlanApproved: {
+        description: "Approve Backburner to implement an accepted plan.",
+        color: "0969DA"
+    },
+    agentReview: {
+        description: "Ask Backburner to review this pull request.",
+        color: "BF8700"
+    },
+    planBreakdownNeeded: {
+        description: "Ask Backburner to break a plan into implementation packets.",
+        color: "8250DF"
+    },
+    agentSyncParentBranch: {
+        description: "Allow Backburner to sync the parent branch from the default branch.",
+        color: "1F883D"
+    },
+    prepareForMerge: {
+        description: "Ask Backburner to prepare this pull request for merge.",
+        color: "CF222E"
+    }
+};
+export class ProvisionLabelsStep {
+    commandRunner;
+    name = "provision-labels";
+    description = "Creating GitHub labels";
+    constructor(commandRunner) {
+        this.commandRunner = commandRunner;
+    }
+    async run(ctx, _prompter) {
+        const draft = ctx.configDraft;
+        if (draft === undefined || draft.repos.length === 0) {
+            return {
+                status: "skipped",
+                message: "Skipped: no repositories selected for label creation"
+            };
+        }
+        const targets = buildLabelTargets(draft);
+        const provisioner = new GitHubLabelProvisioner(this.commandRunner);
+        const results = await provisioner.provisionLabels(targets);
+        const failures = results.filter((result) => result.status === "failed");
+        if (failures.length > 0) {
+            ctx.warnings.push("Some GitHub labels could not be created. You can retry onboarding or create them manually from repos.json.");
+            return {
+                status: "warning",
+                message: `Created labels with ${failures.length} failure${failures.length === 1 ? "" : "s"}`,
+                details: [
+                    ...failures.map((failure) => {
+                        const suffix = failure.message !== undefined ? `: ${failure.message}` : "";
+                        return `${failure.repoSlug}: ${failure.labelName}${suffix}`;
+                    }),
+                    ...buildManualLabelDetails(targets)
+                ]
+            };
+        }
+        return {
+            status: "passed",
+            message: `Created or updated ${results.length} GitHub label${results.length === 1 ? "" : "s"}`,
+            details: targets.map((target) => `${target.owner}/${target.name}: ${target.labels.length} labels`)
+        };
+    }
+}
+function buildManualLabelDetails(targets) {
+    return targets.flatMap((target) => {
+        const repoSlug = `${target.owner}/${target.name}`;
+        return [
+            `Manual labels page for ${repoSlug}: https://github.com/${repoSlug}/labels`,
+            `Required labels: ${target.labels.map((label) => label.name).join(", ")}`
+        ];
+    });
+}
+function buildLabelTargets(draft) {
+    return draft.repos.map((repo) => ({
+        owner: repo.owner,
+        name: repo.name,
+        labels: buildRepoLabels(repo)
+    }));
+}
+function buildRepoLabels(repo) {
+    return [
+        buildLabel("agentInProgress", repo.labels.agentInProgress),
+        buildLabel("agentProductApproved", repo.labels.agentProductApproved),
+        buildLabel("agentPlanApproved", repo.labels.agentPlanApproved),
+        buildLabel("agentReview", repo.labels.agentReview),
+        buildLabel("planBreakdownNeeded", repo.labels.planBreakdownNeeded),
+        buildLabel("agentSyncParentBranch", repo.labels.agentSyncParentBranch),
+        buildLabel("prepareForMerge", repo.labels.prepareForMerge)
+    ];
+}
+function buildLabel(key, name) {
+    return {
+        name,
+        ...LABEL_DEFINITIONS[key]
+    };
+}

package/dist/src/onboarding/steps/select-repos.js

@@ -1,10 +1,12 @@
 import { defaultDemoRepoName } from "../services/demo-repo.js";
 export class SelectReposStep {
     demoRepoCreator;
+    defaultSetupChoice;
     name = "select-repos";
     description = "Select repositories to manage";
-    constructor(demoRepoCreator) {
+    constructor(demoRepoCreator, defaultSetupChoice = "demo") {
         this.demoRepoCreator = demoRepoCreator;
+        this.defaultSetupChoice = defaultSetupChoice;
     }
     async run(ctx, prompter) {
         const { discoveredRepos } = ctx;
@@ -55,36 +57,52 @@ export class SelectReposStep {
     }
     async promptSetupChoice(ctx, prompter) {
         const hasDiscoveredRepos = ctx.discoveredRepos.length > 0;
-        const options = [
-            hasDiscoveredRepos
-                ? "Select existing repositories"
-                : "Enter an existing repository manually",
-            ...(ctx.githubUser !== undefined ? ["Create a private Backburner demo repo"] : []),
-            "Skip repository setup for now"
-        ];
-        const choice = await prompter.choose("How do you want to set up repositories?", options, 0);
+        const existingLabel = hasDiscoveredRepos
+            ? "Select existing repositories (Backburner will create/update its labels on them)"
+            : "Enter an existing repository manually";
+        const hasDemoOption = ctx.githubUser !== undefined;
+        const options = hasDemoOption
+            ? ["Create a private Backburner demo repo", existingLabel, "Skip repository setup for now"]
+            : [existingLabel, "Skip repository setup for now"];
+        const defaultIndex = hasDemoOption && this.defaultSetupChoice === "existing" ? 1 : 0;
+        const choice = await prompter.choose("How do you want to set up repositories?", options, defaultIndex);
+        if (hasDemoOption) {
+            if (choice === 0) {
+                return "demo";
+            }
+            if (choice === 1) {
+                return "existing";
+            }
+            return "skip";
+        }
         if (choice === 0) {
             return "existing";
         }
-        if (ctx.githubUser !== undefined && choice === 1) {
-            return "demo";
-        }
         return "skip";
     }
     async promptNoSelection(ctx, prompter) {
-        const options = [
-            "Add an existing repository manually",
-            ...(ctx.githubUser !== undefined ? ["Create a private Backburner demo repo"] : []),
-            "Skip repository setup for now"
-        ];
+        const hasDemoOption = ctx.githubUser !== undefined;
+        const options = hasDemoOption
+            ? [
+                "Create a private Backburner demo repo",
+                "Add an existing repository manually",
+                "Skip repository setup for now"
+            ]
+            : ["Add an existing repository manually", "Skip repository setup for now"];
         const defaultIndex = 0;
         const choice = await prompter.choose("No repositories selected. How do you want to continue?", options, defaultIndex);
+        if (hasDemoOption) {
+            if (choice === 0) {
+                return await this.promptCreateDemoRepo(ctx, prompter);
+            }
+            if (choice === 1) {
+                return await this.promptManualEntry(ctx, prompter);
+            }
+            return this.noRepositoryWarning();
+        }
         if (choice === 0) {
             return await this.promptManualEntry(ctx, prompter);
         }
-        if (ctx.githubUser !== undefined && choice === 1) {
-            return await this.promptCreateDemoRepo(ctx, prompter);
-        }
         return this.noRepositoryWarning();
     }
     async promptCreateDemoRepo(ctx, prompter) {
@@ -106,7 +124,7 @@ export class SelectReposStep {
                 details: ["Repository names can contain letters, numbers, dots, underscores, and hyphens."]
             };
         }
-        const confirmed = await prompter.confirm(`Create private GitHub repository ${ctx.githubUser}/${repoName} and clone it under ${ctx.codeRoot}?`, false);
+        const confirmed = await prompter.confirm(`Create private GitHub repository ${ctx.githubUser}/${repoName} and clone it under ${ctx.codeRoot}?`, true);
         if (!confirmed) {
             return this.noRepositoryWarning();
         }

package/dist/src/onboarding/steps/show-summary.js

@@ -1,6 +1,9 @@
 import { deriveOverallStatus } from "../engine.js";
 import * as path from "node:path";
+import { createRequire } from "node:module";
 import { defaultBackburnerCodeRoot, defaultBackburnerManagementRoot, defaultBackburnerOutputsRoot } from "../../utils/paths.js";
+const require = createRequire(import.meta.url);
+const terminalQr = require("qrcode-terminal");
 export class ShowSummaryStep {
     name = "show-summary";
     description = "Summary";
@@ -62,13 +65,23 @@ export class ShowSummaryStep {
             }
         }
         if (succeeded) {
+            const issueTarget = buildFirstIssueTarget(ctx);
             lines.push("");
             lines.push("Next steps:");
-            lines.push("  1. Create the configured GitHub labels on each managed repository");
-            lines.push("  2. Start the orchestrator:");
+            lines.push("  1. Start the orchestrator:");
             lines.push(`     ${buildRunCommand(ctx)}`);
-            lines.push("  3. Open an issue on a managed repo and apply the 'agent-plan-approved' label");
-            lines.push("  4. Watch Backburner pick it up on the next orchestration cycle");
+            if (issueTarget !== undefined) {
+                lines.push("  2. Open a Backburner issue:");
+                lines.push(`     ${issueTarget.prefilledIssueUrl}`);
+                lines.push("  3. Watch Backburner pick it up on the next orchestration cycle");
+                lines.push("");
+                lines.push("Repository issues QR:");
+                lines.push(renderQr(issueTarget.repositoryIssuesUrl));
+            }
+            else {
+                lines.push("  2. Add a repository to repos.json");
+                lines.push("  3. Open an issue on a managed repo with the configured product-approved label");
+            }
         }
         else {
             lines.push("");
@@ -79,6 +92,43 @@ export class ShowSummaryStep {
         return { status: "passed", message: "Summary displayed" };
     }
 }
+function buildFirstIssueTarget(ctx) {
+    const repo = ctx.configDraft?.repos[0];
+    if (repo === undefined) {
+        return undefined;
+    }
+    const url = new URL(`https://github.com/${repo.owner}/${repo.name}/issues/new`);
+    url.searchParams.set("title", "Initialize a TypeScript React Native kitchen measurement converter");
+    url.searchParams.set("body", [
+        "Create a small TypeScript React Native application for converting common kitchen measurements.",
+        "",
+        "Goal:",
+        "- Let a cook enter a quantity, choose a source unit, choose a target unit, and see the converted value.",
+        "",
+        "Requirements:",
+        "- Use TypeScript.",
+        "- Support cups, tablespoons, teaspoons, milliliters, liters, fluid ounces, ounces, grams, and kilograms.",
+        "- Include a simple conversion screen with clear input validation and useful empty/error states.",
+        "- Keep the implementation small and easy to review.",
+        "",
+        "Acceptance criteria:",
+        "- The app can convert at least 1 cup to tablespoons, milliliters, and fluid ounces.",
+        "- Invalid or empty input does not crash the app.",
+        "- Add or update tests for the conversion logic where the project test setup supports it."
+    ].join("\n"));
+    url.searchParams.set("labels", repo.labels.agentProductApproved);
+    return {
+        prefilledIssueUrl: url.toString(),
+        repositoryIssuesUrl: `https://github.com/${repo.owner}/${repo.name}/issues`
+    };
+}
+function renderQr(input) {
+    let rendered = "";
+    terminalQr.generate(input, { small: true }, (qr) => {
+        rendered = qr.trimEnd();
+    });
+    return rendered;
+}
 function buildRunCommand(ctx) {
     const args = ["backburner", "run"];
     if (ctx.codeRoot !== defaultBackburnerCodeRoot()) {

package/dist/src/onboarding/steps/welcome.js

@@ -18,7 +18,8 @@ export class WelcomeStep {
             "  5. Detecting available AI providers",
             "  6. Assigning models to agent roles",
             "  7. Generating configuration files",
-            "  8. Running a final readiness check",
+            "  8. Creating configured GitHub labels",
+            "  9. Running a final readiness check",
             ""
         ];
         process.stdout.write(lines.join("\n"));

package/dist/src/utils/paths.js

@@ -18,9 +18,21 @@ export const outputsJournalRoot = path.join(outputsRoot, "journal");
 export function resolveOutputsJournalRoot(outputsDir) {
     return path.join(outputsDir, "journal");
 }
+export function expandHomePath(input) {
+    if (input === "~") {
+        return os.homedir();
+    }
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        return path.join(os.homedir(), input.slice(2));
+    }
+    return input;
+}
+export function resolveUserPath(input) {
+    return path.resolve(expandHomePath(input));
+}
 export function defaultBackburnerRoot() {
     if (process.env.BACKBURNER_ROOT !== undefined && process.env.BACKBURNER_ROOT.trim() !== "") {
-        return process.env.BACKBURNER_ROOT;
+        return resolveUserPath(process.env.BACKBURNER_ROOT);
     }
     return path.join(os.homedir(), ".backburner");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backburner/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Local GitHub-based agent orchestration CLI",
   "license": "MIT",
@@ -55,6 +55,7 @@
   "dependencies": {
     "@smithery/api": "^0.67.0",
     "cross-spawn": "^7.0.6",
+    "qrcode-terminal": "^0.12.0",
     "xstate": "^5.31.0",
     "zod": "^4.4.3"
   }