diff --git a/.agents/skills/no-mistakes/SKILL.md b/.agents/skills/no-mistakes/SKILL.md deleted file mode 100644 index bd4f8734..00000000 --- a/.agents/skills/no-mistakes/SKILL.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -name: no-mistakes -description: Validate your code changes through the no-mistakes pipeline - automated code review, tests, lint, docs, push, PR, and CI - before they reach upstream. Use when the user asks to run no-mistakes, gate or ship or validate their changes, push safely, asks you to do a task and then validate it, or invokes /no-mistakes. -user-invocable: true ---- - -# no-mistakes - -`no-mistakes` is a local gate that validates your code changes through a pipeline -(intent, rebase, review, test, document, lint, push, PR, CI) before they reach -upstream. You drive it through the `no-mistakes axi` command family, which prints -machine-readable [TOON](https://toonformat.dev) to stdout and progress to stderr. - -When the user invokes `/no-mistakes`, report the outcome at the end. If the user -asks for something specific, translate that request into the matching `axi run` -flags yourself - for example, "skip the lint step" becomes `--skip=lint`. Run -`no-mistakes axi run --help` to see the available flags. - -## Two ways to invoke - -`/no-mistakes` works in two modes, depending on whether the user hands you a -task along with the command: - -- **Validate-only** - bare `/no-mistakes` (optionally with flag-style requests - like "skip the lint step"). The user's code changes are already committed; - validate them and report the outcome. -- **Task-first** - `/no-mistakes `, e.g. - `/no-mistakes add a --json flag to the status command`. First carry out the - task yourself, then validate the result through the pipeline: - 1. **Check scope.** Inspect `git status` before you change or commit anything. - Preserve unrelated pre-existing uncommitted changes, and when you commit, - commit only the changes that belong to the user's task. - 2. **Do the work.** Make the changes the task describes, then **commit them on - a feature branch**. If the user is on the repository's default branch, - create a feature branch first - the gate validates committed history on a - non-default branch, so the work must land there before you run. - 3. **Then validate**, passing the user's task as your `--intent`. The task - text is exactly what the user set out to accomplish, in their own words, so - it *is* the intent - pass it through, enriched with the decisions and - tradeoffs you made while doing the work (see - [Intent is required](#intent-is-required)). - -Everything below - preconditions, intent, the validate-and-decide loop - applies -the same way once the work is committed on a feature branch. - -## Before you start - -- The work you want validated must be **committed** on a branch. The gate - validates committed history, not your uncommitted working tree. -- You must be on a **feature branch**, not the repository's default branch. -- The repository must already be initialized with `no-mistakes init`. - -If any of these is not met, `axi run` returns an `error:` with the exact command -to fix it - read it and act on it (commit your work, or create a branch). If the -repository is not initialized, run `no-mistakes init` first; if the `no-mistakes` -command itself is missing or misbehaving, `no-mistakes doctor` reports what is -wrong. Before starting, a quick `no-mistakes axi` (home view) shows whether a -run is already active - resume or `axi abort` it rather than starting a second -run on top of it. - -## Intent is required - -When you start a run you must pass `--intent`: **what the user set out to -accomplish** - the goal or request behind this work, in their terms. This is not -a description of the diff or the files you changed; it is the objective the -change is meant to achieve. You know it from the conversation, so pass it -directly - no-mistakes uses it verbatim instead of inferring it from local agent -transcripts (slower and flakier). - -Err on the side of completeness, not brevity. The review step uses `--intent` -to tell a deliberate decision apart from a mistake, so a thin one-line summary -makes it flag things the user already chose. Capture the nuance: the user's -goal, the specific decisions and tradeoffs they made along the way, any -constraints or approaches they ruled in or out, and anything they explicitly -asked for that might otherwise look surprising in the diff. A few sentences to a -short paragraph is normal - write down what you learned from the conversation -that a reviewer reading only the diff would not know. - -## Validate and decide - -Run the pipeline and decide on its findings as they come up: - -1. Start the run. It blocks until the first decision point or the end: - ```sh - no-mistakes axi run --intent "" - ``` - `axi run` and every `axi respond` block synchronously - the review, test, - and CI steps can each take **several minutes**, so a single call may not - return for a while. That is normal; allow a long timeout and do not cancel - or re-issue the command because it seems slow. To check progress without - disturbing the run, use `no-mistakes axi status` from a separate call. -2. If the output contains a `gate:` object, the pipeline is waiting on you. - Read its `findings` table. Each finding has an `id`, `severity`, - `file`, `description`, and an `action` that tells you how the - pipeline classified it: - - `auto-fix` - mechanical and low-risk; you can authorize the fix on - your own judgment by responding with `--action fix`. - - `no-op` - informational only; nothing to do. - - `ask-user` - the finding challenges the user's deliberate intent or - touches product behavior. This is a call only the user can make - see - [Escalate `ask-user` findings](#escalate-ask-user-findings) below. - - Choose one response: - ```sh - # accept the step as-is and continue - no-mistakes axi respond --action approve - - # have the pipeline fix specific findings, then continue - no-mistakes axi respond --action fix --findings --instructions "" - - # skip this step - no-mistakes axi respond --action skip - ``` - While a run is active, never fix findings by editing the code yourself - - the pipeline owns both the findings and the fixes. Your job at a gate is to - decide and respond; `--action fix` has the pipeline apply the fix and - re-review the result. - - Each `respond` blocks until the next `gate:`, `checks-passed` decision point, or final outcome. - - Two extra flags are available on `respond` when you need them: - - `--add-finding ''` (with `--action fix`) folds a finding you - spotted yourself - one the pipeline did not surface - into the fix round, - as a JSON finding object. Use it for a problem you noticed that is not in - the gate's own `findings` table. - - `--step ` responds to a specific step instead of the one currently - awaiting approval. You rarely need this; omit it to answer the active gate. -3. Repeat step 2 until the output has an `outcome:` instead of a `gate:`. The - outcomes are: - - `checks-passed` - the change is validated and CI is green, but the PR is - not merged yet. **You are done driving the pipeline.** Do not wait for the - merge: tell the user the PR is ready and ask them to review and merge it - (the PR link is in the `help` line). no-mistakes keeps monitoring the PR - in the background, so a human can watch it in the TUI. - - `passed` - the changes cleared the gate and the PR was merged or closed. - - `failed` or `cancelled` - they did not; read the output and address it. - Fix whatever the output points at (a failing test, a lint error, a finding - you skipped), commit the fix on the same feature branch, then drive the - pipeline again - `no-mistakes axi run --intent "..."` starts a fresh run, - or `no-mistakes rerun` re-runs the pipeline for the current branch. Do not - leave the user at a `failed` outcome without either retrying or explaining - what blocks it. - -The CI step deliberately watches the PR until it is merged or closed, so -`axi run` returns `checks-passed` the moment checks are green rather than -blocking on the human merge. Never poll or re-run waiting for the merge yourself. - -On a successful outcome (`checks-passed` or `passed`), close the loop with the -user: summarize what happened during the pipeline in a concise, easily readable -format - what was validated and what was found. If the output includes a -`fixes` table, the pipeline fixed findings your original change missed: -acknowledge those misses and explicitly list each fix so the user can easily -review them. - -## Escalate `ask-user` findings - -A gate whose findings are all `auto-fix` or `no-op` is safe to drive on your -own judgment: respond with `--action fix` or `--action approve` as -appropriate. But a finding marked -`ask-user` is a decision that belongs to the user, not you - the pipeline -flagged it because it challenges their deliberate intent or changes product -behavior. Do not approve, fix, or skip it on your own. Instead, stop and bring -it to the user before you respond: - -- Relay each `ask-user` finding to them as the pipeline wrote it - its - `id`, `file`, and full `description` verbatim. Do not paraphrase, - summarize away the detail, or pre-judge the answer. -- Ask how they want to proceed, then translate their decision into the matching - `respond` call: `--action fix` (pass their guidance through - `--instructions`), `--action approve`, or `--action skip`. - -The one exception is `--yes` (below): it is the user's standing consent to -drive every gate unattended, so under `--yes` you resolve `ask-user` -findings automatically instead of stopping to ask. - -If you have clear consent to drive the run automatically, pass `--yes` to `axi run` -or `axi respond`. It treats every actionable finding - `auto-fix` and -`ask-user` alike - as consent to fix it, selects every current finding for one -fix round, accepts the resulting fix review, and approves gates with only -`no-op` findings. Only use it when the user has asked you to drive the whole -run without checking back. - -## Inspecting state - -```sh -no-mistakes axi # home view: active run, recent runs, next steps -no-mistakes axi status # full detail of the active (or most recent) run -no-mistakes axi logs --step --full # full log output of one step -no-mistakes axi abort # cancel the active run -``` - -## Reading the output - -- Output is TOON: `key: value` pairs, `name[N]{cols}:` tables, and `help[N]:` hints. -- The `help` list at the bottom of most responses tells you the next commands to run. -- Errors are printed as `error: ...` on stdout with a `help` list; act on the suggestion. -- Exit codes: `0` success, no-op, or normal decision gates, `1` failed or cancelled final outcomes, `2` bad usage. - -A `gate:` waiting on you looks roughly like this - a `gate:` line naming the -step, a `findings[N]{...}:` table with one row per finding, and a `help[N]:` -list of next commands: - -``` -gate: review -findings[2]{id,severity,file,description,action}: - r1,medium,internal/pipeline/executor.go,Error from os.Remove is ignored,auto-fix - r2,high,cmd/no-mistakes/main.go,New --force flag bypasses the confirm prompt,ask-user -help[2]: - no-mistakes axi respond --action fix --findings r1 - no-mistakes axi respond --action approve -``` - -Read the `action` column per row: decide `r1` (auto-fix) on your own -judgment - `respond --action fix --findings r1` hands it to the pipeline to -fix - but stop and escalate `r2` (ask-user) to the user before responding. A -final state -instead shows `outcome: ` with no -`findings` table. Field names and exact columns can vary by step and version, -so read the actual `findings` header rather than assuming this layout. diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 00000000..e6b7d6c6 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,46 @@ +name: docs-check + +on: + push: + branches: [main] + paths: + - catalog.yaml + - principles.yaml + - README.md + - docs/index.html + - .agents/skills/axi/SKILL.md + - scripts/** + - .prettierrc + - package.json + - pnpm-lock.yaml + - .github/workflows/docs-check.yml + pull_request: + branches: [main] + paths: + - catalog.yaml + - principles.yaml + - README.md + - docs/index.html + - .agents/skills/axi/SKILL.md + - scripts/** + - .prettierrc + - package.json + - pnpm-lock.yaml + - .github/workflows/docs-check.yml + +jobs: + drift: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v6 + with: + node-version: 24 + cache: pnpm + + - run: pnpm install --frozen-lockfile + - run: pnpm run docs:test + - run: pnpm run docs:check diff --git a/.gitignore b/.gitignore index 7d8e6843..992ca748 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,9 @@ docs/social/rendered/ .DS_Store .gnhf/runs/ + +# Playwright MCP session artifacts +.playwright-mcp/ + +# npm lock file (this project uses pnpm) +package-lock.json diff --git a/.no-mistakes/evidence/fm/agmd-axi-g1/agents-md-governance-verification.md b/.no-mistakes/evidence/fm/agmd-axi-g1/agents-md-governance-verification.md new file mode 100644 index 00000000..9a750d9d --- /dev/null +++ b/.no-mistakes/evidence/fm/agmd-axi-g1/agents-md-governance-verification.md @@ -0,0 +1,22 @@ +# AGENTS.md self-governance verification + +Validated target commit `de7bffd1b9b0263d8a1dd94e6858826623d09605` against base `2fa0f2e9c06cd8baa43a02e1fc257d41f24815e7`. + +The root `CLAUDE.md` agent entry point is a symlink to `AGENTS.md`. + +The target adds only `AGENTS.md`. + +The base did not include this heading. + +The target includes it exactly once, as the final block: + +```markdown +## Maintaining this file + +Keep this file for knowledge useful to almost every future agent session in this project. +Do not repeat what the codebase already shows; point to the authoritative file or command instead. +Prefer rewriting or pruning existing entries over appending new ones. +When updating this file, preserve this bar for all agents and keep entries concise. +``` + +The verification checked the single occurrence, byte-for-byte final block, append-only scope, and the agent entry-point symlink. diff --git a/.no-mistakes/evidence/fm/axi-catalog-verification-vision-v1/catalog-policy-scenario-verification.md b/.no-mistakes/evidence/fm/axi-catalog-verification-vision-v1/catalog-policy-scenario-verification.md new file mode 100644 index 00000000..013d60bf --- /dev/null +++ b/.no-mistakes/evidence/fm/axi-catalog-verification-vision-v1/catalog-policy-scenario-verification.md @@ -0,0 +1,35 @@ +# AXI catalog policy scenario verification + +Tested target: `64f3c4b6fe5bdc70fa3098917e19d3a1e5db0d69` + +This artifact exercises the changed `VISION.md` as a generic catalog reviewer would use it. A positive verdict means the policy permits admission. It does not mean admission is automatic. + +## End-user decision scenarios + +| Proposal evidence available to the reviewer | Catalog | Expected verdict from `VISION.md` | Policy reason | +| --- | --- | --- | --- | +| Reviewer independently inspects source at pinned revision `abc123`, identifies the relevant entrypoint and output/error paths, and runs released package `1.2.3` through representative success, invalid-input error, no-results, and `--help` discovery paths. Direct observations cover every applicable AXI principle. | Community | Positive verdict is permitted | Independent pinned-source inspection, released-package execution, representative behavior, and exact provenance are all present. | +| Same evidence as above, for a package selected by the project owner. | Official | Positive verdict is permitted for the owner-maintained catalog | The evidence bar applies to either catalog, while the official catalog remains maintained directly by the project owner and closed to contributed edits. | +| Contributor supplies claims, pasted success/error transcripts, a generated diff, package metadata, and proof that the package name exists, but the reviewer cannot inspect source. | Community | Inconclusive or request source evidence | Contributor-provided verification and existence/metadata checks are insufficient on their own, and required independent source inspection is unavailable. | +| Reviewer inspects a pinned source revision, but a runnable release exists and the reviewer does not execute it. | Either | Inconclusive or request execution evidence | A runnable release requires representative released-package success, error, and discovery execution. | +| Reviewer independently inspects pinned source for a package with no runnable release and records the relevant files, entrypoint, and observable interface behavior across every applicable principle. | Either | Positive verdict can be considered without package execution | Execution is conditional on a runnable release existing; pinned source inspection and applicable-principle evidence remain mandatory. | +| Reviewer executes a local contributor checkout or unreleased build and labels the results as behavior of release `2.0.0`. | Either | Inconclusive or corrected evidence request | The policy forbids attributing observations to a release or revision that was not inspected and requires the exact released version when execution applies. | +| Independent source and released-package checks cover AXI-facing behavior, but do not audit unrelated dependency licensing or business risks. | Either | AXI admission review can proceed | Review is explicitly proportional to applicable AXI behavior and need not exhaustively audit unrelated package concerns. | +| A proposal was already open when the policy changed, but only contributor claims and metadata are currently present. | Community | Inconclusive until the new evidence bar is met | The policy says every new package proposal may receive a positive verdict only after the required review. It contains no grandfathering exception. | + +## Acceptance-criteria trace + +- Both catalogs: "Every new package proposed for either catalog". +- Independent pinned source: reviewer "must inspect the actual source at a pinned revision or release". +- Released behavior: when runnable, reviewer executes representative "success, error, and discovery paths". +- Complete AXI scope: observations must satisfy "all applicable AXI principles". +- Exact provenance: verdict identifies the pinned revision/release, relevant files or code paths, released version, and exercised behavior. +- Insufficient evidence: contributor claims, pasted verification, generated diffs, metadata, and existence checks do not suffice by themselves. +- Fail closed: unavailable required inspection yields an inconclusive verdict or evidence request. +- Ownership: official catalog remains maintained directly by the project owner and closed to contributed additions or edits. +- Proportionality: unrelated exhaustive auditing is not required. +- Self-contained scope: the policy names no Wheelhouse or downstream implementation. + +## Pending-proposal compatibility check + +At test time, the open community catalog proposals included PRs #79, #93, #98, #99, #101, #102, #104, and #105. The policy text itself applies the evidence bar to every new proposal without grandfathering. However, there is no PR for branch `fm/axi-catalog-verification-vision-v1`, so the required PR-level explanation of how pending proposals should be handled cannot yet be verified. diff --git a/.no-mistakes/evidence/fm/axi-doc-redundancy-cleanup-n6/docs-generation-workflow.md b/.no-mistakes/evidence/fm/axi-doc-redundancy-cleanup-n6/docs-generation-workflow.md new file mode 100644 index 00000000..67fdb1b0 --- /dev/null +++ b/.no-mistakes/evidence/fm/axi-doc-redundancy-cleanup-n6/docs-generation-workflow.md @@ -0,0 +1,46 @@ +# Documentation generation workflow evidence + +An end-to-end contributor simulation added a temporary entry to `catalog.yaml`, ran the documented regeneration command, and confirmed that the new entry appeared in both public documentation surfaces. +The temporary entry was then removed and the documentation regenerated again, restoring the target checkout. + +```text +$ pnpm run docs:gen +wrote README.md +wrote docs/index.html + +$ rg -n -C 1 'e2e-docs-validation-axi|Temporary catalog entry used only' README.md docs/index.html +README.md:131:| [`e2e-docs-validation-axi`](https://example.com/e2e-docs-validation-axi) | Automated validation | Test fixture | Temporary catalog entry used only to validate documentation generation. | +docs/index.html:576: e2e-docs-validation-axi for principle 1 titled "Token-efficient output" +exit_code: 1 +``` + +The generated catalog surfaces retained their original public rows after the source-of-truth migration: + +```text +README catalog tables: byte-identical to base (2 tables) +docs/index.html catalog rows: byte-identical to base (official and community) +``` diff --git a/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.html b/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.html new file mode 100644 index 00000000..18a6a355 --- /dev/null +++ b/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.html @@ -0,0 +1,43 @@ + + + + + + VISION.md rendered review + + + +
+
Rendered from the committed root-level VISION.md
+
+

