convez.ai
MCP ServerDevOps & InfraestruturaAvançado
5uck1ess

Devkit — Motor de Workflows para Agentes IA

5uck1ess/devkit

Workflow engine MCP determinístico com multi-agente consensus para Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Um servidor MCP (Model Context Protocol) que funciona como harness determinístico para agentes de IA, fornecendo controle de execução de workflows via YAML, enforcement hooks e consenso multi-agente entre Claude, Codex e Gemini. Ideal para automação de desenvolvimento com auditoria completa de passos e resultados mensuráveis.

Instalação

$npx convez-ai 5uck1ess/devkit

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
4
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
v2.1.54
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automação de pipelines de desenvolvimento com ordem determinística
  • Consenso multi-agente entre Claude, Codex e Gemini para revisão paralela
  • Auditoria e rastreamento completo de execução de tarefas de desenvolvimento

Veredito

Solução robusta e madura para orquestração de workflows de IA com controle determinístico. Requer conhecimento técnico sólido mas oferece auditoria e repetibilidade raro em ferramentas de agentes.

README

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

Devkit

A deterministic development harness for AI agents. The MCP engine controls workflow execution (step ordering, gates, loops, branches). The agent handles creativity. Every step is tracked, measured, and auditable.

Works with Claude Code as the original full-enforcement host. Other host adapters can use the same MCP engine and workflows by registering bin/devkit mcp; the Codex adapter is distributed separately by devkit-codex. Optionally adds Codex and Gemini for multi-agent consensus.


Install

Claude Code

1. Devkit (required)

/plugin marketplace add 5uck1ess/marketplace
/plugin install devkit@5uck1ess-plugins

Auto-updates are enabled by default. Devkit updates itself when you restart Claude Code.

2. Multi-agent plugins (optional)

These enable tri:* commands (tri-review, tri-debug, tri-security, etc.) to run Claude + Codex + Gemini in parallel.

# Codex plugin
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex

# Gemini plugin
/plugin marketplace add abiswas97/gemini-plugin-cc
/plugin install gemini@abiswas97-gemini

If plugins aren't installed, the CLI fallbacks work too:

brew install codex gemini-cli

3. Companion plugins (optional)

These handle concerns devkit doesn't — methodology, specialized reviews, and context management. No overlap.

# Methodology — brainstorming, planning, TDD, verification, debugging
/plugin install superpowers@claude-plugins-official

# Specialized review agents — comment accuracy, type design, silent failures
/plugin install pr-review-toolkit@claude-plugins-official

# Deep feature exploration — parallel codebase analysis, architecture proposals
/plugin install feature-dev@claude-plugins-official

# Quick commits — /commit, /commit-push-pr, /clean_gone
/plugin install commit-commands@claude-plugins-official

# Hook creation — markdown rules, hot reload, conversation analysis
/plugin install hookify@claude-plugins-official

# Skill development — eval/benchmark framework, blind A/B testing
/plugin install skill-creator@claude-plugins-official

# Context window management — sandboxes large outputs, 98% token savings
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Codex

Codex support lives in the separate devkit-codex adapter. That adapter installs Codex-specific hooks/config and points Codex at this repo's MCP server (bin/devkit mcp). This repo remains the core workflow engine and shared workflow/skill source of truth.

Manual MCP registration shape for host adapters:

[mcp_servers.devkit]
command = "/absolute/path/to/devkit/bin/devkit"
args = ["mcp"]

Optional tools

brew install rtk       # Token optimization (60-90% savings on Bash output)
brew install ast-grep  # AST-based repo mapping (used by onboard skill)

# Browser automation — enables scrape (JS-rendered), screenshot, and browser skills
npx playwright install chromium

Playwright (optional) enables three skills: enhanced scrape for JS-heavy sites, screenshot for page captures, and browser for full automation (clicking, form filling, multi-step flows, codegen). Free and local — no API keys. Install only the browsers you need (chromium is ~170MB).

Verify

/health

This shows which CLIs are installed, which agents are available, and which commands are ready.


Quick Start

# These activate automatically — just ask naturally:
# "write tests for src/parser.ts"
# "generate a changelog"
# "help me understand this codebase"
# "research the best auth library for Node"

