acli-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathieu Neron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+<h1 align="center">acli-axi</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/acli-axi"><img alt="npm" src="https://img.shields.io/npm/v/acli-axi?style=flat-square" /></a>
+  <a href="https://github.com/mathieu-neron/acli-axi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/mathieu-neron/acli-axi/ci.yml?style=flat-square&label=ci" /></a>
+  <a href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square"><img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square" /></a>
+</p>
+
+Jira CLI for agents — designed with [AXI](https://github.com/kunchenguid/axi) (Agent eXperience Interface).
+
+Wraps the official [Atlassian CLI (`acli`)](https://developer.atlassian.com/cloud/acli/) with token-efficient TOON output, definitive totals, contextual next-step suggestions, and structured error handling.
+Built for autonomous agents that interact with Jira via shell execution.
+
+## Measured gains
+
+Jira's REST payloads are built for rendering UIs: avatar URLs in four sizes, `self` links on every entity, status categories with color names.
+`acli --json` passes them through verbatim; an agent reads about six scalars per work item.
+acli-axi flattens each item to those scalars and emits TOON.
+
+Measured on a live Jira Cloud site (same query and filters both sides, single run, 2026-07-13):
+
+| Command             | acli --json | acli-axi | Reduction  |
+| ------------------- | ----------- | -------- | ---------- |
+| `search` (25 items) | 71,947 ch   | 4,983 ch | **−93.1%** |
+| `search` (5 items)  | 15,181 ch   | 744 ch   | **−95.1%** |
+| `view` (1 item)     | 3,619 ch    | 841 ch   | −76.8%     |
+| `sprints`           | 653 ch      | 240 ch   | −63.2%     |
+
+Latency is parity (mean +18 ms on a ~1.2–1.8 s Jira round-trip).
+The gain scales with result count — per-item overhead is what gets flattened — and compounds in agent sessions, where tool output is re-read as input on every subsequent turn.
+
+## Quick Start
+
+Install the acli-axi skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add mathieu-neron/acli-axi --skill acli-axi -g
+```
+
+The skill teaches your agent when to reach for acli-axi and how to install the CLI (`npm install -g acli-axi`, with `npx -y acli-axi` for one-off runs).
+You still need [`acli`](https://developer.atlassian.com/cloud/acli/guides/install-acli/) installed and authenticated via `acli jira auth login --web` (Node 20+ required).
+
+The skill is not a user-facing slash command (`user-invocable: false`).
+Just ask for anything that touches Jira — searching or triaging work items with JQL, filing stories or bugs, editing summaries or assignees, or checking a board's sprints — and the agent loads the skill on its own when it recognizes the task.
+
+`-g` installs the skill for all projects (`~/.claude/skills/`, for example); drop it to install for the current project only (`.claude/skills/`).
+
+## Other Ways to Install
+
+The skill is the recommended path, but it is not the only one.
+
+### Global install
+
+```sh
+npm install -g acli-axi
+```
+
+Upgrade later with the built-in `acli-axi update` (or `acli-axi update --check` to only look).
+
+### Zero setup
+
+acli-axi is an AXI, so any capable agent can run the CLI directly with nothing installed at all.
+Just tell your agent:
+
+```
+Execute `npx -y acli-axi` to get Jira tools.
+```
+
+### From source
+
+Clone and pack a tarball:
+
+```sh
+git clone https://github.com/mathieu-neron/acli-axi.git
+cd acli-axi && npm pack && npm install -g ./acli-axi-*.tgz
+```
+
+**Do not `npm install -g` the git URL directly** — on npm 10/11 a global git install can be reified as a symlink into npm's temporary clone, which npm deletes after install, leaving a broken binary that still reported success. Tarball installs copy files and cannot hit this. Verify any install with `acli-axi --version`.
+
+## Usage
+
+```bash
+acli-axi                            # home - auth state + your open work items, no args needed
+acli-axi search --jql "project = TEAM AND sprint in openSprints()"
+acli-axi search --jql "..." --limit 50 --fields key,summary,labels
+acli-axi view TEAM-123              # long descriptions truncated; --full to expand
+acli-axi sprints --board 36         # active + future sprints by default
+acli-axi create --project TEAM --type Story --summary "New thing" --assignee @me
+acli-axi create --project TEAM --type Story --summary "..." \
+  --parent TEAM-93 -f customfield_10028=1 -f customfield_10020=11144  # custom fields (points, sprint)
+acli-axi edit TEAM-123 --summary "Better title"   # never prompts (--yes under the hood)
+```
+
+List output reports the **true total**, not the page size: when a search fills its `--limit`, acli-axi runs acli's `--count` behind the scenes and tells you `total: 14724, showing: 25` with a hint to raise the limit.
+
+Custom fields (`-f`/`--field <id>=<value>`, repeatable) are **create-only**: acli's edit schema rejects them, and acli-axi says so with a structured error instead of failing cryptically.
+Values that parse as JSON become numbers or arrays; everything else stays a string.
+
+### Commands
+
+| Command   | Description                                                           |
+| --------- | --------------------------------------------------------------------- |
+| `search`  | Search work items with JQL — flattened rows, definitive totals        |
+| `view`    | Full detail for one work item — ADF descriptions as plain text        |
+| `create`  | Create a work item — flags plus `-f` custom fields, echoes invariants |
+| `edit`    | Edit a work item — summary, assignee, labels, type; never prompts     |
+| `sprints` | List a board's sprints — active + future by default                   |
+| `update`  | Built-in self-update command inherited from `axi-sdk-js`              |
+
+### Global flags
+
+- `--help` — show help for any command
+- `-v`, `-V`, `--version` — show the installed `acli-axi` version
+
+Errors are structured (`error:` + `code:` + `help:`): exit 2 for usage errors, exit 1 for everything else; stdout is data, stderr is diagnostics.
+
+## Scope
+
+v0.1 covers Jira core, plus the installable Agent Skill above.
+Not wrapped yet (use `acli` directly): comments, transitions, attachments, links, projects, filters, Confluence.
+Also deferred: session hooks (`installSessionStartHooks` in the SDK).
+
+## Development
+
+```sh
+pnpm install
+pnpm run build       # Compile TypeScript to dist/
+pnpm run build:skill # Regenerate skills/acli-axi/SKILL.md from the CLI's own help
+pnpm test            # Run tests with vitest (the acli boundary is mocked)
+```
+
+The committed `skills/acli-axi/SKILL.md` is generated by `pnpm run build:skill`; `pnpm test` fails if it drifts from the generator — never hand-edit it.
+The npm package includes `skills/acli-axi/`, so published releases ship the same installable Agent Skill documented in Quick Start.
+
+Built on [`axi-sdk-js`](https://www.npmjs.com/package/axi-sdk-js), which provides command dispatch, TOON serialization, structured errors, and the `update` command.
+
+## License
+
+[MIT](LICENSE)

package/dist/acli.js

@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AxiError } from "axi-sdk-js";
+const execFileAsync = promisify(execFile);
+export async function acli(args) {
+    try {
+        const { stdout } = await execFileAsync("acli", args, { maxBuffer: 64 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (error) {
+        throw toAxiError(error);
+    }
+}
+export async function acliJson(args) {
+    const stdout = await acli([...args, "--json"]);
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new AxiError(`acli returned non-JSON output: ${stdout.slice(0, 200)}`, "ACLI_ERROR", ["Check that the installed acli version supports --json for this command"]);
+    }
+}
+export function toAxiError(error) {
+    if (error instanceof AxiError) {
+        return error;
+    }
+    const e = error;
+    if (e.code === "ENOENT") {
+        return new AxiError("acli is not installed or not on PATH", "ACLI_NOT_FOUND", [
+            "Install the Atlassian CLI: https://developer.atlassian.com/cloud/acli/guides/install-acli/",
+        ]);
+    }
+    const raw = [e.stderr, e.stdout].filter(Boolean).join("\n").trim() || e.message || "acli failed";
+    const message = raw.replace(/^✗\s*Error:\s*/m, "").trim();
+    if (/not authenticated|unauthenticated|log ?in|token expired/i.test(message)) {
+        return new AxiError(message, "AUTH_ERROR", ["Run `acli jira auth login --web` to authenticate"]);
+    }
+    return new AxiError(message, "ACLI_ERROR");
+}

package/dist/auth.js

@@ -0,0 +1,6 @@
+export function parseAuthStatus(status) {
+    return {
+        site: status.match(/Site:\s*(\S+)/)?.[1],
+        email: status.match(/Email:\s*(\S+)/)?.[1],
+    };
+}

package/dist/commands/create.js

@@ -0,0 +1,101 @@
+import { AxiError } from "axi-sdk-js";
+import { acli, acliJson } from "../acli.js";
+import { parseAuthStatus } from "../auth.js";
+import { flatten } from "../fields.js";
+import { parseFlags, requireFlag } from "../flags.js";
+import { parseFieldPairs, toAdf, withJsonFile } from "../payload.js";
+const EXAMPLE = 'acli-axi create --project TEAM --type Story --summary "New thing"';
+const PASSTHROUGH = ["description", "assignee", "label", "parent"];
+export async function create(args, _context) {
+    const { values } = parseFlags(args, {
+        project: { type: "string" },
+        type: { type: "string" },
+        summary: { type: "string" },
+        description: { type: "string" },
+        assignee: { type: "string" },
+        label: { type: "string" },
+        parent: { type: "string" },
+        field: { type: "string", multiple: true, short: "f" },
+    }, EXAMPLE);
+    const project = requireFlag(values.project, "project", EXAMPLE);
+    const type = requireFlag(values.type, "type", EXAMPLE);
+    const summary = requireFlag(values.summary, "summary", EXAMPLE);
+    const custom = parseFieldPairs(values.field ?? []);
+    const result = Object.keys(custom).length
+        ? await createFromJson(values, project, type, summary, custom)
+        : await createFromFlags(values, project, type, summary);
+    if (!result.key) {
+        throw new AxiError("acli did not return a work item key; the create may or may not have succeeded", "ACLI_ERROR", [`Verify with: acli-axi search --jql "project = ${project} ORDER BY created DESC" --limit 5`]);
+    }
+    return {
+        created: result.key,
+        ...echoInvariants(result.fields, values, custom),
+        help: [`Run \`acli-axi view ${result.key}\` to inspect it`],
+    };
+}
+// Plain flag path: everything acli exposes as flags. Kept separate because it is
+// the live-verified surface; JSON is only needed for custom fields.
+async function createFromFlags(values, project, type, summary) {
+    const acliArgs = ["jira", "workitem", "create", "--project", project, "--type", type, "--summary", summary];
+    for (const flag of PASSTHROUGH) {
+        if (typeof values[flag] === "string") {
+            acliArgs.push(`--${flag}`, values[flag]);
+        }
+    }
+    return acliJson(acliArgs);
+}
+// Custom fields (sprint, story points, ...) have no acli flag; --from-json is
+// acli's only door to them. The temp payload never enters agent context.
+async function createFromJson(values, project, type, summary, custom) {
+    const payload = {
+        projectKey: project,
+        type,
+        summary,
+        additionalAttributes: custom,
+    };
+    if (typeof values.assignee === "string")
+        payload.assignee = await resolveAssignee(values.assignee);
+    if (typeof values.parent === "string")
+        payload.parentIssueId = values.parent;
+    if (typeof values.label === "string")
+        payload.labels = values.label.split(",");
+    if (typeof values.description === "string")
+        payload.description = toAdf(values.description);
+    return withJsonFile(payload, (path) => acliJson(["jira", "workitem", "create", "--from-json", path]));
+}
+// acli's --assignee flag resolves @me itself, but --from-json treats the
+// assignee string as a user search — a literal "@me" in the payload assigned
+// an unrelated user on a live site. Resolve it to the authed email up front.
+async function resolveAssignee(assignee) {
+    if (assignee !== "@me") {
+        return assignee;
+    }
+    const email = parseAuthStatus(await acli(["jira", "auth", "status"])).email;
+    if (!email) {
+        throw new AxiError("could not resolve @me: no authenticated email in `acli jira auth status`", "AUTH_ERROR", ["Run `acli jira auth login --web` to authenticate, or pass an explicit email/accountId"]);
+    }
+    return email;
+}
+// acli echoes the full created issue; reflect back the invariants the caller
+// set so verification costs zero extra calls.
+function echoInvariants(fields, values, custom) {
+    if (!fields) {
+        return {};
+    }
+    const echo = {};
+    const issuetype = fields.issuetype;
+    if (issuetype?.name)
+        echo.type = issuetype.name;
+    const parent = fields.parent;
+    if (values.parent && parent?.key)
+        echo.parent = parent.key;
+    const assignee = fields.assignee;
+    if (values.assignee && assignee?.displayName)
+        echo.assignee = assignee.displayName;
+    for (const id of Object.keys(custom)) {
+        if (fields[id] !== undefined && fields[id] !== null) {
+            echo[id] = flatten(fields[id]);
+        }
+    }
+    return echo;
+}

