@clipboard-health/groundcrew 4.47.3 → 4.47.4

package/README.md

@@ -111,6 +111,7 @@ crew open <pr> | --branch <name> [--repo <owner/repo>] # iterate on an existing
 crew cleanup [--force] <TASK>                          # tear down every worktree for a task
 crew cleanup [--force] --all                           # tear down every idle worktree (no live workspace)
 crew upgrade [<version>]                                 # reinstall crew globally through npm
+crew completions <bash|zsh|fish>                        # print a shell completion script
 ```
 
 See [command details](./docs/commands.md) for status output, doctor behavior, and the stop/resume workflow.

package/dist/cli.d.ts

@@ -1,2 +1,7 @@
+/**
+ * The command names shown in `crew --help` and offered by shell completions:
+ * every registered subcommand that is neither hidden nor a deprecated alias.
+ */
+export declare function visibleCommandNames(): readonly string[];
 export declare function run(argv: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA4RA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuPA;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAIvD;AAiDD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvD"}

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { cleanupWorkspaceCli } from "./commands/cleanupWorkspace.js";
+import { completionsCli } from "./commands/completions.js";
 import { doctor } from "./commands/doctor.js";
 import { initConfigCli } from "./commands/init.js";
 import { interruptWorkspaceCli } from "./commands/interruptWorkspace.js";
@@ -186,9 +187,26 @@ const SUBCOMMANDS = {
         usage: "[<version>]",
         invoke: upgradeCliInvoke,
     },
+    completions: {
+        summary: "Print a shell completion script for bash, zsh, or fish",
+        usage: "<bash|zsh|fish>",
+        invoke: completionsCli,
+    },
 };
+function isVisibleCommand(command) {
+    return command.hidden !== true && command.deprecated !== true;
+}
+/**
+ * The command names shown in `crew --help` and offered by shell completions:
+ * every registered subcommand that is neither hidden nor a deprecated alias.
+ */
+export function visibleCommandNames() {
+    return Object.entries(SUBCOMMANDS)
+        .filter(([, command]) => isVisibleCommand(command))
+        .map(([name]) => name);
+}
 function printHelp() {
-    const visibleCommands = Object.entries(SUBCOMMANDS).filter(([, command]) => command.hidden !== true && command.deprecated !== true);
+    const visibleCommands = Object.entries(SUBCOMMANDS).filter(([, command]) => isVisibleCommand(command));
     const width = Math.max(...visibleCommands.map(([key]) => key.length));
     writeOutput("Usage: crew <command> [...args]\n");
     writeOutput("Options:");

package/dist/commands/completions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Emits shell completion scripts for the `crew` CLI. The command tree is
+ * declared once in `COMPLETION_SPEC` below and rendered into bash, zsh, and
+ * fish scripts. Keep the spec in sync with the parsers in this directory; the
+ * `completions.test.ts` drift guard asserts the top-level command names match
+ * the visible entries in `SUBCOMMANDS` (see `../cli.ts`).
+ */
+/** Describes the value a flag consumes, driving per-shell value completion. */
+type CompletionArg = {
+    readonly kind: "enum";
+    readonly values: readonly string[];
+} | {
+    readonly kind: "file";
+} | {
+    readonly kind: "dir";
+} | {
+    readonly kind: "string";
+};
+interface CompletionOption {
+    readonly name: string;
+    readonly short?: string;
+    readonly summary: string;
+    /** Omitted for boolean flags; present when the flag takes a value. */
+    readonly arg?: CompletionArg;
+}
+export interface CompletionCommand {
+    readonly name: string;
+    readonly summary: string;
+    readonly options?: readonly CompletionOption[];
+    readonly subcommands?: readonly CompletionCommand[];
+    /** Static positional values (e.g. `crew completions <shell>`). */
+    readonly argValues?: readonly string[];
+}
+export declare const SUPPORTED_SHELLS: readonly ["bash", "zsh", "fish"];
+export type SupportedShell = (typeof SUPPORTED_SHELLS)[number];
+/**
+ * The single source of truth for shell completions. Ordering mirrors
+ * `crew --help`; hidden and deprecated commands are intentionally excluded.
+ */
+export declare const COMPLETION_SPEC: readonly CompletionCommand[];
+/** Renders the completion script for a supported shell. */
+export declare function generateCompletionScript(shell: SupportedShell): string;
+export declare function completionsCli(argv: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=completions.d.ts.map

package/dist/commands/completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/commands/completions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,+EAA+E;AAC/E,KAAK,aAAa,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AA2B/D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,iBAAiB,EAqJvD,CAAC;AAqXF,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEtE;AAQD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlE"}

package/dist/commands/completions.js

@@ -0,0 +1,524 @@
+/**
+ * Emits shell completion scripts for the `crew` CLI. The command tree is
+ * declared once in `COMPLETION_SPEC` below and rendered into bash, zsh, and
+ * fish scripts. Keep the spec in sync with the parsers in this directory; the
+ * `completions.test.ts` drift guard asserts the top-level command names match
+ * the visible entries in `SUBCOMMANDS` (see `../cli.ts`).
+ */
+import { LOCAL_RUNNER_SETTINGS } from "../lib/config.js";
+import { shellSingleQuote } from "../lib/shell.js";
+import { writeOutput } from "../lib/util.js";
+import { INIT_AGENTS } from "./init.js";
+export const SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
+// `--runner` and `init --agent` values come from the canonical lists their
+// parsers validate against (config.ts, init.ts) so completions never drift.
+// Status has no exported canonical array to import, so it stays a local literal.
+const STATUS_VALUES = ["todo", "in-progress", "in-review", "done", "other"];
+// `init` validates `--agent` against a fixed built-in set; `open`/`task` accept
+// any configured agent name, so their `--agent` is declared free-form (string).
+const INIT_AGENT_OPTION = {
+    name: "--agent",
+    summary: "Agent name",
+    arg: { kind: "enum", values: INIT_AGENTS },
+};
+const REPO_OPTION = {
+    name: "--repo",
+    summary: "Repository (owner/repo)",
+    arg: { kind: "string" },
+};
+const SOURCE_OPTION = {
+    name: "--source",
+    summary: "Task source name",
+    arg: { kind: "string" },
+};
+const JSON_OPTION = { name: "--json", summary: "Print JSON output" };
+const DRY_RUN_OPTION = { name: "--dry-run", summary: "Preview without acting" };
+/**
+ * The single source of truth for shell completions. Ordering mirrors
+ * `crew --help`; hidden and deprecated commands are intentionally excluded.
+ */
+export const COMPLETION_SPEC = [
+    {
+        name: "init",
+        summary: "Create a crew.config.ts",
+        options: [
+            { name: "--global", summary: "Write into the XDG config dir" },
+            { name: "--local", summary: "Write into the current directory" },
+            { name: "--force", summary: "Overwrite an existing config" },
+            DRY_RUN_OPTION,
+            { name: "--project-dir", summary: "Workspace project directory", arg: { kind: "dir" } },
+            REPO_OPTION,
+            {
+                name: "--runner",
+                summary: "Sandbox runner",
+                arg: { kind: "enum", values: LOCAL_RUNNER_SETTINGS },
+            },
+            INIT_AGENT_OPTION,
+        ],
+    },
+    {
+        name: "run",
+        summary: "Run the orchestrator over eligible tasks",
+        options: [{ name: "--watch", summary: "Poll continuously" }, DRY_RUN_OPTION],
+    },
+    {
+        name: "start",
+        summary: "Launch one task immediately",
+        options: [DRY_RUN_OPTION],
+    },
+    {
+        name: "doctor",
+        summary: "Verify host prerequisites",
+    },
+    {
+        name: "source",
+        summary: "Inspect configured task sources",
+        subcommands: [
+            { name: "list", summary: "List configured sources", options: [JSON_OPTION] },
+            { name: "verify", summary: "Verify one or all sources", options: [JSON_OPTION] },
+        ],
+    },
+    {
+        name: "task",
+        summary: "List, get, create, and complete tasks",
+        subcommands: [
+            {
+                name: "list",
+                summary: "List tasks across sources",
+                options: [
+                    SOURCE_OPTION,
+                    {
+                        name: "--status",
+                        summary: "Filter by status",
+                        arg: { kind: "enum", values: STATUS_VALUES },
+                    },
+                    { name: "--agent", summary: "Filter by agent name", arg: { kind: "string" } },
+                    REPO_OPTION,
+                    { name: "--blocked", summary: "Show only blocked tasks" },
+                    { name: "--unblocked", summary: "Show only unblocked tasks" },
+                    JSON_OPTION,
+                    { name: "--limit", summary: "Limit output count", arg: { kind: "string" } },
+                ],
+            },
+            {
+                name: "get",
+                summary: "Get one task",
+                options: [
+                    SOURCE_OPTION,
+                    JSON_OPTION,
+                    { name: "--prompt", summary: "Print only the task prompt" },
+                ],
+            },
+            {
+                name: "create",
+                summary: "Create one task",
+                options: [
+                    SOURCE_OPTION,
+                    { name: "--agent", summary: "Assign an agent", arg: { kind: "string" } },
+                    REPO_OPTION,
+                    { name: "--team", summary: "Team key", arg: { kind: "string" } },
+                    { name: "--id", summary: "Explicit task id", arg: { kind: "string" } },
+                    { name: "--priority", summary: "Priority", arg: { kind: "string" } },
+                    { name: "--project", summary: "Project (repeatable)", arg: { kind: "string" } },
+                    { name: "--context", summary: "Context tag (repeatable)", arg: { kind: "string" } },
+                    { name: "--dep", summary: "Dependency (repeatable)", arg: { kind: "string" } },
+                    { name: "--due", summary: "Due date", arg: { kind: "string" } },
+                    { name: "--rec", summary: "Recurrence", arg: { kind: "string" } },
+                    { name: "--prompt-file", summary: "Read prompt from file", arg: { kind: "file" } },
+                    { name: "--description", summary: "Task description", arg: { kind: "string" } },
+                    { name: "--edit", summary: "Open an editor" },
+                    JSON_OPTION,
+                ],
+            },
+            {
+                name: "done",
+                summary: "Mark one task done",
+                options: [{ name: "--allow-dirty", summary: "Allow a dirty worktree" }],
+            },
+            {
+                name: "validate",
+                summary: "Validate task content",
+                options: [JSON_OPTION],
+            },
+        ],
+    },
+    {
+        name: "status",
+        summary: "Print groundcrew state or a task status",
+    },
+    {
+        name: "cleanup",
+        summary: "Tear down a worktree, or all idle worktrees",
+        options: [
+            { name: "--force", summary: "Skip confirmations" },
+            { name: "--all", summary: "Clean up every idle worktree" },
+        ],
+    },
+    {
+        name: "stop",
+        summary: "Stop a live task workspace",
+        options: [{ name: "--reason", summary: "Reason text", arg: { kind: "string" } }],
+    },
+    {
+        name: "resume",
+        summary: "Reopen an existing task worktree",
+        options: [{ name: "--new", summary: "Start a fresh chat session" }],
+    },
+    {
+        name: "open",
+        summary: "Open a PR or branch in a new worktree",
+        options: [
+            { name: "--branch", summary: "Branch name", arg: { kind: "string" } },
+            REPO_OPTION,
+            { name: "--agent", summary: "Agent name", arg: { kind: "string" } },
+            { name: "--prompt", summary: "Prompt text", arg: { kind: "string" } },
+            { name: "--prompt-file", summary: "Read prompt from file", arg: { kind: "file" } },
+            { name: "--task", summary: "Associate a task id", arg: { kind: "string" } },
+            DRY_RUN_OPTION,
+        ],
+    },
+    {
+        name: "upgrade",
+        summary: "Install the latest version of crew",
+    },
+    {
+        name: "completions",
+        summary: "Print a shell completion script",
+        argValues: SUPPORTED_SHELLS,
+    },
+];
+/** Global flags valid only as the first token. */
+const TOP_LEVEL_GLOBALS = [
+    { name: "--help", short: "-h", summary: "Show help" },
+    { name: "--version", short: "-v", summary: "Print version" },
+    { name: "--verbose", summary: "Show diagnostic output" },
+];
+/** The one global flag every subcommand tolerates (stripped before dispatch). */
+const COMMAND_GLOBAL = "--verbose";
+function optionTokens(options) {
+    return (options ?? []).flatMap((option) => option.short === undefined ? [option.name] : [option.name, option.short]);
+}
+/**
+ * Collects every value-taking flag across the tree, keyed by flag name, for the
+ * shell `prev`-based value cases (bash/zsh) which key on flag name globally.
+ * A flag can be declared with different kinds across commands (e.g. `--agent`
+ * is an enum under `init` but free-form under `open`/`task`); prefer the enum so
+ * value suggestions survive regardless of spec order.
+ */
+function valueArgsByName() {
+    const result = new Map();
+    function visit(command) {
+        for (const option of command.options ?? []) {
+            if (option.arg !== undefined) {
+                const existing = result.get(option.name);
+                if (existing?.kind !== "enum") {
+                    result.set(option.name, option.arg);
+                }
+            }
+        }
+        for (const subcommand of command.subcommands ?? []) {
+            visit(subcommand);
+        }
+    }
+    for (const command of COMPLETION_SPEC) {
+        visit(command);
+    }
+    return result;
+}
+/** Appends the one global flag (`--verbose`) every subcommand tolerates. */
+function withVerbose(tokens) {
+    return [...tokens, COMMAND_GLOBAL].join(" ");
+}
+/**
+ * Walks every value-taking flag once and emits a per-shell `case` line via the
+ * given templates. Enum/file/dir flags each get their own line; plain string
+ * flags collapse into one fall-through case that offers no completion.
+ */
+function valueCases(render) {
+    const lines = [];
+    const stringNames = [];
+    for (const [name, arg] of valueArgsByName()) {
+        if (arg.kind === "enum") {
+            lines.push(render.enum(name, arg.values));
+        }
+        else if (arg.kind === "file") {
+            lines.push(render.file(name));
+        }
+        else if (arg.kind === "dir") {
+            lines.push(render.dir(name));
+        }
+        else {
+            stringNames.push(name);
+        }
+    }
+    lines.push(render.string(stringNames));
+    return lines.join("\n");
+}
+// -- bash ------------------------------------------------------------------
+function bashValueCases() {
+    return valueCases({
+        enum: (name, values) => `    ${name}) COMPREPLY=( $(compgen -W "${values.join(" ")}" -- "$cur") ); return ;;`,
+        file: (name) => `    ${name}) COMPREPLY=( $(compgen -f -- "$cur") ); return ;;`,
+        dir: (name) => `    ${name}) COMPREPLY=( $(compgen -d -- "$cur") ); return ;;`,
+        string: (names) => `    ${names.join("|")}) return ;;`,
+    });
+}
+function bashCommandCase(command) {
+    if (command.subcommands !== undefined) {
+        const subNames = command.subcommands.map((sub) => sub.name);
+        const subCases = command.subcommands
+            .map((sub) => `          ${sub.name}) COMPREPLY=( $(compgen -W "${withVerbose(optionTokens(sub.options))}" -- "$cur") ) ;;`)
+            .join("\n");
+        return [
+            `    ${command.name})`,
+            `      if [ -z "$subcommand" ]; then`,
+            `        COMPREPLY=( $(compgen -W "${withVerbose(subNames)}" -- "$cur") )`,
+            `      else`,
+            `        case "$subcommand" in`,
+            subCases,
+            `        esac`,
+            `      fi`,
+            `      ;;`,
+        ].join("\n");
+    }
+    if (command.argValues !== undefined) {
+        return [
+            `    ${command.name})`,
+            `      if [ -z "$subcommand" ]; then`,
+            `        COMPREPLY=( $(compgen -W "${withVerbose([...command.argValues])}" -- "$cur") )`,
+            `      fi`,
+            `      ;;`,
+        ].join("\n");
+    }
+    return [
+        `    ${command.name})`,
+        `      COMPREPLY=( $(compgen -W "${withVerbose(optionTokens(command.options))}" -- "$cur") )`,
+        `      ;;`,
+    ].join("\n");
+}
+function bashScript() {
+    const commandNames = COMPLETION_SPEC.map((command) => command.name).join(" ");
+    const topGlobals = optionTokens(TOP_LEVEL_GLOBALS).join(" ");
+    const commandCases = COMPLETION_SPEC.map(bashCommandCase).join("\n");
+    return `# bash completion for crew
+# Install: source <(crew completions bash)
+_crew() {
+  local cur prev cmd subcommand i word
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  case "$prev" in
+${bashValueCases()}
+  esac
+
+  cmd=""
+  subcommand=""
+  for (( i=1; i < COMP_CWORD; i++ )); do
+    word="\${COMP_WORDS[i]}"
+    case "$word" in -*) continue ;; esac
+    if [ -z "$cmd" ]; then
+      cmd="$word"
+    elif [ -z "$subcommand" ]; then
+      subcommand="$word"
+    fi
+  done
+
+  if [ -z "$cmd" ]; then
+    COMPREPLY=( $(compgen -W "${commandNames} ${topGlobals}" -- "$cur") )
+    return
+  fi
+
+  case "$cmd" in
+${commandCases}
+    *)
+      COMPREPLY=( $(compgen -W "${COMMAND_GLOBAL}" -- "$cur") )
+      ;;
+  esac
+}
+complete -F _crew crew
+`;
+}
+// -- zsh -------------------------------------------------------------------
+function zshValueCases() {
+    return valueCases({
+        enum: (name, values) => `    ${name}) compadd -- ${values.join(" ")}; return ;;`,
+        file: (name) => `    ${name}) _files; return ;;`,
+        dir: (name) => `    ${name}) _files -/; return ;;`,
+        string: (names) => `    ${names.join("|")}) return ;;`,
+    });
+}
+function zshDescribeArray(name, entries) {
+    const items = entries
+        .map((entry) => `    ${shellSingleQuote(`${entry.name}:${entry.summary}`)}`)
+        .join("\n");
+    return [`  local -a ${name}`, `  ${name}=(`, items, `  )`].join("\n");
+}
+function zshCommandCase(command) {
+    if (command.subcommands !== undefined) {
+        const subCases = command.subcommands
+            .map((sub) => `          ${sub.name}) compadd -- ${withVerbose(optionTokens(sub.options))} ;;`)
+            .join("\n");
+        return [
+            `    ${command.name})`,
+            `      if [[ -z $subcommand ]]; then`,
+            zshDescribeArray(`${command.name}_subcommands`, command.subcommands)
+                .split("\n")
+                .map((line) => `    ${line}`)
+                .join("\n"),
+            `        _describe -t subcommands '${command.name} subcommand' ${command.name}_subcommands`,
+            `      else`,
+            `        case $subcommand in`,
+            subCases,
+            `        esac`,
+            `      fi`,
+            `      ;;`,
+        ].join("\n");
+    }
+    if (command.argValues !== undefined) {
+        return [
+            `    ${command.name})`,
+            `      if [[ -z $subcommand ]]; then compadd -- ${withVerbose([...command.argValues])}; fi`,
+            `      ;;`,
+        ].join("\n");
+    }
+    return [
+        `    ${command.name})`,
+        `      compadd -- ${withVerbose(optionTokens(command.options))}`,
+        `      ;;`,
+    ].join("\n");
+}
+function zshScript() {
+    const topGlobals = optionTokens(TOP_LEVEL_GLOBALS).join(" ");
+    const commandCases = COMPLETION_SPEC.map(zshCommandCase).join("\n");
+    return `#compdef crew
+# zsh completion for crew
+# Install: crew completions zsh > "\${fpath[1]}/_crew"  (or: source <(crew completions zsh))
+_crew() {
+  local cur prev cmd subcommand i word
+${zshDescribeArray("commands", COMPLETION_SPEC)}
+  cur=$words[CURRENT]
+  prev=$words[CURRENT-1]
+
+  case $prev in
+${zshValueCases()}
+  esac
+
+  cmd=""
+  subcommand=""
+  for (( i=2; i < CURRENT; i++ )); do
+    word=$words[i]
+    case $word in -*) continue ;; esac
+    if [[ -z $cmd ]]; then
+      cmd=$word
+    elif [[ -z $subcommand ]]; then
+      subcommand=$word
+    fi
+  done
+
+  if [[ -z $cmd ]]; then
+    _describe -t commands 'crew command' commands
+    compadd -- ${topGlobals}
+    return
+  fi
+
+  case $cmd in
+${commandCases}
+    *)
+      compadd -- ${COMMAND_GLOBAL}
+      ;;
+  esac
+}
+
+# Support both fpath autoload and sourcing (source <(crew completions zsh)).
+if [ "$funcstack[1]" = "_crew" ]; then
+  _crew "$@"
+else
+  compdef _crew crew
+fi
+`;
+}
+// -- fish ------------------------------------------------------------------
+function fishDescription(summary) {
+    return summary.replaceAll("\\", String.raw `\\`).replaceAll('"', String.raw `\"`);
+}
+function fishArgFlags(arg) {
+    if (arg === undefined) {
+        return "";
+    }
+    if (arg.kind === "enum") {
+        return ` -x -a "${arg.values.join(" ")}"`;
+    }
+    if (arg.kind === "file") {
+        return " -r -F";
+    }
+    if (arg.kind === "dir") {
+        return ` -x -a "(__fish_complete_directories)"`;
+    }
+    return " -x";
+}
+function fishOptionLine(condition, option) {
+    // Command/subcommand options never carry short forms (only the top-level
+    // globals do, and those are emitted separately), so this renders long flags.
+    const long = option.name.replace(/^--/, "");
+    return `complete -c crew -n '${condition}' -l ${long}${fishArgFlags(option.arg)} -d "${fishDescription(option.summary)}"`;
+}
+function fishOptionLines(condition, options) {
+    return (options ?? []).map((option) => fishOptionLine(condition, option));
+}
+function fishCommandLines(command) {
+    const lines = [];
+    const seenCondition = `__fish_seen_subcommand_from ${command.name}`;
+    lines.push(...fishOptionLines(seenCondition, command.options));
+    if (command.subcommands !== undefined) {
+        const subNames = command.subcommands.map((sub) => sub.name).join(" ");
+        const chooseSub = `${seenCondition}; and not __fish_seen_subcommand_from ${subNames}`;
+        for (const sub of command.subcommands) {
+            lines.push(`complete -c crew -f -n '${chooseSub}' -a ${sub.name} -d "${fishDescription(sub.summary)}"`);
+            const subCondition = `${seenCondition}; and __fish_seen_subcommand_from ${sub.name}`;
+            lines.push(...fishOptionLines(subCondition, sub.options));
+        }
+    }
+    if (command.argValues !== undefined) {
+        const chooseArg = `${seenCondition}; and not __fish_seen_subcommand_from ${command.argValues.join(" ")}`;
+        lines.push(`complete -c crew -f -n '${chooseArg}' -a "${command.argValues.join(" ")}" -d "Shell"`);
+    }
+    return lines;
+}
+function fishScript() {
+    const commandLines = COMPLETION_SPEC.map((command) => `complete -c crew -f -n '__fish_use_subcommand' -a ${command.name} -d "${fishDescription(command.summary)}"`);
+    const globalLines = [
+        `complete -c crew -l verbose -d "Show diagnostic output"`,
+        `complete -c crew -n '__fish_use_subcommand' -l help -s h -d "Show help"`,
+        `complete -c crew -n '__fish_use_subcommand' -l version -s v -d "Print version"`,
+    ];
+    const perCommandLines = COMPLETION_SPEC.flatMap(fishCommandLines);
+    return `# fish completion for crew
+# Install: crew completions fish > ~/.config/fish/completions/crew.fish
+${commandLines.join("\n")}
+${globalLines.join("\n")}
+${perCommandLines.join("\n")}
+`;
+}
+const GENERATORS = {
+    bash: bashScript,
+    zsh: zshScript,
+    fish: fishScript,
+};
+/** Renders the completion script for a supported shell. */
+export function generateCompletionScript(shell) {
+    return GENERATORS[shell]();
+}
+function isSupportedShell(value) {
+    return SUPPORTED_SHELLS.includes(value);
+}
+const COMPLETIONS_USAGE = `Usage: crew completions <${SUPPORTED_SHELLS.join("|")}>`;
+export async function completionsCli(argv) {
+    const [shell, ...extras] = argv;
+    if (shell === undefined || extras.length > 0) {
+        throw new Error(COMPLETIONS_USAGE);
+    }
+    if (!isSupportedShell(shell)) {
+        throw new Error(`crew completions: unsupported shell: ${shell}\n${COMPLETIONS_USAGE}`);
+    }
+    writeOutput(generateCompletionScript(shell));
+}