# Slash commands for complex workflows:
/tri-review                   # Multi-agent code review
# Or just describe: "submit a PR", "ship this" → pr-ready skill auto-activates

Local models (optional)

devkit can dispatch fast-tier work (doc generation, changelogs, summarization, test stubs) to any OpenAI-compatible local inference server. Cloud tiers — Claude, Codex, Gemini — still handle tri-review, architecture planning, and security review.

Environment variables

VarDefaultPurpose
DEVKIT_LOCAL_ENABLEDunsetSet to 1 to enable
DEVKIT_LOCAL_ENDPOINThttp://localhost:11434/v1Base URL — must end in /v1
DEVKIT_LOCAL_MODELqwen3:32bModel name sent in the request payload
DEVKIT_LOCAL_API_KEYunsetBearer token, if endpoint requires auth
DEVKIT_LOCAL_TIMEOUT600Per-request timeout (seconds)
DEVKIT_LOCAL_DEBUGunsetSet to 1 to log probe failures to stderr

Default ports by stack

StackDefault portModel-name source
llama-server (llama.cpp)8080loaded via -m at launch
llama-swap8080names in llama-swap YAML
Ollama11434ollama list
LM Studio1234GUI-loaded model
vLLM8000--model flag at launch
SGLang30000--model-path at launch
LocalAI8080models directory

Port 8080 is the llama.cpp convention; llama-swap reuses it since it fronts llama-server processes.

Examples

Single model, no router (llama-server, LM Studio, vLLM, SGLang):

export DEVKIT_LOCAL_ENABLED=1
export DEVKIT_LOCAL_ENDPOINT=http://<host>:<port>/v1
export DEVKIT_LOCAL_MODEL=<model-loaded-at-launch>
devkit-engine probe-local

