fix: make the generated skill defer to live CLI guidance

[kunchenguid]

Intent

Fix tasks-axi's skill-fragmentation problem: cut skills/tasks-axi/SKILL.md drastically to a minimal stub that defers to the CLI as the single source of truth, via the GENERATOR so the contract holds on every regeneration. Same minimal-stub pattern the captain approved for lavish-axi, applied family-wide.

The skill duplicates instructions the tasks-axi CLI already prints (help / subcommand / dashboard). Users install the skill once and never update it when they bump the npm package, so the baked copy goes stale. The skill already opens well and defers, but it also bakes a Commands index, a long Tips flag-detail section, and exact-syntax Workflow steps that mirror the CLI.

CRITICAL: fix the GENERATOR (src/skill.ts, via scripts/build-skill.ts / pnpm run build:skill), not just the current output. CI runs pnpm run build:skill -- --check and fails on drift. A future regeneration must not re-inflate the skill.

Keep frontmatter (name/description/metadata). Body only: what tasks-axi is (one or two lines), when to reach for it, and pointers telling the agent to get actual instructions from the CLI: npx -y tasks-axi (dashboard), npx -y tasks-axi --help, and npx -y tasks-axi --help. Remove the Commands index, the Tips flag-detail section, and exact-syntax duplication in Workflow.

Document the contract in tasks-axi AGENTS.md: the shipped skill stays minimal and defers to the CLI for all actual guidance (CLI output is the single source of truth); never re-duplicate CLI-owned instructions into the skill; prefer a pointer over restated detail.

The CLI itself is UNCHANGED: do not remove or shrink --help, subcommand, or dashboard output.

Do not merge. No Greptile on tasks-axi. Captain merges and decides the release.

What Changed

• Simplified the generated tasks-axi skill to retain discovery metadata while directing agents to the live dashboard and CLI help.
• Removed duplicated command, workflow, and flag guidance from the generator and generated skill without changing CLI output.
• Updated tests and contributor documentation to enforce the minimal, CLI-deferring skill contract.

Risk Assessment

🚨 High: The change is otherwise well-bounded, but the generated body directly contradicts an explicit authoritative acceptance constraint and should not merge without human resolution.

Testing

Verified the generator emits the minimal CLI-deferring skill without drift, the focused skill tests pass, and the unchanged dashboard, top-level help, and command help remain available end to end. Initial invalid flag-order and external-cwd evidence attempts were discarded and repeated through supported interfaces.

Evidence: Regenerated minimal tasks-axi skill

Source: Regenerated minimal tasks-axi skill

---
name: tasks-axi
description: "Manage a task backlog through the tasks-axi CLI - add, list, show, start, and complete tasks; track blocked-by dependencies, structured holds, and a ready queue; prune and normalize a hand-editable backlog.md. Use whenever a task touches backlog or task state: filing or dispatching work, recording a PR or report on completion, finding dispatchable or held work, or trimming the Done list."
user-invocable: false
author: Kun Chen (kunchenguid)
metadata:
  hermes:
    tags: [tasks, backlog, planning, dependencies]
    category: productivity
---

# tasks-axi

Agent ergonomic task & backlog manager for the current workspace. Prefer this over hand-editing backlog.md for task state, dependency, or hold changes.

## When to use

Use tasks-axi whenever a task touches the backlog: filing or dispatching work, moving a task through queued -> in flight -> done, recording a PR url or report path on completion, tracking blocked-by dependencies, pausing dispatch with structured holds, finding dispatchable ready work or intentionally held work, or trimming the Done list.

Get every command, flag, and workflow from the live CLI - it is the single source of truth:

- `npx -y tasks-axi` - dashboard of the current backlog
- `npx -y tasks-axi --help` - global usage
- `npx -y tasks-axi <command> --help` - per-command usage

You do not need tasks-axi installed globally. If the CLI prints a follow-up starting with `tasks-axi`, run it as `npx -y tasks-axi ...` instead.

Evidence: Live CLI dashboard, top-level help, and subcommand help transcript

Source: Live CLI dashboard, top-level help, and subcommand help transcript

$ npx -y tasks-axi
bin: ~/.no-mistakes/worktrees/4ebfb4ced0b4/01M0RG9QSZ0FEVE7HREXJGB8A5/bin/tasks-axi.ts
description: "Agent ergonomic task & backlog manager for the current workspace. Prefer this over hand-editing backlog.md for task state, dependency, or hold changes."
in_flight: 0 tasks
queued: 0 tasks
public_followups: 0 obligations
done: 0 retained
help[3]:
  - Run `tasks-axi list` for the full backlog
  - Run `tasks-axi ready` to see unblocked queued work
  - "Run `tasks-axi add <id> \"<title>\" --start` to add and start a task"

$ npx -y tasks-axi --help
usage: tasks-axi [command] [args] [flags]
commands[19]:
  (none)=dashboard, add, list, show, start, done, reopen, update, rm, block, unblock, hold, unhold, ready, public-followup, mv, prune, render, setup
flags[4]:
  --backend <name> (after command), --file <path> (after command), --json (mutations: machine-readable result), --help, -v/-V/--version
examples:
  tasks-axi
  tasks-axi add homemux-h7 "owns HomeMux end to end" --kind secondmate --start
  tasks-axi list --state queued
  tasks-axi show homemux-h7 --full
  tasks-axi done sm-idle-handoff-q8 --pr https://github.com/o/r/pull/42
  tasks-axi block fm-x --by treehouse-lease-t4
  tasks-axi hold fm-x --reason "captain decision pending" --kind captain
  tasks-axi ready
  tasks-axi public-followup ready --json
  tasks-axi setup hooks

$ npx -y tasks-axi show --help
usage: tasks-axi show <id> [--full]
aliases: view
examples:
  tasks-axi show homemux-h7
  tasks-axi show homemux-h7 --full

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 error

• ⚠️ README.md:268 - The generator no longer embeds CLI help, but README.md still says the skill is generated from CLI description and help, while CONTRIBUTING.md:39 still directs regeneration after top-level help changes. Update both to describe the minimal CLI-deferring stub so contributor guidance does not preserve the retired anti-pattern.

🔧 Fix: Align skill documentation with minimal generator contract
1 error still open:

• 🚨 src/skill.ts:58 - Intent requires the body to contain only what tasks-axi is, when to use it, and the three specified CLI pointers. This additional follow-up rewriting instruction (tasks-axi to npx -y tasks-axi ...) is CLI invocation guidance outside that closed list and contradicts the documented minimal-body contract at lines 26-30. Confirm whether this exception is intentional or remove it from the generator and generated skill.

✅ **Test** - passed

✅ No issues found.

• pnpm exec vitest run test/skill.test.ts
• pnpm run build:skill followed by pnpm run build:skill -- --check
• pnpm exec tsx bin/tasks-axi.ts
• pnpm exec tsx bin/tasks-axi.ts --help
• pnpm exec tsx bin/tasks-axi.ts show --help
• Captured the regenerated skill and live CLI dashboard/help outputs as reviewer-visible evidence.

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.