package/dist/commands/init.d.ts

@@ -5,7 +5,7 @@
  * `cp` dance documented in the README.
  */
 import { type LocalRunnerSetting } from "../lib/config.ts";
-declare const INIT_AGENTS: readonly ["claude", "codex", "cursor"];
+export declare const INIT_AGENTS: readonly ["claude", "codex", "cursor"];
 type InitConfigScope = "global" | "local";
 type InitAgent = (typeof INIT_AGENTS)[number];
 interface InitConfigOptions {

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAYlF,QAAA,MAAM,WAAW,YAAI,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAE3D,KAAK,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC1C,KAAK,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,UAAU,iBAAiB;IACzB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,qDAAqD;IACrD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,KAAK,iBAAiB,GAAG,qBAAqB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAoB5E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjE"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAYlF,eAAO,MAAM,WAAW,YAAI,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAElE,KAAK,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC1C,KAAK,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,UAAU,iBAAiB;IACzB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,qDAAqD;IACrD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,KAAK,iBAAiB,GAAG,qBAAqB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAoB5E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjE"}

package/dist/commands/init.js

@@ -16,7 +16,7 @@ const DEFAULT_EXAMPLE_PROJECT_DIR = "~/dev/groundcrew";
 const INIT_USAGE = "Usage: crew init [--global | --local] [--force] [--dry-run] [--project-dir <dir>] [--repo <owner/repo>]... [--runner <auto|safehouse|sdx|none>] [--agent <claude|codex|cursor>]";
 // Model-variant presets with hyphens (e.g. `cursor-grok`) are enabled via
 // config, not `init`: renderConfig would emit an unquoted, invalid TS key.
