🇧🇷 Versão em Português · 🌎 English version

A complete team of software specialists inside your coding agent.
Every task is routed to the right specialist, run on the right model, and shipped at production quality.

How to use: see docs/quickstart.md for the 4 common scenarios (CLI image generation, swarm with automatic generation, template bootstrap, runtime adapter).

Every skill, subagent, command, policy, plugin and MCP tool documented — in the format of aihero.dev's "5 Agent Skills I Use Every Day".

We tested every skill and subagent with a published rubric. 53 isolation scenarios + 3 end-to-end tests. Same model, same prompt — with and without the kit. Numbers are measured, code is real, results are auditable.

Includes before/after with full output text, per-skill delta scores, process-based test results, and v2.10.1 fix verification. Methodology in eval-bench/.

If you use AI to build product — whether you're an experienced dev, an indie hacker shipping SaaS, or someone who only knows how to describe what they want — this kit changes the game. In plain language, here's what it does:

AI loves to read everything: the entire output of an npm install, repeated stack traces, huge file lists. All of that turns into tokens, which turn into money. The kit automatically compresses that noise before sending it to the model — you only pay for what matters.

Instead of a generic agent that "guesses" the implementation, the kit has an orchestrator that reads your request, classifies the complexity, and assembles the minimum sufficient pipeline. If you're vague, it asks. If you're clear, it runs. It never makes things up.

Most agents forget everything when you close the window. This one remembers: what you decided, which files matter, the patterns your project follows, the bugs that came up before. Result: less rework, fewer tokens spent re-contextualizing, and far sharper answers each session.

Hand off a complex task with /auto or /loop and go grab a coffee. The agent runs, tests, fixes, validates and only stops when it's ready, working and tested. There's a safety circuit: if it gets stuck on the same error 3 times, it detects and warns — no burning API for nothing.

Landing page with a gray "image here" box? Never again. The kit integrates fal.ai with prompts written by a generative-AI specialist — you describe the scene, the system translates it into a technical prompt, and delivers production-ready images. Illustrations, hero images, icons, mockups, all consistent with your brand.

A security auditor thinks like an attacker and reviews the code before it reaches production. Critical findings come with a proof of concept. No more discovering vulnerabilities on the customer's account.

A QA engineer that follows the "prove-it" principle: if you say it works, prove it with a test. No "looks ok". Covers happy path, failure paths, edge cases and regressions.

• Designer with competitive analysis: looks at competitors and recommends what converts
• Copywriter specialized in marketing: ready-to-ship copy for landing pages, email, ads
• SEO that optimizes before Google indexes — your site is born findable

Backend, frontend, mobile (Tauri), observability, analytics, accessibility (WCAG), refactoring, release, canary deployments (v2.12+), documentation — 48 specialists in total (numeric IDs run 01–48; ID 16 was deprecated and the number is reserved, so 47 physical skill files). Each task goes to the right professional, on the right AI model (Haiku for simple, Sonnet for medium, Opus for architecture) — you don't pay Opus to generate boilerplate.

Native Claude Code plugin + universal MCP server that runs in Cursor, Windsurf, Copilot, Gemini CLI and any MCP-compatible agent. Zero vendor lock-in. Switched tools? Your team comes with you.

No subscription. No trial. No hidden premium tier. Clone it, install it, use it forever — including in commercial projects. Apache-2.0 with a NOTICE file enforces attribution downstream: anyone repackaging the kit must preserve credit to the people whose ideas shaped it.

The Dev Team Kit is a set of 48 specialized skills that turns any compatible coding agent into a complete development team — with orchestrator, backend, frontend, QA, security, deploy, design, copy, SEO, observability, blog publishing automation and more.

What you get:

• Structured pipeline — every task goes through the right steps, in the right order, no improvising
• QA, Security and Reviewer mandatory — no delivery ships without validation
• Automatic model routing — haiku for boilerplate, sonnet for implementation, opus for architecture
• Lifecycle hooks — the agent detects vague context, re-reads files before editing, monitors token cost
• Built-in MCP server — 37 tools exposed for any MCP client
• Persistent memory — working set, context pack, learned skills with confidence scoring accumulated per project
• Multi-platform install — Claude Code, Cursor, Windsurf, Copilot, Gemini CLI and more