package/dist/commands/edit.js

@@ -0,0 +1,51 @@
+import { AxiError } from "axi-sdk-js";
+import { acli } from "../acli.js";
+import { parseFlags } from "../flags.js";
+import { parseFieldPairs } from "../payload.js";
+const EXAMPLE = 'acli-axi edit TEAM-123 --summary "Better title"';
+const CHANGE_FLAGS = ["summary", "description", "assignee", "labels", "type"];
+export async function edit(args, _context) {
+    const { values, positionals } = parseFlags(args, {
+        summary: { type: "string" },
+        description: { type: "string" },
+        assignee: { type: "string" },
+        labels: { type: "string" },
+        type: { type: "string" },
+        "remove-assignee": { type: "boolean" },
+        field: { type: "string", multiple: true, short: "f" },
+    }, EXAMPLE, 1);
+    const key = positionals[0];
+    if (!key) {
+        throw new AxiError("A work item key is required", "VALIDATION_ERROR", [`Example: ${EXAMPLE}`]);
+    }
+    const acliArgs = ["jira", "workitem", "edit", "--key", key];
+    let changed = false;
+    for (const flag of CHANGE_FLAGS) {
+        if (typeof values[flag] === "string") {
+            acliArgs.push(`--${flag}`, values[flag]);
+            changed = true;
+        }
+    }
+    if (values["remove-assignee"]) {
+        acliArgs.push("--remove-assignee");
+        changed = true;
+    }
+    const custom = parseFieldPairs(values.field ?? []);
+    if (!changed && Object.keys(custom).length === 0) {
+        throw new AxiError("At least one change flag is required", "VALIDATION_ERROR", [
+            `Example: ${EXAMPLE}`,
+            `Change flags: ${CHANGE_FLAGS.map((f) => `--${f}`).join(", ")}, --remove-assignee, --field <id>=<value>`,
+        ]);
+    }
+    if (Object.keys(custom).length > 0) {
+        // acli's edit --from-json schema strictly rejects additionalAttributes
+        // (verified live, acli 1.3.22) — custom fields are create-only in acli.
+        throw new AxiError("acli cannot edit custom fields on an existing work item (its edit schema rejects additionalAttributes)", "VALIDATION_ERROR", [
+            "Custom fields can only be set at creation: acli-axi create ... -f <id>=<value>",
+            "To fix a wrong custom field, edit it in the Jira UI or recreate the work item",
+        ]);
+    }
+    // --yes: acli prompts for confirmation otherwise, which would hang an agent
+    await acli([...acliArgs, "--yes"]);
+    return { edited: key, help: [`Run \`acli-axi view ${key}\` to verify`] };
+}

