Plano Lego

O que Plano Lego faz?

Transforme uma mudança já definida em um DAG em camadas de primitivas simples até a funcionalidade completa. Apenas planeje. Depois pare.

O grafo é uma pirâmide: blocos independentes na base, blocos compostos acima, um nó de finalização. Um executor posterior pode executar nós do mesmo nível em paralelo, alterar status e redesenhar este grafo. Esta habilidade não despacha subagentes. Não carrega outras habilidades.

Quando Usar

Carregue quando o trabalho for transformar uma mudança já definida em um mapa de implementação que o executor possa seguir.

• Necessidade: o que construir já está escolhido. Se uma lista de arquivos a tocar ou uma seleção de caminho já estiver nesta conversa, use-os. Caso contrário, derive da intenção definida e do código. Não invente um segundo mapa do sistema.
• Pular: erros de digitação, comentários, formatação, documentação sem código.
• Se a intenção ainda estiver em aberto: pare. Pergunte até que a mudança esteja definida. Não empilhe blocos para uma funcionalidade que não foi escolhida.

Um nó ainda é um DAG. Emita o contrato completo.

Restrições Rígidas

1. Apenas planeje. Não escreva código de produção. Não escreva testes. Nomeie a verificação em done when. Não a implemente aqui.
2. Pare após a emissão. Exiba o DAG mais o arquivo de rascunho. Não despache. Não carregue a próxima habilidade.
3. Sem ciclos. Se um bloco depende de um bloco posterior, a divisão está errada. Divida novamente.
4. Não espere por aprovação. Mostre o DAG e pare. O usuário interrompe se estiver errado.
5. Não abra o arquivo de rascunho para o usuário. Não escreva um plano em docs/.

Granularidade do Nó

Nó do grafo (unidade paralela): uma primitiva independente que pode ser entregue por um subagente sem esperar por outro nó em andamento.

Exemplos: write fetchOrder, write OrderCard, wire fetchOrder into the loader.

Muito grande: implement auth. Divida-o. Muito pequeno: rename a variable. Incorpore-o ao nó que precisa dele.

Partes (dentro de um nó): as funções que devem ser implementadas juntas para que o nó compile. Um subagente faz as partes em ordem. Não divida partes.

Exemplo de nó fetch-order:

• files: src/fetchOrder.ts, src/fetchOrder.test.ts
• parts: tipo Order, depois fetchOrder, depois escrever ou estender src/fetchOrder.test.ts
• essas partes não são nós separados do grafo

Forma do Grafo

• Camada 0: nós com depends on: none. O executor pode executar todos em paralelo.
• Camada N: nós cujas dependências estão todas em camadas anteriores.
• Última camada: um nó (ou um conjunto restrito) que significa que a funcionalidade funciona de ponta a ponta.
• Dois nós que não dependem um do outro devem compartilhar uma camada (ou estar em camadas que não esperam uma pela outra).
• depends on lista ids de nós, nunca nomes de arquivos.

Mesmo arquivo: se dois nós criam ou editam o mesmo caminho, eles não devem compartilhar uma camada. Mescle-os ou adicione uma aresta depends on para que um espere. Não divida um arquivo apenas para executar em paralelo. Dois nós que apenas leem um caminho podem compartilhar uma camada. files lista apenas caminhos de criação ou edição. A regra do mesmo arquivo inclui arquivos de teste.

Campos do Nó

Cada nó tem todos os sete:

1. id: kebab-case, único neste plano, estável (um executor posterior marca este id como concluído).
2. name: nome curto em inglês.
3. depends on: outros ids, ou none.
4. files: criar ou editar (caminhos). Inclua o caminho do teste de done when.
5. parts: lista ordenada em formato C. A última parte é escrever ou estender o teste. Se done when é uma verificação manual e não há arquivo de teste, a última parte é essa verificação e files não tem caminho de teste.
6. done when: um arquivo de teste ou comando que o executor pode executar antes de iniciar os dependentes.
7. status: esta habilidade sempre escreve pending. Um executor posterior pode definir in-progress ou done. Esta habilidade nunca escreve esses dois.

