Samuel¶

Samuel is a Go CLI that ships a thin framework, a plugin loader, and an opinionated methodology for working with AI coding assistants. It treats AGENTS.md as the canonical source of project context. Most coding assistants read AGENTS.md natively (Codex, Aider, Cursor, Gemini, Cline); for the ones that don't, translator plugins emit the tool-specific files needed (.cursor/rules/, .codex/context.md, …). It is agnostic by design with one scoped exception: because Claude Code is the lone major assistant that doesn't read AGENTS.md natively, the trivial AGENTS.md → CLAUDE.md mirror ships built-in (see AGENTS.md) rather than forcing every Samuel user to install a plugin for it.

What you get¶

• A plugin loader with three execution tiers — text-only skills, sandboxed WASM (wazero), and OCI containers (Podman / Docker) for heavy tools.
• A canonical AGENTS.md rendered from samuel.toml, kept ≤150 lines by a CI gate, with per-folder summaries written by samuel sync.
• A methodology runtime — the 4D loop (Deconstruct / Diagnose / Develop / Deliver) plus the Ralph Wiggum iteration cap, with 13 hook points plugins can extend.

Start here¶

• New to Samuel — Installation, then Quick Start.
• Running a first PRD — Your First Task.
• Coming from v1 — Migrating from v1.
• Looking for design rationale — read the RFDs.
• Looking for a flag — CLI reference.

Project links¶

• Source: github.com/samuelpkg/samuel
• Plugin registry: github.com/samuelpkg/samuel-registry
• Releases: signed with Sigstore keyless cosign; verify before installing.

Samuel is MIT-licensed.