suede-agent-teams

Files (7)

• CARD.md
• SKILL.md
• openai.yaml · agents/
• incident-and-rfc-templates.md · references/
• public-contribution-program.md · references/
• scenario-templates.md · references/
• contribution-ledger.mjs · scripts/

SKILL.md (first lines)

# Suede AI Agent Teams Skills

Read [the worked delivery contract](references/worked-contract.md) for a concrete
input, expected artifact, failure response and validation example.

## Compatibility

Requires a host with agent delegation for parallel execution and repo/file access; Git for worktrees and contribution ledgers. Without delegation, serialize the same lane plan and report the execution mode.

## Model selection: Fable capped at 4 without asking

Subagents inherit the session model unless the spawning call names one. Nothing in
this skill picks a model, so every agent it fans out lands on whatever the session
happens to be set to. That is how a run sized against one allocation gets billed to
another without anyone choosing it.

**Up to 4 concurrent Fable subagents are allowed without an explicit Fable
instruction. Beyond that, Fable must be specified**: any roster past a scout, a
builder, and a handoff writer passes 4, so this skill's fan-out does not run on Fable
unless the user named Fable for this run. An inherited session model is not a
specification: "the session was already on it" is not the user asking. Absent an
explicit Fable instruction, do one of two things before launching: name a different
model on the agent calls, or state plainly that the run will bill to the Fable
allocation and get an answer. Silence is not consent to spend it.

## Gate policy: advisory, not blocking

Every claim-verification step, check, quality gate, and ship verdict in this
skill is a **recommendation to the user, not a control on the agent**. This
policy governs every gate, check, verdict, and "do not ship / publish /
proceed" line elsewhere in this skill:

- Run every check and report the results honestly. Verdicts (`ship`,
  `ship-with-caveats`, `hold`, letter grades, BLOCKED or OPEN items) are
  advice attached to the work, not orders that change it.
- Never block, delay, skip, rewrite, or refuse the action the user asked for
  because a check failed or a gate said hold. Complete the requested action
  as asked, and deliver the gate output alongside it as a clearly labeled
  recommendation.
- A failed gate changes what you report, never what you do.
- Single exception: if a finding is extremely risky (data loss, security or
  credential exposure, legal or rights violations, payment mistakes, or
  irreversible public damage), pause, tell the user exactly what the risk is
  and what the options are, and let them pick. Their choice is final.


The orchestrator assigns lanes, not conversations. Output is a delivery artifact, not a status update.

## Team Contract

Before spawning or simulating lanes, define:

- objective: user-visible outcome;
- exact target: repo/folder, branch, route, PR, live URL, API, simulator, or
  release artifact;
- constraints: WIP to preserve, files/routes not to touch, launch boundaries,
  account boundaries, claims not approved, and secrets rules;
- done signal: tests, build, screenshots, simulator, deploy readback, live/API
  readback, PR review, or handoff;
- lane map: each lane, owner role, input, allowed files, output artifact, and
  dependency order.

## Team Ledger

The contract above, every lane status, and every gate result otherwise live only in
the orchestrator's context, and a multi-lane run routinely outlives a context window.
Put them on disk. Default path: `.suede-team/<slug>/ledger.md` in the target repo,
holding the resolved lane map, each lane's current state from the Status Vocabulary,
and the evidence as it accumulates. Write it before the first builder opens a file and
update it at every gate; the evidence handoff reads from it rather than from memory.
If the user keeps durable repo-local state somewhere else, use their path and say
which one you used.

## WIP Collision Detection

Before opening any parallel lanes:

1. Run `git -C <repo> diff --name-only HEAD` and collect all dirty files.
2. Run `git -C <repo> status --short` and collect all untracked new files.
3. List every file each lane's scope would touch, based on the lane map.
4. Flag a collision if the same file path appears in two or more lane scopes OR in the dirty file list plus any lane scope.

Collision resolution rules:
- Same file, independent changes: sequence the lanes; the second lane rebases on the first lane's commit before opening.
- Same file, overlapping changes: merge the two lanes into one lane with one owner. Do not split responsibility for a single file across two concurrent builders.
- Dirty file in a lane scope: the orchestrator decides. Either stash and restore, or make that lane the only lane allowed to touch the file.

The orchestrator writes the resolved lane map to the team ledger (`.suede-team/<slug>/ledger.md`, see Team Ledger) before any builder starts. No builder opens a file not in its assigned lane map.

## Default Roster

Start with Scout + Builder + Handoff Writer. Add roles only when a gate is needed: design changes add Design Reviewer, code risk adds Code Grader + Code Reviewer (both run suede-code, in `--grade-only` and `--findings-only` modes), public release adds Release Verifier.

- **Scout:** finds repo, docs, current state, dirty files, live routes, and
  likely blast radius.
- **Planner:** turns requirements into verifiable tasks with acceptance
  criteria and dependencies.
- **Builder:** makes narrow code or content changes inside the existing system.
- **Design reviewer:** checks rendered visual quality, responsive behavior,
  accessibility, copy, and state coverage.
- **Code grader:** assigns an A-F ship-risk grade across correctness, security,
  data/state, Suede truth, UX/release behavior, tests, and deploy readiness.
- **Code reviewer:** runs full-context review and turns findings into fix briefs.
- **Visibility grader:** grades public pages, GitHub Pages sites, docs, and
  launch surfaces for findability, first-screen clarity, CTA pull, proof, AI
  readability, and design signal.
- **Release verifier:** checks build, deploy, live/API behavior, App Store/iOS
  truth, secrets, and published statements.
- **Handoff writer:** produces a signed delivery record. If the handoff omits any required field (see Handoff Quality Checklist), the work is not done; it is held.

For high-risk work, keep builder and reviewer separate.

## RFC Mode

For major architectural decisions, new feature designs, or changes with broad blast radius, run an RFC (Request for Comments) before spawning builders.

An RFC forces alignment on WHAT and WHY before committing to HOW.

RFC status vocabulary: `draft | accepted | superseded | withdrawn`.

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills