convez.ai
AgenteDevOps & InfraestruturaAvançado
ddfeyes

DevFlow

ddfeyes/devflow

Epic → shipped em produção, hands-off com verificação cega e deploy gateado

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent autônomo que leva epics de uma linha de intenção até produção sem intervenção manual. Combina dois motores (Workflow dinâmico do Claude Code e Agent Teams) com verificação adversarial, gates de saúde e auto-rollback, mantendo sincronização entre local, GitHub e servidor.

Instalação

$npx convez-ai ddfeyes/devflow

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
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar pipeline completo desenvolvimento-review-merge-deploy
  • Implementar loops fechados com verificação adversarial e gates de saúde
  • Manter sincronização automática entre múltiplas cópias do código

Veredito

DevFlow é uma solução sofisticada para equipes que buscam automação end-to-end responsável em CI/CD, eliminando humanos de review/merge/deploy sem eliminar os gates — apenas deslocando-os para verificadores adversariais e sinais de saúde. Exige infraestrutura robusta e compreensão profunda de workflows multi-agent.

README

A tradução para o português deste README ainda está na fila.

devflow

Autonomous developer workflow for Claude Code: take an epic from a one-line intent to shipped in production, hands-off — with independent writer/verifier lanes, machine-checkable gates, and a resumable run journal.

/devflow <repo> "<epic>" → recon → plan → implement·test·integrate → blind verify → merge → health-gated deploy.

The one idea: two engines under one orchestrator

The heavy middle (implement/test/integrate) is stateful and git-heavy — that runs on Agent Teams + .coord/ (a proven multi-agent substrate). The stateless halves (parallel recon scouts, an adversarial verify panel) run on Claude Code's dynamic Workflow primitive, which is built for deterministic fan-out + schema-gated output. The /devflow command is the orchestrator that sequences both.

          /devflow  (orchestrator)
              │
 ┌──────┬─────┼───────────┬─────────┬────────┐
 ▼      ▼     ▼           ▼         ▼        ▼
RECON  PLAN  EXECUTE     VERIFY    MERGE    DEPLOY
Workflow agent Agent-Teams Workflow  gh    Deployer
scouts  +dial  .coord     blind     pr     health-gated
context        impl·test· panel     merge  + auto-rollback
packs          integrate  =merge gate
└── stateless ──┘└─ stateful ─┘└ stateless ┘└── orchestrator ──┘

Why review/merge/deploy are autonomous (and still safe)

Removing the human from review/merge/deploy does not remove the gate — it transfers the gate to the machine:

  • auto-review → a blind adversarial verify panel (≥2 verifiers + completeness critic + browser-runtime checks for web targets). Its unanimous PASS replaces the human reviewer. It can't be talked into green because it runs on a different engine, never sees the writer's reasoning, and re-runs everything from a clean worktree.
  • auto-merge → gh pr merge behind required-green-CI + branch protection. Reversible via revert.
  • auto-deploy → the only irreversible-in-a-window step, so it gets two safeguards (below).

Two safeguards

  • A — health-gated deploy + auto-rollback. A repo only auto-deploys if it exposes a machine-readable health/SLO signal + rollback hook. Deploy is always deploy → read live health → auto-promote OR auto-rollback. No health gate → the loop closes at merge for that repo.
  • B — irreversible-ops tripwire. These always halt for a human (drop/delete data, prod-destructive migration, rotate/read prod creds, disable a killswitch, force-push/history-rewrite). Automation must never do the unrecoverable.

Staying in sync (local ↔ GitHub ↔ server)

Closed-loop autonomy is pointless if the three copies of your code drift. devflow keeps them aligned without ever asking and without per-edit push (which would bypass secret-scanning and ship half-finished states):

  • pull is automatic, push is a scanned checkpoint. Add a SessionStart hook (below) that fast-forwards a clean tree from origin — so you always start work synced. Pushing happens at a checkpoint — /devsync or the end of every /devflow run — so the outgoing diff is always secret-scanned first.
  • /devsync (scripts/devsync.sh) does the full triangle for a repo: fetch → fast-forward/rebase local onto origin → secret-scan the outgoing diff (the exact commits being pushed — computed fail-closed, so a brand-new branch with no upstream is scanned too, not waved through) → push. It refuses on detached HEAD, mid-rebase, or a dirty divergence, and never leaves the repo half-synced. Generic secrets (private keys, AWS/GitHub/Slack/Google tokens, master-key assignments, 64-hex blobs) are blocked on any remote out of the box; your site identifiers (server IPs, SSH hosts, emails, home paths) are only caught once you add them to ~/.claude/devsync.public-deny.txt — on a fresh install that file is the empty template, so populate it before pushing site-specific repos public.
  • server leg is opt-in, never blind. Only repos listed in ~/.claude/devsync.targets (<repo> <ssh-host> <remote-path> <deploy-cmd>) get pulled + redeployed on their server. No line → git-only sync. This avoids the classic "hotfix lives in the container, never makes it back to git" drift — deploy from the merged SHA, always.

Why not auto-push on every edit? Because the secret scan can't be inlined into a per-edit hook, per-edit push ships broken intermediate states to main, and it races devflow's own branch/PR flow. The checkpoint is the right seam.

SessionStart auto-pull hook (add to ~/.claude/settings.json, safe — fetch always, fast-forward only a clean tree, never pushes):

"hooks": {
  "SessionStart": [{ "hooks": [{ "type": "command",
    "command": "if git rev-parse --git-dir >/dev/null 2>&1; then git fetch -q 2>/dev/null || true; if [ -z \"$(git status --porcelain 2>/dev/null)\" ]; then B=$(git rev-list --count HEAD..@{u} 2>/dev/null || echo 0); if [ \"$B\" -gt 0 ] 2>/dev/null; then git merge --ff-only -q @{u} 2>/dev/null && echo \"devsync: fast-forwarded $B commit(s) from origin\" || true; fi; fi; fi"
  }]}]
}

