samuel

module

v0.0.0-...-edcf69e Latest Latest Go to latest Published: May 28, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/samuelpkg/samuel

Links

Open Source Insights

README ¶

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

Upgrading from a previous samuel formula install? v2.4.0-rc.2 switched the tap from a formula to a cask. brew upgrade won't migrate an already-installed formula automatically; run this one-time transition:
brew uninstall --formula samuel
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.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
samuel command Command samuel is the entry point for the Samuel v2 CLI.	Command samuel is the entry point for the Samuel v2 CLI.
internal
agents Package agents declares the AgentAdapter interface and registers the five built-in adapters Samuel v2 ships (claude, codex, copilot, gemini, kiro).	Package agents declares the AgentAdapter interface and registers the five built-in adapters Samuel v2 ships (claude, codex, copilot, gemini, kiro).
builtins Package builtins embeds Samuel's built-in skill content into the binary so `samuel init` can sync it into ~/.samuel/builtins/ without network access.	Package builtins embeds Samuel's built-in skill content into the binary so `samuel init` can sync it into ~/.samuel/builtins/ without network access.
commands Package commands wires the Cobra root command and every subcommand for the Samuel v2 CLI.	Package commands wires the Cobra root command and every subcommand for the Samuel v2 CLI.
components/samuel Package samuel implements Samuel's first concrete plugin: the "samuel-builtins" component.	Package samuel implements Samuel's first concrete plugin: the "samuel-builtins" component.
config Package config models samuel.toml (the user-edited project config) and samuel.lock (the machine-managed resolved-plugin lockfile).	Package config models samuel.toml (the user-edited project config) and samuel.lock (the machine-managed resolved-plugin lockfile).
encoding/toon Package toon implements a Go encoder/decoder for the subset of the TOON v3 specification that Samuel v2 actually uses for its runtime files in .samuel/run/ (task state, project snapshots, task context).	Package toon implements a Go encoder/decoder for the subset of the TOON v3 specification that Samuel v2 actually uses for its runtime files in .samuel/run/ (task state, project snapshots, task context).
errors Package errors defines Samuel's structured error type used by every subsystem instead of bare errors.New / fmt.Errorf strings.	Package errors defines Samuel's structured error type used by every subsystem instead of bare errors.New / fmt.Errorf strings.
lock Package lock provides a cross-process advisory file lock used to serialise mutating Samuel operations (install / uninstall / sync).	Package lock provides a cross-process advisory file lock used to serialise mutating Samuel operations (install / uninstall / sync).
methodology/hooks Package hooks implements the lifecycle-hook framework that methodologies (built-in or plugin-provided) extend the autonomous loop through.	Package hooks implements the lifecycle-hook framework that methodologies (built-in or plugin-provided) extend the autonomous loop through.
methodology/ralph Package ralph wires the built-in Ralph Wiggum methodology: it owns the loop driver, the default hook handlers (snapshot/progress/task context generators, the agent.invoke adapter dispatcher, and the iteration gate that delegates to pilot mode).	Package ralph wires the built-in Ralph Wiggum methodology: it owns the loop driver, the default hook handlers (snapshot/progress/task context generators, the agent.invoke adapter dispatcher, and the iteration gate that delegates to pilot mode).
methodology/ralph/context Package context generates the pre-computed context files Ralph hands to the agent at the start of every iteration.	Package context generates the pre-computed context files Ralph hands to the agent at the start of every iteration.
methodology/ralph/prd Package prd is the v2 port of samuel_v1/internal/core/auto.go + auto_tasks.go — the data model the Ralph methodology stores in .samuel/run/prd.toon.	Package prd is the v2 port of samuel_v1/internal/core/auto.go + auto_tasks.go — the data model the Ralph methodology stores in .samuel/run/prd.toon.
methodology/ralph/templates Package templates embeds and renders the implementation + discovery prompts Ralph hands to the agent.	Package templates embeds and renders the implementation + discovery prompts Ralph hands to the agent.
orchestrator Package orchestrator coordinates installation, detection, health checking, and uninstallation of the Plugins that make up a Samuel project.	Package orchestrator coordinates installation, detection, health checking, and uninstallation of the Plugins that make up a Samuel project.
plugin Package plugin defines the universal Plugin contract every installable unit in Samuel v2 satisfies: built-in framework components, text skills, WASM modules, and OCI containers.	Package plugin defines the universal Plugin contract every installable unit in Samuel v2 satisfies: built-in framework components, text skills, WASM modules, and OCI containers.
plugin/capability Package capability models the host resources a Samuel plugin can request and the grant flow that gates them at install time.	Package capability models the host resources a Samuel plugin can request and the grant flow that gates them at install time.
plugin/manifest Package manifest parses, validates, and renders samuel-plugin.toml — the on-disk descriptor every installable Samuel plugin ships at the root of its repository (or inside its OCI image).	Package manifest parses, validates, and renders samuel-plugin.toml — the on-disk descriptor every installable Samuel plugin ships at the root of its repository (or inside its OCI image).
plugin/oci Package oci implements the OCI-tier plugin loader: container images pulled by Podman (rootless), Podman (root), or Docker and launched on demand with a fixed mount layout and a Unix-socket bridge for the framework hooks (see internal/plugin/oci/bridge/).	Package oci implements the OCI-tier plugin loader: container images pulled by Podman (rootless), Podman (root), or Docker and launched on demand with a fixed mount layout and a Unix-socket bridge for the framework hooks (see internal/plugin/oci/bridge/).
plugin/oci/bridge Package bridge implements the host-side server an OCI plugin container talks to over /samuel-bridge (a Unix-domain socket bind- mounted into the container's filesystem).	Package bridge implements the host-side server an OCI plugin container talks to over /samuel-bridge (a Unix-domain socket bind- mounted into the container's filesystem).
plugin/oci/policy Package policy implements the OCI tier's deny-by-default network policy (PRD 0010 §Functional 4 + 5):	Package policy implements the OCI tier's deny-by-default network policy (PRD 0010 §Functional 4 + 5):
plugin/oci/policy/proxy Package proxy is the userspace HTTP/HTTPS proxy that enforces the OCI tier's network policy (PRD 0010 §Functional 5).	Package proxy is the userspace HTTP/HTTPS proxy that enforces the OCI tier's network policy (PRD 0010 §Functional 5).
plugin/oci/policy/session Package session bundles the policy.Engine + proxy.Server lifecycle the OCI sandbox path consumes.	Package session bundles the policy.Engine + proxy.Server lifecycle the OCI sandbox path consumes.
plugin/registry Package registry implements the plugin index protocol Samuel v2 uses to discover installable plugins.	Package registry implements the plugin index protocol Samuel v2 uses to discover installable plugins.
plugin/semver Package semver implements the subset of SemVer 2.0 + Cargo range syntax that Samuel v2's plugin loader needs:	Package semver implements the subset of SemVer 2.0 + Cargo range syntax that Samuel v2's plugin loader needs:
plugin/service Package service glues the plugin loader's parts together:	Package service glues the plugin loader's parts together:
plugin/skill Package skill implements the skill-tier plugin loader: a text-only Agent Skill bundle that lands as SKILL.md (+ optional scripts/, references/, assets/) under <project>/.samuel/plugins/<name>/.	Package skill implements the skill-tier plugin loader: a text-only Agent Skill bundle that lands as SKILL.md (+ optional scripts/, references/, assets/) under <project>/.samuel/plugins/<name>/.
plugin/source Package source materializes a plugin's source tree (manifest + files) into a local directory the loaders can read from.	Package source materializes a plugin's source tree (manifest + files) into a local directory the loaders can read from.
plugin/verify Package verify — production sigstore-go implementation.	Package verify — production sigstore-go implementation.
plugin/wasm Package wasm — Capabilities collects every resource a wasm plugin can request: filesystem mounts, environment variables, network hosts, memory cap, and per-invocation timeout.	Package wasm — Capabilities collects every resource a wasm plugin can request: filesystem mounts, environment variables, network hosts, memory cap, and per-invocation timeout.
sandbox Package sandbox is the host-process / OCI launch surface the methodology layer calls through to invoke an agent.	Package sandbox is the host-process / OCI launch surface the methodology layer calls through to invoke an agent.
sync Package sync writes per-folder AGENTS.md files describing each directory's purpose, primary languages, key files, and whether tests live there.	Package sync writes per-folder AGENTS.md files describing each directory's purpose, primary languages, key files, and whether tests live there.
translator/claude Package claude mirrors AGENTS.md files into sibling CLAUDE.md files so Claude Code (which still treats CLAUDE.md as primary) picks up the same project context that every AGENTS.md-native tool already reads.	Package claude mirrors AGENTS.md files into sibling CLAUDE.md files so Claude Code (which still treats CLAUDE.md as primary) picks up the same project context that every AGENTS.md-native tool already reads.
ui Package ui is Samuel v2's human-output layer: lipgloss colour tokens plus the six-category vocabulary v1 settled on (success / error / warn / info / bold / dim) and a handful of list-and-table helpers.	Package ui is Samuel v2's human-output layer: lipgloss colour tokens plus the six-category vocabulary v1 settled on (success / error / warn / info / bold / dim) and a handful of list-and-table helpers.
scripts
migrate-v1-skills command Command migrate-v1-skills mechanically ports the 79 v1 SKILL.md directories at samuel_v1/.claude/skills/ into either per-plugin source trees (default) or a single subpath-layout monorepo (-target=monorepo, per RFD 0012).	Command migrate-v1-skills mechanically ports the 79 v1 SKILL.md directories at samuel_v1/.claude/skills/ into either per-plugin source trees (default) or a single subpath-layout monorepo (-target=monorepo, per RFD 0012).
wasm-fixtures command scripts/wasm-fixtures rebuilds the committed binary fixture at testdata/wasm-fixture/plugin.wasm using the hand-encoded helper in internal/plugin/wasm.	scripts/wasm-fixtures rebuilds the committed binary fixture at testdata/wasm-fixture/plugin.wasm using the hand-encoded helper in internal/plugin/wasm.
template Package template embeds and renders the canonical AGENTS.md template that Samuel writes into every initialised project.	Package template embeds and renders the canonical AGENTS.md template that Samuel writes into every initialised project.