t1k:ax
| Field | Value |
|---|---|
| Module | t1k-engineering |
| Version | 2.10.23 |
| Effort | low |
| Tools | — |
Keywords: agent-experience, agent-readable, ax, cli, exit-codes, hook, json-output, mcp, no-prompt, review-for-agents
How to invoke
Section titled “How to invoke”/t1k:ax[checklist <type> | audit <path...>]t1k-ax: agent experience for new tooling
Section titled “t1k-ax: agent experience for new tooling”A tool is agent-ready when a model can run it, parse it and recover from its errors without a human.
This skill is the checklist you read before writing it and the audit you run after. It cites, never
restates: docs/development-principles.md § “AI-Native by Default” (the rule), docs/marker-namespaces.md
(the [t1k:ax-review ...] frame), docs/ai-driven-design.md (scripts emit facts, the model decides)
and docs/one-click-handoff.md (when the tool must hand a step to a human).
Mode selector
Section titled “Mode selector”| You are | Mode | Do |
|---|---|---|
| About to write or change a CLI, hook, script, skill, agent, rule, MCP tool or doc | CHECKLIST | Read the matching headings of references/ax-checklist.md, build to them, state the ids in the plan AX: line |
| Reviewing a diff or a hook frame asked you to | AUDIT | Run bun .claude/skills/t1k-ax/scripts/ax-audit.cjs <path...> --json (or --changed), then judge per references/audit-rubric.md |
The principle ids, titles, strengths and applicability are read from data/ax-principles.json at audit
time; this file never lists them (single source).
Quick list by artifact (ids only; full text in the checklist)
Section titled “Quick list by artifact (ids only; full text in the checklist)”| Type | Start with |
|---|---|
| cli | AX-01, AX-04, AX-07, AX-08, AX-10, AX-14, AX-23 |
| hook | AX-04, AX-07, AX-08, AX-14, AX-15, AX-16 |
| skill | AX-10, AX-12, AX-16, AX-17, AX-20 |
| agent | AX-05, AX-06, AX-09, AX-12 |
| mcp | AX-15, AX-21, AX-03, AX-05, AX-16 |
| doc | AX-19, AX-20, AX-23 |
Gated (the only ids CI may enforce): AX-04, AX-07, AX-08, AX-15. AX-10 is detected but advisory
(strength A, gate: false): a non-blocking severity: advisory finding, never a failing exit; it is
enforced at author time by the checklists, the hook nudge and the plan AX: row. Strength B ids are
advisory too.
AUDIT mode
Section titled “AUDIT mode”bun .claude/skills/t1k-ax/scripts/ax-audit.cjs <path...> [--type <t>] [--changed [--base <ref>]] [--only AX-NN] [--limit n] --json| Exit | Meaning | You do |
|---|---|---|
| 0 | no blocking finding | answer each needs-judgment question, one line |
| 1 | blocking finding | apply the finding’s fix, rerun; max 3 attempts, then escalate to a human |
| 2 | needs input (path, --type, flag) | supply the flag named in stderr fix |
The script reads the file and never executes it. Output stays under 8 KB; omitted and more say how
to see the rest. To waive: ax:waive AX-NN reason="<at least 15 characters>" (see the rubric).
Enforcement surfaces
Section titled “Enforcement surfaces”| Surface | When it fires | Fix path |
|---|---|---|
| Creator checklists (skill, agent, hook creators) | while authoring | read CHECKLIST for the type |
Plan AX: line (t1k-plan, from plan date 261015) | a phase adds a rubric path | write AX: <ids and how> or AX: n/a because <reason> |
Hook frame [t1k:ax-review ...] | after a Write/Edit of a new rubric file | run AUDIT on the named path |
CI gate validate-ax-new-tooling (release-action) | a PR adds JS/TS tooling | fix the cited id or add a waiver with a reason |
Known traps live in the gotcha ledger skills/t1k-rsi/ledger/gotchas/t1k-ax.md.
Executed by
Section titled “Executed by”The audit is a deterministic script run: collecting its JSON is mechanical, answering each
needs-judgment question and deciding a waiver is not. Routing SSOT:
docs/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run ax-audit.cjs and relay the JSON | t1k-data-verifier |
Judge needs-judgment findings, write fixes, decide waivers | the invoking session (reasoning tier, not cheap) |
References
Section titled “References”references/ax-checklist.md: one heading per principle id, mechanical test and sourcesreferences/audit-rubric.md: status semantics, questions per judged id, waiver and retry rulesdocs/t1k-ax.md: human companion page and source register