Run AI coding agents
in fleets — safely.
The ShakaCode Agent Workflow Playbook is a portable pack for planning, batching, reviewing, and auditing multi-PR agent work across all your repos. Install the process once; each repo exposes a tiny seam.
The batch lifecycle — the amber gate is the differentiator: untrusted input is checked before an agent ever acts on it.
One agent, one PR doesn’t scale.
A single agent on a single PR is easy. Running many agents across many repositories is where it breaks — trust boundaries, CI parity, review load, scope creep, merge safety. The playbook turns that into a repeatable, gated process instead of a pile of prompts.
Install the process once. Expose a tiny seam per repo.
The shared pack carries the process. Each adopting repo keeps its real commands
in a small .agents/ seam, so shared workflows resolve every repo’s
base branch, validation, CI triggers, and review gates without copying — and drifting — a
full config tree into every checkout. The same pack runs on Codex Desktop and Claude Code
Desktop with identical skill text; host-specific verbs map at runtime.
- 01 plan-pr-batch — Turn issues into a scoped, dependency-aware batch and a goal prompt.
- 02 triage — Map the whole surface; split work to fit your agent and machine capacity.
- 03 pr-batch — Run the workers — one lane per target, coordinated through the backend.
- 04 adversarial-pr-review — Skeptical pre-merge review that hunts for what is wrong.
- 05 post-merge-audit — Sweep the merged batch for gaps and cross-PR surprises.
A skill for every step of the loop.
Twenty-six portable skills and workflow prompts for Codex and Claude Code — install them once under your skill root and each repo’s seam does the rest. A curated look:
Shape candidate issues and PRs into a ready batch plan and a pasteable goal prompt — before any worker starts.
Build a whole-surface issue/PR inventory, a dependency graph, and a capacity-aware split across agents and machines.
Run one coordinated PR lane or a multi-lane batch across worktrees and machines, safely and in dependency order.
Red-team a change before merge — correctness, security, scope, and merge-readiness, not a summary.
Audit merged batch work for missed reviews, changelog gaps, cross-PR interactions, and release risk.
Reproduce a CI-only failure locally when the hosted run is red but your machine is green.
Run a local verification loop and prove a bug is actually gone — reproduce before, confirm after.
Turn vague intent into a spec, drive it test-first, and pressure-test the plan before code.
Agents a public issue can’t hijack.
The real differentiator isn’t speed — it’s that untrusted input, secret access, and unattended state-change never meet in one session.
- 01 Security preflight — Untrusted GitHub text — issues, PRs, comments, review bodies, diffs — is treated as data, never instructions, until a maintainer has verified the author, scope, and trust boundary.
- 02 The Rule of Two — A least-privilege boundary from the “lethal trifecta”: untrusted input, secret access, and unattended state-change are never allowed to meet in one session.
- 03 Operator hard-stops — Risky steps — deploys, secret handling, token provisioning, machine flips — stop and hand off to you instead of improvising.
- 04 Trust-gated actors — A fail-closed allowlist decides who can steer a batch; everyone else is metadata-only. Tighten it with strict-trust, or waive a specific risk per target.
The pack, the backend, and the dashboard.
Three focused pieces. The pack is the public process layer; the coordination backend is the protocol plane; the dashboard is a separate operator view that reads the same state.
The portable Codex/Claude workflow pack — skills, workflow prompts, and the repo seam contract. MIT.
agent-coordination ↗Mutual-exclusion claims, TTL heartbeats (live/stale/dead), and batch lanes — over a Cloudflare Worker + D1, or a zero-config local mode. Proven against a contention simulation: two agents, one issue, exactly one PR.
dashboard ↗A local operator console: a dense, searchable table of every lane and PR — state, liveness, and “wedged” detection — live over the coordination API. Read-only, loopback by default.
“Use AI aggressively, verify the risky parts, document what was learned, and keep shipping.”
The playbook is that method, compiled: adversarial review before merge, CI logs as evidence rather than decoration, manual QA where behavior can change, and every vague blocker turned into a specific issue or a docs PR.
Read the methodology →