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. references/ai-reviewer-prompt-lessons.md captures the empirical prompt-engineering lessons from arXiv:2605.20668 (correctness before significance, hard caps, exact evidence, devil’s-advocate, boundaries, tool-enabled scrutiny) — apply them when authoring or revising reviewer, verifier, or meta-reviewer prompts.

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/<name>/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/<skill-name>/, 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/<skill-name>/test-<skill>.mjs (or every tests/<skill-name>/ 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/<skill-name>/ 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/<slug>.md
• Intermediate research: <slug>-research-<scope>.md
• Draft: outputs/.drafts/<slug>-draft.md
• Cited brief: outputs/.drafts/<slug>-cited.md
• Verification: <slug>-verification.md
• Final output: outputs/<slug>.md or papers/<slug>.md
• Post draft and card: outputs/<slug>-post.md, outputs/<slug>-post.html
• Goal-check record: <slug>-goal-check.json (machine gate beside the candidate)
• Goal requirements manifest: <slug>-goal-requirements.json (frozen before goal-check)
• Problem anchor: <slug>-problem-anchor.json (binds findings to the artifacts studied)
• Provenance: <slug>.provenance.md (next to the final output)
• Habit ledger: outputs/.habits/<slug>.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.