@ramon-sg/issue-flow 0.2.5 → 0.2.6

package/README.md

@@ -8,6 +8,7 @@ Flujo de trabajo de issue a PR para cualquier repo, en local y en las sesiones d
 
 - **`issue-flow init|doctor|upgrade`:** escribe, revisa y mueve a su versión lo que el flujo deja en el repo: `.agents/flow.json` con sus recetas, las dependencias y los hooks. Los corre `agent-kitchen`.
 - **`issue-flow issue branch <n>`:** propone la rama de una issue (con Claude por defecto, o desde el título). Con `--missing`, agrega el slug de rama a todas las issues abiertas que no lo tienen.
+- **`issue-flow labels sync`:** crea en GitHub los labels que el flujo espera y le faltan al repo: los de tipo y `P1` a `P4`, con los mismos colores en todos los repos.
 - **`issue-flow issue start <n>`:** crea la rama y el worktree, hace el commit inicial, abre el PR en draft, asigna la issue y abre Claude. Con `--cloud`, lo hace en una sesión en la nube.
 - **`issue-flow worktree setup|teardown|ports|cleanup|prune`:** prepara y limpia cada worktree con los pasos del repo, le da un bloque de puertos y borra los worktrees con el PR cerrado.
 - **`issue-flow pr worktree <n>`:** abre un PR en su propio worktree, en la rama del PR, para revisarlo sin soltar lo que estás haciendo.
@@ -270,6 +271,40 @@ Todo es opcional; sin el archivo valen los valores por defecto. Una clave descon
 | `start.cloudPrompt` | `/start-issue {number} --yes{flags}` | Lo que `--cloud` le pide a la sesión; `{flags}` es `--new` o `--resume <rama>` |
 | `plans.dirs` | `docs/plans`, `docs/specs` | Dónde buscar el plan de la issue: lo que tocó la rama, o el documento cuyo `prs:` nombra su PR |
 | `colors` | `critical-path` y `P1:` rojo, `P2:` naranjo, `P3:` amarillo, `P4:` cian | Color de la sesión por prefijo de label; gana el primero que calce |
+| `labels` | Los 8 de abajo | Labels que crea `labels sync`; lo del repo se suma al default (ver abajo) |
+
+## Labels: `issue-flow labels sync`
+
+```sh
+npx @ramon-sg/issue-flow labels sync --dry-run   # qué haría
+npx @ramon-sg/issue-flow labels sync             # crea los que faltan
+npx @ramon-sg/issue-flow labels sync --update    # también corrige color y descripción
+```
+
+Crea en GitHub los labels de `labels` que el repo no tiene. Los nombres se comparan sin mayúsculas, como en GitHub: un `Bug` cuenta como `bug` y nunca se renombra. Uno que existe con otro color o descripción solo se avisa, salvo con `--update`. Nunca borra. `--json` da la lista con el estado de cada uno: `created`, `updated`, `ok`, `differs`, o `to-create` y `to-update` con `--dry-run`. Si GitHub rechaza uno, sigue con los demás, lo marca `failed` y sale con 1.
+
+| Label | Color | Descripción |
+|---|---|---|
+| `bug` | `d73a4a` | Something isn't working |
+| `enhancement` | `a2eeef` | New feature or request |
+| `documentation` | `0075ca` | Improvements or additions to documentation |
+| `spike` | `fbca04` | Time-boxed research before building |
+| `P1: urgent` | `B60205` | Breaks production or blocks work |
+| `P2: important` | `F9D0C4` | Real impact, with some slack |
+| `P3: minor` | `FEF2C0` | Default when in doubt |
+| `P4: low` | `BFDADC` | Nice-to-have |
+
+Los tres primeros son los de GitHub, con sus colores y textos. A diferencia de `branch.types` y `colors`, lo que pone el repo **se suma** al default: un nombre reemplaza al de por defecto con ese nombre, y `null` lo quita. La taxonomía del repo va acá y no en el `project.md` de `github-issues`, porque con `claude-repo-guard` el agente no puede escribir en `.agents/skills/`:
+
+```json
+{
+  "labels": {
+    "area:api": { "color": "1d76db", "description": "packages/api" },
+    "size:S": { "color": "c5def5", "description": "Menos de 1 día" },
+    "spike": null
+  }
+}
+```
 
 ## Desarrollo
 

