A structured pipeline of AI agents for shipping software — not just prompting an AI to write code, but engineering the process around it.
dev-agents is a Claude Code plugin: a sequential pipeline of 7 specialist subagents (research → story → spec → backend → frontend → tests → validation), with file-based handoff and mandatory human approval gates. It's not a product built with AI — it's a system for structuring how AI is used to build products.
| Item | Information |
|---|---|
| Status | Published Claude Code plugin |
| My role | Primary builder and methodology designer |
| Collaboration | Solo |
| Outcome | Installable seven-stage, human-gated AI build pipeline; already used to build two other projects in this portfolio |
| Stack | Claude Code plugin · 7 specialist subagents · 34 methodology skills · file-based handoff |
| Privacy | Methodology and tooling only; no secrets or client data |
Ask an AI coding agent to "add a feature" and it will happily write code — with no shared understanding of what to build, no design review before implementation, and no independent check of what actually shipped. That produces fast, confident, and frequently wrong code: rework, scope drift, and bugs that only surface after the fact.
dev-agents exists to put a process around that instead of just a prompt. It's an opinionated pipeline: a maestro (orchestrator) routes the request to the right entry point, then 7 specialists work in sequence — each one reads the previous stage's output, produces its own, and stops. Three of those stops are human gates: nothing moves past Story, Spec, or the final Validator without explicit approval.
flowchart LR
O["Orchestrator<br/>triage"] --> S1["01 · Researcher<br/>maps the terrain"]
S1 --> S2["02 · Story Writer<br/>defines the WHAT"]
S2 -->|GATE| S3["03 · Spec<br/>defines the HOW"]
S3 -->|GATE| S4["04 · Backend<br/>server-side"]
S4 --> S5["05 · Frontend<br/>UI"]
S5 --> S6["06 · Tester<br/>proves it"]
S6 --> S7["07 · Validator<br/>audits it"]
S7 -->|GATE| Done(["Approved"])
| Stage | Does | Touches production code? | Human gate |
|---|---|---|---|
| Orchestrator | Triage: picks the entry point, justifies skipping earlier stages | no | — |
| 01 Researcher | Maps the terrain: relevant files, similar features, risks | no | — |
| 02 Story Writer | User story, acceptance criteria, edge cases | no | ✅ |
| 03 Spec | Technical design: API contracts, schema, UI plan | no | ✅ |
| 04 Backend | Implements the server (Supabase: Postgres, Auth, Edge Functions) | yes | — |
| 05 Frontend | Implements the UI (React/Tailwind), consuming the real backend contract | yes | — |
| 06 Tester | Covers the acceptance criteria, runs the suite | tests only | — |
| 07 Validator | Independent audit against the approved story — does not fix what it finds | no | ✅ |
Each stage is a subagent that preloads a handful of methodology skills (sharp, stack-agnostic techniques for investigation, API design, RLS, testing, security review, etc. — 34 in total) and writes its artifact to .work/<slug>/ in the project it's working on. The next stage reads from there — context lives on disk, not in a shared conversation, so nothing gets lost in translation between agents and work can resume exactly where it left off.
Default entry point is 01 (full pipeline). If the scope is obviously narrow — a UI change against an existing contract, a backend-only endpoint — the orchestrator enters directly at the matching stage and states why it skipped the earlier ones.
# Inside Claude Code
/plugin marketplace add octaviosilva2/dev-agents
/plugin install dev-agents@dev-agentsLocal development/testing, without the marketplace:
git clone https://github.com/octaviosilva2/dev-agents.git
claude --plugin-dir ./dev-agentsRun the full pipeline:
/dev-agents:feature add Google login
The skill triages the request, drives each stage in order, and stops at the 3 gates (after story, spec, and validation) waiting for your approval. Per-feature artifacts live in .work/<feature>/ inside the project being worked on (a gitignored, ephemeral folder).
Other ways to use it:
- Plan before running: call the
orquestradoragent ("how would you approach X?") — it returns a plan without executing anything. - Single stage: call one agent directly (e.g.
07-validator) when you already know exactly what you need.
dev-agents/
├── .claude-plugin/
│ ├── plugin.json plugin manifest
│ └── marketplace.json catalog (makes the repo installable via /plugin)
├── agents/ orchestrator + the 7 pipeline stages
├── skills/ 35 skills: 1 orchestration + 34 methodology
│ ├── feature/ the score — drives the pipeline (/dev-agents:feature)
│ ├── (process) triagem-de-demanda, gestao-de-handoff, conduzir-gate
│ ├── (research) investigar-codebase, mapear-impacto, ler-historia-do-projeto
│ ├── (story) user-stories-e-aceite, fatiar-escopo, detectar-ambiguidade
│ ├── (spec) design-de-api, modelagem-de-dados, gate-de-simplicidade, plano-de-teste
│ ├── (backend) supabase-patterns, supabase-rls, migrations-seguras, postgres-performance, integracao-webhooks, typescript-rigoroso
│ ├── (frontend) componentes-react, data-fetching, design-system-tailwind, formularios-validacao, acessibilidade-a11y, ui-ux-pro-max
│ ├── (tests) testes-que-importam, testes-e2e, fixtures-e-dados, mocking-estrategico
│ └── (quality) code-review-rigoroso, verificacao-objetiva, checagem-de-regressao, seguranca-baseline, analise-seguranca
└── README.md
Every skill is original and stack-agnostic — distilled from established practice (spec-kit-style workflows, OWASP, Supabase docs, React patterns), not copy-pasted.
Context. Before this pipeline existed, every AI-assisted feature was a fresh negotiation: explain the codebase again, hope the agent picked the right approach, review a wall of code after the fact. The failure mode wasn't "the AI writes bad code" — it's that without a shared, written checkpoint for what to build and how, mistakes only became visible once code already existed, which is the most expensive place to catch them. The goal was to move the review earlier: approve the plan, not just the diff.
AI-Workflow. The pipeline itself was designed and built with Claude Code, iterating on the agent/skill definitions the same way the pipeline asks any feature to be built: a spec of the roles first (docs/ESPECIFICACAO.md — source of truth for the architecture), then the agents, then the skill catalog. Key non-obvious decisions baked into the design:
- Sequential pipeline, not a swarm. Several loosely-coordinated agents fragment context and produce unpredictable results; one maestro plus 7 specialists in a fixed order keeps handoff explicit.
- File-based handoff (
.work/<slug>/). Context lives on disk between stages instead of in shared memory — this is what makes a run resumable and auditable after the fact. - "Whoever audits doesn't fix it." The Researcher, Story Writer, and Validator never touch production code. The Validator in particular is an independent auditor: it finds a problem, documents it, and hands it back — it doesn't patch its own grading.
- Backend and Frontend are separate stages. Frontend consumes the real contract the Backend already delivered, instead of both guessing at an API shape in parallel.
- Plain Claude Code, no extra framework. No custom orchestration engine, no parallel-session tooling — native subagents and skills only, revisited only if a real limitation shows up in practice.
Architecture. Claude Code plugin format: agents/*.md (subagent definitions with scoped tools and preloaded skills), skills/*/SKILL.md (the 34 methodology skills, invoked on demand or preloaded), and a feature skill that drives the pipeline end to end from the main session (subagents can't invoke other subagents, so orchestration lives one level up). Target stack for the projects this pipeline builds: React + TypeScript + Tailwind on the frontend, Supabase (Postgres/Auth/Edge Functions) on the backend.
Evidence. This isn't a theoretical exercise — it's the same pipeline used to build two other projects in this portfolio: Optomax Software (a validated SaaS product, in production) and CRM-V4 (an internal tool with a green test suite). Both document the research→story→spec→backend→frontend→tests→validation pipeline as their actual build process, not a retrofit for this README.
- Base pipeline: 8 agents + 34 methodology skills + orchestration
- Adjust prompts/skills from real usage patterns
- More domain-specific skills as gaps show up in practice
- Integrated MCPs (Supabase, GitHub)
MIT — see LICENSE.
Peça a um agente de IA para "adicionar uma feature" e ele vai escrever código de bom grado — sem entendimento compartilhado sobre o que construir, sem revisão de desenho antes da implementação, e sem checagem independente do que de fato foi entregue. O resultado é código rápido, confiante e frequentemente errado: retrabalho, escopo que escorrega, e bugs que só aparecem depois de prontos.
O dev-agents existe para colocar um processo em volta disso, em vez de só um prompt. É um pipeline opinativo: um maestro (orquestrador) direciona o pedido para o ponto de entrada certo, e então 7 especialistas trabalham em sequência — cada um lê o resultado do estágio anterior, produz o seu, e para. Três dessas paradas são gates humanos: nada avança além de Story, Spec ou do Validator final sem aprovação explícita.
flowchart LR
O["Orquestrador<br/>triagem"] --> S1["01 · Researcher<br/>mapeia o terreno"]
S1 --> S2["02 · Story Writer<br/>define o QUÊ"]
S2 -->|GATE| S3["03 · Spec<br/>define o COMO"]
S3 -->|GATE| S4["04 · Backend<br/>servidor"]
S4 --> S5["05 · Frontend<br/>UI"]
S5 --> S6["06 · Tester<br/>prova"]
S6 --> S7["07 · Validator<br/>audita"]
S7 -->|GATE| Done(["Aprovado"])
| Estágio | Faz | Toca código de produção? | Gate humano |
|---|---|---|---|
| Orquestrador | Triagem: escolhe o ponto de entrada, justifica o que pulou | não | — |
| 01 Researcher | Mapeia o terreno: arquivos relevantes, features similares, riscos | não | — |
| 02 Story Writer | User story, critérios de aceite, edge cases | não | ✅ |
| 03 Spec | Desenho técnico: contratos de API, schema, plano de UI | não | ✅ |
| 04 Backend | Implementa o servidor (Supabase: Postgres, Auth, Edge Functions) | sim | — |
| 05 Frontend | Implementa a UI (React/Tailwind), consumindo o contrato real do backend | sim | — |
| 06 Tester | Cobre os critérios de aceite, roda a suíte | só testes | — |
| 07 Validator | Audita de forma independente contra a story aprovada — não conserta o que encontra | não | ✅ |
Cada estágio é um subagent que pré-carrega um punhado de skills de metodologia (técnicas afiadas e stack-agnósticas de investigação, design de API, RLS, testes, segurança etc. — 34 no total) e escreve seu artefato em .work/<slug>/, dentro do projeto atendido. O próximo estágio lê dali — o contexto vive em disco, não numa conversa compartilhada, então nada se perde de um agente para o outro e o trabalho pode retomar exatamente de onde parou.
O ponto de entrada padrão é o 01 (pipeline completo). Se o escopo é obviamente restrito — uma mudança de UI sobre um contrato já existente, um endpoint isolado — o orquestrador entra direto no estágio certo e diz por que pulou os anteriores.
# Dentro do Claude Code
/plugin marketplace add octaviosilva2/dev-agents
/plugin install dev-agents@dev-agentsDesenvolvimento/teste local, sem marketplace:
git clone https://github.com/octaviosilva2/dev-agents.git
claude --plugin-dir ./dev-agentsRode a esteira completa:
/dev-agents:feature quero adicionar login com Google
O skill faz a triagem, conduz cada estágio na ordem, e para nos 3 gates (após story, spec e validação) esperando sua aprovação. Os artefatos de cada feature ficam em .work/<feature>/, dentro do projeto atendido (pasta efêmera, ignorada pelo Git).
Outras formas de usar:
- Planejar antes de rodar: chame o agente
orquestrador("como você abordaria X?") — ele devolve um plano sem executar nada. - Estágio avulso: chame um agente direto (ex:
07-validator) quando já souber exatamente o que precisa.
dev-agents/
├── .claude-plugin/
│ ├── plugin.json manifesto do plugin
│ └── marketplace.json catálogo (torna o repo instalável via /plugin)
├── agents/ orquestrador + os 7 estágios da esteira
├── skills/ 35 skills: 1 de orquestração + 34 de metodologia
│ ├── feature/ a partitura — conduz a esteira (/dev-agents:feature)
│ ├── (processo) triagem-de-demanda, gestao-de-handoff, conduzir-gate
│ ├── (pesquisa) investigar-codebase, mapear-impacto, ler-historia-do-projeto
│ ├── (story) user-stories-e-aceite, fatiar-escopo, detectar-ambiguidade
│ ├── (spec) design-de-api, modelagem-de-dados, gate-de-simplicidade, plano-de-teste
│ ├── (backend) supabase-patterns, supabase-rls, migrations-seguras, postgres-performance, integracao-webhooks, typescript-rigoroso
│ ├── (frontend) componentes-react, data-fetching, design-system-tailwind, formularios-validacao, acessibilidade-a11y, ui-ux-pro-max
│ ├── (testes) testes-que-importam, testes-e2e, fixtures-e-dados, mocking-estrategico
│ └── (qualidade) code-review-rigoroso, verificacao-objetiva, checagem-de-regressao, seguranca-baseline, analise-seguranca
└── README.md
Todas as skills são originais e stack-agnósticas — destiladas de boas práticas já estabelecidas (workflows no estilo spec-kit, OWASP, docs do Supabase, padrões React), não copiadas.
Context. Antes desse pipeline existir, cada feature construída com IA era uma negociação do zero: explicar o codebase de novo, torcer para o agente escolher a abordagem certa, revisar uma parede de código depois de pronto. O problema não era "a IA escreve código ruim" — é que sem um checkpoint compartilhado e registrado sobre o que construir e como, os erros só ficavam visíveis quando o código já existia, que é o lugar mais caro para descobri-los. O objetivo era antecipar a revisão: aprovar o plano, não só o diff.
AI-Workflow. O próprio pipeline foi desenhado e construído com o Claude Code, iterando sobre as definições de agentes/skills do mesmo jeito que o pipeline pede para qualquer feature ser construída: primeiro uma especificação dos papéis (docs/ESPECIFICACAO.md — source of truth da arquitetura), depois os agentes, depois o catálogo de skills. Decisões de design não óbvias embutidas nisso:
- Pipeline sequencial, não um enxame de agentes. Vários agentes soltos, coordenados frouxamente, fragmentam contexto e produzem resultado imprevisível; um maestro mais 7 especialistas em ordem fixa mantém o handoff explícito.
- Handoff por arquivo (
.work/<slug>/). O contexto vive em disco entre os estágios em vez de em memória compartilhada — é isso que torna uma execução retomável e auditável depois do fato. - "Quem audita não conserta." Researcher, Story Writer e Validator nunca tocam código de produção. O Validator, em especial, é um auditor independente: encontra um problema, documenta, e devolve — não corrige a própria prova.
- Backend e Frontend são estágios separados. O Frontend consome o contrato real que o Backend já entregou, em vez de os dois adivinharem o formato de uma API em paralelo.
- Claude Code puro, sem framework extra. Nenhum motor de orquestração customizado, nenhuma ferramenta de sessões paralelas — só subagents e skills nativos, a revisitar apenas se uma limitação real aparecer na prática.
Architecture. Formato de plugin do Claude Code: agents/*.md (definições de subagent com tools escopadas e skills pré-carregadas), skills/*/SKILL.md (as 34 skills de metodologia, invocadas sob demanda ou pré-carregadas), e um skill feature que conduz a esteira de ponta a ponta a partir da sessão principal (subagent não invoca outro subagent, então a orquestração mora um nível acima). Stack-alvo dos projetos atendidos por este pipeline: React + TypeScript + Tailwind no frontend, Supabase (Postgres/Auth/Edge Functions) no backend.
Evidence. Isso não é um exercício teórico — é o mesmo pipeline usado para construir dois outros projetos deste portfólio: o Optomax Software (SaaS validado, em produção) e o CRM-V4 (ferramenta interna com suíte de testes passando). Os dois documentam o pipeline research→story→spec→backend→frontend→testes→validação como processo real de construção, não como algo reconstituído para este README.
- Pipeline base: 8 agentes + 34 skills de metodologia + orquestração
- Ajustar prompts/skills a partir de padrões de uso real
- Mais skills de domínio conforme lacunas aparecerem na prática
- MCPs integrados (Supabase, GitHub)
MIT — ver LICENSE.