convez.ai
AgenteAutomaçãoAvançado
shanemhamilton

SmokeJumper

shanemhamilton/smokejumper

Crew autônomo de product dev que executa sprints completos e autoavalia

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent 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/smokejumper

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
smokejumper--v1.0.0
Issues abertas
1
Contribuidores
1

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/*.md persona and acts as that role for the phase. RECON runs scripts/sj scan, which resolves the leads, writes the mapping into repo-knowledge.md + adapter-scan.json, and prints a "Leads established" banner — so lead establishment is a visible, durable artifact, not an implicit step.
  • The sj CLI 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.md with no dependency on any external skill.
  • anthropic-skills:handoff-prompt unavailable → Phase 8 writes <target>/.smokejumper/HANDOFF.md directly.
  • choo-choo-ralph / bd absent → 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")]
  1. 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, derives functionalHealth → designPosture, and a product-context bootstrap establishes a PRODUCT_PILOT-style brief — creating one on a brand-new repo where none exists.
  2. DECIDE — The established leads choose the highest-leverage next move, reading the product-context artifact from RECON as authoritative. When designPosture is WEIGHTED, design-debt and polish objectives rank higher. No fixed pipeline; they assess the actual state of the product and pick.
  3. 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-vetted marker (sj gate record). Bad assumptions and unsafe decompositions are caught here, before hours of coding.
  4. 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=high with per-child mechanical gates (tests, build, lint, coverage). Launched as nohup ./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.
  5. REVIEW — Lane B gets full adversarial review before push, recorded via sj gate record adversarial-review and verified by sj gate check before any push. Lane A children have per-child mechanical gates baked into the formula; milestone spot-checks sample the autonomous batch.
  6. INTEGRATE — Commit and push. Merging ≠ deploying; releases need explicit human greenlight.
  7. LESSONS LEARNED (dual write-back) — Learnings flow into two places: (a) <target>/.smokejumper/repo-knowledge.md committed to the target repo — including design-skill effectiveness scored into the ## Design skills tally; (b) if a portable improvement was found, a versioned commit to this plugin repo with a CHANGELOG.md entry.
  8. 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 conditionBehavior
Has project-specific leadsAdapter prefers them; bundled generics stand down
No project leadsBundled smokejumper-{engineering,product,design}-lead run
Codex (or non-Claude) orchestratorInline-adoption mode — leads/reviewers adopted by reading their definition files; embedded references used directly
No product context layerRECON bootstraps a PRODUCT_PILOT-style brief before DECIDE
Product context layer presentRECON reads it; LESSONS LEARNED updates it
Design system present in repoDesign 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/FAIRdesignPosture WEIGHTED vs. ADVISORY — design-debt prioritized in DECIDE accordingly (recoverable, windowed)
choo-choo-ralph installedLane A (big pour) available
choo-choo-ralph absentchoo-choo-ralph:install offered; else Lane-B-only; gap logged
Issue tracker present (beads, etc.)Used for durable state
No issue trackerState lives in <target>/.smokejumper/ only
Missing specialist agentSelf-heal: authored into <target>/.claude/agents/ + gap logged
Has CLAUDE.md / AGENTS.mdRECON 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.

DependencyRoleStatus
choo-choo-ralphLane A async "big pour" engineoptional backend
metaswarmoptional adversarial-gate backend (cross-model gates, PR shepherd)optional backend
bugsweepoptional deep bug-hunt (Hunter→Skeptic→Referee) in REVIEWoptional backend
product-pilotproduct-context layervendored (embedded, re-synced from upstream)
handoff-prompt-skillPhase 8 handoffoptional (built-in fallback)
Beads (bd) · Codex CLI · ghtracker / exec / tracker-fallbackoptional, 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

Ver o original no GitHub

Bom para

Relacionados