Agent Baseline

Portable tooling for evidence-backed coding-agent guidance. It helps an agent set up project instructions, detect stale supporting evidence, validate guidance structure, and run declared checks. It works with your existing coding agent and has no model API or service dependency.

Guidance improves the agent's working environment. Host discovery is best effort; the target is better decisions when the agent reads the guidance. The tool does not control agent harnesses, make models equally capable, or prove architecture quality through file hashes.

Start in any project

Requires uv and Python 3.11+. Project commands run on macOS/Linux; Git is optional for inventory. The package supplies its own Markdown and YAML parsers, so setup does not require Node, Bun, or another project's runtime.

uvx agent-baseline@0.4.3 init . --agent codex --agent claude --agent grok

Choose the hosts you use; omit host flags for the explicit CLI workflow. Initialization installs the skill and creates an empty evidence-record draft. It preserves existing project instructions and does not invent domain rules, sources, or test commands.

Then start a new agent session and ask:

Use baseline-project to set up this project's agent baseline. Preserve existing guidance, ground instructions in inspected contracts and code, configure the evidence record, and run the relevant verification.

Completed setup connects important engineering rules to when they apply, the behavior to preserve, their supporting authority, and a relevant check or concrete review criterion. The authoring output contract requires missing coverage to be explicit. These relationships live in maintained guidance; their semantic review is separate from the CLI's structural and command checks.

The setup agent also configures outcome follow-ups: it chooses an existing evidence store or a local Markdown fallback, writes the project's retrieval/update instructions, and creates an initial pending case when the inspected work supplies a real finding. Consumers do not need to design or write that workflow. Later comparable work supplies evidence of improvement, no change, regression, or an inconclusive result. The CLI's init command installs this procedure; completing the agent-led setup applies it to the project.

Invoke $baseline-project in Codex or /baseline-project in Claude Code or Grok Build, or select it in the host's skill picker. If the host does not discover local skills, ask it to run and follow:

uvx agent-baseline@0.4.3 skill show

That command prints the complete skill and references. Running uvx alone does not load instructions into the agent.

To load guidance selectively, start with the router and then request its relevant reference:

uvx agent-baseline@0.4.3 skill show --file SKILL.md
uvx agent-baseline@0.4.3 skill show --file references/audit.md

--file accepts exact bundled paths. Installed skills can read the linked references directly. The audit workflow reviews trigger scope, source authority, prerequisites, approval stops, and completion criteria; it recommends evidence-backed changes without editing files or running project checks unless that work is also requested.

Grok Build reads .grok/skills and also scans .agents/skills. Use --agent grok so init and doctor cover the native .grok/skills route. User-scope installs go to ~/.grok/skills. The 0.2.0 native trials used an explicit skill read against Grok Build 1.0.13; discovery in other versions remains best effort.

Daily use

uvx agent-baseline@0.4.3 doctor .
uvx agent-baseline@0.4.3 check .
uvx agent-baseline@0.4.3 verify .

doctor checks local Markdown links, referenced guidance, skill YAML, and selected host routes. Add --agent codex --agent claude --agent grok for native project discovery requirements. It understands Markdown references and code examples instead of searching prose with a link regex.

check detects changed evidence and names the guidance that depends on it. verify requires current evidence, runs built-in guidance validation and declared project commands, and checks that monitored inputs stayed unchanged. These commands do not replace task-specific engineering review, UI checks, or required application CI.

On drift, ask the agent to inspect the changed evidence and update or affirm the affected guidance. After that review:

uvx agent-baseline@0.4.3 record .
uvx agent-baseline@0.4.3 verify .

Never automatically re-record to clear a failure. An empty draft cannot pass as a reviewed baseline. If there are no project checks, version 2 records allow an empty check list and verification reports that limitation explicitly.

Track the relevant evidence

The same configuration works across languages and repository layouts:

{
  "schema_version": 2,
  "artifacts": [
    {
      "path": "AGENTS.md",
      "sources": [
        {"path": "package.json", "json_pointer": "/scripts"},
        {"path": "docs/architecture.md", "heading": "Ownership"},
        "tests/domain.test.ts"
      ]
    }
  ],
  "checks": [
    {"name": "tests", "argv": ["npm", "test"], "cwd": ".", "timeout_seconds": 600}
  ]
}

Replace these illustrative sources and commands with inspected project evidence. Track a whole file, one JSON value, or one named Markdown section. Selectors reduce irrelevant drift; missing or ambiguous selections fail. Version 1 records remain readable.

The record specification describes validation, exit codes, compatibility, execution boundaries, and verification limits. --help and --version describe the installed CLI.

Keep guidance canonical

Initialization installs the baseline skill in .agents/skills and creates aliases for the selected hosts. Link an existing project skill without copying it:

uvx agent-baseline@0.4.3 skill link tooling/skills/team-engineering --agent codex --agent claude --agent grok

The linker validates the resulting relative links and preserves existing destinations. A skill whose references depend on its original nesting may need its links corrected before it can be shared at another location.

For a user-level installation across your local projects:

uvx agent-baseline@0.4.3 skill install --agent codex --scope user

Use --agent claude for Claude Code and --agent grok for Grok Build. Project discovery uses .agents/skills for Codex, .claude/skills for Claude Code, and .grok/skills for Grok Build. User discovery uses those directories under the user's home. The repository also includes a Codex plugin manifest; CLI installation does not register that plugin with a marketplace.

Installed files are persistent copies outside uv's cache. To upgrade a managed installation:

uvx agent-baseline@0.4.3 skill install --agent codex --scope user --upgrade

Installation receipts identify the previous managed files. Upgrades preserve local edits and extra files by refusing conflicting replacements. They roll back a failed directory replacement. Older installations without receipts require a one-time comparison and manual move-aside before replacement; the tool does not assume those files are unmodified. Update the canonical directory when other hosts use aliases.

Host routing is based on Codex's local skills documentation, Claude Code's skills documentation, Grok Build's skills documentation, and the Agent Skills specification. File placement and host loading are separate checks; native policies can disable discovery.

Evaluate actual agent results

Use the evaluation protocol to compare natural discovery and explicit skill invocation against observable acceptance criteria. Keep model/host versions, environment, inputs, and budgets recorded. Judge output artifacts independently; neither the agent's self-assessment nor a green structural check measures model parity.

When evaluating added guidance, compare it with a minimal condition that retains required owner policy and essential commands. For authoring changes, freeze the generated baseline and test its use by a fresh consumer agent. Keep loading, task correctness, and engineering effort separate. The research reference records primary sources and their limits; it is optional background, not a prerequisite for ordinary work or evidence of measured gains in this release.

The reproducible authoring exercise includes a small Python project, an intentional documentation contradiction, a task prompt, and artifact-level grading criteria. Copy it into an isolated workspace to try your own agent.

The behavioral fixtures cover authorized completion, a small documentation correction, competing skill selection, and instruction auditing. They include deterministic preparation and artifact grading; transcript review is still required to assess pauses, unnecessary checks, skill loading, and final claims.

The 0.2.0 evaluation report records actual New Faces and authoring trials, including failed policy-authoring criteria and successful repeats. It is development evidence, not a model-parity benchmark.

The package does not launch model APIs or claim performance scores. Evaluation runners are selected by the user. The New Faces integration is a testing ground; no New Faces paths, domain rules, or language commands belong in the package implementation.

Develop and publish

python3 -m pip install -e .
python3 -m unittest discover -s tests -v

The implementation is in src/agent_baseline; canonical skill content is in skills/baseline-project. Runtime dependencies are markdown-it-py and PyYAML for their supported syntax and safe parsers. uv tool install agent-baseline is available for a persistent CLI installation.

GitHub releases matching v<project.version> trigger the build and isolated PyPI Trusted Publishing workflow. Tests, distribution metadata, wheel execution outside the checkout, and bundled guidance are checked before publication. No PyPI API token is stored in the repository.