The kit's architecture maps to the context engineering hierarchy: individual skills are atoms, templates are molecules, learned-skills + working-set are cells, dispatched subagents are organs, and protocol-shell-composed programs are the emergent field layer. New in v1.1: typed protocol shells for 3 pilot subagents, I/O schemas in schemas/skill-io/, iteration scoring in the auto-loop circuit breaker, and declarative programs/ definitions. See docs/WIKI.md → Context Engineering Stack.

5-min tour: docs/SKILLS-OVERVIEW.md — every skill, mode, subagent and policy in one navigable page (aihero.dev format).

Installs the 50 skills and hooks globally. Works in any project with no extra configuration.

# Via Claude Code CLI
claude plugin install https://github.com/felvieira/claude-skills-fv

What gets installed globally: skills, hooks, commands (/audit-repo, /devkit-install-fv, /plan-feature, /review-release, /inventory-assets).

With the plugin installed, run inside the repo you want to configure:

/devkit-install-fv

This installs the full .bot/: MCP server, policies, templates, docs, hooks, learned-skills and multi-platform configs.

git clone https://github.com/felvieira/claude-skills-fv /tmp/dev-team-kit
bash /tmp/dev-team-kit/setup/install.sh /path/to/project

If the kit is already in .bot/, you can also run directly from the installed repo:

bash .bot/setup/install.sh

The installer ships setup/ and every kit directory under .bot/. Supports non-interactive profile flags:

• --profile lean — installs without MCP and heavy scripts
• --no-input — no prompts, uses defaults
• --yes — accepts everything automatically

In the table below, treat dev-team-kit as 37 tools backed by the 50 skills. The MCP exposes 37 tools backed by the installed skills.

For platforms without native hooks, the same rules live in policies/hooks.md — the agent applies them manually.

Setup (one-time per user):

# Create your blog repo + GitHub Pages + config
node scripts/init-blog-repo.mjs \
  --path=/abs/path/to/blog \
  --user=<github-username> \
  --repo=blog \
  --create-github

# Then in any Claude Code session:
# "publica um post sobre <topic>"  → skill 41 takes it from there

The init script creates ~/.dev-team-kit/blog-config.json so the skill knows where to publish. See scripts/init-blog-repo.mjs and templates/blog/ for details.

flowchart LR
    A[Task] --> B[Orchestrator 09]
    B --> C[Context Manager 08]
    B --> D[Minimum sufficient pipeline]
    D --> E[Specialists 01–48]
    E --> F[QA 05 + Security 06 + Reviewer 11]
    F --> G[Deploy 07 or Release 24]
    B --> H[Model routing per step]

Automatic enforcement (Claude Code):

• EnterPlanMode → hook suggests /model opus
• ExitPlanMode → hook suggests /model sonnet
• Subagent without explicit model → hook warns and suggests tier by keywords

On other environments: follow policies/model-routing.md manually.

27 hook scripts total in hooks/scripts/ — the table above lists the user-facing ones. Toggle any via DEVKIT_DISABLED_HOOKS or the minimal profile.

Controlled by the env variable DEVKIT_HOOK_PROFILE (default: standard):

• DEVKIT_HOOK_PROFILE — sets the active profile (minimal, standard or strict)
• DEVKIT_DISABLED_HOOKS — comma-separated list of hookIds to disable regardless of profile

The context-guard-stop hook operates on two levels:

• 50% — non-blocking warning: suggests /compact while there's still margin
• 75% — smart block: shows current task hint, files edited in the session and decisions from the working set before blocking

The kit ships 16 Claude Code subagents in .claude/agents/, ready to dispatch with the Task tool or invoke from the prompt.

Invocation example:

Dispatch the code-reviewer subagent to review changes in src/auth/login.ts

Use the debugger subagent to investigate the crash TypeError: Cannot read properties of undefined in api/users.ts

Subagents are copied to the consuming repo's .claude/agents/ by install.sh. See docs/skill-guides/subagents.md for the full guide on when to use each.

