AGENTS.md¶

AGENTS.md is the canonical context file Samuel maintains for every project. It is the single source of truth that AI coding assistants read first.

Most coding assistants read AGENTS.md natively (Codex, Aider, Cursor, Gemini, Cline). For tools with their own context conventions, translator plugins emit the necessary tool-specific files (.cursor/rules/*.mdc, .codex/<rel>/context.md, …) from this one source. The Claude translator is the one carve-out from that rule — see below.

What's in it¶

Rendered from samuel.toml, plugin metadata, and .samuel/run/ state:

Methodology summary (4D + Ralph iteration cap)
Boundaries (files the agent must not touch)
Quick reference (paths, branch, detected stacks)
Active plugins
Guardrails (function size, file size, conventional commits, custom rules)
Quality checks (commands the loop runs between iterations)
Project context (next task, queue summary)

The template lives at template/AGENTS.md.tmpl. Override it per-project at .samuel/templates/AGENTS.md.tmpl.

Where it's written¶

Path	When	Owner
`<root>/AGENTS.md`	`samuel init`, `samuel sync`	Samuel
`<subdir>/AGENTS.md`	`samuel sync` walks per folder	Samuel
`<root>/CLAUDE.md`	`samuel init`, `samuel sync`	Samuel (built-in Claude translator)
`<subdir>/CLAUDE.md`	`samuel sync` walks per folder	Samuel (built-in Claude translator)
`.cursor/`, `.codex/`, others	`sync.after` hook	translator plugin

The framework writes CLAUDE.md mirrors via the built-in Claude translator. Every other tool-specific file — .cursor/rules/, .codex/<rel>/context.md, anything an editor needs — is emitted by an installed translator plugin. The agnostic-check CI workflow verifies the framework never writes the non-Claude paths.

Claude translator¶

Claude Code is the only major coding assistant that does not read AGENTS.md natively. Every other ecosystem we tested converged on AGENTS.md. Requiring every Samuel user to install a plugin just to obtain a CLAUDE.md mirror was friction without payoff, so the mirror is shipped built-in.

The mirror is a verbatim copy of the source AGENTS.md (per folder) with a header pointing readers at AGENTS.md as the source of truth:

<!-- Auto-generated by Samuel (Claude translator). Source: AGENTS.md. -->
<!-- Edit AGENTS.md and run `samuel sync` to refresh this file. -->

# my-project
…

Behavior contract (matches sync's AGENTS.md rules):

Missing CLAUDE.md → create.
CLAUDE.md carrying the translator's autogen marker → update on every sync.
CLAUDE.md without the marker (hand-edited or v1-authored) → skip unless samuel sync --force.

Opt out in samuel.toml:

[translators.claude]
  enabled = false

Absent configuration is treated as enabled (default-on). The opt-out is for explicit dissent, not opt-in — every project initialized before the carve-out shipped continues to receive mirror updates automatically.

The non-Claude translator surface (Cursor rules, future tools, anything richer than a flat mirror) stays in plugins. The rationale for the scoped carve-out is documented in the v2.0.0-rc.4 release notes and the source comment at internal/translator/claude/translator.go.

The 150-line CI gate¶

The rendered AGENTS.md must stay ≤ 150 lines. The gate is enforced by .github/workflows/agents-md-check.yml on every PR; CI fails if the rendered output exceeds the cap. The rationale: context windows are finite, and a context file that crowds out actual code is a regression — see RFD 0002.

What it looks like rendered¶

# AGENTS.md

Canonical AI-coding-assistant context for **my-project**. This file is
managed by Samuel and is the single source of truth across every AI tool.
Most assistants read this file directly; CLAUDE.md is mirrored by the
built-in Claude translator, and .cursor/rules/ / .codex/ are emitted by
translator plugins when installed.

> Samuel v2.0.0 • methodology: `ralph` (built-in) • encoding: TOON for
> `.samuel/run/*.toon`, markdown for prose logs.

## 4D Methodology
1. Deconstruct — restate the goal in one sentence; list the smallest set of
   files that change.
2. Diagnose — what currently exists, what's broken, what assumptions are at
   risk.
3. Develop — make the change with tests; respect the guardrails below.
4. Deliver — run the quality checks, summarise what changed, commit.

Iteration cap for autonomous loops: **20** (production mode, iteration 4/20).

## Boundaries
Do not edit without explicit instruction:
- `go.sum`, `go.mod` (unless adding a dep is the task)
- ...

## Guardrails
- Function ≤ **50** lines. Split with helpers when you cross.
- File ≤ **400** lines.
- New code carries tests. Bug fixes carry regression tests.
- Conventional commits: `type(scope): description`. One logical change per
  commit.

## Quality checks
```bash
go test ./...
golangci-lint run

Project context¶

Next task (T002, high): Wire route in internal/http/router.go - Total tasks: 4 (1 done, 1 in progress, 2 pending)

## Editing it

Most of `AGENTS.md` is regenerated on every `samuel sync`. The only safe-to-edit zone is the **Project context** lead-in (a free-form paragraph) and any block placed outside the autogen marker. Anything inside `<!-- Auto-generated by Samuel -->` … `<!-- /Auto-generated by Samuel -->` will be overwritten.

To regenerate after editing `samuel.toml`:

```bash
samuel sync