package/dist/cli.d.ts

@@ -84,6 +84,9 @@ declare const OPTIONS: {
     readonly recipe: {
         readonly type: "string";
     };
+    readonly update: {
+        readonly type: "boolean";
+    };
 };
 /** The parsed flags. */
 export type Flags = ReturnType<typeof parseArgs<{

package/dist/cli.js

@@ -8,6 +8,7 @@ import { parseArgs } from "node:util";
 import { GitHubError, InvalidRepoEnvError, resolveRepo } from "@ramon-sg/github-rest";
 import { branchMissing, branchOf } from "./commands/issue-branch.js";
 import { issueStart } from "./commands/issue-start.js";
+import { labelsSync } from "./commands/labels.js";
 import { ADAPTER_COMMANDS, HOOK_COMMANDS, runAdapter, runHook, runSession, runWorktree, WORKTREE_COMMANDS } from "./cli-worktree.js";
 import { runSetupCommand, SETUP_COMMANDS } from "./cli-setup.js";
 import { prWorktree } from "./commands/pr-worktree.js";
@@ -41,6 +42,7 @@ const OPTIONS = {
     next: { type: "boolean" },
     "no-setup": { type: "boolean" },
     recipe: { type: "string" },
+    update: { type: "boolean" },
 };
 /** Flags each command takes, besides `--repo`, `--help` and `--namer`. */
 const COMMAND_FLAGS = {
@@ -75,6 +77,7 @@ const COMMAND_FLAGS = {
     init: ["yes", "recipe"],
     doctor: ["json"],
     upgrade: ["dry-run"],
+    "labels sync": ["update", "dry-run", "json"],
 };
 /** An issue number: digits only. */
 const NUMBER = /^\d+$/;
@@ -216,6 +219,8 @@ export async function main(argv, out, cwd) {
         throw new UsageError("-- only goes with pr worktree.");
     if (group === "pr")
         return runPr(sub, rest, flags, { out, cwd, command });
+    if (group === "labels")
+        return runLabels(sub, rest, flags, { out, cwd });
     if (group !== undefined && SETUP_COMMANDS.includes(group)) {
         ownFlags(group, flags);
         return runSetupCommand(group, flags, [sub, ...rest].filter((item) => item !== undefined), { out, cwd });
@@ -253,6 +258,24 @@ async function runPr(sub, rest, flags, run) {
     const config = loadConfig(run.cwd);
     return prWorktree({ repo: repoOf(flags.repo, config, run.cwd), config, cwd: run.cwd, number: Number(text), setup: !(flags["no-setup"] ?? false), command: run.command }, run.out);
 }
+/**
+ * Runs `issue-flow labels sync`.
+ * @param sub - The word after `labels`.
+ * @param rest - The positionals after it.
+ * @param flags - The flags.
+ * @param run - Where it writes and runs.
+ * @returns The exit code.
+ * @throws UsageError if the arguments do not fit; GitHubError if GitHub fails.
+ */
+async function runLabels(sub, rest, flags, run) {
+    if (sub !== "sync")
+        throw new UsageError("labels expects sync.");
+    ownFlags("labels sync", flags);
+    if (rest.length > 0)
+        throw new UsageError("labels sync takes no arguments.");
+    const config = loadConfig(run.cwd);
+    return labelsSync({ repo: repoOf(flags.repo, config, run.cwd), labels: config.labels, update: flags.update ?? false, dryRun: flags["dry-run"] ?? false, json: flags.json ?? false }, run.out);
+}
 /**
  * Runs the `issue`, `worktree` and `session` commands.
  * @param group - The first word.

package/dist/commands/labels.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file `issue-flow labels sync [--update] [--dry-run] [--json]`: makes in GitHub the labels
+ * of `labels` in `.agents/flow.json` that the repo lacks. Names compare ignoring case, as
+ * GitHub does, so `Bug` counts as `bug` and is never renamed. A label that exists with
+ * another color or description is only reported, unless `--update`. It never deletes. A
+ * write that fails does not stop the rest: every label is reported, and it exits 1.
+ */
+import { type Label } from "@ramon-sg/github-rest";
+import type { LabelSpec } from "../config.js";
+import { type Output } from "../output.js";
+/**
+ * What happened to one label: with `--dry-run`, `to-create` and `to-update` instead of
+ * `created` and `updated`; `failed` when GitHub refused the write.
+ */
+export type LabelStatus = "created" | "updated" | "ok" | "differs" | "to-create" | "to-update" | "failed";
+/** One label of the result. */
+export interface LabelResult {
+    name: string;
+    status: LabelStatus;
+    color: string;
+    description: string;
+    /** What GitHub has, when it differs. */
+    found?: {
+        color: string;
+        description: string;
+    };
+    /** Why the write failed. */
+    error?: string;
+}
+/** The options of `labels sync`. */
+export interface LabelsSyncOptions {
+    repo: string;
+    labels: Record<string, LabelSpec>;
+    update: boolean;
+    dryRun: boolean;
+    json: boolean;
+}
+/**
+ * What to do with each label, before writing anything.
+ * @param wanted - The labels of the config.
+ * @param existing - The labels in GitHub.
+ * @param update - Whether to fix the ones that differ.
+ * @returns Each label with its status, as if every write worked, and its name in GitHub if it exists.
+ */
+export declare function planLabels(wanted: Record<string, LabelSpec>, existing: Label[], update: boolean): LabelResult[];
+/**
+ * Runs `labels sync`; see the file's header.
+ * @param options - The repo, the labels and the flags.
+ * @param out - Where to write.
+ * @returns 0 when done; 1 if GitHub's list came back cut short (nothing is written then) or a write failed.
+ * @throws GitHubError if GitHub fails to list the labels.
+ * @example await labelsSync({ repo: "acme/widgets", labels, update: false, dryRun: true, json: false }, out)
+ */
+export declare function labelsSync(options: LabelsSyncOptions, out: Output): Promise<number>;

package/dist/commands/labels.js

@@ -0,0 +1,113 @@
+/**
+ * @file `issue-flow labels sync [--update] [--dry-run] [--json]`: makes in GitHub the labels
+ * of `labels` in `.agents/flow.json` that the repo lacks. Names compare ignoring case, as
+ * GitHub does, so `Bug` counts as `bug` and is never renamed. A label that exists with
+ * another color or description is only reported, unless `--update`. It never deletes. A
+ * write that fails does not stop the rest: every label is reported, and it exits 1.
+ */
+import { createLabel, listLabels } from "@ramon-sg/github-rest";
+import { emitJson } from "../output.js";
+/** Width of the status column in the text output. */
+const STATUS_WIDTH = 10;
+/**
+ * Whether a label in GitHub has the wanted color and description (colors ignore case).
+ * @param found - The label in GitHub.
+ * @param spec - The wanted one.
+ * @returns True if they match.
+ */
+function matches(found, spec) {
+    return found.color.toLowerCase() === spec.color.toLowerCase() && found.description === spec.description;
+}
+/**
+ * What to do with each label, before writing anything.
+ * @param wanted - The labels of the config.
+ * @param existing - The labels in GitHub.
+ * @param update - Whether to fix the ones that differ.
+ * @returns Each label with its status, as if every write worked, and its name in GitHub if it exists.
+ */
+export function planLabels(wanted, existing, update) {
+    const byName = new Map(existing.map((label) => [label.name.toLowerCase(), label]));
+    return Object.entries(wanted).map(([name, spec]) => {
+        const found = byName.get(name.toLowerCase());
+        const base = { name, color: spec.color, description: spec.description };
+        if (found === undefined)
+            return { ...base, status: "created" };
+        if (matches(found, spec))
+            return { ...base, name: found.name, status: "ok" };
+        return { ...base, name: found.name, status: update ? "updated" : "differs", found: { color: found.color, description: found.description } };
+    });
+}
+/** The word of each status in the text output. */
+const WORDS = {
+    created: "created",
+    updated: "updated",
+    ok: "ok",
+    differs: "differs",
+    "to-create": "to create",
+    "to-update": "to update",
+    failed: "failed",
+};
+/**
+ * One line of the text output.
+ * @param result - The label.
+ * @returns The line.
+ */
+function line(result) {
+    const head = `${WORDS[result.status].padEnd(STATUS_WIDTH)}${result.name}`;
+    if (result.error !== undefined)
+        return `${head}: ${result.error}`;
+    if (result.found === undefined)
+        return head;
+    const was = `${result.found.color} "${result.found.description}"`;
+    const wanted = `${result.color} "${result.description}"`;
+    return result.status === "differs" ? `${head}: has ${was}, the flow wants ${wanted} (--update fixes it)` : `${head}: ${was} → ${wanted}`;
+}
+/**
+ * Writes one label and says how it went. A label that appeared in GitHub after the list
+ * was read fails without `--update`, with a message that says to run it again.
+ * @param repo - `owner/repo`.
+ * @param result - The label, as planned.
+ * @returns The label with its final status.
+ */
+async function write(repo, result) {
+    try {
+        await createLabel(repo, { name: result.name, color: result.color, description: result.description, force: result.status === "updated" });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const appeared = result.status === "created" && message.includes("already exists");
+        return { ...result, status: "failed", error: appeared ? "it appeared in GitHub meanwhile: run labels sync again" : message };
+    }
+}
+/**
+ * Runs `labels sync`; see the file's header.
+ * @param options - The repo, the labels and the flags.
+ * @param out - Where to write.
+ * @returns 0 when done; 1 if GitHub's list came back cut short (nothing is written then) or a write failed.
+ * @throws GitHubError if GitHub fails to list the labels.
+ * @example await labelsSync({ repo: "acme/widgets", labels, update: false, dryRun: true, json: false }, out)
+ */
+export async function labelsSync(options, out) {
+    const { labels: existing, truncated } = await listLabels(options.repo);
+    if (truncated) {
+        out.stderr(`issue-flow: could not read every label of ${options.repo}; nothing written, so no label is made twice.\n`);
+        return 1;
+    }
+    const results = [];
+    for (const item of planLabels(options.labels, existing, options.update)) {
+        const writes = item.status === "created" || item.status === "updated";
+        // NOTE: one at a time, as GitHub asks of writes, to stay clear of its secondary rate limit.
+        if (!writes)
+            results.push(item);
+        else if (options.dryRun)
+            results.push({ ...item, status: item.status === "created" ? "to-create" : "to-update" });
+        else
+            results.push(await write(options.repo, item));
+    }
+    if (options.json)
+        emitJson(out, { repo: options.repo, dryRun: options.dryRun, labels: results });
+    else
+        out.stdout(`${results.map(line).join("\n")}\n`);
+    return results.some((result) => result.status === "failed") ? 1 : 0;
+}

package/dist/config.d.ts

@@ -6,6 +6,11 @@ export interface TypeRules {
     labels: Record<string, string>;
     titlePrefixes: Record<string, string>;
 }
+/** A label the flow wants in the repo: its color (hex, no `#`) and description. */
+export interface LabelSpec {
+    color: string;
+    description: string;
+}
 /** The whole config, with every default applied. */
 export interface FlowConfig {
     repo: string | null;
@@ -30,6 +35,7 @@ export interface FlowConfig {
         dirs: string[];
     };
     colors: Record<string, string>;
+    labels: Record<string, LabelSpec>;
 }
 /** The defaults, the same rules Abastio uses. */
 export declare const DEFAULT_CONFIG: FlowConfig;

package/dist/config.js

@@ -49,6 +49,16 @@ export const DEFAULT_CONFIG = {
         "P3:": "yellow",
         "P4:": "cyan",
     },
+    labels: {
+        bug: { color: "d73a4a", description: "Something isn't working" },
+        enhancement: { color: "a2eeef", description: "New feature or request" },
+        documentation: { color: "0075ca", description: "Improvements or additions to documentation" },
+        spike: { color: "fbca04", description: "Time-boxed research before building" },
+        "P1: urgent": { color: "B60205", description: "Breaks production or blocks work" },
+        "P2: important": { color: "F9D0C4", description: "Real impact, with some slack" },
+        "P3: minor": { color: "FEF2C0", description: "Default when in doubt" },
+        "P4: low": { color: "BFDADC", description: "Nice-to-have" },
+    },
 };
 /** The colors a Claude session takes with `/color`. */
 export const SESSION_COLORS = ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"];
@@ -171,6 +181,55 @@ function colorsSection(value) {
     }
     return value;
 }
+/** A label color: six hex digits, without `#`. */
+const LABEL_COLOR = /^[0-9a-fA-F]{6}$/;
+/** A label name: no spaces at the ends, since GitHub trims them. */
+const LABEL_NAME = /^\S(?:.*\S)?$/;
+/** GitHub's limits for a label's name and description, in characters. */
+const LABEL_NAME_MAX = 50;
+const LABEL_DESCRIPTION_MAX = 100;
+/**
+ * The `labels` map: the labels `labels sync` makes in the repo. Unlike the other maps, it
+ * merges over the default, because a repo usually adds labels: a name replaces the default
+ * of the same name (ignoring case, as GitHub does) and `null` drops it.
+ * @param value - The map, or undefined.
+ * @returns The labels.
+ * @throws ConfigError if a label is invalid.
+ * @example labelsSection({ spike: null, "area:api": { color: "1d76db" } })["area:api"].description // ""
+ */
+function labelsSection(value) {
+    if (value === undefined)
+        return DEFAULT_CONFIG.labels;
+    if (!isObject(value))
+        throw new ConfigError(`${CONFIG_PATH}: "labels" must be an object.`);
+    // NOTE: a Map, so a "__proto__" key from JSON.parse stays a label and not the prototype.
+    const labels = new Map(Object.entries(DEFAULT_CONFIG.labels));
+    const seen = new Set();
+    for (const [name, spec] of Object.entries(value)) {
+        const where = `labels.${name}`;
+        if (!LABEL_NAME.test(name) || [...name].length > LABEL_NAME_MAX)
+            throw new ConfigError(`${CONFIG_PATH}: "${where}" needs a name of 1 to ${LABEL_NAME_MAX} characters, without spaces at the ends.`);
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            throw new ConfigError(`${CONFIG_PATH}: "labels" has "${name}" twice (names ignore case).`);
+        seen.add(key);
+        for (const known of [...labels.keys()])
+            if (known.toLowerCase() === key)
+                labels.delete(known);
+        if (spec === null)
+            continue;
+        if (!isObject(spec))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}" must be an object or null.`);
+        onlyKeys(spec, ["color", "description"], where);
+        if (typeof spec.color !== "string" || !LABEL_COLOR.test(spec.color))
+            throw new ConfigError(`${CONFIG_PATH}: "${where}.color" must be six hex digits, without #, such as "1d76db".`);
+        const description = spec.description ?? "";
+        if (typeof description !== "string" || [...description].length > LABEL_DESCRIPTION_MAX)
+            throw new ConfigError(`${CONFIG_PATH}: "${where}.description" must be a string of up to ${LABEL_DESCRIPTION_MAX} characters.`);
+        labels.set(name, { color: spec.color, description });
+    }
+    return Object.fromEntries(labels);
+}
 /**
  * Validates a parsed config and fills in the defaults.
  * @param raw - The parsed JSON.
@@ -181,7 +240,7 @@ function colorsSection(value) {
 export function parseConfig(raw) {
     if (!isObject(raw))
         throw new ConfigError(`${CONFIG_PATH} must be a JSON object.`);
-    onlyKeys(raw, ["repo", "baseBranch", "branch", "worktrees", "start", "plans", "colors"], "");
+    onlyKeys(raw, ["repo", "baseBranch", "branch", "worktrees", "start", "plans", "colors", "labels"], "");
     const repo = text(raw.repo, "repo", null);
     if (repo !== null && !REPO.test(repo))
         throw new ConfigError(`${CONFIG_PATH}: "repo" must be owner/repo.`);
@@ -193,6 +252,7 @@ export function parseConfig(raw) {
         start: textSection(raw.start, "start", DEFAULT_CONFIG.start),
         plans: plansSection(raw.plans),
         colors: colorsSection(raw.colors),
+        labels: labelsSection(raw.labels),
     };
 }
 /**

package/dist/usage.d.ts

@@ -2,4 +2,4 @@
  * @file The usage text of the CLI, printed with `--help` and after a usage error.
  */
 /** Usage text. */
-export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow init [--yes] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow upgrade [--dry-run]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\ninit sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),\nthe dev dependencies and scripts, and the hooks. doctor checks them at this version, and\nupgrade moves them to this version. npx agent-kitchen runs the three, along with the\nskills, claude-cloud and claude-repo-guard.";
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow init [--yes] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow upgrade [--dry-run]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, and with no sandbox nor questions with --free. --plan prints the branch\nand the prompt as JSON and changes nothing.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\ninit sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),\nthe dev dependencies and scripts, and the hooks. doctor checks them at this version, and\nupgrade moves them to this version. npx agent-kitchen runs the three, along with the\nskills, claude-cloud and claude-repo-guard.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";