Modern capability bolt-ons

  • context7 MCP — implementers/verifiers ground API/SDK usage against live docs (kills stale-API hallucination).
  • chrome-devtools MCP — verify lane drives the real UI for web targets (console, network, lighthouse).
  • LSP — precise edits instead of grep-and-pray.
  • graphify + codebase-memory + codebase-search — retrieval-based per-task Context Packs instead of dumping the repo.

Layout

DEVFLOW.md            # the playbook — full source of truth (roles, phases, gates, safeguards)
commands/devflow.md   # the slash command — the orchestrator script
workflows/devflow.js  # the fan-out engine — modes: recon | verify (stateless only)
scripts/devsync.sh    # local↔GitHub↔server checkpoint sync (secret-scanned push)
commands/devsync.md   # the /devsync slash command
devsync.targets.example          # per-repo server deploy targets (copy to ~/.claude, gitignored)
devsync.public-deny.example.txt  # site identifiers that must never reach a public remote
selftest/gates.test.mjs  # proves the recon/verify gates fail correctly (run: node selftest/gates.test.mjs)
schemas/*.json        # machine-checkable contracts: acceptance, task, handoff, verdict, run_state
.devflow/quality.example.yml  # per-repo required/conditional CI checks + coverage policy
install.sh            # copy the core files into ~/.claude, seed devsync config, fix the engine path

Install

git clone <this repo> devflow && cd devflow
./install.sh          # copies into $HOME/.claude and rewrites the engine path

Or manually: copy DEVFLOW.md → ~/.claude/, commands/devflow.md → ~/.claude/commands/, workflows/devflow.js → ~/.claude/workflows/, then edit the scriptPath in the command to match your home.

Requires: Claude Code with the team-orchestrator skill, graphify, codebase-memory-mcp, and (optional but recommended) context7 + chrome-devtools MCP servers.

Usage

/devflow <repo> "<epic intent>"               # closed loop to production (default)
/devflow --supervised <repo> "<epic>"         # + one plan-approval checkpoint
/devflow --pr <repo> "<epic>"                 # stop at a ready PR (escape hatch)
/devflow --resume <runId>                      # resume a detached/interrupted run

First run should be a low-stakes repo with --supervised. Watch a rollback drill fire before trusting auto-deploy on anything that touches money.

Steer mid-run by editing .coord/runs/<runId>/control.json (pause/redirect/abort); honored at the next barrier. Results land in .coord/runs/<runId>/REPORT.md.

Known gotchas (from real runs)

  • The Workflow args global may not propagate into devflow.js in some harness versions → mode:recon sees an empty epic and falls back to a single epic-wide scout. Workaround: inline the run data into a self-contained copy of the script and invoke it via scriptPath, rather than relying on the args param.
  • The Plan agent type is read-only (no Write/Edit) — it emits packets inline; spawn a writable agent to persist .coord packets.

Hardening status & roadmap

The gates are not just prompt rules — the fan-out engine's two gates are strict and proven:

  • recon gate fails the run unless every expected scout returned a pack with real files (a missing/crashed scout no longer false-greens — it's reported in missing[]/empty[]).
  • verify gate requires the full expected vote count (N correctness + 1 completeness + runtime-if-web), exact lens coverage, every vote pass:true, and non-empty evidence on each — "unanimous" can't mean "unanimous among the survivors."
  • Parallel agents no longer share a journal/report file (per-agent event files, merged by the orchestrator) — no write races.

The contracts are enforced in code, not just specified (run via the selftests):

  • scripts/validate.mjs — AJV validation of any doc against schemas/*.json (a verdict with empty evidence, or a packet missing required acceptance, is rejected, exit 1).
  • scripts/run_state.mjs — canonical run-state source-of-truth with monotonic phase transitions and an epoch fence-token lock. save() is the single chokepoint: it re-checks transition-legality and epoch-freshness against the on-disk state before writing (atomic tmp+rename), so an illegal phase jump or a stale-epoch write cannot reach disk even if a caller bypasses the pure functions.
  • scripts/quality.mjs — runs .devflow/quality.yml (required + stack-conditional checks + coverage floor); a failing required check is exit 1, never swallowed.
  • failure taxonomy in the engine (PARTIAL_QUORUM | LENS_MISSING | EVIDENCE_MISSING | VERDICT_FAIL, MISSING_SCOUT | EMPTY_PACK) — additive, never weakens a gate.

Two selftests prove it and exit non-zero on regression (run after any change): selftest/gates.test.mjs (8 scenarios — loads the real engine in a vm sandbox: missing-scout, partial-quorum, empty-evidence, web-runtime, unknown-mode) and selftest/contracts.test.mjs (10 scenarios — incl. illegal-transition, stale-epoch, and the save() bypass being closed).

Done: strict P0 gates + selftests • AJV-enforced contract schemas • run_state source-of-truth with locks • quality.yml runner • failure taxonomy. Next (genuinely not built yet): a dedicated Wave Integrator role for semantic cross-task conflicts (lives in the team-orchestrator/execution layer, prompt-level today), and wiring run_state.json into the live orchestrator loop end-to-end. Treat those as the design target, not a guarantee.

Status

Validated on real end-to-end runs (greenfield builds and brownfield epics shipped to main): the blind verify panel has caught real blockers and majors that would otherwise have merged. Auto-deploy to high-stakes targets stays gated until a rollback drill is observed.

Ver o original no GitHub

Bom para

Relacionados