/suede-agent-teams · Agent orchestration

Five lanes, one plan, nobody steps on the work.

Suede Agent Teams assigns lanes, not conversations. It detects work-in-progress collisions before any builder opens a file, runs an RFC before high-blast-radius changes, gates the work through quality and adversarial review, and closes with a handoff that will not sign off until every required field is present and truthful.

Install the skill View skill folder

"run this rewrite as coordinated lanes" /suede-agent-teams Ask in plain words. The router reads the request and loads this lane; MCP agents find it with list_suede_skills.

$ /suede-agent-teams auth-rewrite lanes: scout · build · review · verify · release WIP collision check · dirty files fenced correction ledger · new root causes only · maximum 3 fixes HANDOFF SIGNED · EVIDENCE ATTACHED

Public install command

Claude Code: add the marketplace and install the orchestration subset:

/plugin marketplace add JasonColapietro/suede-creator-skills
/plugin install suede-agent-workflows@suede

Codex: this is the public route. It installs from GitHub as a standard Codex skill folder.

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo JasonColapietro/suede-creator-skills \
  --path skills/suede-agent-teams

Restart Codex after installing the skill.

The default roster

Start with Scout, Builder, and Handoff Writer. Add a role only when a gate needs it.

Scout maps the repo, current state, dirty files, live routes, and likely blast radius.
Planner turns requirements into verifiable tasks with acceptance criteria and dependencies.
Builder makes narrow changes inside the existing system, in assigned files only.
Design reviewer, code grader, and code reviewer attach when design or code risk is present.
Release verifier owns build, deploy, live and API truth, and published-statement accuracy.
Handoff writer produces a signed delivery record, held if any required field is missing.

Where it fits

Reach for it when a change is too broad, too risky, or too release-bound for one lane: shared interface changes, auth and payment paths, data migrations, and public launches. For high-risk work it keeps the builder and the reviewer separate so the implementation gets a second, adversarial set of eyes.

Use the smallest loop that can finish the work, and escalate deliberately when the task is broad, risky, release-bound, or you ask for max agent teams.

Collision detection and quality gates

Before any parallel lanes open, the orchestrator collects every dirty and untracked file, maps each lane's scope, and flags a collision when two lanes, or a lane and existing work, would touch the same path. No builder opens a file outside its assigned lane map.

RFC modeShared interfaces, schema, auth, payment, and public API changes require an accepted RFC before a builder opens.

Feature flagsRisky or non-revertible changes ship behind a flag with a removal date set at creation and a staged ramp.

Rollback treePre-agreed decisions: roll back immediately on data loss or security exposure; hold and investigate on degraded performance.

Adversarial reviewOne lens asks whether it works; another asks how it fails in production, release, abuse, accessibility, and handoff.

Escalation protocolRepeated fix cycles, unknown-severity security findings, and cost spikes stop the loop and surface for sign-off.

Correction budgetUp to three genuinely different fixes per failing check. Each must change the diagnosis or strategy. Stop early when the same root cause repeats.

Status vocabulary"Changed locally" is not "verified locally"; "deployed" is not "verified live." States do not skip.

Public contribution program

Run a repeatable owned-repository contribution lane without assigning the same issue twice. Candidates are scored by impact, confidence, effort, risk, and ownership; the included ledger grants one atomic lease per repository and issue pair.

Unknown ownership is treated as external.
Every task starts local-only with publication disabled.
Each builder uses an isolated branch or worktree and exact file ownership.
Branch, commit, and PR checks are stored with content hashes before a packet becomes ready.
Push, draft PR, ready PR, and merge each require a one-shot grant bound to that task and packet hash.
Disabling publication revokes unused grants so authority does not cross runs.
External work stops at a reviewed contribution packet unless the owner separately approves a draft PR.

node skills/suede-agent-teams/scripts/contribution-ledger.mjs init \
  --ledger <control-dir>/contributions.json \
  --publish-mode disabled