package/dist/usage.js

@@ -21,6 +21,7 @@ export const USAGE = `Usage:
   issue-flow init [--yes] [--recipe <name>,...]
   issue-flow doctor [--json]
   issue-flow upgrade [--dry-run]
+  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]
 
 The slug comes from the issue's "Slug de rama" block, then from Claude, then from the title,
 and the branch from the repo's template (an older "Rama sugerida" block is used if it fits).
@@ -51,4 +52,8 @@ Code's WorktreeCreate and WorktreeRemove for claude --worktree.
 init sets the flow up in the repo: .agents/flow.json (with the recipes its files suggest),
 the dev dependencies and scripts, and the hooks. doctor checks them at this version, and
 upgrade moves them to this version. npx agent-kitchen runs the three, along with the
-skills, claude-cloud and claude-repo-guard.`;
+skills, claude-cloud and claude-repo-guard.
+
+labels sync makes in GitHub the labels the flow wants ("labels" in .agents/flow.json: the
+issue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never
+renamed nor deleted; --update also fixes the color and description of those that differ.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Issue-to-PR workflow for any repo: names each issue's branch, creates its worktree, opens the draft PR and launches Claude Code, locally and in Claude's cloud.",
   "license": "MIT",
   "type": "module",

package/schema.json

@@ -267,6 +267,50 @@
         "P3:": "yellow",
         "P4:": "cyan"
       }
+    },
+    "labels": {
+      "description": "Labels that `issue-flow labels sync` makes in GitHub when the repo lacks them. Merges over the default: a name replaces the default of the same name (ignoring case) and null drops it.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^\\S(?:.*\\S)?$",
+        "maxLength": 50
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "null"
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "color"
+            ],
+            "properties": {
+              "color": {
+                "description": "Six hex digits, without #.",
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{6}$"
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100,
+                "default": ""
+              }
+            }
+          }
+        ]
+      },
+      "default": {
+        "bug": { "color": "d73a4a", "description": "Something isn't working" },
+        "enhancement": { "color": "a2eeef", "description": "New feature or request" },
+        "documentation": { "color": "0075ca", "description": "Improvements or additions to documentation" },
+        "spike": { "color": "fbca04", "description": "Time-boxed research before building" },
+        "P1: urgent": { "color": "B60205", "description": "Breaks production or blocks work" },
+        "P2: important": { "color": "F9D0C4", "description": "Real impact, with some slack" },
+        "P3: minor": { "color": "FEF2C0", "description": "Default when in doubt" },
+        "P4: low": { "color": "BFDADC", "description": "Nice-to-have" }
+      }
     }
   },
   "$defs": {