# 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 `; 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//`), 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 --state open` — take one 2. `f0rge issue view ` — 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 --issue ` 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.