AGENTS.md — operating manual for agents in this repo

Read this first. It is the one file every agent in this repo gets in context. Goal: zero ambiguity, minimum tokens, maximum signal. Errors are costly; this file exists to make them rare.

What this repo is

f0rge — a local, gh-literal git forge: state lives in .forge/ files, driven by a thin Rust CLI, built for one owner and their swarm. This repo dogfoods: building f0rge is the first f0rge project (from PLAN M3 on).

Install

f0rge release install installs THIS project's release artifact:

• latest release: f0rge release install
• pinned version: f0rge release install v0.1.1 (record sha, else git tag, else checkout)
• moving tip: f0rge release install main (builds current checkout)
• preview only: append --dry-run (prints each step, changes nothing)

f0rge release install resolves the release and runs the project's installer (or cargo for cargo projects); placement is the project script's job. Convention: repo-root install.sh runs as ./install.sh <ver>; cargo projects without it use cargo install --locked; otherwise it prints no installer for this project (install.sh or Cargo.toml). f0rge is the example: it has no install.sh, so a fresh machine starts with cargo install --locked --path . from the clone.

Reading order

1. AGENTS.md — this file
2. .forge/wiki/docs/OUTLINE.md — the what/why; read once before any work
3. .forge/wiki/docs/PLAN.md — the how/when; find your chunk, obey its contract exactly
4. spec/ at repo root — frozen schema (exists after M0); the only source of truth for formats

Canonical agent contract: f0rge --skill (single source of truth; skill.md body == SKILL_TEXT, golden test; 1000B budget).

Philosophies (non-negotiable)

• Bitter lesson. The forge stays dumb; agent intelligence does the work. No locks, no claim protocols, no auto-resolvers, no merge engines, no CI frameworks. When two agents collide, they reconcile — that is the design.
• Simplicity. Prefer the dumbest thing that passes. Boring beats clever. Fewer deps, fewer knobs, fewer lines.
• Shape. gh-literal: same commands, flags, and --json field names models are trained on. The command tree mirrors the folder tree (.forge/issues/ ↔ f0rge issue). Never invent a new UX.
• Token-minimal surface. Every byte you emit to another agent costs tokens. Output is compact, parseable, empty where empty. If it can be 5 lines instead of 15, it is 5. Same for your prose: be terse everywhere.
• Files are the API. Markdown is truth; the CLI is the enforced view. Never hold state the files don't have; never duplicate it.
• Nothing is deleted. Close/archive only (state: closed|archived + .forge/archive/). git is the undo log; history is the product. Wiki pages are plain files in git: edit or remove with rm + git (git is the undo log).
• CI is just scripts. Steps are executable files in filename order; first nonzero exit is the verdict. Posture (local/docker) is explicit, never implicit.
• Merges are agent work. f0rge merge CI-gates the patch in a scratch worktree, NEVER touches main or branches; the ORCHESTRATOR fast-forwards the applied sha and deletes the branch; conflicts are reconciled by the agent; you do not merge your own work onto main.
• One owner, many agents. You are never the authority. The owner — or an agent they explicitly delegated to — merges. You do not merge your own work onto main.

Operating rules

• Work in your own worktree. Take an issue, claim it, do the work, ship a PR folder (diff + .forge/prs/<uuid>/), CI green before merge.
• Claim one chunk from PLAN.md; do exactly its scope (Inputs → Outputs → Interfaces → Definition of done). Never expand scope mid-chunk.
• Log one line per chunk in build-log.md (co-located in .forge/wiki/docs/): chunk | sha | verdict.
• When a change smells like design, file an issue — don't improvise into code. Design changes go to OUTLINE.md first, then PLAN.md, then code.

Code standards (every diff must pass this checklist)

• #![forbid(unsafe_code)] in both crates. No unsafe, no excuses.
• Dependencies: exact pins (=) only, declared in [workspace.dependencies], Cargo.lock committed, cargo build --locked. Never add a dep without updating PLAN.md §5's pin table and running cargo audit.
• YAML: yaml_serde only. Never serde_yaml (deprecated) or serde_yml (RUSTSEC-2025-0068 — unsound).
• Subprocesses via argv arrays (Command::new). Never sh -c with untrusted strings. Never shell-interpolate filenames.
• Atomic writes: temp file + fsync + rename. No partial entities, ever.
• Paths: canonicalize + prefix-check every read; reject symlinks escaping .forge/; document-parse caps (256 KiB files, depth caps, strict schema: unknown field = warning, missing required = error).
• Errors: one line on stderr + exit code (0 ok / 1 runtime / 2 usage). No panics on hostile input. No stack traces. No paths beyond the offending file name.
• Output: --json compact, fixed field order documented in repo-root spec/; empty result is [] or {}, never prose. Human mode is a thin aligned view of the same data. Hard budgets: PLAN [M2] table in wiki — f0rge ≤300B/12ln, -h ≤250B/8ln, --skill ≤1000B/30ln, errors 1 line.
• Tests: golden fixtures + e2e against temp repos; every SEC fixture from PLAN §5 has a test; budget tests byte-count output.
• Keep it boring: std over crates, fewer deps over more, dumb over clever.

Never (hard blockers — skip the work, file an issue instead)

• Never redesign or change scope vs PLAN.md.
• Never add lock/claim/merge/CI machinery — that violates the bitter lesson. Orchestration is the orchestrator's job; collisions are reconciled, not prevented by the tool.
• Never store derived state (numbers, board columns, wiki index) — derive, never store.
• Never delete or overwrite entity history — close/archive only.
• Never put secrets anywhere in the repo or .forge/ (that includes ci.env — non-secret knobs only).
• Never run untrusted PR CI steps bare without an explicit posture (ci.env runner: or --docker).
• Never use your own judgment over PLAN.md's contract — when they differ, the contract wins and the doc is wrong; file an issue about the doc.

Daily loop

1. f0rge issue list --assignee <you> --state open — take one
2. f0rge issue view <id> — understand, claim, work in your worktree
3. Verify with the repo's own CI steps; keep main green by construction
4. f0rge pr create --base main --head <branch> --issue <id>
5. Wait for merge; if asked to reconcile a conflict list, do it — that is your job, not the tool's
6. When you learned something durable: f0rge wiki put research/…

Be terse in everything you produce: comments, commit subjects, log lines, help text. No filler, no praise, no ceremony. Your output is someone's context.