{
  "mcpServers": {
    "dev-team-kit": {
      "command": "node",
      "args": [".bot/mcp-server/dist/index.js"],
      "env": {
        "FAL_KEY": "fal-...",
        "BRAVE_SEARCH_KEY": "BSA...",
        "FIRECRAWL_KEY": "fc-..."
      }
    }
  }
}

Works in Claude Code, Windsurf, Gemini CLI, Cursor and any MCP client.

See mcp-server/README.md for full tool documentation.

The installer prompts for each key and saves them in the project's .env.local.

• read docs/quickstart.md to get into the flow fast
• reuse docs/repo-audit/current.md before exploring the repo
• use devkit_context_pack to start a task without re-reading half the repo
• use devkit_diff_brief to resume work or prep a review
• use devkit_working_set to persist hot files and next steps
• use commands/ as operational shortcuts
• consult docs/skill-call-matrix.md when there's overlap between skills
• consult docs/skill-guides/ only on demand
• consult docs/skill-guides/ideation-frameworks.md — SCAMPER, HMW, First Principles, JTBD for the ideation phase
• consult docs/skill-guides/skill-discovery.md — decision tree to pick the right skill per task type
• consult docs/skill-guides/context-engineering.md — context hierarchy, trust levels and packing strategies
• consult docs/skill-guides/autonomous-loop.md — /auto protocol for autonomous execution

scripts/auto-loop/ is an autonomous orchestrator that ships tasks ready, working, polished and tested. Run it overnight, wake up to a PR ready to merge.

# Basic usage (single run, claude agent)
node scripts/auto-loop "your task here"

# Pick the agent
node scripts/auto-loop "task" --agent codex
node scripts/auto-loop "task" --agent claude

# Isolated worktree + parallel (3 tasks in 3 worktrees)
node scripts/auto-loop --worktree --parallel 3 -- "task A" -- "task B" -- "task C"

# Configurable polishing pass (default: standard)
node scripts/auto-loop "task" --polish=full

# Fine-grained control
node scripts/auto-loop "task" --max-tokens 200000 --stop-when "tests cover the new endpoint"

v2 features:

Circuit breaker: same error 3x, stall (3 iterations without git diff), budget exhausted, or task blocked — stops automatically.

Exit codes: 0 ok / 1 usage / 2 permanent error / 3 retryable exhausted / 4 breaker tripped / 5 stall / 6 token cap / 7 polish incomplete / 130 interrupted / 99 fatal.

Production-ready:

• 21 smoke tests under scripts/tests/auto-loop/, all green. Run: node scripts/tests/auto-loop/run-all.mjs.
• Cross-platform (macOS, Linux, Windows) — adapters spawn through the shell on Windows so npm-installed .cmd launchers resolve.
• Each run writes .auto/runs/<runId>/status.json with {iterations, commits, exitCode, worktreePath, ...} for parallel parents and external tooling to consume.
• Opt-in real-LLM smoke: node scripts/tests/auto-loop/smoke-real.mjs (manual, costs tokens).

What changed 2026-04-30 → 2026-05-01:

• Initial v2 release on 04-30: multi-agent (claude + codex), integrated worktree, parallel mode, polishing pass, gnhf-inspired flags (--max-tokens, --stop-when, prevent-sleep, JSONL log, classified backoff, 2-stage Ctrl+C, robust resume), bilingual docs.
• Gap fixes shipped 05-01: codex E2E test with fake CLI shim (zero tokens), polish skill-path verification + retry path test, runner+worktree integration test, status.json wired into parallel summary (was showing - placeholders), Windows portability fixes (gitDiffSinceBaseline no longer POSIX-only; adapters resolve .cmd/.bat launchers).
• Tests: 17 → 21, all passing. Commands and exit codes unchanged.

