Samuel

Rails for AI coding assistants. A small Go CLI that ships a framework, a plugin loader, and an opinionated methodology — everything tool-specific lives in plugins.

What it is

• Agent-agnostic with a Claude carve-out. AGENTS.md is the canonical project context. .cursor/rules/, .codex/*, and future tool-specific surfaces are produced by translator plugins — the framework knows about none of them. The lone exception is the AGENTS.md → CLAUDE.md mirror, which ships in core because Claude Code is the only major coding assistant that doesn't read AGENTS.md natively.
• Plugin-driven. Three tiers: skill (text + scripts), WASM (sandboxed via wazero), OCI (containers for heavy tools). Plugins are intended to be signed by Sigstore keyless OIDC. v2.0 caveat: the default verifier is a policy-only stub — identity_patterns and allow_unsigned_for are enforced, but no Sigstore math runs. samuel doctor prints a one-line advisory until v2.1 wires the sigstore-go backend.
• Methodology built in. The 4D loop (Deconstruct / Diagnose / Develop / Deliver) with Ralph-Wiggum-style iteration cap as the default. Methodology plugins add hooks; the framework runs the loop.
• TOON-encoded runtime. State files (.samuel/run/*.toon) are token-efficient for LLM context. Markdown stays for prose-heavy logs.
• CLI-mutation pattern. The agent never edits state directly — it runs samuel run done <id> or samuel run skip <id>. The CLI owns the schema; the agent owns the decisions.

Full design rationale: read RFDs 0001–0008.

Install

Homebrew (macOS/Linux):

brew update
brew install ar4mirez/tap/samuel

curl install script:

curl -sSL https://raw.githubusercontent.com/samuelpkg/samuel/main/install.sh | sh

go install:

go install github.com/samuelpkg/samuel/cmd/samuel@latest

Verify:

samuel version
samuel doctor

Every release artifact is signed by Sigstore keyless OIDC. See the cosign verification snippet in any release's notes.

60-second tour

samuel init my-project
cd my-project

# AGENTS.md is your canonical context. CLAUDE.md was mirrored
# automatically by the built-in Claude translator — see `samuel sync`
# for how to keep it fresh after you edit AGENTS.md. .samuel/.gitignore
# was also written so the transient state stays out of git.

# Browse the registry and add a plugin:
samuel search go
samuel install go-guide

# Start the autonomous loop (dry-run first to see the prompt that
# would be sent, then drop --dry-run when you're ready):
samuel run init --prd .samuel/tasks/0001-prd-feature.md
samuel run start --dry-run --iterations 1 --yes

The autonomous loop is iteration-capped (Ralph Wiggum methodology) and emits hooks at every boundary. Plugins attach to the hooks; the framework drives the loop. Full walkthrough in Quick Start. A ready-to-run example project lives at examples/tetris/ with a complete manual-test recipe in its README.

Documentation

• Site: samuelpkg.github.io/samuel
• Getting started: Installation, Quick start, Your first task, Migrating from v1
• Concepts: overview, plugin format, AGENTS.md primary, methodology hooks
• Plugin authoring: manifest, hooks, capabilities, TinyGo + WASM, OCI + gRPC, signing
• Reference: CLI, FAQ, cross-tool generation
• RFDs (design record): index

For v1 users

v2 is a clean break. The binary name is the same; installing v2 overwrites v1. The v1 source lives at the v1-final tag.

If you used CLAUDE.md directly, you'll get AGENTS.md → CLAUDE.md mirroring out of the box — the built-in Claude translator handles it on every samuel init and samuel sync. (Pre-rc.4 this was a separate plugin; carve-out shipped in v2.0.0-rc.4 because Claude Code is the only major coding assistant that doesn't read AGENTS.md natively. See AGENTS.md docs for the opt-out.) If you used gstack or gbrain, see RFD 0008 for the rationale and migration path.

Full notice: Migrating from v1.

Repo layout

samuel/
├── cmd/samuel/             # CLI entry point
├── internal/
│   ├── commands/           # cobra commands (init, install, run, sync, doctor, plugin, version)
│   ├── methodology/        # built-in methodologies (ralph)
│   ├── orchestrator/       # component lifecycle + rollback
│   ├── plugin/             # three tiers + manifest + capability + verify + registry
│   ├── sync/               # AGENTS.md generator (root + per-folder)
│   ├── translator/         # built-in translators (claude — AGENTS.md → CLAUDE.md mirror)
│   ├── ui/                 # Charm UI (lipgloss + huh + bubbles)
│   └── ...
├── template/AGENTS.md.tmpl # canonical template (≤150 lines, CI-enforced)
├── examples/tetris/        # ready-to-run sample project + manual-test recipe
├── e2e/hermetic/           # end-to-end test suite (build tag `e2e`, ~3s)
├── docs/                   # mkdocs site (deployed to samuelpkg.github.io/samuel/)
├── wiki/                   # design knowledge base (not auto-published)
├── scripts/                # release-checklist, docs/RFD generators, v1 deprecation
├── .goreleaser.yaml        # signed builds + brew tap + cosign bundle
└── rfd-index.toml          # RFD source of truth

Contributing

See CONTRIBUTING.md. Bug? Open one. Idea? Discussions. Vulnerability? Private advisory — never a public issue.

Changelog + RFDs

• CHANGELOG.md — per-version release notes (Keep-a-Changelog format).
• docs/rfd/ — design record (RFDs 0001–0008 inaugural).

License

MIT — see LICENSE.