package/dist/commands/home.js

@@ -0,0 +1,28 @@
+import { acli, acliJson } from "../acli.js";
+import { parseAuthStatus } from "../auth.js";
+import { flattenFields } from "../fields.js";
+const MY_OPEN_JQL = "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC";
+export async function home(_args, _context) {
+    const [status, items] = await Promise.all([
+        acli(["jira", "auth", "status"]),
+        acliJson([
+            "jira", "workitem", "search", "--jql", MY_OPEN_JQL, "--limit", "5", "--fields", "key,status,summary",
+        ]),
+    ]);
+    const parsed = parseAuthStatus(status);
+    const site = parsed.site ?? "unknown";
+    const email = parsed.email ?? "unknown";
+    const open = items ?? [];
+    return {
+        auth: { site, email },
+        my_open_workitems: open.length
+            ? open.map((item) => ({ key: item.key, ...flattenFields(item.fields) }))
+            : "0 open work items assigned to you",
+        help: [
+            'acli-axi search --jql "project = TEAM AND sprint in openSprints()"',
+            "acli-axi view <KEY>",
+            "acli-axi sprints --board <id>",
+            'acli-axi create --project TEAM --type Story --summary "..."',
+        ],
+    };
+}

package/dist/commands/search.js

@@ -0,0 +1,40 @@
+import { AxiError } from "axi-sdk-js";
+import { acli, acliJson } from "../acli.js";
+import { flattenFields } from "../fields.js";
+import { parseFlags, requireFlag } from "../flags.js";
+const EXAMPLE = 'acli-axi search --jql "project = TEAM AND sprint in openSprints()"';
+export async function search(args, _context) {
+    const { values } = parseFlags(args, { jql: { type: "string" }, limit: { type: "string" }, fields: { type: "string" } }, EXAMPLE);
+    const jql = requireFlag(values.jql, "jql", EXAMPLE);
+    const limit = values.limit ?? "25";
+    const acliArgs = ["jira", "workitem", "search", "--jql", jql, "--limit", limit];
+    if (typeof values.fields === "string") {
+        acliArgs.push("--fields", values.fields);
+    }
+    const items = (await acliJson(acliArgs)) ?? [];
+    if (items.length === 0) {
+        return { total: 0, message: "No work items match this JQL query." };
+    }
+    // A full page means the true total is unknown; one extra --count call makes it definitive.
+    const total = items.length >= Number(limit) ? await countMatches(jql) : items.length;
+    const truncated = total > items.length;
+    return {
+        total,
+        ...(truncated ? { showing: items.length } : {}),
+        workitems: items.map((item) => ({ key: item.key, ...flattenFields(item.fields) })),
+        help: [
+            ...(truncated
+                ? [`Re-run with --limit ${Math.min(total, 500)} to see more of the ${total} matches`]
+                : []),
+            "Run `acli-axi view <key>` for full details including description",
+        ],
+    };
+}
+async function countMatches(jql) {
+    const output = await acli(["jira", "workitem", "search", "--jql", jql, "--count"]);
+    const match = output.match(/:\s*(\d+)/);
+    if (!match) {
+        throw new AxiError(`Could not parse total from acli --count output: ${output.slice(0, 120)}`, "ACLI_ERROR");
+    }
+    return Number(match[1]);
+}