-const INIT_AGENTS = ["claude", "codex", "cursor"];
+export const INIT_AGENTS = ["claude", "codex", "cursor"];
 export function initConfig(options = {}) {
     const scope = options.scope ?? "local";
     const cwd = options.cwd ?? process.cwd();

package/docs/commands.md

@@ -166,3 +166,24 @@ Open checks out the PR's actual head branch (fetching it from the remote when it
 When `--prompt`/`--prompt-file` is given, the agent starts with that prompt; otherwise it opens its interactive session with no prompt and hands control to you.
 
 `crew cleanup <task>` removes the opened worktree but never deletes the remote PR branch. Fork (cross-repository) PRs and `provision`/sparse-checkout repositories are not supported; for a fork, check the branch out locally and use `--branch`.
+
+## Completions
+
+`crew completions <bash|zsh|fish>` prints a shell completion script to stdout. The script completes command names, subcommands (for `crew source` and `crew task`), flags, and enumerated flag values (`--runner`, `--status`, `--agent`); `--prompt-file` and `--project-dir` fall back to file and directory completion. Task IDs, source names, and repositories are configuration-specific and are not completed.
+
+Load it once per shell session, or install it so your shell loads it automatically.
+
+```bash
+# bash — add to ~/.bashrc
+source <(crew completions bash)
+
+# zsh — write into a directory on your $fpath (run once), then restart the shell
+crew completions zsh > "${fpath[1]}/_crew"
+# or, to load in the current session, add to ~/.zshrc:
+source <(crew completions zsh)
+
+# fish — install once; fish loads it automatically on the next session
+crew completions fish > ~/.config/fish/completions/crew.fish
+```
+
+The command tree is generated from a single spec in `src/commands/completions.ts`, so completions stay in sync with the CLI as commands and flags change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.47.3",
+  "version": "4.47.4",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",