From superjurista-dev
Plans agentic system architecture by generating a complete blueprint with agents, data flow, and contracts. Produces a BLUEPRINT.md file before any artifact creation, solving circular dependency between agent and orchestrator design.
How this command is triggered — by the user, by Claude, or both
Slash command
/superjurista-dev:planejar-sistemaThe summary Claude sees in its command listing — used to decide when to auto-load this command
# Command: planejar-sistema v1.0 > **Propósito:** Planejador de arquitetura para sistemas agênticos - resolve o problema de dependência circular entre criação de agents e orquestradores > > **Diferencial:** Gera blueprint completo ANTES de criar artefatos, permitindo design top-down > > **Nota:** Este é um command de planejamento que executa diretamente (não delega para subagentes). Usa estrutura de fases para organização mas não segue padrão "Orquestrador Cego". --- description: Planeja arquitetura de sistemas agênticos - gera blueprint com agents, fluxo e contratos argument-hint: [descr...
Propósito: Planejador de arquitetura para sistemas agênticos - resolve o problema de dependência circular entre criação de agents e orquestradores
Diferencial: Gera blueprint completo ANTES de criar artefatos, permitindo design top-down
Nota: Este é um command de planejamento que executa diretamente (não delega para subagentes). Usa estrutura de fases para organização mas não segue padrão "Orquestrador Cego".
<regras_uso> - SEMPRE validar com usuário antes de prosseguir entre fases - SEMPRE verificar agents existentes via Glob antes de marcar como "a criar" - SEMPRE incluir diagrama ASCII no blueprint - NUNCA criar agents automaticamente - apenas especificar - NUNCA pular a fase de brainstorming </regras_uso>
- NUNCA criar agents ou orquestradores - apenas gera especificação - NUNCA salvar blueprint sem validar arquitetura com usuário - NUNCA assumir que agent existe sem verificar via Glob - NUNCA prosseguir para Fase 2 sem conceito aprovado - SEMPRE usar português com acentos corretos - SEMPRE mostrar preview do blueprint antes de salvar Expandir brainstorming com mais perguntas socráticas → Clarificar objetivo, entrada, saída, transformações → Não prosseguir até ter clareza mínima<se_muitas_etapas> Pipelines ideais têm 3-8 etapas → Sugerir agrupamento ou divisão em sub-pipelines → Validar com usuário antes de prosseguir </se_muitas_etapas>
<se_agent_ambiguo> Capacidade deve ser atômica (uma coisa bem feita) → Sugerir divisão em 2+ agents → Validar com usuário </se_agent_ambiguo>
<se_conflito_specs> Consultar specs originais via Read → ${CLAUDE_PLUGIN_ROOT}/spec/templates/agent.md → ${CLAUDE_PLUGIN_ROOT}/spec/templates/orquestrador.md → Seguir spec, não intuição </se_conflito_specs>
<se_blueprint_rejeitado> Usuário escolheu "Não, ajustar" na validação → Perguntar: "Qual parte precisa ser ajustada?" → Se ajuste em fluxo/etapas → voltar para Fase 1 → Se ajuste em especificação → retrabalhar Fase 2 → Máximo 3 iterações por fase → Se 3x sem aprovação → parar e informar limitação </se_blueprint_rejeitado>
<contratos_dados>
| # | Fase | Entrada | Saída | Validação |
|---|---|---|---|---|
| 0 | Inicialização | $ARGUMENTS (descrição) | TodoWrite criado | Descrição não vazia |
| 1 | Descoberta | $ARGUMENTS | Conceito aprovado | Fluxo validado com usuário |
| 2 | Design e Geração | Conceito | Blueprint .md | Arquivo salvo com sucesso |
| </contratos_dados> |
<rastreamento_progresso>
<formato_todowrite>
javascript TodoWrite([ {content: "Fase 0 - Inicialização", status: "in_progress", activeForm: "Preparando"}, {content: "Fase 1 - Descoberta (Brainstorming)", status: "pending", activeForm: "Explorando domínio"}, {content: "Fase 2 - Design e Geração", status: "pending", activeForm: "Gerando blueprint"}, ])
</formato_todowrite>
</rastreamento_progresso>
<sinalizadores_formato>
| Fase | Sinalização de Conclusão |
|---|---|
| 0 | TodoWrite criado |
| 1 | Usuário aprovou fluxo de etapas |
| 2 | Blueprint salvo em ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/ |
| </sinalizadores_formato> |
<sufixos_correcao>
<sufixo_sintese_incompleta> [SÍNTESE INCOMPLETA. A síntese DEVE conter: - Nome do sistema (kebab-case) - Categoria (jurídico ou genérico) - Objetivo claro - Entrada definida (tipo e origem) - Saída definida (tipo e formato) - 3-8 etapas identificadas Corrija e reapresente ao usuário.] </sufixo_sintese_incompleta>
<sufixo_blueprint_incompleto> [BLUEPRINT INCOMPLETO. O blueprint DEVE conter: - Diagrama ASCII do fluxo - Tabela de agents (com status: existe/criar) - Tabela de contratos de dados - Sinalizadores de cada etapa - Checklist de implementação Corrija e reapresente ao usuário.] </sufixo_blueprint_incompleto>
<sufixo_agents_nao_verificados> [AGENTS NÃO VERIFICADOS. Antes de listar agents: - Executar Glob: .claude/agents//.md - Comparar capacidade necessária com agents existentes - Marcar corretamente: ✅ existe ou ❌ CRIAR Corrija e reapresente ao usuário.] </sufixo_agents_nao_verificados>
<sufixo_acentos> [FALHA DE ACENTOS. Use português correto COM acentos: é, á, ã, ç, ô, ê, í, ú. Documento brasileiro EXIGE acentuação correta. Corrija e regenere.] </sufixo_acentos> </sufixos_correcao>
<fases_pipeline>
1. **Receber argumento:** ``` $ARGUMENTS = [descrição do sistema fornecida pelo usuário] Se vazio ou muito curto (< 10 palavras) → pedir clarificação via AskUserQuestion ``` 2. **Definir variáveis:**
```
$NOME_SISTEMA = [extrair nome do sistema da descrição ou pedir ao usuário]
$CATEGORIA = [juridico | generico] → inferir ou perguntar
```
3. **Criar TodoWrite:**
```javascript
TodoWrite([
{content: "Fase 0 - Inicialização", status: "completed", activeForm: "Preparando"},
{content: "Fase 1 - Descoberta (Brainstorming)", status: "in_progress", activeForm: "Explorando domínio"},
{content: "Fase 2 - Design e Geração", status: "pending", activeForm: "Gerando blueprint"},
])
```
4. **Prosseguir para Fase 1**
</acao_orquestrador>
Clarificar domínio e definir etapas principais do sistema
<acao_orquestrador>
1. **Iniciar exploração com perguntas socráticas:**
<perguntas_essenciais>
<!-- OBJETIVO -->
- "Qual é o OBJETIVO FINAL deste sistema? O que ele produz?"
- "Quem vai usar este sistema? (você mesmo, equipe, externo)"
<!-- ENTRADA -->
- "Qual é a ENTRADA do sistema? (PDF, TXT, dados estruturados, processo judicial)"
- "De onde vem essa entrada? (PJE, upload, API externa)"
<!-- SAÍDA -->
- "Qual é a SAÍDA esperada? (relatório, decisão, análise, parecer)"
- "Em que formato? (MD, PDF, JSON)"
<!-- TRANSFORMAÇÕES -->
- "Quais TRANSFORMAÇÕES precisam acontecer entre entrada e saída?"
- "Cada transformação pode ser feita independentemente?"
- "Existe ordem obrigatória ou algumas podem rodar em paralelo?"
<!-- VALIDAÇÕES -->
- "Quais VALIDAÇÕES são críticas? (formato, conteúdo, completude)"
- "O que acontece se uma etapa falhar?"
<!-- DOMÍNIO -->
- "Este sistema é específico do domínio jurídico ou genérico?"
- "Precisa de conhecimento especializado? (temas jurídicos, legislação)"
</perguntas_essenciais>
2. **Iterar até ter clareza sobre:**
- [ ] Objetivo claro e específico
- [ ] Entrada definida (tipo e origem)
- [ ] Saída definida (tipo e formato)
- [ ] 3-8 etapas principais identificadas
- [ ] Categoria (jurídico/genérico) definida
3. **Sintetizar descobertas:**
```
SÍNTESE DO SISTEMA:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Nome: [nome-do-sistema]
Categoria: [jurídico | genérico]
Objetivo: [O que o sistema faz]
Entrada: [Tipo e origem]
Saída: [Tipo e formato]
FLUXO DE ETAPAS:
1. [Nome da Etapa 1] → [O que transforma]
2. [Nome da Etapa 2] → [O que transforma]
3. [Nome da Etapa N] → [O que transforma]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
4. **Validar com usuário:**
```
AskUserQuestion:
"Essa síntese está correta? Posso prosseguir para o design da arquitetura?"
Opções: [Sim, prosseguir] [Não, ajustar]
```
</acao_orquestrador>
<criterio_conclusao>
- [ ] Objetivo, entrada e saída definidos
- [ ] 3-8 etapas identificadas
- [ ] Categoria (jurídico/genérico) definida
- [ ] Usuário aprovou síntese EXPLICITAMENTE (respondeu "Sim, prosseguir")
</criterio_conclusao>
<transicao>
Atualizar TodoWrite:
- Fase 1 → completed
- Fase 2 → in_progress
Prosseguir para FASE 2
</transicao>
Especificar agents, contratos e gerar blueprint completo
<acao_orquestrador>
1. **Consultar specs para referência:**
```
Read: ${CLAUDE_PLUGIN_ROOT}/spec/templates/agent.md
Read: ${CLAUDE_PLUGIN_ROOT}/spec/templates/orquestrador.md
→ Entender estrutura esperada de agents e orquestradores
```
2. **Verificar agents existentes:**
```
Glob: .claude/agents/*/*.md
→ Listar APENAS agents (exclui references/)
→ Para cada etapa, verificar se já existe agent com capacidade similar
```
3. **Especificar cada etapa:**
Para cada etapa identificada na Fase 1:
```
ETAPA [N]: [Nome]
├── Capacidade necessária: [verbo + objeto]
├── Entrada: [tipo genérico]
├── Saída: [tipo genérico]
├── Categoria: [extracao | analise | pesquisa | revisao | redacao]
├── Agent existente? [✅ nome | ❌ CRIAR]
└── Sinalizadores: Início "[X]" | Fim "[Y]"
```
4. **Desenhar diagrama ASCII:**
```
ARQUITETURA: [nome-do-sistema]
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ETAPA 0 │────▶│ ETAPA 1 │────▶│ ETAPA 2 │
│ Preparação │ │ [Nome] │ │ [Nome] │
│ │ │ │ │ │
│ $ARGUMENTS │ │ Agent: │ │ Agent: │
│ → $WORKSPACE│ │ [nome] │ │ [nome] │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
▼ ▼
[arquivo-1] [arquivo-2]
```
5. **Montar tabela de contratos:**
```
| # | Etapa | Entrada | Saída | Validação |
|---|-------|---------|-------|-----------|
| 0 | Preparação | $ARGUMENTS | $WORKSPACE | Variáveis calculadas |
| 1 | [Nome] | [tipo] | [arquivo] | [sinalizadores] |
| N | Finalização | [todos] | [final] | [critérios] |
```
6. **Gerar blueprint completo:**
Usar estrutura definida em <formato_blueprint>
7. **Mostrar preview:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PREVIEW DO BLUEPRINT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Conteúdo do blueprint]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
8. **Pedir confirmação:**
```
AskUserQuestion:
"Blueprint pronto. Deseja salvar em ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/[nome]-BLUEPRINT.md?"
Opções: [Sim, salvar] [Não, ajustar]
```
9. **Salvar blueprint:**
```
$CAMINHO = "${CLAUDE_PLUGIN_ROOT}/spec/blueprints/[nome-sistema]-BLUEPRINT.md"
Write: $CAMINHO
[Conteúdo do blueprint]
```
10. **Exibir próximos passos:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLUEPRINT GERADO COM SUCESSO
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Arquivo: $CAMINHO
RESUMO:
• Agents reutilizados: [N]
• Agents a criar: [M]
• Total de etapas: [X]
PRÓXIMOS PASSOS:
1. CRIAR AGENTS FALTANTES:
[lista de comandos /criar-agente]
2. CRIAR ORQUESTRADOR:
/criar-orquestrador [nome-pipeline]
3. TESTAR:
/[nome-pipeline] [argumento-teste]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
</acao_orquestrador>
<criterio_conclusao>
- [ ] Todos agents especificados (capacidade, categoria, existência)
- [ ] Diagrama ASCII completo
- [ ] Tabela de contratos preenchida
- [ ] Blueprint salvo em ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/
</criterio_conclusao>
<transicao>
Atualizar TodoWrite:
- Fase 2 → completed
Exibir resumo final e próximos passos
</transicao>
</fases_pipeline>
<formato_blueprint>
# Blueprint: [Nome do Sistema]
**Gerado por:** /planejar-sistema
**Data:** [YYYY-MM-DD]
**Categoria:** [Jurídico | Genérico]
---
## 1. Visão Geral
**Objetivo:** [O que o sistema faz]
**Entrada:** [Tipo e origem]
**Saída:** [Artefato final]
---
## 2. Diagrama de Arquitetura
[ENTRADA: $ARGUMENTS] │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ ORQUESTRADOR: [nome-pipeline] │ ├──────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ ETAPA 0 │───▶│ ETAPA 1 │───▶│ ETAPA 2 │───▶│ ETAPA N │ │ │ │ Prep. │ │ [nome] │ │ [nome] │ │ Final. │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ $WORKSPACE [arquivo-1] [arquivo-2] [artefato] │ │ │ └──────────────────────────────────────────────────────────────┘ │ ▼ [SAÍDA: artefato final]
---
## 3. Especificação de Agents
| # | Etapa | Capacidade | Categoria | Status | Arquivo |
|---|-------|------------|-----------|--------|---------|
| 1 | [Nome] | [Verbo + objeto] | [cat] | [✅ Existe / ❌ CRIAR] | `.claude/agents/[cat]/[nome].md` |
| 2 | [Nome] | [Verbo + objeto] | [cat] | [✅ Existe / ❌ CRIAR] | `.claude/agents/[cat]/[nome].md` |
**Agents a Criar:** [listar]
**Agents Reutilizados:** [listar]
---
## 4. Contratos de Dados
| # | Etapa | Entrada | Saída | Validação |
|---|-------|---------|-------|-----------|
| 0 | Preparação | $ARGUMENTS | $WORKSPACE, $NUMERO | Variáveis calculadas |
| 1 | [Nome] | [tipo] | [arquivo] | Sinalizadores: "[X]"..."[Y]" |
| N | Finalização | [artefatos] | [final] | Todos existem |
**Convenção de Nomenclatura:** `[NUMERO]-tipo.md` (se jurídico) ou `[id]-tipo.md` (se genérico)
---
## 5. Sinalizadores de Formato
| Etapa | Início Obrigatório | Fim Obrigatório |
|-------|-------------------|-----------------|
| 1 | "[SINALIZADOR_1]" | "[FIM_1]" |
| 2 | "[SINALIZADOR_2]" | "[FIM_2]" |
---
## 6. Checklist de Implementação
### Fase 1: Criar Agents Faltantes
```bash
# Para cada agent a criar:
/criar-agente [descrição-da-capacidade]
Especificações:
[...]
/criar-orquestrador [nome-pipeline]
Usar este blueprint como referência:
# Teste com argumento real
/[nome-pipeline] [argumento-exemplo]
# Verificar saídas
ls $WORKSPACE/*.md
[Decisões arquiteturais, trade-offs, considerações futuras]
Próximo Passo: Execute os comandos da Fase 1 (Criar Agents Faltantes)
</formato_blueprint>
<resumo_arquitetura>
PIPELINE /planejar-sistema - Arquitetura
│
├── FASE 0: Inicialização
│ ├── Recebe: $ARGUMENTS (descrição do sistema)
│ ├── Define: $NOME_SISTEMA, $CATEGORIA
│ └── Cria: TodoWrite
│
├── FASE 1: Descoberta (Brainstorming)
│ ├── Perguntas socráticas sobre domínio
│ ├── Identifica: objetivo, entrada, saída, etapas
│ ├── Sintetiza: fluxo de alto nível
│ └── Valida: com usuário antes de prosseguir
│
└── FASE 2: Design e Geração
├── Consulta: specs de agent e orquestrador
├── Verifica: agents existentes via Glob
├── Especifica: cada etapa (capacidade, categoria, existência)
├── Desenha: diagrama ASCII
├── Monta: tabela de contratos
├── Gera: blueprint completo
├── Valida: com usuário
└── Salva: em ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/
FLUXO DE DADOS:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Ideia bruta │────▶│ Conceito │────▶│ Blueprint │
│ (descrição) │ │ (etapas │ │ (arquitetura │
│ │ │ validadas) │ │ completa) │
└──────────────┘ └──────────────┘ └──────────────┘
INTEGRAÇÃO COM CICLO DE CRIAÇÃO:
/planejar-sistema → BLUEPRINT.md → /criar-agente (n vezes) → /criar-orquestrador → /testar
</resumo_arquitetura>
<checklist_orquestrador>
Antes de iniciar, verificar:
**Fase 0:**
- [ ] Descrição suficiente (>10 palavras)?
- [ ] Categoria identificável (jurídico/genérico)?
**Fase 1:**
- [ ] Objetivo claro?
- [ ] Entrada e saída definidas?
- [ ] 3-8 etapas identificadas?
- [ ] Usuário aprovou fluxo?
**Fase 2:**
- [ ] Specs consultadas?
- [ ] Agents existentes verificados via Glob?
- [ ] Cada etapa tem capacidade, categoria, sinalizadores?
- [ ] Diagrama ASCII criado?
- [ ] Tabela de contratos completa?
- [ ] Preview mostrado ao usuário?
- [ ] Blueprint salvo em ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/?
</checklist_orquestrador>
<exemplos>
### Exemplo 1: Sistema Jurídico
Usuário: /planejar-sistema pipeline para análise de embargos de declaração
[Fase 1 - Descoberta] Claude: Vou explorar o domínio deste sistema... • "Embargos de declaração contra qual tipo de decisão? (sentença, acórdão)" • "A entrada é o processo completo ou apenas os embargos?" • "A saída é uma análise de admissibilidade ou a decisão final?"
Usuário: [respostas]
Síntese aprovada:
[Fase 2 - Design e Geração] Verificando agents... ✅ analista-embargos (existe) ✅ embargos-decisao (existe) ❌ verificador-fundamentacao (CRIAR)
Blueprint salvo em: ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/pipeline-embargos-BLUEPRINT.md
### Exemplo 2: Sistema Genérico
Usuário: /planejar-sistema sistema para validar contratos comerciais
[Fase 1 - Descoberta] Claude: Explorando o domínio... • "Que tipo de contratos? (prestação de serviço, compra e venda)" • "A entrada é PDF ou já texto extraído?" • "Quais validações são críticas? (cláusulas abusivas, completude, prazos)"
Usuário: [respostas]
Síntese aprovada:
[Fase 2 - Design e Geração] Verificando agents... ✅ super-conversor-pdf (existe - extração) ❌ analisador-estrutura-contrato (CRIAR) ❌ detector-clausulas-abusivas (CRIAR) ❌ verificador-completude (CRIAR) ❌ consolidador-analise (CRIAR)
Blueprint salvo em: ${CLAUDE_PLUGIN_ROOT}/spec/blueprints/pipeline-validacao-contratos-BLUEPRINT.md
</exemplos>
npx claudepluginhub georgemarmelstein/superjurista-dev/plan-systemInvokes rcc:planning-agent-systems skill to plan agent system components with traceability and reuse analysis.
/design-workflowDesigns a complete multi-agent workflow for a user goal or task, producing overview diagram, task decomposition, agent roles, handoffs, state management, interventions, recovery, and observability plan.
/planOrchestrates multi-agent workflow across analysis and design phases to produce requirements, constraints, NFRs, data model, API contracts, and quickstart guide.
/runParses and executes legacy inline orchestration workflow syntax supporting raw operators, YAML frontmatter templates, and temporary AI agents with model overrides.
/delegateOrchestrates complex tasks: decomposes into agent waves/tasks, plans execution, awaits user approval, then executes via subagents or teams.
/plan-modeCreates multi-agent task hierarchy for planning consultation on a feature, dispatching specialist consultations in parallel and synthesizing an implementation plan (planning only).