Não coloque o código fonte completo no plano.

Quadro Vivo

Caminho: <repo>/.agent/scratch/lego-plan.json

Mesmo JSON da cerca de chat. Agentes seguem este arquivo. O produto visível para o usuário é a imagem do chat.

• Crie .agent/scratch/ se necessário.
• Sempre sobrescreva. Não pergunte, mesmo se nós existentes estiverem in-progress ou done.
• Se o repositório tiver git, certifique-se de que .gitignore contenha .agent/scratch/. Se .gitignore existir e a linha estiver faltando, anexe-a. Se .gitignore estiver faltando, crie-o com essa única linha.
• Não abra o arquivo. Não o despeje como uma segunda cópia no chat. A cerca JSON é a cópia visível para o usuário.

Procedimentos

Procedimento 1: Confirmar uma mudança definida

1. Se a mudança estiver clara, continue.
2. Se o usuário ainda está escolhendo o que deseja, pare. Pergunte. Volte aqui depois que estiver definida.

Procedimento 2: Coletar entradas já na sessão

1. Se esta conversa já tiver uma lista de arquivos final, partes ou uma seleção de caminho, use-os como conjunto inicial.
2. Se não, derive blocos da intenção definida e do código que você precisa ler para nomear arquivos. Não percorra todo o repositório.

Procedimento 3: Dividir em nós e partes

1. Liste primitivas candidatas (granularidade B).
2. Para cada primitiva, liste as partes C que devem compilar juntas. Termine com escrever ou estender o teste (ou a verificação manual).
3. Desenhe depends on: um nó depende de outro apenas se chama ou incorpora o resultado desse nó.
4. Atribua camadas com base nas dependências. Nós independentes → mesma camada.
5. Se dois nós criam ou editam o mesmo caminho e compartilham uma camada, mescle-os ou adicione uma aresta. Em seguida, reatribua camadas.
6. Se um ciclo aparecer, divida o nó errado e repita este procedimento.

Procedimento 4: Preencher cada nó

Preencha os sete campos. status é pending em todos os nós.

Procedimento 5: Mostrar o DAG no chat

Mostre, nesta ordem:

1. Camadas: camada 0 até a última. Em cada camada, os nós dessa camada.
2. Nós: os sete campos para cada id.
3. Mermaid: sempre. Um flowchart (ou graph TD). Os ids dos nós no diagrama devem corresponder aos ids do plano. Sem classDef. Sem cores de status. Cada nó está pendente.
4. Cerca JSON: um bloco json com o objeto do quadro vivo. Fonte verdade para ids, deps, arquivos, partes, doneWhen e status. As camadas são derivadas de depends. Não armazene um campo layer.

Em seguida, Procedimento 6.

Forma Mermaid:

flowchart TD
  fetch-order[fetch-order]
  order-card[order-card]
  wire-loader[wire-loader]
  fetch-order --> wire-loader
  order-card --> wire-loader

Nós na mesma camada não têm arestas entre si.

Forma JSON:

{
  "version": 1,
  "nodes": [
    {
      "id": "fetch-order",
      "name": "fetch order",
      "depends": [],
      "files": ["src/fetchOrder.ts", "src/fetchOrder.test.ts"],
      "parts": ["Order type", "fetchOrder", "write or extend src/fetchOrder.test.ts"],
      "doneWhen": "pnpm test src/fetchOrder.test.ts",
      "status": "pending"
    }
  ]
}

depends é um array de ids. Vazio significa nenhum.

Procedimento 6: Escrever o quadro vivo

1. Escreva o mesmo JSON em .agent/scratch/lego-plan.json (sobrescreva).
2. Certifique-se de que .gitignore ignore .agent/scratch/ conforme descrito em Quadro Vivo.
3. Não abra o arquivo.

Procedimento 7: Parar

Após o Procedimento 6, pare. Não escreva código. Não despache. Não carregue outra habilidade.

