Move work between coding agents without copying the whole conversation — or building an orchestrator.
The human is the orchestrator. The repo is the memory. Markdown is the protocol.
Hand off coding tasks between Claude Code, Codex, and any agent — with one Markdown file and one paste. Agent Spartan Protocol is a portable, human-mediated handoff protocol for software work performed across authenticated coding-agent hosts: one repository-local Markdown task artifact preserves context, and one concise prompt transfers the next bounded action.
The protocol is intentionally not an orchestrator. It does not launch models, manage credentials, keep a daemon alive, retry work, monitor sessions, coordinate concurrency, or adopt patches automatically.
sequenceDiagram
actor H as Human
participant C as Claude Code
participant R as Repo<br/>spartan/tasks/NNNN-slug.md
participant X as Codex
H->>C: start session + prompt
C->>R: read or create task file
C->>R: one bounded round + record evidence
C-->>H: short handoff
H->>X: paste handoff (manual)
X->>R: read same task file
X->>R: next role, next bounded round
X-->>H: next handoff or completion
Note over H: The human starts every session.<br/>Nothing runs in the background.
Add the marketplace once, then install the plugin:
/plugin marketplace add angelopublio/agent-spartan-protocol
/plugin install spartan@agent-spartan-protocol
Invoke it in any project with /spartan:spartan (or simply /spartan when no other command uses that name):
/spartan:spartan
Implement a small, reversible change that fixes the empty-state message and updates the relevant regression test.
Install with the skills CLI, which detects your installed agents (Codex, Cursor, and many others):
npx skills add angelopublio/agent-spartan-protocol --skill spartanInvoke it in Codex by mentioning the skill:
Use `$spartan`.
Implement a small, reversible change that fixes the empty-state message and updates the relevant regression test.
Either way, Spartan creates or continues one task file under spartan/tasks/ in your project, performs one bounded round, and returns one short handoff you can paste into the next host. You choose and start every next session; nothing runs in the background.
Coding agents already know how to inspect repositories, edit files, run checks, and review diffs. The missing piece is a small, durable contract that lets a human move work between hosts without copying the full conversation or building an execution platform.
Spartan provides that contract:
- The current host reads or creates
spartan/tasks/NNNN-<slug>.md. - It performs one useful, bounded round.
- It records decisions, work, concise evidence, blockers, and the next action.
- It returns one short English handoff referencing the task file.
- The human chooses and starts the next host.
- Repository files, the current diff, and check results are the truth of implementation.
- The task Markdown is the truth of handoff.
- Chat history is disposable context.
spartan/tasks/remains public and version-controlled as living proof that the protocol can carry real work without hidden state.
Phase and status fields describe the current snapshot. They are not an executable state machine. The task file is not an event log, database, audit ledger, or transcript.
Newer task files also carry a compact HX-NNN handoff identifier so a receiving round can detect a stale pasted prompt instead of silently acting on it; older tasks without it remain valid unchanged. The full handoff contract ships with the skill in agent-skill/skills/spartan/references/protocol.md.
The package root is agent-skill/, and the portable skill itself lives one level down in agent-skill/skills/spartan/:
agent-skill/
|- .claude-plugin/
| `- plugin.json
|- CHANGELOG.md
|- version.txt
`- skills/
`- spartan/
|- SKILL.md
|- agents/
| `- openai.yaml
|- references/
| |- protocol.md
| `- routing.md
`- assets/
|- spartan-readme.md
`- task-template.md
The split is deliberate. agent-skill/ is the distribution root and carries only packaging: the plugin manifest, the changelog, and the version stamp. agent-skill/skills/spartan/ is the skill folder and carries only behavior. Keeping them apart means the skill owns its own subdirectory names instead of competing with the names a plugin root reserves, and a symlink install exposes the skill without dragging packaging files along with it. skills/<name>/ is also the layout every host discovers without a manifest hint.
agents/openai.yaml is optional Codex interface metadata. The behavior contract remains in portable Markdown shared by all hosts.
Distribution metadata is static only: .claude-plugin/marketplace.json at the repository root lists the plugin for Claude Code, and agent-skill/.claude-plugin/plugin.json carries the package's passive Semantic Version. Neither adds runtime behavior, and the skills CLI needs nothing beyond SKILL.md.
Project-local discovery uses symbolic links to the same skill folder:
.agents/skills/spartan -> ../../agent-skill/skills/spartan
.claude/skills/spartan -> ../../agent-skill/skills/spartan
Codex uses the .agents link, Claude Code uses the .claude link, and compatible hosts may use the same canonical source. These links install no runtime and create no divergent skill copies.
Start the coding host with the target project as its working folder. Spartan stores continuation state in that target project under spartan/tasks/; it does not store the target project's task state in this protocol repository. The spartan/README.md file explains this durable task namespace.
When Spartan creates that first task in a repository whose root has neither an AGENTS.md nor a CLAUDE.md, the round also adds one advisory line suggesting you create an AGENTS.md (stack, dev/build/lint/test commands, conventions) plus a minimal CLAUDE.md that points to it, so later hosts start with shared instructions to read. The suggestion is tied to the repository's first task — it fires once, with no hidden flag — and Spartan never writes those files for you. You decide whether to add them.
A human can also declare repository-specific host preferences in AGENTS.md, under a ## Spartan host preferences heading. This guides future handoff recommendations; it never authorizes Spartan to start a host or round. One rule shapes any such declaration: a reviewer must not be the host that produced the work under review, because self-review correlates blind spots.
With two hosts that rule cannot be satisfied by a fixed assignment, since the same host plans one round and implements another. Say so instead of pinning the reviewer:
## Spartan host preferences
| Role | Host |
|---|---|
| planner | Claude Code |
| implementer | Codex |
| reviewer, independent-reviewer, verifier | whichever host did not produce the work under review |
Roles not listed here follow the Spartan package default.
These are routing preferences, not execution authority. The human starts every round.With three hosts a fixed assignment satisfies the rule on its own, because neither producer is the reviewer:
## Spartan host preferences
| Role | Host |
|---|---|
| planner | Claude Code |
| implementer | Cursor |
| reviewer, independent-reviewer, verifier | Codex |
Roles not listed here follow the Spartan package default.
These are routing preferences, not execution authority. The human starts every round.Both examples map only Spartan's existing roles and name no model. The maintained model list ships with the skill in agent-skill/skills/spartan/references/routing.md; name models in your own declaration only if you keep them current.
A repository that also runs the Spartan Bridge carries a second, differently shaped section in the same AGENTS.md: ## Agent hosts, a | Binding | Host | Client context | table that the Bridge parses. The Bridge is an optional runtime, installed separately from this protocol; nothing above depends on it, and a repository without it needs no such section. The two sections sit on different axes — ## Spartan host preferences is an advisory routing preference between hosts, ## Agent hosts is an execution binding between named client contexts — so they stay separate and must not be merged, nor one converted into the other. This repository's own AGENTS.md is such a Bridge configuration; the full configuration reference lives in the Bridge project.
A Bridge binding table does not satisfy Spartan's no-self-review preference. Binding the same host to producer and reviewer buys context separation, not cross-host or cross-vendor independence — which is why this repository, pinning Cursor to both implementation and implementation review, says so in its own AGENTS.md rather than presenting that shape as advice to copy.
One coupling is worth knowing before a failed run teaches it: the Bridge treats the sentence The human starts every round. alone on a line in AGENTS.md as an explicit denial of automatic review.
To continue an existing task in either host, reference its exact artifact instead of repeating its history:
Open `spartan/tasks/NNNN-<slug>.md`.
Act as the next role recorded in the task and follow the current Next Handoff. A writable prompt updates the same task file. A read-only prompt returns its verdict and findings in the response and writes nothing.
The human must start every new host session and manually transfer every handoff. Spartan never opens or invokes another platform.
The installable package uses Semantic Versioning. Release automation lives in repository CI, outside agent-skill/; it prepares the changelog and package metadata, then creates the tag and GitHub Release after its release pull request is merged. See RELEASING.md for the operator flow.
The protocol value copied into a newly created task is only a birth-stamp. Spartan performs no version negotiation or network check, and package releases never rewrite existing tasks or version an adopting repository.
This project does not provide:
- cross-provider model invocation;
- API-key or subscription management;
- workers, daemons, schedulers, polling, or crash recovery;
- queues, locks, concurrency control, or worktree allocation;
- automatic retries or correction loops;
- secret scanners, sandboxes, or policy engines;
- event ledgers, projections, patch digests, or transactional adoption;
- external actions initiated automatically by Spartan, such as commit, push, pull request, merge, or deployment. Repository release CI is separate from the portable protocol and its installable package.
If a requirement needs those guarantees, it belongs in a separate runtime or workbench rather than this protocol.
The decisive test is deletion:
If the skill is removed, do the task files remain understandable, and can a human continue the work manually?
If the answer is no, the feature has crossed from protocol into runtime.
This is Steph Ango's file over app, applied to models: the task file must outlive every host that touched it.
Working on the protocol itself, or on a host that cannot use the marketplace or the skills CLI? See docs/INSTALL-DEV.md for the symlink-based installation.
The current release is always the latest entry on the GitHub Releases page; the packaged version is recorded in agent-skill/version.txt and bumped only by the release automation, which has been exercised end to end (see the completed spartan/tasks/0008-verify-first-hosted-release.md). The validated static-package baseline and its bootstrap approvals are recorded in spartan/tasks/0001-bootstrap-v0-1.md.
The next phase is real-project dogfooding: one small reversible task completed in one host, one material change with fresh-context review, and one high-impact plan or review handed manually across vendors. Do not add protocol features until repeated trial evidence justifies them.
See docs/DOGFOODING.md for the sequence and exit criteria.