package/dist/commands/sprints.js

@@ -0,0 +1,43 @@
+import { acliJson } from "../acli.js";
+import { truncate } from "../fields.js";
+import { parseFlags, requireFlag } from "../flags.js";
+const EXAMPLE = "acli-axi sprints --board 36";
+const GOAL_LIMIT = 120;
+export async function sprints(args, _context) {
+    const { values } = parseFlags(args, { board: { type: "string" }, state: { type: "string" }, limit: { type: "string" }, full: { type: "boolean" } }, EXAMPLE);
+    const board = requireFlag(values.board, "board", EXAMPLE);
+    const state = values.state ?? "active,future";
+    const result = await acliJson([
+        "jira", "board", "list-sprints", "--id", board, "--state", state, "--limit", values.limit ?? "50",
+    ]);
+    let goalsTruncated = false;
+    const rows = (result.sprints ?? []).map((sprint) => {
+        const goal = sprint.goal?.replaceAll("\n", " ");
+        if (goal && !values.full && goal.length > GOAL_LIMIT) {
+            goalsTruncated = true;
+        }
+        return {
+            id: sprint.id,
+            name: sprint.name,
+            state: sprint.state,
+            start: sprint.startDate?.slice(0, 10),
+            end: sprint.endDate?.slice(0, 10),
+            goal: goal && !values.full ? truncate(goal, GOAL_LIMIT) : goal,
+        };
+    });
+    if (rows.length === 0) {
+        return { total: 0, message: `No sprints on board ${board} in state: ${state}.` };
+    }
+    const total = result.total ?? rows.length;
+    const truncated = total > rows.length;
+    return {
+        total,
+        ...(truncated ? { showing: rows.length } : {}),
+        sprints: rows,
+        help: [
+            ...(truncated ? [`Re-run with --limit ${total} to see all ${total} sprints`] : []),
+            ...(goalsTruncated ? ["Re-run with --full for complete sprint goals"] : []),
+            `acli-axi search --jql "sprint = <id>" to list a sprint's work items`,
+        ],
+    };
+}