Árvore de Decisão

• Intenção não definida → Procedimento 1.
• Mudança definida, precisa de mapa de implementação → Procedimento 2 → 3 → 4 → 5 → 6 → 7.
• Um nó → ainda Procedimento 2 → 7 (contrato completo).
• Erro de digitação / formatação / apenas documentação → esta habilidade não se aplica.
• Ciclo nas dependências → Procedimento 3, passo 6.
• Mesmo caminho em dois nós da mesma camada → Procedimento 3, passo 5.
• Nó é "implementar a funcionalidade inteira" → divida (Procedimento 3).

Bandeiras Vermelhas

Sinal	O que significa	Faça em vez disso
Escrever a função de busca nesta habilidade	Plano se tornou implementação	Procedimento 7. Pare.
Uma lista linear sem camadas	Não é possível expandir	Coloque nós independentes na mesma camada.
Despachar subagentes daqui	Folha se tornou executor	Procedimento 7. Pare.
Ids Mermaid diferentes dos ids dos nós	Executor não pode marcar como concluído	Mesmo id em kebab-case em ambos os lugares.
Cerca JSON diferente do arquivo de rascunho	Duas fontes de verdade	Escreva um objeto. Copie-o para ambos.
Ciclo (a → b → a)	Divisão está errada	Divida e reatribua camadas.
Dois nós da mesma camada editam order.ts	Conflito de escrita paralela	Mescle ou adicione uma aresta depends on.
Dividir um arquivo para que dois nós possam executar em paralelo	Design não solicitado	Mantenha o arquivo. Sequencie os nós.
Caminho do teste faltando em files / última parte	Nó não é entregável	Procedimento 3, passo 2.
classDef ou cores de status no Mermaid do plano	Esta habilidade pinta progresso	Sem estilo. Tudo pendente.
Partes de um nó divididas em nós paralelos que não compilam sozinhos	C tratado como B	Mantenha essas partes dentro de um nó.
"Implementar autenticação" como um único nó	Muito grande	Divida em primitivas.
Esperar por "parece bom?"	Portão é mostrar-e-parar	Emita e pare.
Perguntar antes de sobrescrever o arquivo de rascunho	Quadro vivo é um slot único	Procedimento 6. Sobrescreva.
Abrir .agent/scratch/lego-plan.json	Extra voltado ao usuário	Apenas chat. O arquivo é para agentes.
Escrever docs/lego-plan.md	Artefato extra	Chat mais rascunho. Sem plano em docs.

Tratamento de Erros

• Nenhum arquivo a tocar na sessão: derive da intenção e de leituras direcionadas. Se não puder nomear arquivos, pare e diga o que está faltando. Não invente caminhos.
• Ciclo: reporte o ciclo pelos ids. Divida. Execute novamente o Procedimento 3. Não mostre um Mermaid cíclico como plano.
• Última camada não significa que a funcionalidade funciona: adicione um nó de finalização que depende das peças compostas (a montagem), ou diga por que a última camada atual já é o caminho ponta a ponta.
• Usuário interrompe dizendo que um nó está errado: edite esse nó e quaisquer depends on que apontavam para ele. Mantenha ids estáveis se o nó ainda existir. Se você remover um nó, remova-o também do Mermaid e do JSON. Sobrescreva o arquivo de rascunho. Mostre o DAG novamente. Pare.
• done when é vago ("funciona"): substitua por um comando ou caminho de teste. Se o projeto ainda não tiver um comando de teste, nomeie a verificação manual em uma linha. A última parte é essa verificação.
• Não é um repositório git: ainda escreva .agent/scratch/lego-plan.json no diretório de trabalho, se gravável. Pule a etapa do gitignore. Diga isso em uma linha no chat.
• Falha na escrita do rascunho (permissões, disco): ainda mostre o DAG e a cerca JSON no chat. Diga que o quadro vivo não foi escrito. Não finja que o arquivo existe.
• JSON de rascunho existente é inválido ou está em execução: sobrescreva. Não mescle. Não pergunte.