Vision

+

axi should evolve conservatively.
We accept contributions that strengthen AXI without diluting its rigor or expanding shared infrastructure beyond common needs.

+

AXI principles

+

New principles and behavioral changes to existing principles require rigorous validation across representative agents, models, and tasks.
Intuition, preference, and isolated examples are not sufficient.

+

Small, objective corrections that improve clarity without changing meaning or behavior are welcome.

+

Catalog

+

Contributions adding real, verifiable AXIs to the community catalog are welcome.

+

The official catalog is maintained directly by the project owner and is not open to contributed additions or edits.

+

SDKs

+

The AXI SDK should provide common-denominator facilities that nearly every AXI needs.
Niche utilities specific to one tool or narrow class of tools do not belong in the shared SDK.

+

SDKs for additional programming languages are welcome when they:

+
    +
  • remain faithful to the AXI principles;
    • +
  • are structurally similar to the JavaScript SDK; and
    • +
  • expose the same common-denominator facilities without language-specific scope expansion.
    • +
+
+
+ + diff --git a/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.png b/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.png new file mode 100644 index 00000000..a50e48c4 Binary files /dev/null and b/.no-mistakes/evidence/fm/axi-vision-ship-r8/vision-rendered.png differ diff --git a/.no-mistakes/evidence/fm/oracle-axi-catalog-catalog-admission/source-review.md b/.no-mistakes/evidence/fm/oracle-axi-catalog-catalog-admission/source-review.md new file mode 100644 index 00000000..29d29875 --- /dev/null +++ b/.no-mistakes/evidence/fm/oracle-axi-catalog-catalog-admission/source-review.md @@ -0,0 +1,40 @@ +# oracle-axi catalog admission review + +Review target: `thatdudealso/oracle-axi` at source revision `4f4d3da6cfd1578d871fa3e23389264e3faf93ff` (repository `HEAD` on 2026-07-21). + +## Provenance + +- Source repository: https://github.com/thatdudealso/oracle-axi +- Pinned entrypoint: `bin/oracle-axi.js` +- Package metadata: `package.json`, version `0.1.0`, binary `oracle-axi: ./bin/oracle-axi.js` +- No Git tag was advertised by `git ls-remote`; `npm view oracle-axi` returned registry `E404`. No released package exists, so released-package execution is not applicable. + +## Source inspection and observations + +The pinned entrypoint defines `home`, `services`, and `discover` handlers, validates command-specific flags before dependency calls, emits structured stdout, and adds actionable `help` commands. Representative source executions at the pinned revision produced: + +```text +$ curl -fsSL https://raw.githubusercontent.com/thatdudealso/oracle-axi/4f4d3da6cfd1578d871fa3e23389264e3faf93ff/bin/oracle-axi.js | node - +targets_count: 0 +targets: 0 Oracle targets detected in this workspace +help[3]: + Run `oracle-axi doctor` to check Oracle readiness + Run `oracle-axi discover --full` to inspect project Oracle targets + Run `oracle-axi recommend --goal local-dev` to choose an Oracle path + +$ curl -fsSL https://raw.githubusercontent.com/thatdudealso/oracle-axi/4f4d3da6cfd1578d871fa3e23389264e3faf93ff/bin/oracle-axi.js | node - services --capability querying +count: 1 of 12 Oracle domains +services[1]{capability,domain,use}: + querying,"capped-reads|write-guards|result-truncation",run safe SQL with default read-only behavior +help[1]: + Run `oracle-axi recommend --goal ` for workflow paths + +$ curl -fsSL https://raw.githubusercontent.com/thatdudealso/oracle-axi/4f4d3da6cfd1578d871fa3e23389264e3faf93ff/bin/oracle-axi.js | node - discover --bogus +error: unknown flag --bogus for `discover` +help[1]: + valid flags for `discover`: --connect, --cwd, --fields, --full, --help, --password, --service, --tns-admin, --user, --wallet +``` + +The source paths inspected for these observations are `main`, `parseArgs`, `home`, `services`, `discover`, `formatHelp`, and `usageError` in `bin/oracle-axi.js`. + +Verdict: source inspection supports the proposed community catalog admission for the described AXI-facing behavior. This review does not claim released-package behavior because no release was available at the pinned review time. diff --git a/AGENTS.md b/AGENTS.md index 2c1228ed..adf5e2ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,3 +76,13 @@ Because the release PR carries the version bump, a downstream `*-axi` tool only - Packages use ES modules (`"type": "module"`) with TypeScript targeting ES2022/Node16. - Tests are colocated in `test/` directories mirroring `src/` structure and use vitest. +- The AXI catalog and principle summaries are single-sourced from `catalog.yaml` and `principles.yaml`. + `pnpm run docs:gen` rewrites the marked `generated:...` regions of README.md and docs/index.html; never hand-edit those regions. + The `docs-check` workflow runs `pnpm run docs:check` and fails on drift, including when `.agents/skills/axi/SKILL.md` section headings stop matching the canonical principle titles. + +## Maintaining this file + +Keep this file for knowledge useful to almost every future agent session in this project. +Do not repeat what the codebase already shows; point to the authoritative file or command instead. +Prefer rewriting or pruning existing entries over appending new ones. +When updating this file, preserve this bar for all agents and keep entries concise. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7a61e42..ab4a8013 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,17 @@ Release-please PRs are exempt because they are the only place those files should See the [no-mistakes quick start](https://kunchenguid.github.io/no-mistakes/start-here/quick-start/) for the full first-run walkthrough. +## Adding your AXI to the catalog + +The catalog has one source of truth: [`catalog.yaml`](catalog.yaml). +The tables in README.md and on [axi.md](https://axi.md) are generated from it. + +1. Add one entry for your AXI to the `community` list in `catalog.yaml`. +2. Run `pnpm run docs:gen` to regenerate README.md and docs/index.html. +3. Commit all three files and open your PR through the workflow above. + +Do not hand-edit the generated table regions (marked with `generated:...` comments); the `docs-check` CI job fails on drift. + ## Repo conventions - AXI is a pnpm monorepo for the AXI docs, benchmark harnesses, installable agent skills, and the `axi-sdk-js` package. diff --git a/README.md b/README.md index 7f80b65a..ed71dfd1 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,12 @@ Evaluated across 425 runs (17 tasks × 5 conditions × 5 repeats) using Claude S | GitHub MCP + ToolSearch | 82% | $0.147 | 41.1s | 8 | | MCP + Code Mode | 84% | $0.101 | 43.4s | 7 | +Claude Sonnet 4.6 is the model the published runs used, not a limit of the +harness. Both benchmarks take `--model`, which is passed straight through to +the agent CLI, so any Claude model works - for example +`--model claude-opus-4-6`. Results for other models are simply not published +here, and they may respond differently to output format. + ## Quick Start Reference AXI implementations: @@ -66,13 +72,16 @@ Use `gh-axi` for GitHub and `chrome-devtools-axi` for browser automation. ## The 10 Principles -These principles define what makes a CLI tool "an AXI": +These principles define what makes a CLI tool "an AXI". +The table below is generated from [`principles.yaml`](principles.yaml); the full specification of each principle lives in the [AXI skill](.agents/skills/axi/SKILL.md). + + | # | Principle | Summary | | --- | ---------------------------------- | ------------------------------------------------------------------------------------------- | | 1 | **Token-efficient output** | Use [TOON](https://toonformat.dev/) format for ~40% token savings over JSON | -| 2 | **Minimal default schemas** | 3–4 fields per list item, not 10 | -| 3 | **Content truncation** | Truncate large text with size hints and `--full` escape hatch | +| 2 | **Minimal default schemas** | 3–4 fields per list item, not 10+ | +| 3 | **Content truncation** | Truncate large text with size hints and a `--full` escape hatch | | 4 | **Pre-computed aggregates** | Include aggregated counts and statuses that eliminate round trips | | 5 | **Definitive empty states** | Explicit "0 results" rather than ambiguous empty output | | 6 | **Structured errors & exit codes** | Idempotent mutations, structured errors, no interactive prompts, fail loud on unknown flags | @@ -81,12 +90,18 @@ These principles define what makes a CLI tool "an AXI": | 9 | **Contextual disclosure** | Include next-step suggestions after each output | | 10 | **Consistent way to get help** | Concise per-subcommand reference when agents need it | + + ## AXI Catalog +The catalog tables below are generated from [`catalog.yaml`](catalog.yaml) - see [CONTRIBUTING.md](CONTRIBUTING.md) to add your AXI. + ### Official Reference implementations maintained by the AXI project, validating the principles across different domains: + + | AXI | Domain | What it does | | --------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | [`gh-axi`](https://github.com/kunchenguid/gh-axi) | GitHub | Issues, PRs, workflow runs, releases, and more. Wraps the official `gh` CLI with agent-ergonomic output. | @@ -94,24 +109,42 @@ Reference implementations maintained by the AXI project, validating the principl | [`lavish-axi`](https://github.com/kunchenguid/lavish-axi) | Human review | Turns agent-generated HTML artifacts into collaborative review surfaces - annotate, comment, and send feedback back to the agent. | | [`quota-axi`](https://github.com/kunchenguid/quota-axi) | Quota / usage | Reports local Claude, Codex, Cursor, Copilot, and Grok quota/usage windows for routing-aware agents - data-only and local-first. | + + ### Community AXIs built and maintained by the community: -| AXI | Author | Domain | What it does | -| -------------------------------------------------------------------------------------------------- | ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| [`npm-axi`](https://github.com/SSBrouhard/npm-axi) | SSBrouhard | npm | Search and inspect npm registry packages, versions, dependencies, README previews, and downloads with token-efficient output. | -| [`sqlite-axi`](https://github.com/SSBrouhard/sqlite-axi) | SSBrouhard | SQLite | Inspect schemas, sample rows, and run capped read-only SQLite queries with token-efficient TOON output. | -| [`slack-axi`](https://github.com/JarvusInnovations/slack-axi) | Jarvus Innovations | Slack | Read, search, sweep, and safely draft Slack messages with token-efficient output. | -| [`gws-axi`](https://github.com/JarvusInnovations/gws-axi) | Jarvus Innovations | Google Workspace | Gmail, Calendar, Docs, Drive, and Slides behind one command, with multi-account write-safety - drafts mail, never sends. | -| [`harvest-axi`](https://github.com/JarvusInnovations/harvest-axi) | Jarvus Innovations | Time tracking | Review, log, and edit Harvest time entries by period - for yourself, your team, a project, or a client. | -| [`specops`](https://github.com/JarvusInnovations/specops) | Jarvus Innovations | Spec-driven dev | Spec-driven development for agents - and a demo of shipping an AXI embedded in a skill, not a standalone npm executable. | -| [`gitsheets-axi`](https://github.com/JarvusInnovations/gitsheets/tree/main/packages/gitsheets-axi) | Jarvus Innovations | Git-backed data | Read and mutate git-backed record sheets over the shell - TOON output, idempotent commits. | -| [`metabase-axi`](https://github.com/JarvusInnovations/metabase-axi) | Jarvus Innovations | Analytics / BI | Query, explore, and export from Metabase over the shell - SQL/MBQL, saved questions, schema introspection, full-data export. | -| [`otter-axi`](https://github.com/JarvusInnovations/otter-axi) | Jarvus Innovations | Meetings | Find and pull Otter.ai meeting transcripts from the shell - wraps Otter.ai's hosted MCP server as a scriptable, headless CLI. | -| [`notion-axi`](https://github.com/maximebrmd/notion-axi) | maximebrmd | Notion | Search, read, create, and update Notion pages and databases over the shell - token-efficient TOON output, PAT or integration auth. | -| [`clickup-axi`](https://github.com/JanSuthacheeva/clickup-axi) | JanSuthacheeva | ClickUp | List your open tasks, view a task with its newest comments inline, and change task status - truncation-aware, TOON-style output. | -| [`databricks-axi`](https://github.com/p33ves/databricks-axi) | p33ves | Databricks | Run Databricks jobs, watch runs, and pull failure logs inline over the official databricks CLI - more domains coming soon. | + + +| AXI | Author | Domain | What it does | +| -------------------------------------------------------------------------------------------------- | ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`jj-axi`](https://github.com/aivv73/jj-axi) | aivv73 | Version control | Inspect and reshape Jujutsu history through deterministic, non-interactive commands with compact TOON output and operation-aware undo. | +| [`npm-axi`](https://github.com/SSBrouhard/npm-axi) | SSBrouhard | npm | Search and inspect npm registry packages, versions, dependencies, README previews, and downloads with token-efficient output. | +| [`sqlite-axi`](https://github.com/SSBrouhard/sqlite-axi) | SSBrouhard | SQLite | Inspect schemas, sample rows, and run capped read-only SQLite queries with token-efficient TOON output. | +| [`slack-axi`](https://github.com/JarvusInnovations/slack-axi) | Jarvus Innovations | Slack | Read, search, sweep, and safely draft Slack messages with token-efficient output. | +| [`gws-axi`](https://github.com/JarvusInnovations/gws-axi) | Jarvus Innovations | Google Workspace | Gmail, Calendar, Docs, Drive, and Slides behind one command, with multi-account write-safety - drafts mail, never sends. | +| [`harvest-axi`](https://github.com/JarvusInnovations/harvest-axi) | Jarvus Innovations | Time tracking | Review, log, and edit Harvest time entries by period - for yourself, your team, a project, or a client. | +| [`specops`](https://github.com/JarvusInnovations/specops) | Jarvus Innovations | Spec-driven dev | Spec-driven development for agents - and a demo of shipping an AXI embedded in a skill, not a standalone npm executable. | +| [`gitsheets-axi`](https://github.com/JarvusInnovations/gitsheets/tree/main/packages/gitsheets-axi) | Jarvus Innovations | Git-backed data | Read and mutate git-backed record sheets over the shell - TOON output, idempotent commits. | +| [`metabase-axi`](https://github.com/JarvusInnovations/metabase-axi) | Jarvus Innovations | Analytics / BI | Query, explore, and export from Metabase over the shell - SQL/MBQL, saved questions, schema introspection, full-data export. | +| [`otter-axi`](https://github.com/JarvusInnovations/otter-axi) | Jarvus Innovations | Meetings | Find and pull Otter.ai meeting transcripts from the shell - wraps Otter.ai's hosted MCP server as a scriptable, headless CLI. | +| [`notion-axi`](https://github.com/maximebrmd/notion-axi) | maximebrmd | Notion | Search, read, create, and update Notion pages and databases over the shell - token-efficient TOON output, PAT or integration auth. | +| [`clickup-axi`](https://github.com/JanSuthacheeva/clickup-axi) | JanSuthacheeva | ClickUp | List your open tasks, view a task with its newest comments inline, and change task status - truncation-aware, TOON-style output. | +| [`databricks-axi`](https://github.com/p33ves/databricks-axi) | p33ves | Databricks | Run Databricks jobs, watch runs, and pull failure logs inline over the official databricks CLI - more domains coming soon. | +| [`aws-axi`](https://github.com/thatdudealso/aws-axi) | thatdudealso | AWS | Discover, plan, provision, deploy, and inspect AWS services for hosting web, backend, database, and AI workloads through safe token-efficient CLI workflows. | +| [`docker-axi`](https://github.com/thatdudealso/docker-axi) | thatdudealso | Docker | Discover, build, run, debug, publish, inspect, and clean up Docker apps through safe token-efficient CLI workflows. | +| [`dynamodb-axi`](https://github.com/thatdudealso/dynamodb-axi) | thatdudealso | DynamoDB | Discover, inspect, query, scan, create, update, back up, restore, export, import, and safely operate DynamoDB tables through token-efficient CLI workflows. | +| [`pg-axi`](https://github.com/thatdudealso/pg-axi) | thatdudealso | PostgreSQL | Discover, create, inspect, query, back up, restore, and maintain PostgreSQL databases through safe token-efficient CLI workflows. | +| [`mongodb-axi`](https://github.com/thatdudealso/mongodb-axi) | thatdudealso | MongoDB | Discover, create, inspect, query, export, import, maintain, and diagnose MongoDB databases through safe token-efficient CLI workflows. | +| [`elasticsearch-axi`](https://github.com/thatdudealso/elasticsearch-axi) | thatdudealso | Elasticsearch | Discover, inspect, query, index, map, snapshot, restore, diagnose, and operate Elasticsearch clusters through safe token-efficient CLI workflows. | +| [`kubernetes-axi`](https://github.com/thatdudealso/kubernetes-axi) | thatdudealso | Kubernetes | Discover, inspect, deploy, debug, scale, roll out, expose, and clean up Kubernetes workloads through safe token-efficient CLI workflows. | +| [`redis-axi`](https://github.com/thatdudealso/redis-axi) | thatdudealso | Redis | Discover, inspect, query, export, import, maintain, and diagnose Redis databases through safe token-efficient CLI workflows. | +| [`celery-axi`](https://github.com/thatdudealso/celery-axi) | thatdudealso | Celery | Discover, inspect, run, debug, monitor, schedule, control, and safely operate Celery task queues through token-efficient CLI workflows. | +| [`cyber-mux`](https://github.com/cyberuni/cyber-mux) | unional | Terminal multiplexers | Open, send, read, focus, and close terminal panes across tmux, herdr, and WezTerm through one detection-driven contract with token-efficient output. | +| [`oracle-axi`](https://github.com/thatdudealso/oracle-axi) | thatdudealso | Oracle Database | Discover, create, inspect, query, export, import, maintain, and diagnose Oracle databases through safe token-efficient CLI workflows. | + + Built an AXI? Follow the [contributor workflow](CONTRIBUTING.md) to add it to this list. diff --git a/VISION.md b/VISION.md new file mode 100644 index 00000000..616ef37c --- /dev/null +++ b/VISION.md @@ -0,0 +1,38 @@ +# Vision + +`axi` should evolve conservatively. +We accept contributions that strengthen AXI without diluting its rigor or expanding shared infrastructure beyond common needs. + +## AXI principles + +New principles and behavioral changes to existing principles require rigorous validation across representative agents, models, and tasks. +Intuition, preference, and isolated examples are not sufficient. + +Small, objective corrections that improve clarity without changing meaning or behavior are welcome. + +## Catalog + +Contributions adding real, verifiable AXIs to the community catalog are welcome. + +Every new package proposed for either catalog may receive a positive admission verdict only after independent review of the package itself. +The reviewer must inspect the actual source at a pinned revision or release and, when a runnable release exists, execute that released package through representative success, error, and discovery paths. +The observed interface and behavior must satisfy all applicable AXI principles, including agent-oriented ergonomics, structured and truthful outputs and errors, and discoverability. + +Contributor assertions, pasted transcripts or other contributor-provided verification, generated diffs, package metadata, or existence checks are insufficient evidence on their own. +The verdict must identify the exact pinned source revision or release, the specific relevant source components inspected, such as files, entrypoints, or code paths, and, when execution is required, the exact released package version and representative success, error, and discovery behavior exercised. +It must distinguish direct observations from unverified claims and avoid attributing observations to a release or revision that was not inspected. +If required source inspection or, when applicable, runnable-package execution cannot be completed, the verdict must remain inconclusive or request the missing evidence rather than recommend admission. +The identified source components and execution paths should be representative of applicable AXI behavior; exhaustive auditing of unrelated package concerns is not required. + +The official catalog is maintained directly by the project owner and is not open to contributed additions or edits. + +## SDKs + +The AXI SDK should provide common-denominator facilities that nearly every AXI needs. +Niche utilities specific to one tool or narrow class of tools do not belong in the shared SDK. + +SDKs for additional programming languages are welcome when they: + +- remain faithful to the AXI principles; +- are structurally similar to the JavaScript SDK; and +- expose the same common-denominator facilities without language-specific scope expansion. diff --git a/bench-browser/social/AGENTS.md b/bench-browser/social/AGENTS.md index 506ecf39..15349294 100644 --- a/bench-browser/social/AGENTS.md +++ b/bench-browser/social/AGENTS.md @@ -1,23 +1,27 @@ # HyperFrames Composition Project -## Skills +## Skills — Use These First -This project uses AI agent skills for framework-specific patterns. Install them if not already present: +**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions. -```bash -npx skills add heygen-com/hyperframes -``` +| Skill | Command | When to use | +| ------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | +| **hyperframes** | `/hyperframes` | Creating or editing HTML compositions, captions, TTS, audio-reactive animation, marker highlights | +| **hyperframes-cli** | `/hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts | +| **gsap** | `/gsap` | GSAP animations for HyperFrames — tweens, timelines, easing, performance | -Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start. +> **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their +> agent session, or install manually: `npx skills add heygen-com/hyperframes`. ## Commands ```bash -npx hyperframes preview # preview in browser (studio editor) -npx hyperframes render # render to MP4 -npx hyperframes lint # validate compositions (errors + warnings) -npx hyperframes lint --json # machine-readable output for CI -npx hyperframes docs # reference docs in terminal +npx hyperframes preview # preview in browser (studio editor) +npx hyperframes render # render to MP4 +npx hyperframes lint # validate compositions (errors + warnings) +npx hyperframes lint --verbose # include info-level findings +npx hyperframes lint --json # machine-readable output for CI +npx hyperframes docs # reference docs in terminal ``` ## Project Structure @@ -30,29 +34,46 @@ npx hyperframes docs # reference docs in terminal ## Linting — Always Run After Changes -After creating or editing any `.html` composition, run the linter before considering the task complete: +After creating or editing any `.html` composition, **always** run the linter before considering the task complete: ```bash npx hyperframes lint ``` -Fix all errors before presenting the result. +Fix all errors before presenting the result. Warnings are informational and usually safe to ignore. ## Key Rules 1. Every timed element needs `data-start`, `data-duration`, and `data-track-index` -2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control +2. Elements with timing **must** have `class="clip"` — the framework uses this for visibility control 3. GSAP timelines must be paused and registered on `window.__timelines`: ```js window.__timelines = window.__timelines || {}; window.__timelines["composition-id"] = gsap.timeline({ paused: true }); ``` 4. Videos use `muted` with a separate `