package/dist/commands/view.js

@@ -0,0 +1,26 @@
+import { AxiError } from "axi-sdk-js";
+import { acliJson } from "../acli.js";
+import { flattenFields } from "../fields.js";
+import { parseFlags } from "../flags.js";
+const EXAMPLE = "acli-axi view TEAM-123";
+const DESCRIPTION_LIMIT = 1000;
+export async function view(args, _context) {
+    const { values, positionals } = parseFlags(args, { full: { type: "boolean" }, fields: { type: "string" } }, EXAMPLE, 1);
+    const key = positionals[0];
+    if (!key) {
+        throw new AxiError("A work item key is required", "VALIDATION_ERROR", [`Example: ${EXAMPLE}`]);
+    }
+    const acliArgs = ["jira", "workitem", "view", key];
+    if (typeof values.fields === "string") {
+        acliArgs.push("--fields", values.fields);
+    }
+    const item = await acliJson(acliArgs);
+    const fields = flattenFields(item.fields);
+    const description = fields.description;
+    if (typeof description === "string" && !values.full && description.length > DESCRIPTION_LIMIT) {
+        fields.description = description.slice(0, DESCRIPTION_LIMIT);
+        fields.description_truncated = `showing ${DESCRIPTION_LIMIT} of ${description.length} chars`;
+        fields.help = [`Run \`acli-axi view ${key} --full\` for the complete description`];
+    }
+    return { key: item.key, ...fields };
+}

package/dist/fields.js

