AGENTS.md

September 20, 2026 · View on GitHub

House rules for agents working in this repo.

evaluate is a Go MCP stdio server that forwards typed questions to TypeSafe Jev. One static binary. README.md is user-facing.

Read this before your first action in a session. It overrides your defaults.

Main purpose: let agents outsource narrow validation and judgment to Jev instead of burning additional reasoning/context tokens on questions Jev can answer cheaply and directly. The server stays a thin direct Jev connection for any AI agent — setup concerns never leak into the runtime environment the agent-launched MCP server receives.

Pack layout (field-notes style, MCP identity preserved):

Path	What it is
`AGENTS.md`	This file — house rules
`ANTIPATTERNS.md`	What breaks → why → principle
`agents/`	Verification, orchestration, skills/routines, prompts, named skills
`roster/`	Lean paste-ready roles
`playbooks/`	Engineering and Jev-host workflows
`docs/`	Product docs (CONTEXT, ROADMAP, jev, ADR)
`cmd/evaluate/AGENTS.md`	Go/MCP layer constraints

The one rule

Verification is the job. Writing code is the easy part.

If you cannot demonstrate that your change works, you have not finished — no matter how confident you are. Everything below is downstream of this.

Every new feature and bug fix must be tested, verified, and validated before it is committed or pushed. No exceptions for small changes, follow-ups, or "obviously correct" edits. Committing or pushing on unverified green is a process failure, not a shortcut.

Tested — the behavior is covered by a test that fails without the change (bugs: the reproduction is red, then the same steps are green).
Verified — task check (gofmt, go vet, go test -race -count=1) runs clean, and the output is observed directly: never piped through filters that can mask a failure (| tail, | head, || true). A verification command whose exit status you did not see is not a verification.
Validated — the change is demonstrated against the real thing it claims to fix: live smoke (task smoke) whenever request/response validation rules change; a stdio round-trip (task inspect or against ./evaluate) for tool-contract or transport changes.

Done means proven, not "should pass". Details: agents/VERIFICATION.md.

Hard constraints (identity)

These are not style nits. Do not “simplify” them away.

Canonical surface is cmd/evaluate/tools.go. Schema + user-facing prose. Host adapters own transport and registration only — they never author Jev semantics.
evaluate mcp stdout is MCP-only. Diagnostics go to stderr. Secrets stay out of logs and stdout.
state and questions are hostile input. HTTP client, 16 MiB cap, and criteria validate are the boundary.
Jev answers come from the API. Do not fabricate probabilities.
Client validates both sides of the upstream contract (request in, successful response out against the request’s criteria).
Failed adapter writes leave the previous registration intact.
Do not reopen docs/ROADMAP.md §0 baseline seams without observed pressure.
Prefer evaluate + host code over new MCP tools for judgment/orchestration.
Jev does not spawn agents. Hosts execute delegation.
Keys, billing routes, destructive git, production publish → stop and ask.

Layer detail: cmd/evaluate/AGENTS.md. Failure log: ANTIPATTERNS.md.

Hosts

evaluate is the same canonical MCP surface for every host.

Host	How it attaches
Claude Code	`evaluate setup mcp` — user-scope MCP registration via the `claude` CLI
Codex	`evaluate setup mcp` — MCP registration via the `codex` CLI
Claude Desktop	`evaluate setup mcp` — config-file registration when the app is installed
Pi	`evaluate setup pi` writes the native extension (stock pi has no MCP client); or register `evaluate mcp` in an MCP adapter config (`pi-mcp-adapter` and similar)
OMP (Oh My Pi)	stdio MCP client — `/absolute/path/to/evaluate mcp` with `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY` in env
PyThinker	stdio MCP client — same registration as any other MCP-capable agent/CLI
Any other MCP client	`/absolute/path/to/evaluate mcp` + key in env

Automated setup covers Claude Code, Codex, Claude Desktop, and stock pi. OMP, PyThinker, and other MCP-capable CLIs/agents use the manual stdio path — same binary, same tool contract.

Load by branch