Multi-model via router (Ollama, llama-swap, LocalAI — LocalAI supports either mode depending on how it's configured):

export DEVKIT_LOCAL_ENABLED=1
export DEVKIT_LOCAL_ENDPOINT=http://<host>:<port>/v1
export DEVKIT_LOCAL_MODEL=<name-the-router-recognizes>
devkit-engine probe-local

Verifying the setup

devkit-engine probe-local calls $DEVKIT_LOCAL_ENDPOINT/models, reports reachability and latency, and checks whether your configured model is present in the server's model list. Exit 0 on healthy (or when the local runner is disabled), 1 otherwise. Add --json for structured output.

Limits

  • Fast tier only — local models have higher tool-call error rates than cloud tiers, so tri-review / architecture / security still go to the cloud.
  • No function-calling (plain /v1/chat/completions only).
  • No streaming.

How It Works

Devkit runs as an MCP server inside the host agent. Under Claude Code it is packaged as a plugin; other adapters register bin/devkit mcp through their host-specific MCP config. When a workflow starts, the engine takes control:

devkit_start("research", "best Go testing frameworks")
  → Engine creates session, returns Step 1 + condensed principles
  → Host agent executes the step using standard tools
  → Host agent calls devkit_advance(session_id)
  → Engine validates, records output, returns Step 2
  → ...repeat until WORKFLOW COMPLETE

Claude Code enforcement (runs automatically):
  PreToolUse hook → blocks out-of-step actions during command steps
  Stop hook → prevents session end during active workflows

External adapters:
  Register the same MCP server and provide host-specific hooks/guardrails.

Why MCP? The host agent can't skip steps because the engine controls what comes next. The engine holds state — the agent doesn't self-report workflow position. Claude Code additionally blocks invalid tools through hooks; other hosts can add equivalent adapter-side guardrails while still relying on engine-owned command steps.


Workflows

All 22 YAML workflows are invoked via the MCP engine. Every workflow has a trigger skill so natural-language keywords dispatch deterministically — saying "build a feature", "fix this bug", "tri review", or "deep research X" fires the matching skill, which calls devkit_start and the engine takes over.

Every workflow is also a tab-completable slash command. Bare names work (/feature, /bugfix, /tri-review, /health, /setup-rules); the fully-qualified /devkit:<name> form also works if you want to disambiguate from another plugin or a Claude Code built-in.

WorkflowWhat it does
featureBrainstorm, plan, implement, test, lint, review
bugfixReproduce, diagnose, fix, regression test, verify
refactorAnalyze smells, plan, restructure, verify nothing broke
researchClarify, decompose, parallel search, corroborate, synthesize
deep-researchACH: hypotheses, disconfirmation, evidence matrix
self-testRun tests, fix failures, repeat until passing
self-lintRun linter, fix violations, repeat until clean
self-perfBenchmark, optimize, repeat until target met
self-improveRun metric, fix issues, repeat until passing
self-migrateMigrate code incrementally with test gate
self-auditMeasure codebase, rank improvements by evidence
autoloopAutonomous audit/fix/measure/keep-or-revert loop
auditDependencies, vulnerabilities, licenses, lint, security
pr-readyFull PR preparation pipeline
tri-reviewMulti-agent code review
tri-debugMulti-agent debugging
tri-securityMulti-agent security audit
tri-dispatchSend any task to multiple agents
test-genGenerate tests via test-writer agent, iterate until passing
doc-genGenerate docs via documenter agent
onboardGenerate codebase onboarding guide via researcher agent

Skills

Skills activate automatically based on context. No slash command needed. Every workflow has a matching trigger skill — saying the keyword dispatches to the engine which then enforces every step.

Workflow trigger skills (dispatch to engine-enforced workflows):

TriggerSkill → Workflow
"build a feature", "new feature X"feature
"fix this bug", "this is broken"bugfix
"refactor this", "clean up X"refactor
"audit this project", "project health"audit
"research X"research
"deep research", "validate this"deep-research
"make a PR", "ship this", "create a pull request"pr-ready
"tri review", "triple review"tri-review
"tri debug", "triple debug"tri-debug
"tri security", "triple security audit"tri-security
"tri dispatch", "send to three models"tri-dispatch
"self-audit", "audit the codebase"self-audit
"self-improve", "keep fixing until X passes"self-improve
"self-lint", "fix all lint"self-lint
"self-migrate", "migrate incrementally"self-migrate
"self-perf", "optimize performance"self-perf
"self-test", "fix failing tests"self-test
"autoloop", "run experiments overnight"autoloop
"write tests for X"test-gen
"document this module"doc-gen
"onboard to this codebase"onboard

Other skills (tools, meta-orchestration, content):

TriggerSkill
"generate a changelog"changelog
"create an ADR"adr
"mega PR review"mega-pr (dispatches tri-review + pr-review-toolkit in parallel)
"scrape this URL"scrape
"screenshot this page"screenshot (requires Playwright)
"automate this browser flow"browser (requires Playwright)
Google Workspace CLI commandsgcli

Coding principles (clean-code, dry, yagni, dont-reinvent, executing, stuck, scratchpad) are injected as condensed rules (~120 tokens) per workflow step — not loaded as full skill files.


Hooks

12 hooks across 4 lifecycle events. All installed automatically with the plugin.

EventHookWhat it catches
PreToolUsesafety-checkrm -rf /, DROP TABLE, force push, editing secrets
PreToolUsesecurity-patternseval(), XSS, shell injection, weak hashes, hardcoded secrets
PreToolUseaudit-trailLogs every command to .devkit/audit.log
PreToolUsepr-gatePrompts to run the pr-ready skill before gh pr create
PreToolUsertk-rewriteCompresses Bash output via RTK (no-op if not installed)
PreToolUsedevkit-guardBlocks out-of-step tools during workflow command AND prompt steps (hard enforce); soft enforce emits a reminder. Skills are intentionally unguarded.
PostToolUsepost-validateSuppressed errors, leaked secrets, writes outside repo
PostToolUseslop-detectAI code patterns — doc/code imbalance, restating comments
PostToolUselang-reviewLanguage-aware checks: Go, TypeScript, Rust, Python, Shell
SubagentStopsubagent-stopVerifies subagent work before accepting
Stopstop-gateMerge conflicts, cross-domain test gaps, linter pass
Stopdevkit-stop-guardBlocks session end during active workflows

Agents

AgentModelUsed by
reviewerOpustri-review workflow, feature workflow
researcherSonnetresearch, deep-research, tri-debug workflows
improverOpusself-improve, self-lint, self-perf, refactor workflows
test-writerSonnetself-test, tri-test-gen workflows
documenterHaikudoc-gen skill
security-auditorOpustri-security, pr-ready, audit workflows

All agents run in worktree isolation.


Coding Rules

Language-specific rules that auto-activate when Claude reads matching files. Installed to ~/.claude/rules/ — rules guide how to write, hooks catch what you missed. Other host adapters should load the matching files from resources/rules/.

/setup-rules
LanguageExamples
CommonCross-platform paths, assumption-surfacing, error messages, temp dirs
GoError wrapping, context.Context, defer traps, JSON float64 gotcha
TypeScriptunknown not any, discriminated unions, catch narrowing
PythonException chains, type hints, dataclasses, pathlib
RustOwnership, ? propagation, newtypes, clippy-as-errors
Shellset -euo pipefail, quoting, macOS portability
JavaOptional, records, try-with-resources, BigDecimal for money
Kotlinval default, sealed classes, coroutines, Elvis operator
Swiftguard let, struct-first, async/await, weak self
C#Records, pattern matching, async Task, Path.Combine

Architecture

MCP Server (bin/devkit mcp — auto-started by plugin)
  ├── bin/devkit = POSIX shell wrapper (committed to git)
  │   └── On first run, downloads matching release asset from GitHub,
  │       verifies SHA256, caches as bin/devkit-engine-v<ver>-<os>-<arch>,
  │       then execs it. Local dev builds (make install-plugin) are used
  │       directly via the fast path.
  ├── Tools: devkit_start, devkit_advance, devkit_status, devkit_list
  ├── State: session.json (hot, <50ms reads) + SQLite (cold history)
  ├── Parse YAML → validate steps, branches, budget
  ├── Walk steps:
  │   ├── Command steps → engine executes shell directly ($0 cost)
  │   │   Values passed via $DEVKIT_INPUT / $DEVKIT_OUT_<step_id>
  │   │   env vars — never interpolated into the command string.
  │   ├── Prompt steps → host agent works, calls devkit_advance when done
  │   ├── Loop with gate → run, verify, keep or revert
  │   ├── Branch → case-insensitive word-boundary match → goto
  │   └── Parallel → host subagent/external runner dispatch
  └── Principles injected per step (~120 tokens, not full skill files)

Enforcement:
  ├── MCP state — host agent can only progress by calling devkit_advance
  ├── Claude Code: PreToolUse hook exits 2 to block invalid tools
  ├── Claude Code: Stop hook blocks session end during active workflows
  └── External adapters: host-specific hooks/proxies enforce what their host exposes

Terminal usage (devkit workflow <name> "<description>"):
  ├── Subprocess runners for Codex/Gemini CLI
  └── In-process HTTP runner for Ollama/llama-server/vLLM (opt-in via DEVKIT_LOCAL_ENABLED=1)

Repository Structure

devkit/
├── commands/          # Legacy (references/ only); new entry points go in skills/
├── skills/            # 39 skills (workflow triggers, principles, tools, utilities) + _principles.yml
├── agents/            # 6 agents (reviewer, researcher, improver, ...)
├── hooks/             # 12 hooks (safety, security, quality gates, workflow enforcement)
├── workflows/         # 22 YAML workflow definitions
├── resources/rules/   # Language-specific coding rules
├── src/               # Go engine + MCP server
│   ├── mcp/           # MCP server (tools, principles loader, session management)
│   ├── engine/        # YAML workflow engine (parser, executor, tests)
│   ├── runners/       # Claude/Codex/Gemini CLI interfaces + local HTTP runner (Ollama-compat, opt-in)
│   ├── lib/           # DB, git, metrics, session state, reporting
│   └── cmd/           # CLI entry points (including `devkit mcp`)
├── bin/               # devkit wrapper (committed) + downloaded engine binaries (gitignored)
└── .github/workflows/ # CI (build+test+vet) + auto-release (6 platforms)

Support

If devkit saved you time:

Ver o original no GitHub

Bom para

Relacionados