@@ -0,0 +1,47 @@
+// Collapses Jira's deeply nested field payloads (avatar URLs, self links,
+// status categories) into the scalar an agent actually reads.
+export function flattenFields(fields) {
+    return Object.fromEntries(Object.entries(fields)
+        .map(([key, value]) => [key, flatten(value)])
+        .filter(([, value]) => value !== null && value !== undefined));
+}
+export function flatten(value) {
+    if (Array.isArray(value)) {
+        return value.map(flatten);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const record = value;
+    if (record.type === "doc" && Array.isArray(record.content)) {
+        return adfToText(record);
+    }
+    const scalar = record.displayName ?? record.name ?? record.value ?? record.emailAddress;
+    if (scalar !== undefined && scalar !== null) {
+        return scalar;
+    }
+    return Object.fromEntries(Object.entries(record)
+        .filter(([key]) => !NOISE_KEYS.has(key))
+        .map(([key, nested]) => [key, flatten(nested)]));
+}
+// Jira hypermedia noise an agent never reads; keeps custom/--fields '*all'
+// output as lean as the default field set.
+const NOISE_KEYS = new Set(["self", "avatarUrls", "iconUrl", "expand"]);
+// Minimal Atlassian Document Format -> plain text: joins text nodes,
+// newline per block. ponytail: ignores marks/tables/media, add if agents need them.
+function adfToText(node) {
+    if (typeof node.text === "string") {
+        return node.text;
+    }
+    if (!Array.isArray(node.content)) {
+        return "";
+    }
+    const joiner = node.type === "doc" ? "\n" : "";
+    return node.content
+        .map((child) => adfToText(child))
+        .filter((text) => text.length > 0)
+        .join(joiner);
+}
+export function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}… (${text.length} chars total)` : text;
+}

package/dist/flags.js

@@ -0,0 +1,34 @@
+import { parseArgs } from "node:util";
+import { AxiError } from "axi-sdk-js";
+export function parseFlags(args, options, example, maxPositionals = 0) {
+    try {
+        const { values, positionals } = parseArgs({ args, options, strict: true, allowPositionals: true });
+        if (positionals.length > maxPositionals) {
+            throw new AxiError(`Unexpected argument: ${positionals[maxPositionals]}`, "VALIDATION_ERROR", [
+                `Valid flags: ${Object.keys(options)
+                    .map((flag) => `--${flag}`)
+                    .join(", ")}`,
+                `Example: ${example}`,
+            ]);
+        }
+        return { values: values, positionals };
+    }
+    catch (error) {
+        if (error instanceof AxiError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new AxiError(message, "VALIDATION_ERROR", [
+            `Valid flags: ${Object.keys(options)
+                .map((flag) => `--${flag}`)
+                .join(", ")}`,
+            `Example: ${example}`,
+        ]);
+    }
+}
+export function requireFlag(value, flag, example) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new AxiError(`--${flag} is required`, "VALIDATION_ERROR", [`Example: ${example}`]);
+    }
+    return value;
+}

package/dist/help.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+export const { version: VERSION, description: DESCRIPTION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const TOP_LEVEL_HELP = `acli-axi — ${DESCRIPTION}
+
+commands:
+  search   --jql <query> [--limit N] [--fields a,b]      Search work items
+  view     <KEY> [--full] [--fields a,b]                 View one work item
+  create   --project P --type T --summary S [...]        Create a work item
+  edit     <KEY> --summary|--assignee|--labels|... S     Edit a work item
+  sprints  --board <id> [--state active,future,closed]   List board sprints
+
+Run \`acli-axi <command> --help\` for flags and examples.
+Requires the Atlassian CLI (acli) installed and authenticated (\`acli jira auth login --web\`).
+`;
+export const COMMAND_HELP = {
+    search: `search: query Jira work items with JQL
+flags:
+  --jql <query>     JQL query (required)
+  --limit <n>       Max results (default 25)
+  --fields <a,b>    Comma-separated fields (default: issuetype,key,assignee,priority,status,summary)
+example: acli-axi search --jql "project = TEAM AND sprint in openSprints()"
+`,
+    view: `view: full detail for one work item
+usage: acli-axi view <KEY> [--full] [--fields a,b]
+  --full            Do not truncate long descriptions
+  --fields <a,b>    Field subset ('*all' for everything)
+example: acli-axi view TEAM-123
+`,
+    create: `create: create a work item
+flags: --project (required), --type (required), --summary (required),
+       --description, --assignee ('@me' to self-assign), --label, --parent,
+       -f/--field <id>=<value> (repeatable; custom fields, e.g. story points, sprint)
+note:  --description takes plain text or an ADF doc as JSON. Markdown is never
+       converted — it is stored as literal characters.
+example: acli-axi create --project TEAM --type Story --summary "New thing" --assignee @me -f customfield_10028=1
+`,
+    edit: `edit: change fields on a work item (never prompts)
+usage: acli-axi edit <KEY> [--summary S] [--description D] [--assignee A] [--labels L] [--type T] [--remove-assignee] [-f/--field <id>=<value>]
+example: acli-axi edit TEAM-123 --summary "Better title"
+`,
+    sprints: `sprints: list sprints on a board
+flags: --board <id> (required), --state <s> (default active,future), --limit <n>, --full (untruncated goals)
+example: acli-axi sprints --board 36
+`,
+};

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { runAxiCli } from "axi-sdk-js";
+import { COMMAND_HELP, TOP_LEVEL_HELP, VERSION } from "./help.js";
+import { search } from "./commands/search.js";
+import { view } from "./commands/view.js";
+import { create } from "./commands/create.js";
+import { edit } from "./commands/edit.js";
+import { sprints } from "./commands/sprints.js";
+import { home } from "./commands/home.js";
+await runAxiCli({
+    description: "Manage Jira work items and sprints via the Atlassian CLI",
+    version: VERSION,
+    topLevelHelp: TOP_LEVEL_HELP,
+    getCommandHelp: (command) => COMMAND_HELP[command],
+    home,
+    commands: { search, view, create, edit, sprints },
+});

package/dist/payload.js

@@ -0,0 +1,60 @@
+import { unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AxiError } from "axi-sdk-js";
+// --field customfield_10028=0.5 → { customfield_10028: 0.5 }
+// Values that parse as JSON become numbers/arrays/objects; everything else stays a string.
+export function parseFieldPairs(pairs) {
+    const fields = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq < 1) {
+            throw new AxiError(`--field must be <id>=<value>, got: ${pair}`, "VALIDATION_ERROR", [
+                "Example: --field customfield_10028=0.5",
+            ]);
+        }
+        const raw = pair.slice(eq + 1);
+        let value = raw;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            // not JSON — keep the raw string
+        }
+        fields[pair.slice(0, eq)] = value;
+    }
+    return fields;
+}
+export function adfParagraph(text) {
+    return {
+        type: "doc",
+        version: 1,
+        content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+    };
+}
+// acli's own --description flag accepts "plain text or ADF" and detects which it
+// got; --from-json takes only ADF. Mirroring that detection keeps both create
+// branches equivalent — without it, adding any -f flag silently downgraded a
+// caller's ADF doc into the literal JSON text of that doc.
+export function toAdf(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === "object" && parsed !== null && parsed.type === "doc") {
+            return parsed;
+        }
+    }
+    catch {
+        // not JSON — plain text
+    }
+    return adfParagraph(text);
+}
+export async function withJsonFile(payload, run) {
+    const path = join(tmpdir(), `acli-axi-${process.pid}-${Date.now()}.json`);
+    writeFileSync(path, JSON.stringify(payload));
+    try {
+        return await run(path);
+    }
+    finally {
+        unlinkSync(path);
+    }
+}