Conventional outward artifacts

Branches, commits, and PR copy describe the project change: problem, approach, tests, scope, and risks. The packaging check requires a valid branch ref, a conventional commit subject, and nonempty Summary, Why, Testing, Scope, and Risks sections. It rejects voluntary tool-origin footers, model badges, robot markers, and model/tool co-author trailers.

It never rewrites provenance or suppresses a required disclosure. Unknown disclosure blocks packaging. Required disclosure must appear exactly once in the PR draft and needs an explicit owner decision on the checked content hash. Git identity, signatures, approvals, and timestamps are never forged.

node skills/suede-agent-teams/scripts/contribution-ledger.mjs artifact-check \
  --ledger <control-dir>/contributions.json --id <task-id> \
  --worker <lane-id> --kind commit --input <artifact.txt>

Model tiering

Assign the least capable model that can still do the role correctly. Cost and latency compound across a roster.

Mechanical tasks (an isolated function, a single file, or a complete spec with no judgment call) get the cheapest capable model.
Integration and judgment tasks (multi-file coordination, pattern-matching against the existing codebase, or non-trivial debugging) get a standard model.
Architecture, design, and review roles (RFC authoring, code grading, security-sensitive review, or release verification) get the most capable model available.

When a lane's complexity is ambiguous, default up a tier. A cheap model returning a wrong answer costs more in re-dispatch than starting at the right tier.

Builder dispatch protocol

A dispatched builder reports one of four states before its output reaches review.

Done means the builder finished cleanly; proceed to the next roster stage.
Done with concerns means the builder flagged a doubt; resolve it first if it touches correctness or scope, otherwise note it in the handoff and proceed.
Needs context means the builder is missing information the lane map should have supplied; provide it and re-dispatch the same builder rather than guessing on its behalf.
Blocked means the builder cannot proceed. Diagnose why before re-dispatching: a context gap gets more context, a reasoning gap gets a more capable model, an oversized task splits into smaller lanes, and a wrong plan escalates to the human.

Scenario templates

Pre-built rosters for common high-risk deployments. Adjust only the named target.

Auth rewrite: RFC and flag required; builder touches auth files only; release verifier confirms in production.
Payment integration: idempotency, webhook signatures, and decline and replay paths tested before ramp.
Public launch review: review-only roster across design, visibility, links, secrets, and claim truth.
Data migration: rollback script defined and tested in staging before production promotion.
Performance audit: rank fixes by impact, implement only the ranked set, confirm no regression.

Handoff that won't fake done

The delivery record is held until every field is present and truthful: exact target, every changed file, every command with output, observable verification, a real status, the single next step, and every caveat.

Target:
Changed:
Verification:
Caveats:
Status:
Next:

Best prompts

Use $suede-agent-teams to plan lanes for this multi-file change. Run WIP collision detection first and give me the lane map.

Use $suede-agent-teams with the auth-rewrite template. Require an RFC and a feature flag before any builder opens.

Use $suede-agent-teams to coordinate this public launch review and hold the handoff until every field has evidence.

Use $suede-agent-teams to run an owned public-repository contribution program. Score candidate issues, lease each task before opening a worktree, keep publication disabled, and return a reviewed contribution packet with conventional branch, commit, and PR drafts.

Use $suede-agent-teams to recover this failing check. Allow up to three genuinely different fixes, stop early when the same root cause repeats, and include the correction ledger in the handoff.

Safety boundary

No lane may override an escalation threshold by re-scoping the task or declaring a condition resolved without sign-off. Release truth, meaning build, deploy, live and API behavior, and published statements, is owned by the release verifier before any completion claim.

The orchestrator organizes the work; it does not invent verification, deploy status, or approved claims.

Cue Suede

Feedback can happen mid-workflow or at the end. Say Cue Suede to ask for choices: change something, preserve what worked so the agent can mimic it later, or keep as-is by saying nothing.