Branch	File
Editing under `cmd/`	`cmd/evaluate/AGENTS.md`
Writing `evaluate` questions / interpreting answers	`docs/jev/README.md`
Domain terms (System One, canonical surface, adapter)	`docs/CONTEXT.md`
Agent pack index	`agents/README.md`
Verify loop	`agents/VERIFICATION.md`
Roster / autopilot / Jev-as-supervisor	`agents/ORCHESTRATION.md`
Skills & routines	`agents/SKILLS-AND-ROUTINES.md`
Named skills	`agents/skills/`
Prompt patterns	`agents/PROMPTS.md`
Paste-ready roles	`roster/`
End-to-end workflows	`playbooks/`
What breaks	`ANTIPATTERNS.md`
Product roadmap	`docs/ROADMAP.md`

Before you write any code

Reproduce first. Get the bug red — a failing test or a real evaluate call. For a feature, name the current behaviour you will change.
Restate the task before anything non-trivial: what you will do, what you will not do, what you assumed.
Say what you'd need to see to call it done. One sentence — the proof.
If asked to investigate, investigate. Do not start fixing because you spotted something on the way.

While you work

Small changes. One scoped concern per change.
Run the thing. Not only task check — the binary when the change is in tool, setup, or stdio paths.
Fix the root cause. If about to workaround, say why the real fix is out of scope.
Use what this repo chose. cobra, MCP SDK, stdlib.
Don't invent content. Jev/TypeSafe facts from docs/jev or https://docs.typesafe.ai only.
No internal language in user-facing output. README, tool prose, errors stay in product language from tools.go.

Before you open a PR

Attach proof. Every time.

Change type	Required proof
Bug fix	The reproduction, then the same steps passing
MCP / tool contract	`task check` plus `task inspect` or captured stdio
Setup / host adapter	Host client path, or `go test -run TestPiAdapterRoundTrip ./cmd/evaluate/` / `pi -e`
Request/response validation	`task check` plus `task smoke`
Refactor	`task check` showing behaviour unchanged
Docs	Claim matches `tools.go` or live TypeSafe docs

A PR with no proof is a draft. Also state what changed and why, what you did not change that a reviewer might expect, and anything unsure.

Code style

Comments for non-obvious why only — never what as a crutch.
No dead code, no commented-out blocks, no debug leftovers.
Delete scaffolding you added to investigate.
Hostile input at the boundary; prompt-injection called out when user text enters prompts or state.

When you are corrected

Apply the fix.
Name the general rule.
Write it here, in cmd/evaluate/AGENTS.md, or under agents/ / a skill.
Strip the incident. Principle only.

Bad: "When editing setup.go, watch the Claude Desktop rollback because it failed on 2026-09-18."

Good: "A failed adapter write must leave the previous registration intact."

When to stop and ask

keys, billing routes, auth, credentials
destructive git
production publish / release
product decision you would have to guess
same approach failed twice — report; do not loop

Status

Done / in progress / blocked. No change since last update → say "no change" or stay silent.

Workflow

Product documentation lives under docs/. Root product entry files: README.md, CHANGELOG.md, LICENSE, AGENTS.md. Agent process pack (do not move into docs/): agents/, roster/, playbooks/, ANTIPATTERNS.md. New product docs → docs/; new process rules → the pack.
Roadmap §-numbering in docs/ROADMAP.md is canonical for milestones.
task check before calling work done.
task build → ./evaluate (gitignored). task inspect → MCP Inspector.

Commits

Conventional Commits → release-please: feat minor, fix patch, ! breaking (still minor pre-1.0), docs/test/chore no bump. Scopes in use: tools, setup, client, cli, readme. Generated: CHANGELOG.md, .release-please-manifest.json.

A commit carries verification with it per The one rule. No proof → draft.

Vocabulary

Term	Meaning
Verification skill	Deterministic exercise of the product — `agents/VERIFICATION.md`, `agents/skills/`
Feature map	Binary surface, hosts, flows — in `agents/VERIFICATION.md`
Autopilot ladder	investigate → draft → autopilot → full autopilot — `agents/ORCHESTRATION.md`
Skill / routine	how / when — `agents/SKILLS-AND-ROUTINES.md`
Principle, not incident	How rules get written — above
System One / Jev / state / criteria / canonical surface / adapter / route	`docs/CONTEXT.md`

The short version

Reproduce it. Run it. Prove it. Fix the cause, not the symptom. Keep the MCP contract canonical. When you're wrong, write the principle — not the story.