package/dist/skill-build.js

@@ -0,0 +1,13 @@
+// Regenerates skills/acli-axi/SKILL.md from the shared CLI guidance.
+// Drift is caught by test/skill.test.ts, which pins the committed file
+// byte-for-byte to createSkillMarkdown().
+//
+//   pnpm run build:skill
+import { mkdir, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { createSkillMarkdown } from "./skill.js";
+const dir = new URL("../skills/acli-axi/", import.meta.url);
+const target = new URL("SKILL.md", dir);
+await mkdir(dir, { recursive: true });
+await writeFile(target, createSkillMarkdown());
+console.log(`Wrote ${fileURLToPath(target)}`);

package/dist/skill.js

@@ -0,0 +1,84 @@
+import { DESCRIPTION, TOP_LEVEL_HELP } from "./help.js";
+// Trigger string agent harnesses match against to auto-load the skill.
+// Kept terse and outcome-focused so it fires on "needs Jira" intents.
+export const SKILL_DESCRIPTION = "Operate Jira through the acli-axi CLI - search work items with JQL, view full item detail, " +
+    "create and edit work items (including create-time custom fields like story points and sprint), " +
+    "and list board sprints. " +
+    "Use whenever a task touches Jira: searching or triaging work items, filing stories or bugs, " +
+    "editing summaries or assignees, or checking sprint contents.";
+export const SKILL_AUTHOR = "Mathieu Neron";
+function yamlDoubleQuote(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Extract the `commands:` block from the top-level help so the skill's
+ * command list can never drift from what `acli-axi --help` prints.
+ */
+export function extractCommandsBlock() {
+    const match = TOP_LEVEL_HELP.match(/^(commands:\n(?: {2}.*\n)+)/m);
+    if (!match) {
+        throw new Error("Could not find commands block in TOP_LEVEL_HELP");
+    }
+    return match[1].trimEnd();
+}
+/**
+ * Render the installable SKILL.md for the acli-axi skill. The body is built
+ * from the same shared guidance the CLI prints (package description and
+ * top-level help). The package is published to npm, so the skill teaches the
+ * plain global install with npx as a one-off fallback.
+ *
+ * @returns full SKILL.md contents including YAML frontmatter
+ */
+export function createSkillMarkdown() {
+    return `---
+name: acli-axi
+description: ${yamlDoubleQuote(SKILL_DESCRIPTION)}
+user-invocable: false
+author: ${SKILL_AUTHOR}
+---
+
+# acli-axi
+
+${DESCRIPTION}. Prefer it over raw \`acli\` for Jira reads and searches - output is TOON-encoded and token-efficient, with definitive totals and structured errors.
+
+acli-axi is published to npm; install it globally:
+
+\`\`\`sh
+npm install -g acli-axi
+\`\`\`
+
+If \`acli-axi\` is not on PATH, ask the user to run that install (or offer to run it for them - it is a non-credential npm install), or use \`npx -y acli-axi\` for one-off runs.
+
+acli-axi wraps the [Atlassian CLI (\`acli\`)](https://developer.atlassian.com/cloud/acli/), which must be installed and authenticated. If a command fails with an authentication error (\`AUTH_ERROR\`), ask the user to run \`acli jira auth login --web\` themselves - it is an interactive OAuth flow, never run it for them.
+
+## When to use
+
+Use acli-axi whenever a task touches Jira: searching work items with JQL, viewing one item's full detail, creating stories or bugs (including custom fields such as story points or sprint), editing summaries, assignees, labels, or types, or listing a board's sprints.
+
+## Workflow
+
+1. Run \`acli-axi\` with no arguments for a home view - auth state plus your open work items and suggested next commands.
+2. Search with \`acli-axi search --jql "..."\`. Totals are definitive: when a page fills its \`--limit\`, the output reports \`total\` vs \`showing\` - raise \`--limit\` to see more instead of guessing.
+3. Drill in with \`acli-axi view <KEY>\` (long descriptions truncate; add \`--full\` to expand).
+4. Create with \`acli-axi create --project P --type T --summary S\`; custom fields go in as repeatable \`-f customfield_XXXXX=<value>\` flags. The response echoes the created item - no read-back needed.
+5. Edit flag-editable fields with \`acli-axi edit <KEY> --summary ...\` (never prompts). Custom fields are create-only: acli's edit schema rejects them, and acli-axi refuses \`-f\` on edit with a structured error - that is an upstream acli limitation, not a bug to retry.
+6. Every response ends with contextual next-step hints under \`help:\` - follow them.
+
+## Commands
+
+\`\`\`
+${extractCommandsBlock()}
+\`\`\`
+
+Run \`acli-axi --help\` for global flags, or \`acli-axi <command> --help\` for per-command usage.
+
+The SDK built-in \`update\` command queries the npm registry, so it fails with a structured not-found while the package is unpublished - that is expected. Upgrade by re-running the git install command above.
+
+## Tips
+
+- Output is TOON-encoded and token-efficient; the gain scales with result count, so prefer \`search\` over per-item loops.
+- Values passed to \`-f\` parse as JSON when possible (numbers, arrays); everything else stays a string.
+- \`view\` can intermittently fail inside acli's JSON formatter and surfaces as a structured \`ACLI_ERROR\`; it is a read, so retrying once is safe.
+- Errors are structured (\`error:\` + \`code:\` + \`help:\`): exit 2 for usage errors, exit 1 for everything else; stdout is data, stderr is diagnostics.
+`;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "acli-axi",
+  "version": "0.1.0",
+  "description": "AXI for Atlassian Jira \u2014 token-efficient agent interface over the Atlassian CLI (acli)",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mathieu Neron <mathieu.neron.ing@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mathieu-neron/acli-axi.git"
+  },
+  "homepage": "https://github.com/mathieu-neron/acli-axi#readme",
+  "bugs": {
+    "url": "https://github.com/mathieu-neron/acli-axi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "jira",
+    "atlassian",
+    "cli",
+    "agent",
+    "axi",
+    "toon",
+    "acli"
+  ],
+  "bin": {
+    "acli-axi": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills/acli-axi",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "build:skill": "npm run build && node dist/skill-build.js"
+  },
+  "dependencies": {
+    "axi-sdk-js": "^0.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0",
+    "yaml": "^2.9.0"
+  },
+  "packageManager": "pnpm@10.30.2"
+}

package/skills/acli-axi/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: acli-axi
+description: "Operate Jira through the acli-axi CLI - search work items with JQL, view full item detail, create and edit work items (including create-time custom fields like story points and sprint), and list board sprints. Use whenever a task touches Jira: searching or triaging work items, filing stories or bugs, editing summaries or assignees, or checking sprint contents."
+user-invocable: false
+author: Mathieu Neron
+---
+
+# acli-axi
+
+AXI for Atlassian Jira — token-efficient agent interface over the Atlassian CLI (acli). Prefer it over raw `acli` for Jira reads and searches - output is TOON-encoded and token-efficient, with definitive totals and structured errors.
+
+acli-axi is published to npm; install it globally:
+
+```sh
+npm install -g acli-axi
+```
+
+If `acli-axi` is not on PATH, ask the user to run that install (or offer to run it for them - it is a non-credential npm install), or use `npx -y acli-axi` for one-off runs.
+
+acli-axi wraps the [Atlassian CLI (`acli`)](https://developer.atlassian.com/cloud/acli/), which must be installed and authenticated. If a command fails with an authentication error (`AUTH_ERROR`), ask the user to run `acli jira auth login --web` themselves - it is an interactive OAuth flow, never run it for them.
+
+## When to use
+
+Use acli-axi whenever a task touches Jira: searching work items with JQL, viewing one item's full detail, creating stories or bugs (including custom fields such as story points or sprint), editing summaries, assignees, labels, or types, or listing a board's sprints.
+
+## Workflow
+
+1. Run `acli-axi` with no arguments for a home view - auth state plus your open work items and suggested next commands.
+2. Search with `acli-axi search --jql "..."`. Totals are definitive: when a page fills its `--limit`, the output reports `total` vs `showing` - raise `--limit` to see more instead of guessing.
+3. Drill in with `acli-axi view <KEY>` (long descriptions truncate; add `--full` to expand).
+4. Create with `acli-axi create --project P --type T --summary S`; custom fields go in as repeatable `-f customfield_XXXXX=<value>` flags. The response echoes the created item - no read-back needed.
+5. Edit flag-editable fields with `acli-axi edit <KEY> --summary ...` (never prompts). Custom fields are create-only: acli's edit schema rejects them, and acli-axi refuses `-f` on edit with a structured error - that is an upstream acli limitation, not a bug to retry.
+6. Every response ends with contextual next-step hints under `help:` - follow them.
+
+## Commands
+
+```
+commands:
+  search   --jql <query> [--limit N] [--fields a,b]      Search work items
+  view     <KEY> [--full] [--fields a,b]                 View one work item
+  create   --project P --type T --summary S [...]        Create a work item
+  edit     <KEY> --summary|--assignee|--labels|... S     Edit a work item
+  sprints  --board <id> [--state active,future,closed]   List board sprints
+```
+
+Run `acli-axi --help` for global flags, or `acli-axi <command> --help` for per-command usage.
+
+The SDK built-in `update` command queries the npm registry, so it fails with a structured not-found while the package is unpublished - that is expected. Upgrade by re-running the git install command above.
+
+## Tips
+
+- Output is TOON-encoded and token-efficient; the gain scales with result count, so prefer `search` over per-item loops.
+- Values passed to `-f` parse as JSON when possible (numbers, arrays); everything else stays a string.
+- `view` can intermittently fail inside acli's JSON formatter and surfaces as a structured `ACLI_ERROR`; it is a read, so retrying once is safe.
+- Errors are structured (`error:` + `code:` + `help:`): exit 2 for usage errors, exit 1 for everything else; stdout is data, stderr is diagnostics.