SmokeJumper
shanemhamilton/smokejumper
Crew autônomo de product dev que executa sprints completos e autoavalia
Ver no GitHubAgent autônomo de desenvolvimento de produtos que aterrissa em qualquer repositório, analisa a codebase, decide o próximo movimento de maior impacto e executa via Claude + agents. Realiza gate de revisão adversarial em cada push e aprende continuamente, melhorando o repositório e a si mesmo a cada deployment.
Instalação
npx convez-ai shanemhamilton/smokejumper1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de ciclos de desenvolvimento com revisão de segurança
- Melhoria contínua de repositórios com aprendizado acumulado
- Decisão e execução autônoma de features de maior impacto
Veredito

SmokeJumper é uma abordagem sofisticada e ambiciosa para automação de desenvolvimento, com gates de segurança e capacidade de aprendizado. Recomendado para times maduros que querem automação real com controle, não apenas sugestões.
README
A tradução para o português deste README ainda está na fila.
SmokeJumper
A drop-in, autonomous product-development crew packaged as a standalone plugin for Claude Code and Codex.
SmokeJumper lands cold in any repo, builds a model of what exists, decides the highest-leverage next move itself, executes via a mix of Claude agents and Codex, gates every push through an adversarial review, and runs a lessons-learned pass at the end — enriching both the target repo's own knowledge store and the plugin itself. Two things compound per deployment: the repo gets better, and the crew gets sharper.
SmokeJumper installs from the same plugin manifest in both runtimes — Claude Code and
Codex share the SKILL.md + agents/ + .claude-plugin/marketplace.json format.
Claude Code
From GitHub:
claude plugin marketplace add https://github.com/shanemhamilton/smokejumper
claude plugin install smokejumper@smokejumper
Or from a local checkout (swap the marketplace source):
claude plugin marketplace add ~/Documents/SmokeJumper
claude plugin install smokejumper@smokejumper
Codex
codex plugin marketplace add shanemhamilton/smokejumper
Then install the smokejumper plugin from within Codex (its skill-installer handles
enablement). For a local checkout, point the marketplace at the directory instead:
codex plugin marketplace add ~/Documents/SmokeJumper
Validate / release (Claude Code)
Validate before installing:
claude plugin validate ~/Documents/SmokeJumper
Cut a versioned release tag:
claude plugin tag ~/Documents/SmokeJumper
Usage
/smokejumper
Starts a full sprint. SmokeJumper proceeds through all eight phases autonomously, pausing only for decisions that require product strategy, budget authority, or explicit release sign-off.
Running under a Codex (or non-Claude) orchestrator
SmokeJumper is built for Claude Code, but it also runs when a Codex agent (or any
file-and-shell capable agent) is the top-level orchestrator — point the agent at
skills/smokejumper/SKILL.md and have it follow the eight phases. A runtime preflight
(references/runtime.md) detects what your runtime can do and adapts:
- No subagent dispatch → leads and reviewers are adopted inline: the orchestrator reads the resolved
agents/*.mdpersona and acts as that role for the phase. RECON runsscripts/sj scan, which resolves the leads, writes the mapping intorepo-knowledge.md+adapter-scan.json, and prints a "Leads established" banner — so lead establishment is a visible, durable artifact, not an implicit step. - The
sjCLI is runtime-agnostic → any orchestrator that can run a shell command gets the same deterministic gates (sj gate), state validation (sj validate-state), and safety tripwires (sj lane-check). - No Skill tool → the embedded reference files are used directly. Product context is bootstrapped by
references/product-context.md+templates/product-context.mdwith no dependency on any external skill. anthropic-skills:handoff-promptunavailable → Phase 8 writes<target>/.smokejumper/HANDOFF.mddirectly.choo-choo-ralph/bdabsent → Lane A is unavailable; all work routes to Lane B (the synchronous crew).
Lead establishment & product context
Two RECON outputs are durable, visible artifacts rather than steps an orchestrator has to remember — so they hold up under any runtime, including a Codex agent that skims prose.
Leads are established by a deterministic scan, not from memory. scripts/sj scan resolves the product / engineering / design leads (a project-specific override or the bundled fallback), the gate roles, and the available capabilities; writes the mapping into <target>/.smokejumper/repo-knowledge.md; emits a leads_established event to the sprint log; and prints a banner:
=== SmokeJumper — Leads Established ===
Product lead: smokejumper-product-lead [BUNDLED]
Engineering lead: smokejumper-engineering-lead [BUNDLED]
Design lead: smokejumper-design-lead [BUNDLED]
Gates resolved: designReviewer=null thesisGuardian=null reviewIntegrity=null firstUseCritic=null qualityControl=null
Capabilities: asyncLoop=no codex=yes metaswarm=no bugsweep=no tracker=beads
Design skills: review=design-review consult=design-consultation a11y=accessibility-wcag frontend=frontend-design (plugin)
Design system: tailwind.config.js,src/theme.css,.storybook/
Functional health: HEALTHY → design posture: WEIGHTED
Product context: MISSING — run Setup before DECIDE
=======================================
A lead is a persona, not a mandatory subagent: the orchestrator establishes it by reading its definition file and adopting it — or dispatching it, where the runtime supports that. Gate roles and safety/invariant guardians resolve from the target repo's .claude/agents/ only — a foreign project's gate pulled from the global dir is misleading, and a foreign guardian is unsafe (absent must route safety-critical work to the human).
Product context is bootstrapped, not inferred. Before DECIDE, RECON establishes a compact PRODUCT_PILOT-style brief — phase, active milestone, blockers, metrics, differentiator:
- Context mode — a product-context layer already exists → read it as authoritative input to DECIDE.
- Setup mode — none exists (the brand-new-repo case) → a short discovery interview writes one to
docs/product/PRODUCT_PILOT.md. - Update mode — LESSONS LEARNED reflects shipped work back into it.
The bootstrap is fully self-contained (references/product-context.md + templates/product-context.md) with no dependency on any external skill, and it never fabricates: unknown metrics, competitors, and milestones are marked [TODO], and an autonomous run with no human to interview stamps the artifact unverified.
Design strength
SmokeJumper treats design as a first-class concern that scales with functional health — design is taken at face value while a repo is still stabilizing, and weighted more heavily once the fundamentals are solid. Four mechanisms, all visible and durable like everything else:
Functional-health-gated weighting. The adapter scan derives a windowed functionalHealth (POOR | FAIR | HEALTHY, from gate/outcome failures over the last 2 sprints) and maps it to a designPosture (ADVISORY | WEIGHTED). DECIDE reads it: when WEIGHTED, the product lead ranks design-debt / polish / UX objectives higher; when ADVISORY, functional work wins. The signal is windowed, not cumulative — so it recovers: design gets weighted once functional issues are actually addressed, not blocked forever by one rough sprint. This affects objective prioritization only — never gating, never a forced skill invocation.
Design-system discovery + a durable model. The scan surfaces design-system source-of-truth candidate paths (adapter.designSystem — Tailwind config, theme files, tokens, Storybook, DESIGN.md). The design lead then searches the repo/code itself, identifies the real source of truth, and records it — token/theme paths, color/spacing/type scales, component library, UI conventions — into a durable ## Design system section of repo-knowledge.md that every later sprint inherits and verifies. No design is produced without the system in hand; no token, hue, or spacing value is ever invented.
Real design skills, in both runtimes. The scan detects installed design tooling (adapter.skills.design.review|consult|a11y|frontend) by scanning ~/.claude/skills/, gstack, and installed plugins. The design lead resolves through these adapter keys — never a hardcoded name — invoking them via the native Skill tool under Claude Code, or by reading the skill's SKILL.md inline under Codex (where the Skill tool is absent). The two non-negotiables — design critique and a WCAG 2.2 AA accessibility check — run by skill if present, by hand if not.
It learns which skills work. Each design-skill invocation is scored (a gate-or-ship proxy) into an append-only ## Design skills tally in repo-knowledge.md; RECON surfaces the proven ones as recommendations next sprint, and portable recommendations graduate upstream through the same Mode B contribution flow. The ## Design system and ## Design skills sections are agent-owned — the adapter scan records detection into ## Capabilities but never clobbers either accumulated section.
Deterministic enforcement — the sj CLI (v1.0.0)
The safety contracts are commands, not prose. skills/smokejumper/scripts/sj is a single
dependency-light CLI (bash + standard unix tools; jq optional with a fallback) that any
runtime — Claude Code, Codex, plain CI — invokes the same way:
sj init <target> scaffold .smokejumper/ state (validates it's a git repo)
sj scan <target> adapter scan → banner + repo-knowledge.md + adapter-scan.json
sj gate record <gate> --reviewers a,b write an evidence-backed gate marker
sj gate check <gate> verify the marker before push (exit nonzero = no push)
sj gate clear <gate> remove a stale marker explicitly
sj validate-state <target> [--phase P] schema-check sprint-log.jsonl + per-phase required events
sj lane-check <target> <unit-file> safety tripwire before any Lane A pour
sj hooks install <target> optional pre-push hook enforcing the gate check
sj deps / sj version --check dependency-pin drift / plugin update notices
The gate evidence chain. A gate marker is a claim with provenance, not a touch file:
sj gate record appends reviewer events to sprint-log.jsonl and writes a marker citing
those event IDs, the reviewed git HEAD, and a timestamp. sj gate check verifies all
three — cited events exist in the log, the reviewed commit is an ancestor of HEAD, and no
EXECUTE-phase work postdates the review. A fabricated, stale, or imported marker fails.
Lane A pours additionally require a verified plan-vetted marker plus a CLEAR
sj lane-check verdict per unit (migrations, auth/payments/secrets, CI config, release
scripts, and ## Gate locations paths trip it).
Tested. A 44-test bats suite covers the gate chain end-to-end, scan fixtures
(including a stale-plugin decoy and a regex-metacharacter repo path), and state
validation; CI runs shellcheck + bats on ubuntu and macOS, including a no-jq fallback
pass. A contract test keeps references/adapter.md and adapter-scan.json in sync — the
prose can no longer drift from the implementation silently.
The 8-phase lifecycle
Full design: docs/specs/2026-06-04-smokejumper-framework-design.md
flowchart TD
R["RECON<br/>build repo model"] --> D["DECIDE<br/>highest-leverage move"]
D --> P{"PLAN<br/>adversarial gate"}
P -- BLOCK --> D
P -- PASS --> E["EXECUTE"]
E --> LA["Lane A<br/>async big pour"]
E --> LB["Lane B<br/>synchronous crew"]
LA --> RV["REVIEW"]
LB --> RV
RV --> I["INTEGRATE<br/>commit + push"]
I --> LL["LESSONS LEARNED"]
LL --> H["HANDOFF"]
LL -. write-back .-> RK[("target repo<br/>repo-knowledge.md")]
LL -. write-back .-> FW[("plugin repo<br/>VERSION + CHANGELOG")]
- RECON — Build a repo model: stack, conventions, gate locations, available tools, and any prior sprint knowledge from
.smokejumper/repo-knowledge.md. A deterministic adapter scan (sj scan) establishes the leads (visible banner + durable mapping), detects design skills + design-system candidates, derivesfunctionalHealth→designPosture, and a product-context bootstrap establishes a PRODUCT_PILOT-style brief — creating one on a brand-new repo where none exists. - DECIDE — The established leads choose the highest-leverage next move, reading the product-context artifact from RECON as authoritative. When
designPostureisWEIGHTED, design-debt and polish objectives rank higher. No fixed pipeline; they assess the actual state of the product and pick. - PLAN (front-loaded adversarial gate) — Design + implementation plan produced, then put through the full adversarial review. PASS here authorizes execution — including any autonomous pour — and is recorded as an evidence-backed
plan-vettedmarker (sj gate record). Bad assumptions and unsafe decompositions are caught here, before hours of coding. - EXECUTE (two lanes)
- Lane A — big pour (async, hours→days): For large, decomposable, non-safety-critical work. Spec converted into a bead molecule; Codex runs each child at
model_reasoning_effort=highwith per-child mechanical gates (tests, build, lint, coverage). Launched asnohup ./ralph.sh &loops that grind autonomously and survive context resets. - Lane B — synchronous crew (in-session): For novel, architectural, design-sensitive, or safety-critical units. Engineering Lead dispatches Claude + Codex directly through the full adversarial flow to merged+pushed.
- Lane A — big pour (async, hours→days): For large, decomposable, non-safety-critical work. Spec converted into a bead molecule; Codex runs each child at
- REVIEW — Lane B gets full adversarial review before push, recorded via
sj gate record adversarial-reviewand verified bysj gate checkbefore any push. Lane A children have per-child mechanical gates baked into the formula; milestone spot-checks sample the autonomous batch. - INTEGRATE — Commit and push. Merging ≠ deploying; releases need explicit human greenlight.
- LESSONS LEARNED (dual write-back) — Learnings flow into two places: (a)
<target>/.smokejumper/repo-knowledge.mdcommitted to the target repo — including design-skill effectiveness scored into the## Design skillstally; (b) if a portable improvement was found, a versioned commit to this plugin repo with aCHANGELOG.mdentry. - HANDOFF — Clean handoff prompt so the next session resumes with zero lost context. When Lane A loops are still running, the handoff carries them explicitly.
Portability contract
SmokeJumper hard-requires only: a git repo, and the bundled agents, skill, and scripts. It runs best under the Claude Code runtime (subagent dispatch + skills) but degrades gracefully to inline persona adoption under any other orchestrator — including a Codex agent driving the sprint (see Running under a Codex orchestrator). Everything else is detected and adapted to.
| Target condition | Behavior |
|---|---|
| Has project-specific leads | Adapter prefers them; bundled generics stand down |
| No project leads | Bundled smokejumper-{engineering,product,design}-lead run |
| Codex (or non-Claude) orchestrator | Inline-adoption mode — leads/reviewers adopted by reading their definition files; embedded references used directly |
| No product context layer | RECON bootstraps a PRODUCT_PILOT-style brief before DECIDE |
| Product context layer present | RECON reads it; LESSONS LEARNED updates it |
| Design system present in repo | Design lead finds it, records the durable ## Design system model; never invents tokens |
| Design skills installed (gstack, frontend-design, …) | Detected → adapter.skills.design.*; invoked via Skill tool (Claude) or inline SKILL.md (Codex); effectiveness learned over sprints |
| Functional health HEALTHY vs. POOR/FAIR | designPosture WEIGHTED vs. ADVISORY — design-debt prioritized in DECIDE accordingly (recoverable, windowed) |
choo-choo-ralph installed | Lane A (big pour) available |
choo-choo-ralph absent | choo-choo-ralph:install offered; else Lane-B-only; gap logged |
| Issue tracker present (beads, etc.) | Used for durable state |
| No issue tracker | State lives in <target>/.smokejumper/ only |
| Missing specialist agent | Self-heal: authored into <target>/.claude/agents/ + gap logged |
Has CLAUDE.md / AGENTS.md | RECON honors its rules as defaults (model floor, git discipline, gates) |
Any work unit marked safety-critical by the target repo's guardian convention is barred from Lane A regardless of how cleanly it decomposes.
Dependencies
SmokeJumper is a thin orchestration layer — it composes other projects rather than
reimplementing them. The set is declared in skills/smokejumper/references/dependencies.json
(explained in dependencies.md), so it's explicit, trackable, and easy to extend.
| Dependency | Role | Status |
|---|---|---|
| choo-choo-ralph | Lane A async "big pour" engine | optional backend |
| metaswarm | optional adversarial-gate backend (cross-model gates, PR shepherd) | optional backend |
| bugsweep | optional deep bug-hunt (Hunter→Skeptic→Referee) in REVIEW | optional backend |
| product-pilot | product-context layer | vendored (embedded, re-synced from upstream) |
| handoff-prompt-skill | Phase 8 handoff | optional (built-in fallback) |
Beads (bd) · Codex CLI · gh | tracker / exec / tracker-fallback | optional, adapter-detected |
Only git and one of Claude Code or Codex are hard-required; every dependency above degrades gracefully when absent (it never blocks a sprint).
Staying current — pin → notify → opt-in (never silent auto-pull). Each dependency carries
a tested pin. At sprint start, scripts/sj deps notifies (fail-silent,
time-boxed) when an upstream has moved past its pin; sj deps --update bumps the
pins on demand and prints the upgrade commands. A scheduled GitHub Action
(.github/workflows/dependency-scan.yml) runs the same check in this repo and opens an issue
when an upstream moves — so the plugin stays current without touching anyone's sprint.
Adding a new dependency is one JSON entry (dependencies.md documents the schema).
How it self-improves
Every sprint produces two write-backs:
Per-repo (committed to the target): RECON loads .smokejumper/repo-knowledge.md on arrival; LESSONS LEARNED enriches it on departure — accumulating stack facts, known traps, gate locations, what worked and what to avoid. This file is append-only in its history sections and survives every context reset.
Framework (committed here): When a sprint surfaces a portable improvement — a better recon heuristic, a lifecycle fix, a gap worth bundling into the plugin — the orchestrator makes a versioned commit to this repo: VERSION and plugin.json bumped per SemVer, a CHANGELOG.md entry naming the deployment. claude plugin tag cuts the release. One deployment, one version increment: the crew gets sharper every drop.
Repo layout
.claude-plugin/
plugin.json # plugin manifest
marketplace.json # local marketplace entry (source: "./")
agents/
smokejumper-engineering-lead.md
smokejumper-product-lead.md
smokejumper-design-lead.md
skills/smokejumper/
SKILL.md # 8-phase orchestrator (the /smokejumper entry point)
references/ # runtime, recon, adapter, product-context, dependencies, gated-pour, self-healing, schema, lessons-learned
references/dependencies.json # declared dependency manifest (single source of truth)
agents/openai.yaml # Codex skill-discovery metadata
templates/
product-context.md # embedded PRODUCT_PILOT-style brief (no external skill needed)
schemas/ # JSON Schemas for sprint-log.jsonl + gaps.jsonl
scripts/
sj # the SmokeJumper CLI: init | scan | deps | version | gate | validate-state | lane-check | hooks
lib/ # shared shell lib (atomic writes, locking, JSON, events) + subcommand impls
sj-adapter-scan.sh # `sj scan` implementation: lead/gate/capability scan → adapter-scan.json + banner + events
sj-version-check.sh # `sj version --check` implementation
sj-deps-check.sh # `sj deps` implementation (--update to bump pins)
sj-init.sh # DEPRECATED shim → `sj init`
tests/ # bats suite (gate evidence chain, scan contract, state validation)
.github/workflows/
ci.yml # shellcheck + bats on ubuntu/macos (incl. no-jq fallback pass)
dependency-scan.yml # scheduled upstream-drift scan → opens an issue
docs/specs/ # design spec
CHANGELOG.md
VERSION
Contributing
See CONTRIBUTING.md — validate with claude plugin validate ., bump
VERSION + plugin.json together per SemVer, and record changes in CHANGELOG.md.
License
MIT © Shane Hamilton