• GLOBAL.md is the highest instruction layer
• policies/ standardize execution, risk, persistence, quality and evaluation
• templates/ reduce variation in handoff, plan, review and rejection
• policies/tool-safety.md — safe usage of write, network, MCP and external actions
• policies/model-routing.md — model tiers, enforcement and integration with cost-tracker
• policies/evals.md — minimum evidence for structural changes to the kit
• policies/search-first.md — research mandatory before implementing (feature, bugfix, integration, refactor)
• policies/iterative-retrieval.md — progressive retrieval in 3 rounds for delegated subagents and skills
• policies/anti-rationalization.md — common rationalization tables + rebuttals per critical skill
• policies/source-driven.md — mandatory source hierarchy for framework/lib decisions
• policies/confusion-management.md — STOP-NAME-OPTIONS-WAIT protocol for detected confusion
• policies/context-engineering.md — 5-level context hierarchy and 3 trust levels

1. GLOBAL.md
2. policies/*.md
3. skills/*/SKILL.md
4. templates/*.md

.
├── .claude/              ← slash commands (/spec, /plan, /build, /test, /review, /simplify, /ship, /pipeline, /best, /auto, /loop)
│   └── commands/
├── .claude-plugin/       ← Claude Code plugin manifest
│   └── plugin.json
├── .github/              ← CI workflows (validate-plugin, validate)
│   └── workflows/
├── AGENTS.md
├── CLAUDE.md
├── GLOBAL.md
├── README.md
├── commands/             ← slash commands (/audit-repo, /devkit-install-fv, ...)
├── docs/
│   ├── quickstart.md
│   ├── repo-audit/
│   ├── skill-guides/
│   └── skill-call-matrix.md
├── evals/
├── hooks/                ← lifecycle hooks for Claude Code
│   ├── hooks.json
│   ├── config.json
│   └── scripts/
├── mcp-server/           ← MCP server with 37 tools
├── patterns/ai-integration/
├── personas/             ← agent personas (code-reviewer, security-auditor, test-engineer)
├── policies/             ← model-routing, tool-safety, cost-optimization, evals
├── scripts/              ← generate-image.py and utilities
├── setup/                ← multi-platform install.sh
├── skills/               ← 48 specialists (*/SKILL.md)
├── src/                  ← reusable hooks, stores, components and middleware
└── templates/            ← handoff, plan, review, rejection

When installed via /devkit-install-fv or setup/install.sh:

consumer-repo/
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── .claude/settings.json         ← hooks + MCP registered
├── .claude/commands/             ← slash commands (/spec, /plan, /build, /loop, ...)
├── .claude/agents/               ← subagents dispatchable via Task tool
├── .github/copilot-instructions.md
├── .windsurf/rules/dev-team-kit.md
├── .windsurf/mcp.json
├── .gemini/settings.json
└── .bot/
    ├── GLOBAL.md
    ├── commands/                 ← operational commands (/audit-repo, /devkit-install-fv, ...)
    ├── docs/                     ← skill-guides, repo-audit, quickstart
    ├── evals/
    ├── hooks/                    ← lifecycle hooks
    ├── learned-skills/           ← project-accumulated knowledge (score 0-1, weekly decay, auto-archived in .archive/ below 0.3)
    ├── mcp-server/               ← compiled and ready
    ├── patterns/ai-integration/
    ├── personas/                 ← code-reviewer, security-auditor, test-engineer
    ├── policies/
    ├── scripts/
    ├── setup/
    ├── skills/
    └── templates/

The consumer repo also receives .claude/commands/ (10 slash commands) at the root, installed by setup/install.sh.

pytest scripts/tests -q
node scripts/check-consistency.mjs
cd mcp-server && npm run build
bash scripts/smoke-install.sh

Want to add a skill, fix a bug or propose an improvement? See the full guide in CONTRIBUTING.md.

Quick summary:

1. Create the skill in skills/NN-name/SKILL.md and register it in plugin.json
2. For slash commands, add them to .claude/commands/ and register in plugin.json
3. Run node scripts/check-consistency.mjs before committing
4. Open a PR with an entry in CHANGELOG.md

Full release history in CHANGELOG.md.

The only command that takes you from prompt → PR mergeable without human intervention.

/swarm "implement social auth with Google + GitHub"

The kit:

1. Creates isolated git worktree
2. Generates PRD + breaks into stories
3. Ralph loop: implements each story with fresh context (no contamination)
4. 4 parallel review agents: code + security + tests + anti-AI-writing
5. Synthesizes findings with severity decision matrix
6. Self-fixes CRITICAL/HIGH automatically
7. Creates PR with synthesis as comment, rebased on main

