# Agents `AGENTS.md` is the repo-level contract for agents working in the Vitruvius repository, and the always-on ruleset that portable hosts (Pi, Claude Code, Codex, OpenCode, Cursor, Qoder, ...) load for free. ## What Vitruvius is Vitruvius is an **engineering research agent**. It runs a research loop over engineering questions and artifacts — **discover → read → synthesize → verify → review** — with auditable provenance throughout. The disciplines are: mechanical, software, civil, electrical, and architectural. It is **not** an engineering coach. No persona lectures, no generic "discipline stance", no adjacent tooling lanes (CAD/BIM/unit conversion are out of scope unless they serve an active research run). ## Feature scope (F1 — Feature-scope discipline) Vitruvius must stay lean. It is a research agent for engineering, not a bundle of adjacent engineering productivity workflows. ### What belongs (core research jobs) Every new skill, command, or capability must fight for its life before implementation. Keep or add something only when it directly improves at least one core research job: - **Discovering** engineering knowledge: standards, code provisions, handbooks, vendor docs, datasheets, prior designs, repos, or prior art - **Reading**, extracting, and understanding engineering documents, drawings, specs, or code - **Ranking** evidence, methods, or design alternatives - **Verifying** claims and numbers against sources, standards, models, or experiments - **Synthesizing** engineering research into auditable artifacts - **Improving** provenance, verification, or reliability of the research loop ### What does NOT belong (reject by default) - CAD/BIM tooling (modeling, drafting, rendering) - Unit conversion or general calculation engines - Project management, funding, sales, admin - Generic writing (marketing, documentation not tied to research output) - Coaching or persona lectures ("explain like I'm 5" is fine for engineering; life coaching is not) - Adjacent product lanes unless explicitly scoped as support for a specific active research run When in doubt, reject. A capability can always be added later when a real research need emerges. ### How to evaluate a new skill proposal 1. Which core research job does it improve? 2. Can an existing skill already do this with a parameter change? 3. Does it serve all five disciplines, or is it domain-specific? (Both are fine — but know which.) 4. What is the maintenance cost? (References, scripts, and frontmatter add long-term burden.) 5. Can it be tested? (If you can't write a test for it, it shouldn't ship.) If the answer to (1) is vague or (2) is "yes", reject the proposal. ## Research subagents Vitruvius ships research roles (as subagents when the host supports them, otherwise performed by the lead agent): - `researcher` - evidence gathering - `writer` - synthesis - `verifier` - citations + source verification (read-only: no Write/Edit — a judge, not a fixer) - `reviewer` - adversarial review (read-only: reports findings, never repairs) - `arbiter` - adjudicates verifier disagreement (no re-research) - `goal-checker` - independent end-of-run completion check (default NOT-DONE; re-derives every ask from the original question, not the plan) - `habit` - durable research-preference extraction (read-only, abstention-first; proposes compact candidates, never applies them) The source of truth for their behavior is the canonical role definitions in `agents/` (`agents/researcher.md`, `agents/verifier.md`, `agents/reviewer.md`, `agents/arbiter.md`, `agents/writer.md`, `agents/habit.md`) and `skills/engineering-research/SKILL.md`. Do not duplicate those prompts in this file. OpenCode host adapters are rendered into `.opencode/agent/` as thin copies by `installer/install.mjs`. ## Integrity commandments (apply to every agent, every run) 1. **Never fabricate a source.** Every named standard, code, provision, product, material, project, or dataset must have a verifiable reference. If you cannot find one, do not mention it. 2. **Never claim something exists without checking.** Before citing a standard, code section, vendor doc, or repo, verify it exists. If a search returns zero results, it does not exist — do not invent it. 3. **Never extrapolate details you haven't read.** If you have not fetched and inspected a source, you may note its existence but must not describe its contents, numbers, or claims. 4. **A reference or it didn't happen.** Every claim in an output must trace to a checkable source: standard + section, URL, artifact path, or calculation. 5. **Read before you summarize.** Do not infer a code provision, a spec value, or a material property from a title, a snippet, or memory when a direct read is possible. 6. **Mark status honestly.** Distinguish `verified`, `inferred`, `blocked`, and `unverified`. Never smooth over missing checks. ### Prompt-Authoring Checklist (positive) When writing a prompt, plan, or instruction for any agent or subagent: - **State what TO do, not just what NOT to do.** Pair each prohibition with a positive action ("cite the section that supports this claim" not just "do not fabricate"). - **Name the artifact.** "Check `packages/solver/src/x.ts:42`" beats "check the code." - **Specify the output format.** "Return a table with columns #, Source, Reference, Status, Verdict" beats "summarize your findings." - **Set the effort bound.** "Stop after 3 rounds" or "continue until evidence saturates" — never leave it implicit. - **Include the integrity reminder.** Every prompt that touches sources must carry at least one integrity commandment reference. `references/prompt-patterns.md` catalogs the failure modes to catch on review — vague quantifiers, unspecified authority, false precision, citation laundering, and others — numbered by strength, each with what to watch for and why it is a tell. Read it before reviewing or rewriting a prompt. ### Anti-Rationalization Tables Agents skip mandatory steps by rationalizing. Pair each excuse with a factual counter-argument. Add a "Common Rationalizations" section to any skill that has a mandatory gate the agent might try to skip. See `references/anti-rationalization.md` for the full table and usage pattern. ## Provenance and verification - Every research output must include a `.provenance.md` sidecar. - Provenance sidecars record source accounting and verification status. - If a workflow uses the words `verified`, `confirmed`, or `checked`, the underlying artifact must record what was actually checked and how. - For quantitative or code-backed outputs, keep raw artifact paths, scripts, calculations, or logs that support the final claim. Do not rely on polished summaries alone. - Never claim a fix or a check landed unless an explicit on-disk verification (read, grep, diff) proves it. - If verification could not be completed, mark the output `Verification: BLOCKED` or `PASS WITH NOTES` and list the missing checks. ## Grounding rules (why a report is about *your* problem) A well-cited literature review that never opens the codebase it was commissioned about passes every citation check and answers nobody. These rules narrow that failure. They do not eliminate it — see the honesty note at the end. 1. **Name the artifacts before searching.** Every run states the files, repos, or documents it studies plus the commit that pins them. A run with no artifact is a literature review — say so rather than implying code was read. 2. **`repo` claims carry an anchor.** A claim about the artifact under study resolves to `path:line` on disk. Never assert that a system does, lacks, or needs something without opening it. 3. **Every finding names its landing site.** `change`, `measure`, `defer`, `product-decision`, or `background`. A finding with no landing site is background or a product decision and must say which. 4. **Every decision gets a position.** A report may not list a decision and then ignore it. 5. **Silence is not a finding.** Record what you searched for, did not find, and the boundary of the search. 6. **Weight follows evidence.** An impact or priority claim states the evidence behind it and the cost of being wrong. **What is machine-checked, and what is not.** `vitruvius-problem-anchor` proves rules 1, 2, 4 and 5 mechanically: anchors resolve to real non-blank lines, files are hash-pinned to a snapshot, every declared decision reaches a finding, and negative coverage is bound to the candidate. It does **not** read the claim and compare it to the anchored line, so rule 2 catches a missing anchor but not an anchor that points at the wrong thing — an absence claim citing a file that proves the opposite still passes. Rule 3 is enforced only as a required enum value, and rule 6 is prose plus a cheap heading check. Closing those three gaps is the verifier's and the goal-checker's job; do not report a grounded report as a correct one. `scholarly-research` supplies the evidence layer and does not write the report; `engineering-research` owns these rules. ## Commit rule (read before every `git commit`) Full rule, with reasoning and the subjects it exists to refuse: `references/commit-rule.md`. Enforced by `scripts/commit-message-check.mjs` and, once per clone, `git config core.hooksPath .githooks`. - **Format:** `type(scope): subject`, where type is one of `feat`, `fix`, `docs`, `test`, `refactor`, `build`, `chore`. Scope is the skill, script family, or repo area. Subject is imperative, lowercase after the colon, no trailing period, under 72 characters as a target. - **The subject names a finding, not an activity.** "bound the PDF download that had no deadline", not "fix download bug". `lint fixes`, `cleanup`, `CI pipeline failure`, and `wip` are refused by the checker. - **The body carries the honesty claims.** Never claim a fix landed, a number was measured, or something is `verified`/`confirmed`/`checked` unless this session ran the check that proves it, and the body says which one. If the real state is BLOCKED, PARTIAL, or NOT-DONE, the subject says that. - **Before committing:** run the gate covering what you touched (`npm test` for scripts, skills, contracts, docs), then read `git diff --staged` and confirm every staged file was meant. `tests/routing/*.txt` are rewritten by the routing eval on every run — do not stage them as part of your change. - **Never commit:** secrets, `tasks/benchmark/run-api.mjs` (hardcoded key, deliberately untracked), or generated output under `outputs/`, `papers/`, and benchmark `results-*`. - **One commit, one adjudicated change.** A behavior change, its gate, its test, and its doc update belong together; unrelated cleanup does not. A rejected experiment goes to `notes/rejected-changes.md` via `scripts/rejected-change-ledger.mjs append`, never into the log disguised as work. - **N7:** a commit touching `skills//SKILL.md` bumps that skill's `metadata.version` in the same commit. The checker enforces this. The checker verifies message shape and the version bump. Two limits are stated in `--explain` and are worth knowing here: the vagueness list is a known-offender list, not a completeness guarantee (a vague subject it does not know about passes), and the checker cannot verify that a number was measured or a claim is true. Both need a reviewer, and the gate is not a substitute for one. ## Skill frontmatter rules (S9 — AGENTS.md rigor) Every skill's `SKILL.md` frontmatter MUST conform to the structural contract enforced by `scripts/validate-contract.mjs`: - **Allowed fields:** `name`, `description`, `license`, `compatibility`, `allowed-tools`, `argument-hint`, `metadata`. Anything else goes under `metadata`. - **Required fields:** `name`, `description`, `metadata.version`. - **Version bump discipline (N7):** any behavioral change to a skill MUST bump its `metadata.version` in the same change. - **Name matches directory:** The `name` field must equal the skill's directory name (e.g., `skills/gap-analysis/SKILL.md` has `name: gap-analysis`). - **allowed-tools format:** Space-separated string, no commas or arrays (e.g., `allowed-tools: Write Edit Bash`). - **Length limit:** SKILL.md must be ≤ 500 lines. - **No stray tests:** Tests belong in `tests//`, not inside the skill directory. - **Local links resolve:** Any `references/`, `assets/`, `scripts/`, or `agents/` path referenced in the skill must exist on disk. - **Skill references resolve:** Every `/skill-name` mentioned in a SKILL.md must be an actual skill in `skills/` (validated). ### Validation steps Before committing a new skill or capability: 1. Run `npm run test:contract` — all skills must pass the structural contract. 2. Run the skill's own test file — `node tests//test-.mjs` (or every `tests//` file) — and `npm test`. Skill-specific tests must pass. 3. Verify the skill appears in the README "What each skill does" section. 4. Verify the skill links to `references/evidence-quality-tiers.md` if it produces research output. 5. Verify S7 boundary language is present ("research-only, not for final engineering sign-off"). ### Update discipline When modifying an existing skill: 1. Update the skill's SKILL.md — do not duplicate its content in AGENTS.md. 2. Update the README "What each skill does" section if behavior changes significantly. 3. Add or update tests in `tests//` for new logic. 4. Run the full test suite (`npm test`) before committing. The five **discipline skills are generated**: edit `scripts/discipline-payloads.mjs` and run `node scripts/generate-discipline-skills.mjs`. Never hand-edit `skills/{mechanical,software,civil,electrical,architectural}/SKILL.md`; `npm test` runs `--check` and fails when the generated file and the payload disagree. ## Artifact conventions - Derive a short **slug** from the topic: lowercase, hyphenated, no filler words, at most 5 words (e.g. `steel-brace-connection`). Every file in a run uses that slug as a prefix. - Plan: `outputs/.plans/.md` - Intermediate research: `-research-.md` - Draft: `outputs/.drafts/-draft.md` - Cited brief: `outputs/.drafts/-cited.md` - Verification: `-verification.md` - Final output: `outputs/.md` or `papers/.md` - Goal-check record: `-goal-check.json` (machine gate beside the candidate) - Goal requirements manifest: `-goal-requirements.json` (frozen before goal-check) - Problem anchor: `-problem-anchor.json` (binds findings to the artifacts studied) - Provenance: `.provenance.md` (next to the final output) - Habit ledger: `outputs/.habits/.json` plus `.provenance.md` sidecar (never an `AGENTS.md` write) Never use generic names like `research.md`, `draft.md`, or `brief.md`. Concurrent runs must not collide. ## Delegation rules - The lead agent plans, delegates, synthesizes, and delivers. - Use subagents when work is meaningfully decomposable; do not spawn them for trivial work. - Prefer file-based handoffs over dumping large intermediate results back into parent context. - The lead agent is responsible for reconciling task completion. Subagents may not silently skip assigned tasks. - For critical claims, require at least one adversarial verification pass after synthesis. Fix fatal issues before delivery or surface them explicitly. ## Tool discipline - Use only tool names visible in the current tool set. If a tool returns "not found", do not retry the same invalid call — map to a canonical visible tool or record the capability as blocked. - Prefer official standards portals, code body text, primary vendor documentation, and primary data over secondary summaries. - When a source is paywalled or unreachable, cite it from search metadata and mark full-text access as blocked instead of guessing at its contents.