@clipboard-health/groundcrew 4.45.11 → 4.46.0

package/README.md

@@ -109,6 +109,7 @@ crew resume [--new] <TASK>                             # reopen a paused task (-
 crew open <pr> | --branch <name> [--repo <owner/repo>] # iterate on an existing PR or branch
          [--prompt <text> | --prompt-file <path>] [--task <id>] [--dry-run]
 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
 ```
 

package/dist/cli.js

@@ -147,8 +147,8 @@ const SUBCOMMANDS = {
         invoke: statusCli,
     },
     cleanup: {
-        summary: "Tear down a worktree",
-        usage: "[--force] <task>",
+        summary: "Tear down a worktree, or every idle worktree with --all",
+        usage: "[--force] <task> | [--force] --all",
         invoke: cleanupWorkspaceCli,
     },
     stop: {

package/dist/commands/cleanupWorkspace.d.ts

@@ -4,6 +4,17 @@ export interface CleanupWorkspaceOptions {
     /** Default false. The automated cleanup path keeps in-flight uncommitted work. */
     force?: boolean;
 }
+export interface CleanupAllOptions {
+    /** Default false. Force-remove even worktrees with uncommitted work. */
+    force?: boolean;
+}
 export declare function cleanupWorkspace(config: ResolvedConfig, options: CleanupWorkspaceOptions): Promise<void>;
+/**
+ * Tear down every local worktree whose task is not currently in use — that is,
+ * has no live workspace session. Worktrees backed by a running session are left
+ * untouched. Uncommitted work is still protected by teardown's dirtiness guard
+ * unless `--force` is passed.
+ */
+export declare function cleanupAllWorkspaces(config: ResolvedConfig, options: CleanupAllOptions): Promise<void>;
 export declare function cleanupWorkspaceCli(argv: string[]): Promise<void>;
 //# sourceMappingURL=cleanupWorkspace.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cleanupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/cleanupWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQnE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAwBD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE"}
+{"version":3,"file":"cleanupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/cleanupWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAcnE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA+DD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE"}

package/dist/commands/cleanupWorkspace.js

@@ -5,24 +5,60 @@ import { log } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
 import { worktrees } from "../lib/worktrees.js";
 import { logTeardown } from "./teardownReporter.js";
+const USAGE = [
+    "Usage: crew cleanup [--force] <task>",
+    "       crew cleanup [--force] --all",
+    "Example: crew cleanup team-220",
+].join("\n");
 function parseArguments(argv) {
     let force = false;
+    let all = false;
     const positionals = [];
     for (const argument of argv) {
         if (argument === "--force") {
             force = true;
             continue;
         }
+        if (argument === "--all") {
+            all = true;
+            continue;
+        }
         if (argument.startsWith("-")) {
-            throw new Error(`Unknown option: ${argument}\nUsage: crew cleanup [--force] <task>\nExample: crew cleanup team-220`);
+            throw new Error(`Unknown option: ${argument}\n${USAGE}`);
         }
         positionals.push(argument);
     }
+    if (all) {
+        if (positionals.length > 0) {
+            throw new Error(`crew cleanup --all takes no task argument.\n${USAGE}`);
+        }
+        return { mode: "all", force };
+    }
     const [task, ...extras] = positionals;
     if (task === undefined || task.length === 0 || extras.length > 0) {
-        throw new Error("Usage: crew cleanup [--force] <task>\nExample: crew cleanup team-220");
+        throw new Error(USAGE);
+    }
+    return { mode: "task", task: task.toLowerCase(), force };
+}
+/**
+ * A worktree is "in use" when its task has a live workspace session — present
+ * in the probe and not exited. An exited session is a dead agent, so its
+ * worktree is idle and safe to reap. An `unavailable` probe is "we don't know",
+ * handled by the caller (never inferred as idle).
+ */
+function isWorkspaceInUse(probe, task) {
+    if (probe.kind !== "ok" || !probe.names.has(task)) {
+        return false;
+    }
+    return probe.exitedNames?.has(task) !== true;
+}
+async function teardownEntries(config, entries, force) {
+    const result = await worktrees.teardown(config, entries, { force });
+    recordCleanedUpRuns(config, result.removed);
+    logTeardown(result);
+    if (result.failures.length > 0) {
+        throw result.failures[0]?.error;
     }
-    return { task: task.toLowerCase(), force };
 }
 export async function cleanupWorkspace(config, options) {
     const { task, force = false } = options;
@@ -45,15 +81,46 @@ export async function cleanupWorkspace(config, options) {
         log(`No worktree found for ${task}; cleared stale run-state.`);
         return;
     }
-    const result = await worktrees.teardown(config, entries, { force });
-    recordCleanedUpRuns(config, result.removed);
-    logTeardown(result);
-    if (result.failures.length > 0) {
-        throw result.failures[0]?.error;
+    await teardownEntries(config, entries, force);
+}
+/**
+ * Tear down every local worktree whose task is not currently in use — that is,
+ * has no live workspace session. Worktrees backed by a running session are left
+ * untouched. Uncommitted work is still protected by teardown's dirtiness guard
+ * unless `--force` is passed.
+ */
+export async function cleanupAllWorkspaces(config, options) {
+    const { force = false } = options;
+    const entries = worktrees.list(config);
+    if (entries.length === 0) {
+        log("No worktrees found; nothing to clean up.");
+        return;
+    }
+    const workspaceProbe = await workspaces.probe(config);
+    if (workspaceProbe.kind === "unavailable") {
+        log("Workspace probe unavailable; cannot tell which worktrees are in use, leaving all intact.");
+        return;
     }
+    const idle = [];
+    for (const entry of entries) {
+        if (isWorkspaceInUse(workspaceProbe, entry.task)) {
+            log(`Skipping ${entry.task} (${entry.repository}); workspace in use.`);
+            continue;
+        }
+        idle.push(entry);
+    }
+    if (idle.length === 0) {
+        log("No idle worktrees to clean up.");
+        return;
+    }
+    await teardownEntries(config, idle, force);
 }
 export async function cleanupWorkspaceCli(argv) {
     const config = await loadConfig();
-    const options = parseArguments(argv);
-    await cleanupWorkspace(config, options);
+    const parsed = parseArguments(argv);
+    if (parsed.mode === "all") {
+        await cleanupAllWorkspaces(config, { force: parsed.force });
+        return;
+    }
+    await cleanupWorkspace(config, { task: parsed.task, force: parsed.force });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.45.11",
+  "version": "4.46.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -28,7 +28,8 @@
     "crew.config.example.ts",
     "dist",
     "docs",
-    "static"
+    "static",
+    "task-sources"
   ],
   "type": "module",
   "main": "./dist/index.js",

package/task-sources/README.md

@@ -0,0 +1,41 @@
+# Task sources
+
+First-class, connectable [task sources](../docs/task-sources.md) for groundcrew.
+Each subdirectory is a self-contained source that can be installed into a user's
+`crew.config.json`.
+
+## Anatomy of a source
+
+| File          | Purpose                                                                      |
+| ------------- | ---------------------------------------------------------------------------- |
+| `source.json` | Install manifest (see below). The canonical description of the wiring.       |
+| `README.md`   | Human setup guide. Its config block renders the same wiring as the manifest. |
+| script(s)     | The executable(s) the manifest lists in `files` (e.g. `jira.sh`).            |
+
+## Manifest (`source.json`)
+
+A machine-readable description that the
+[crew-config](https://github.com/clipboard-health/groundcrew-config) TUI reads to
+install a source. groundcrew itself does **not** load it at runtime — it is a
+contract between this repo (which produces sources) and crew-config (which writes
+them into `crew.config.json`).
+
+| Field           | Consumed by  | Purpose                                                  |
+| --------------- | ------------ | -------------------------------------------------------- |
+| `name`, `kind`  | crew.config  | written into the `sources[]` entry                       |
+| `commands`      | crew.config  | command templates, written verbatim (`${id}` is runtime) |
+| `env`           | crew.config  | environment defaults, written verbatim                   |
+| `installDir`    | install step | where `files` are copied                                 |
+| `files`         | install step | scripts copied to `installDir`, made executable          |
+| `prerequisites` | install step | binaries to check on PATH, with install/setup hints      |
+| `secrets`       | install step | secrets to prompt for and write to a file                |
+| `description`   | TUI / docs   | human-readable summary                                   |
+
+The command keys (`verify`, `listTasks`, `getTask`, `markInProgress`,
+`markInReview`, `markDone`) match groundcrew's shell adapter contract;
+`listTasks` is required.
+
+## Available sources
+
+- [`jira/`](./jira/README.md) — JIRA issues via the
+  [`jira` CLI](https://github.com/ankitpokhrel/jira-cli).

package/task-sources/jira/README.md

@@ -0,0 +1,182 @@
+# JIRA shell source
+
+A ready-to-use [`shell` task source](../../docs/task-sources.md) that feeds JIRA
+issues into groundcrew using the [`jira` CLI](https://github.com/ankitpokhrel/jira-cli).
+Everything lives in one script, [`jira.sh`](./jira.sh), which the shell adapter
+calls with a subcommand per operation:
+
+| Subcommand                   | Adapter command                                | What it does                                                     |
+| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| `jira.sh verify`             | `verify`                                       | Checks the token and connectivity (`jira me`).                   |
+| `jira.sh list`               | `listTasks`                                    | Prints a `ShellIssue[]` JSON array for the configured JQL.       |
+| `jira.sh get <KEY>`          | `getTask`                                      | Prints one `ShellIssue`, or exits `3` when the key is not found. |
+| `jira.sh move <KEY> <STATE>` | `markInProgress` / `markInReview` / `markDone` | Transitions the issue.                                           |
+
+## Prerequisites
+
+- [`jira` CLI](https://github.com/ankitpokhrel/jira-cli) — `brew install ankitpokhrel/jira-cli/jira-cli`, then `jira init`.
+- [`jq`](https://jqlang.github.io/jq/) — `brew install jq`.
+
+> **Note:** `list` and `get` detect "no results" and "not found" by matching the
+> `jira` CLI's stderr wording (it exposes no machine-readable signal for either).
+> Those strings are validated against **jira-cli 1.7.x**; re-verify them if you
+> upgrade the CLI, since a reworded message would be misread as a real failure.
+
+### What `jira init` sets up
+
+`jira init` is a one-time wizard that writes `~/.config/.jira/.config.yml` — the
+non-secret connection details every `jira` command (and therefore `jira.sh`)
+relies on. It prompts for:
+
+- **Installation** (`Cloud` vs. on-prem Server/Data Center) and the **server
+  URL** the CLI talks to.
+- Your **login** email and **auth type** (`basic` = email + API token on Cloud).
+- A **default project** and **board**. The default project matters here: the
+  `list` JQL has no `project = …` clause, so it implicitly scopes to whatever
+  project `jira init` selected.
+
+It also introspects your instance and caches every custom-field definition, so
+the config file can be large (hundreds of KB) — that is expected.
+
+Note that `jira init` does **not** store the API token. jira-cli reads the token
+from the OS keyring or the `JIRA_API_TOKEN` environment variable; this source
+supplies it via the latter from a gitignored file (see [Setup](#setup) step 2).
+So `jira init` owns the connection (server, login, project) and `jira.sh` layers
+the token on per invocation.
+
+## Setup
+
+1. **Install the script** where your config references it:
+
+   ```bash
+   mkdir -p ~/.config/groundcrew
+   cp task-sources/jira/jira.sh ~/.config/groundcrew/jira.sh
+   chmod +x ~/.config/groundcrew/jira.sh
+   ```
+
+2. **Store the API token** in a gitignored file so it stays scoped to this
+   source instead of your global environment ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens)):
+
+   ```bash
+   echo '<your-token>' > ~/.config/groundcrew/jira.token
+   chmod 600 ~/.config/groundcrew/jira.token
+   ```
+
+   The script reads the token from this file, trims surrounding whitespace (so a
+   trailing newline or CRLF is fine), and exports `JIRA_API_TOKEN` only into its
+   own process — nothing global, and no secret in your config file.
+
+3. **Label your issues** so groundcrew knows what to pick up and where to
+   dispatch it:
+
+   | Label                  | Example                            | Effect                                                                                                                                                                                                                                                                                                         |
+   | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `groundcrew`           | `groundcrew`                       | Opts the issue in. The default JQL fetches only issues carrying this label, so work is dispatched explicitly rather than every open issue being swept up. The label name is just a JQL convention — change the `labels = …` clause in `JIRA_GROUNDCREW_JQL` to use a different one.                            |
+   | `repo:<name>`          | `repo:wild-horses`                 | Sets `repository: "wild-horses"`. Use a bare repository name when your config's `knownRepositories` lists it by name — no owner needed.                                                                                                                                                                        |
+   | `repo:<Owner>__<name>` | `repo:ClipboardHealth__groundcrew` | Sets `repository: "ClipboardHealth/groundcrew"`. JIRA labels cannot contain `/`, so the slash is encoded as exactly **two** underscores (`__`). Every `__` decodes to `/`, so only two-component `Owner/name` repos are supported — a repository whose owner or name itself contains `__` cannot be expressed. |
+   | `agent:<name>`         | `agent:claude`                     | **Optional** — omit it to use `JIRA_DEFAULT_AGENT` (`claude` in the sample config). Only add this label to override the default for a specific issue.                                                                                                                                                          |
+
+   So a typical dispatchable issue carries just `groundcrew` + a `repo:` label.
+   An issue without a `repo:` label is listed but not dispatchable (and with no
+   `agent:` label and no `JIRA_DEFAULT_AGENT`, its agent is `null`).
+
+4. **Add the source** to your `crew.config.json` (or `crew.config.ts`):
+
+   ```json
+   {
+     "kind": "shell",
+     "name": "jira",
+     "commands": {
+       "verify": "~/.config/groundcrew/jira.sh verify",
+       "listTasks": "~/.config/groundcrew/jira.sh list",
+       "getTask": "~/.config/groundcrew/jira.sh get ${id}",
+       "markInProgress": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_IN_PROGRESS\"",
+       "markInReview": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_IN_REVIEW\"",
+       "markDone": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_DONE\""
+     },
+     "env": {
+       "JIRA_GROUNDCREW_JQL": "labels = groundcrew AND (statusCategory != Done OR (statusCategory = Done AND updated >= -7d))",
+       "JIRA_REVIEW_PATTERN": "review",
+       "JIRA_TODO_PATTERN": "",
+       "JIRA_DEFAULT_AGENT": "claude",
+       "JIRA_STATE_IN_PROGRESS": "In Progress",
+       "JIRA_STATE_IN_REVIEW": "In Review",
+       "JIRA_STATE_DONE": "Done"
+     },
+     "timeouts": {
+       "listTasks": 60000,
+       "markInReview": 15000,
+       "markDone": 15000
+     }
+   }
+   ```
+
+## Configuration knobs
+
+The script reads these from the source's `env` block:
+
+| Variable              | Default                                                                                          | Purpose                                                                                                                                                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `JIRA_GROUNDCREW_JQL` | `labels = groundcrew AND (statusCategory != Done OR (statusCategory = Done AND updated >= -7d))` | Which issues `list` returns, capped at the first 20 (`--paginate 0:20` in `jira.sh`). Defaults to open issues plus those done in the last 7 days (so groundcrew can clean up their worktrees). Omit `ORDER BY` (jira-cli adds its own). |
+| `JIRA_REVIEW_PATTERN` | `review`                                                                                         | Case-insensitive regex; matching In-Progress status names map to `in-review`.                                                                                                                                                           |
+| `JIRA_TODO_PATTERN`   | _(empty -> off)_                                                                                 | Case-insensitive regex; matching In-Progress status names map to `todo` so groundcrew dispatches them as new work. Set it to e.g. `acknowledged` for an "Acknowledged" triage status. Checked before `JIRA_REVIEW_PATTERN`.             |
+| `JIRA_DEFAULT_AGENT`  | _(empty -> `null`)_                                                                              | Agent used when an issue has no `agent:` label.                                                                                                                                                                                         |
+| `JIRA_TOKEN_FILE`     | `~/.config/groundcrew/jira.token`                                                                | Token file path.                                                                                                                                                                                                                        |
+| `JIRA_STATE_*`        | `In Progress` / `In Review` / `Done`                                                             | Native JIRA state names used by `move`. Match your project's workflow.                                                                                                                                                                  |
+
+## Status mapping
+
+JIRA Cloud groups statuses into three `statusCategory` keys; groundcrew needs
+five. The catch-all `indeterminate` ("In Progress") category covers in-flight
+workflow, so `in-review` and `todo` are recovered from the status _name_: a name
+matching `JIRA_TODO_PATTERN` demotes to `todo` (so e.g. an "Acknowledged" triage
+status is dispatched as new work); a name matching `JIRA_REVIEW_PATTERN` promotes
+to `in-review`. The todo pattern is checked first.
+
+| JIRA `statusCategory.key` | Canonical status                                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `new`                     | `todo`                                                                                                                  |
+| `indeterminate`           | `in-progress`; `todo` when the name matches `JIRA_TODO_PATTERN`, else `in-review` when it matches `JIRA_REVIEW_PATTERN` |
+| `done`                    | `done`                                                                                                                  |
+| anything else             | `other`                                                                                                                 |
+
+## Notes
+
+- `list` returns at most 20 issues (the `--paginate 0:20` bound in `jira.sh`).
+  Raise that bound or narrow `JIRA_GROUNDCREW_JQL` if you have more eligible
+  issues than that.
+- The default JQL keeps tickets done within the last 7 days in the list, not
+  just open ones. groundcrew only tears down a task's worktree once `list`/`get`
+  report it `done`, so dropping done tickets immediately would leak worktrees;
+  the 7-day window gives cleanup time to run, then the ticket falls out so the
+  steady-state list stays small. The window is keyed on `updated`, so a done
+  ticket edited within 7 days stays listed (harmless — groundcrew never
+  re-dispatches a `done` task). Shorten or drop the
+  `statusCategory = Done AND updated >= -7d` clause in `JIRA_GROUNDCREW_JQL` if
+  your source closes out worktrees some other way.
+- The default JQL has no `project = …` clause, so it implicitly scopes to the
+  default project `jira init` selected (see [What `jira init` sets up](#what-jira-init-sets-up)).
+  On a multi-project instance, add an explicit `project = "ENG"` clause to
+  `JIRA_GROUNDCREW_JQL` to constrain which project `list` sweeps.
+- A query that matches nothing is the steady state (no issue is ready to
+  dispatch). jira-cli treats "no results" as an error and exits non-zero, but
+  `list` folds that into an empty array and exits `0`, so the shell adapter sees
+  "no tasks" instead of throwing a fetch failure on every poll. Genuine failures
+  (auth, network) still print to stderr and propagate as a non-zero exit.
+- `jira issue list --raw` returns a reduced shape (no `id`, `self`, or
+  `statusCategory`), so `list` reads the matching keys and then enriches each one
+  with `jira issue view <key> --raw` — the full REST issue the transform needs.
+  That means one extra API call per listed issue, so a tighter
+  `JIRA_GROUNDCREW_JQL` keeps `list` fast.
+- Cloud descriptions are rich text (ADF); the script flattens their text nodes
+  into a plain description and prepends a `Repository:`/issue-URL header, since
+  groundcrew uses the description as the agent's prompt.
+- Issue comments are appended to that description under a `--- Comments ---`
+  heading (oldest first, each headed by author and timestamp), since `ShellIssue`
+  has no comments field and the description is what the agent sees. Comment text
+  is flattened the same way as the description, so `@mentions` come through as
+  their display text. jira-cli returns only the first page of comments, so a
+  heavily-commented issue may be truncated.
+- Writeback (`move`) uses the native state names from `JIRA_STATE_*`; if a
+  transition name does not exist in your workflow, `jira issue move` fails and
+  groundcrew surfaces the error.

package/task-sources/jira/jira.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+#
+# JIRA <-> groundcrew shell source (single file).
+# The shell adapter's commands.* point at one of these subcommands:
+#   jira.sh verify             token + connectivity check        (commands.verify)
+#   jira.sh list               ShellIssue[] JSON on stdout       (commands.listTasks)
+#   jira.sh get <KEY>          one ShellIssue, exit 3 if absent  (commands.getTask)
+#   jira.sh move <KEY> <STATE> transition the issue              (markInProgress/InReview/Done)
+#
+# Requires the `jira` CLI (https://github.com/ankitpokhrel/jira-cli) and `jq`.
+#
+# Auth: the API token is read from a gitignored file so it is scoped to this
+# source and never global. Set it once:
+#   printf '%s' '<token>' > ~/.config/groundcrew/jira.token
+#   chmod 600 ~/.config/groundcrew/jira.token
+#
+# Knobs (set via the source's `env` block in crew.config):
+#   JIRA_GROUNDCREW_JQL  JQL for `list`  (default: open + last-7-days-done issues labeled groundcrew; no ORDER BY — see below)
+#   JIRA_REVIEW_PATTERN  case-insensitive regex; matching In-Progress status names -> in-review (default: review)
+#   JIRA_TODO_PATTERN    case-insensitive regex; matching In-Progress status names -> todo (default: empty -> off)
+#   JIRA_DEFAULT_AGENT   agent when an issue has no agent:<x> label (default: empty -> null)
+#   JIRA_TOKEN_FILE      token path (default: ~/.config/groundcrew/jira.token)
+set -euo pipefail
+
+TOKEN_FILE="${JIRA_TOKEN_FILE:-${HOME}/.config/groundcrew/jira.token}"
+# No ORDER BY here: jira-cli appends its own (see --order-by below), and a
+# second ORDER BY in the JQL makes JIRA reject the query with a 400.
+# The default gates dispatch on an explicit `groundcrew` label so only issues
+# you opt in are picked up — see the README's labeling step. It also keeps
+# tickets done within the last 7 days in the list: groundcrew only tears down a
+# task's worktree once `list`/`get` report it `done`, so dropping done tickets
+# immediately would leak worktrees. The 7-day window lets cleanup happen, then
+# the ticket falls out so the steady-state list stays small.
+LIST_JQL="${JIRA_GROUNDCREW_JQL:-labels = groundcrew AND (statusCategory != Done OR (statusCategory = Done AND updated >= -7d))}"
+REVIEW_PATTERN="${JIRA_REVIEW_PATTERN:-review}"
+TODO_PATTERN="${JIRA_TODO_PATTERN:-}"
+DEFAULT_AGENT="${JIRA_DEFAULT_AGENT:-}"
+
+if [[ -r "${TOKEN_FILE}" ]]; then
+  JIRA_API_TOKEN="$(cat "${TOKEN_FILE}")"
+  # Trim surrounding whitespace so a token written with `echo`, saved with a
+  # trailing newline, CRLF line endings, or stray spaces still authenticates.
+  JIRA_API_TOKEN="${JIRA_API_TOKEN#"${JIRA_API_TOKEN%%[![:space:]]*}"}"
+  JIRA_API_TOKEN="${JIRA_API_TOKEN%"${JIRA_API_TOKEN##*[![:space:]]}"}"
+  # An empty (or whitespace-only) file would export a blank token and surface a
+  # cryptic auth failure deep in a `jira` call; reject it up front instead.
+  if [[ -z "${JIRA_API_TOKEN}" ]]; then
+    echo "jira token file is empty: ${TOKEN_FILE}" >&2
+    exit 1
+  fi
+  export JIRA_API_TOKEN
+fi
+
+# Reshape one JIRA REST issue -> one groundcrew ShellIssue. Shared by list & get
+# so the two code paths can never drift. Labels carry dispatch metadata:
+#   repo:Owner__name -> repository "Owner/name"   (__ decodes to /)
+#   agent:<name>     -> agent "<name>"
+# `read -d ''` reads until a NUL; the heredoc has none, so `read` consumes the
+# whole body but returns 1 at EOF. The `|| true` keeps that expected non-zero
+# from tripping `set -e` — JQ_TRANSFORM is still fully populated.
+read -r -d '' JQ_TRANSFORM <<'JQ' || true
+def adfText: [.. | .text? // empty] | join(" ");
+# A rich-text field is either a plain string (REST v2) or an ADF object (v3);
+# flatten both to text. Shared by the description and each comment body.
+def bodyText: if type == "string" then . elif type == "object" then adfText else "" end;
+def labelValue($p):
+  ((.fields.labels // []) | map(select(startswith($p))) | .[0] // null)
+  | if . == null then null else ltrimstr($p) end;
+def browseUrl:
+  ((.self // "") | capture("^(?<b>https?://[^/]+)") | .b) as $base
+  | if ($base // "") == "" then null else $base + "/browse/" + .key end;
+# JIRA has only three status *categories* (new/indeterminate/done) but groundcrew
+# needs five canonical states. The indeterminate ("In Progress") category is the
+# catch-all for in-flight workflow, so review and todo are recovered from the
+# status *name*: a name matching $tp (e.g. "Acknowledged") demotes to todo so
+# groundcrew dispatches it as new work; a name matching $rp promotes to in-review.
+# $tp is checked first and only when non-empty (an empty regex matches every name).
+def canonStatus($rp; $tp):
+  (.fields.status.statusCategory.key // "") as $c
+  | (.fields.status.name // "") as $n
+  | if   $c == "done"          then "done"
+    elif $c == "new"           then "todo"
+    elif $c == "indeterminate" then
+      (if   ($tp != "" and ($n | test($tp; "i"))) then "todo"
+       elif ($n | test($rp; "i"))                  then "in-review"
+       else "in-progress" end)
+    else "other" end;
+# Render the issue's comments (oldest first) as one text block, each headed by
+# author and timestamp. groundcrew feeds `description` to the agent as its
+# prompt, and ShellIssue has no comments field, so the discussion is folded in
+# here. NOTE: jira-cli returns only the first page of comments (the REST view
+# endpoint paginates), so heavily-commented issues may be truncated.
+def commentsText:
+  ((.fields.comment.comments // [])
+   | map("[" + (.author.displayName // "Unknown")
+         + (if (.created // "") == "" then "" else " (" + .created + ")" end)
+         + "]\n" + (.body | bodyText))
+   | join("\n\n"));
+def toShellIssue($rp; $tp; $da):
+  (labelValue("repo:")  | if . == null then null else gsub("__"; "/") end) as $repo
+  | (labelValue("agent:") // (if $da == "" then null else $da end)) as $agent
+  | (.fields.description | bodyText) as $body
+  | commentsText as $comments
+  | ([ (if $body == "" then empty else $body end),
+       (if $comments == "" then empty else "--- Comments ---\n\n" + $comments end) ] | join("\n\n")) as $content
+  | browseUrl as $url
+  | ([ (if $repo != null then "Repository: " + $repo else empty end),
+       (if $url  != null then "Issue: " + $url       else empty end) ] | join("\n")) as $hdr
+  | { id: .key,
+      title: (.fields.summary // .key),
+      description: (if $hdr == "" then $content else $hdr + "\n\n" + $content end),
+      status: canonStatus($rp; $tp),
+      repository: $repo,
+      agent: $agent,
+      assignee: (.fields.assignee.displayName // "Unassigned"),
+      updatedAt: (.fields.updated // ""),
+      blockers: [],
+      hasMoreBlockers: false,
+      url: $url,
+      sourceRef: { key: .key, nativeId: .id } }
+  | if .url == null then del(.url) else . end;
+JQ
+
+require_token() {
+  [[ -r "${TOKEN_FILE}" ]] || {
+    echo "jira token file not found/readable: ${TOKEN_FILE}" >&2
+    exit 1
+  }
+}
+
+cmd="${1:-}"
+shift || true
+case "${cmd}" in
+  verify)
+    require_token
+    jira me >/dev/null
+    ;;
+  list)
+    require_token
+    # jira-cli's `issue list --raw` returns a reduced array (no id/self/
+    # statusCategory), so we read just the keys and enrich each via `issue view`,
+    # whose `--raw` is the full REST issue the transform needs. `jq -s` slurps
+    # the stream of per-issue objects into one array.
+    #
+    # jira-cli exits non-zero (and prints to stderr) when a query matches
+    # nothing. groundcrew's shell adapter treats any non-zero `listTasks` exit
+    # as a fetch failure, so a no-match query (the steady state when no issue
+    # carries the dispatch label) must NOT propagate that exit. Capture the list
+    # separately: fold "no results" into an empty array, but still surface real
+    # failures (auth, network) instead of masking them as "no tasks".
+    list_err="$(mktemp)"
+    trap 'rm -f "${list_err}"' EXIT
+    if ! list_raw="$(jira issue list -q "${LIST_JQL}" --order-by updated --reverse --raw --paginate 0:20 2>"${list_err}")"; then
+      # jira-cli has no machine-readable "empty result" signal, so we match its
+      # stderr wording. These strings are validated against jira-cli 1.7.x and
+      # may drift on upgrade (see README Prerequisites); the same caveat applies
+      # to the not-found match in `get` below.
+      if grep -qiE "no result|no issues" "${list_err}"; then
+        list_raw="[]"
+      else
+        cat "${list_err}" >&2
+        exit 1
+      fi
+    fi
+    # Enrich each listed key with its full issue: 1 `list` + 1 `view` per key
+    # (≤21 calls at the 20-issue cap), which can approach the 60s `listTasks`
+    # timeout on a wide JQL — see README Notes. A failed `view` logs and skips
+    # that one key rather than `|| true` silently dropping it from the array.
+    printf '%s' "${list_raw:-[]}" \
+      | jq -r 'if type == "array" then .[].key else empty end' \
+      | while IFS= read -r key; do
+          [[ -n "${key}" ]] || continue
+          jira issue view "${key}" --raw 2>/dev/null \
+            || { echo "jira.sh list: skipping ${key} (view failed)" >&2; continue; }
+        done \
+      | jq -s -c --arg rp "${REVIEW_PATTERN}" --arg tp "${TODO_PATTERN}" --arg da "${DEFAULT_AGENT}" \
+            "${JQ_TRANSFORM} [ .[] | toShellIssue(\$rp; \$tp; \$da) ]"
+    ;;
+  get)
+    require_token
+    key="${1:?usage: jira.sh get <KEY>}"
+    get_err="$(mktemp)"
+    trap 'rm -f "${get_err}"' EXIT
+    if ! out="$(jira issue view "${key}" --raw 2>"${get_err}")"; then
+      # jira-cli exits non-zero for a genuinely missing key AND for transient
+      # auth/network failures. Only the former is the not-found sentinel (exit 3);
+      # surface the rest as a retryable error so groundcrew does not treat a live
+      # task as vanished. Not-found wording validated vs jira-cli 1.7.x (see S3).
+      if grep -qiE "not found|does not exist|404" "${get_err}"; then
+        exit 3
+      fi
+      cat "${get_err}" >&2
+      exit 1
+    fi
+    [[ -n "${out}" ]] || exit 3
+    printf '%s' "${out}" \
+      | jq -c --arg rp "${REVIEW_PATTERN}" --arg tp "${TODO_PATTERN}" --arg da "${DEFAULT_AGENT}" \
+            "${JQ_TRANSFORM} toShellIssue(\$rp; \$tp; \$da)"
+    ;;
+  move)
+    require_token
+    key="${1:?usage: jira.sh move <KEY> <STATE>}"
+    state="${2:?missing STATE}"
+    jira issue move "${key}" "${state}" >/dev/null
+    ;;
+  *)
+    echo "usage: jira.sh {verify|list|get <KEY>|move <KEY> <STATE>}" >&2
+    exit 2
+    ;;
+esac

package/task-sources/jira/source.json

@@ -0,0 +1,39 @@
+{
+  "name": "jira",
+  "kind": "shell",
+  "description": "Feed JIRA issues into groundcrew via the jira CLI.",
+  "installDir": "~/.config/groundcrew",
+  "files": ["jira.sh"],
+  "prerequisites": [
+    {
+      "bin": "jira",
+      "install": "brew install ankitpokhrel/jira-cli/jira-cli",
+      "setup": "jira init"
+    },
+    {
+      "bin": "jq",
+      "install": "brew install jq"
+    }
+  ],
+  "secrets": [
+    {
+      "env": "JIRA_API_TOKEN",
+      "file": "jira.token",
+      "mode": "0600",
+      "url": "https://id.atlassian.com/manage-profile/security/api-tokens"
+    }
+  ],
+  "env": {
+    "JIRA_STATE_IN_PROGRESS": "In Progress",
+    "JIRA_STATE_IN_REVIEW": "In Review",
+    "JIRA_STATE_DONE": "Done"
+  },
+  "commands": {
+    "verify": "~/.config/groundcrew/jira.sh verify",
+    "listTasks": "~/.config/groundcrew/jira.sh list",
+    "getTask": "~/.config/groundcrew/jira.sh get ${id}",
+    "markInProgress": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_IN_PROGRESS\"",
+    "markInReview": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_IN_REVIEW\"",
+    "markDone": "~/.config/groundcrew/jira.sh move ${id} \"$JIRA_STATE_DONE\""
+  }
+}