You come back to a PR ready for review.

/swarm "implement feature X"           # free text
/swarm fix #142                        # GitHub issue
/swarm --prd docs/prd/auth.md          # existing PRD
/swarm --resume <run-id>               # continue stopped run

In ~/.claude/dev-team-kit-config.json set intent_classifier.autonomous: true:

• Hook detects feature intent → auto-suggests /swarm
• Claude auto-executes (no gates pause)
• You come back to a PR ready

Worktree NEVER deleted automatically. After PR merged:

git worktree remove .swarm/<run-id>/workspace
rm -rf .swarm/<run-id>

Full protocol: policies/swarm-protocol.md.

The kit detects intent from your prompt and suggests the appropriate program automatically — you don't have to remember to invoke /run-program manually.

You say: "I need to add social auth to the app"
   ↓
[intent-classifier hook]
   → detects feature pattern → emits: /run-program spec-driven-development
   ↓
[Claude] invokes skill 39 (program-router)
   → asks via AskUserQuestion: dry-run / direto / ad-hoc / cancelar
   ↓
You choose → program executes with human gates where defined

Active vs Autonomous — the key difference:

• Active = "show me the plan automatically, but pause at gates so I can approve them during execution"
• Autonomous = "execute everything without asking me anything"

The real difference is whether human gates during execution stay active.

// hook config (via /update-config or settings.json)
{
  "intent_classifier": {
    "enabled": true,         // false = Level 0 (manual)
    "auto_dry_run": true,    // DEFAULT v1.9.0+ — Level 2 Active
    "autonomous": false,     // true = Level 3 (autonomous, CI only)
    "suppress": []           // program ids to never suggest
  }
}

Edit ~/.claude/settings.json (Windows: C:\Users\<user>\.claude\settings.json), save, and restart Claude Code.

⚠ Zero human confirmations. Use only in non-interactive contexts (CI, scheduled tasks). Recomended: put this in user-wide config so the repo default stays Active (safer). File: ~/.claude/dev-team-kit-config.json

{
  "intent_classifier": {
    "enabled": true,
    "autonomous": true,
    "suppress": [
      "adversarial-dev",       // tem bash que mexe em $ARTIFACTS_DIR/app
      "comprehensive-review"   // postaria em PR sem revisão humana
    ]
  }
}

Pre-flight checklist before enabling Autonomous:

• Backup do repo / working tree limpa
• Programs perigosos no suppress list
• CI/cron tem timeout (ex: máx 30min)
• Logs persistentes em .run-program/*.log.json acessíveis para debug pós-mortem
• git push --force proibido (ver policies/tool-safety.md)
• Notification webhook em caso de falha

{
  "intent_classifier": {
    "enabled": false
  }
}

# bash/zsh — uma sessão só
export DEVKIT_INTENT_CLASSIFIER_AUTONOMOUS=true
claude

# powershell
$env:DEVKIT_INTENT_CLASSIFIER_AUTONOMOUS="true"; claude

Full reference: policies/auto-orchestration.md.

Skip auto: informational prompts ("o que é..."), trivial ("fix typo"), or already a /slash command.

This kit is the result of looking at a lot of prior art and re-implementing the ideas that fit our skill-kit model. Nothing here is copied code — each item below was reimagined as policy, skill, or zero-dep script in our own conventions. Links lead to the upstream projects that inspired each direction.

Full third-party attribution (license + scope) is in NOTICE, preserved per Apache-2.0 §4(d).

Every entry above is an idea-level inspiration. We do not bundle code from these projects; our implementations are independent and aligned with this kit's zero-runtime-dep, markdown-first conventions. When a project's approach didn't fit (LangGraph runtime, proxy servers, Python CLIs, etc.), we said so in NOTICE.

Licensed under the Apache License, Version 2.0. See LICENSE for the full text and NOTICE for the third-party attribution that must be preserved in any redistribution.

If you fork, repackage, or build on top of this kit: keep NOTICE intact. The people listed there shaped the patterns inside — attribution is the only thing the license asks of you.

🇧🇷 Leia em Português