Transforme ideias em código com sessões de proposta

As sessões de proposta são o ponto de entrada certo quando uma solicitação é importante demais para ser tratada como um único prompt livre. Em vez de editar de imediato, o HagiCode primeiro transforma a solicitação em objetivos, escopo, tarefas e critérios de validação, permite que você os revise e só então passa para a execução.

Pré-requisitos

Antes de iniciar uma sessão de proposta, confirme que você:

• concluiu qualquer método de instalação (Microsoft Store ou Desktop) seguindo o Guia de instalação
• concluiu a Configuração pelo assistente, que cria seu primeiro Agent e pelo menos um projeto
• tem contexto suficiente do projeto para descrever a alteração; se não tiver, comece com Criar uma sessão de conversa
• para entender o fluxo do OpenSpec por trás das sessões de proposta, leia primeiro a Introdução ao OpenSpec

Para que servem as sessões de proposta

As sessões de proposta funcionam melhor quando:

• a alteração precisa de um escopo claro antes de começar a edição
• vários repositórios, módulos ou entregáveis estão envolvidos
• o trabalho deve ser dividido em etapas revisáveis
• você quer que o raciocínio e o histórico de execução continuem visíveis depois

Se você só precisa entender o repositório ou ter uma discussão leve, uma sessão de conversa é mais rápida. Se você precisa de estrutura e rastreabilidade, continue aqui.

Visão geral do fluxo

Etapa	O que você faz	O que acontece
Criar a ideia	Clique em New Idea (nova ideia) e descreva a solicitação	Uma sessão de proposta é criada e colocada na fila para otimização automática
Revisar o rascunho	Abra o cartão da sessão	O HagiCode refina o título e a descrição e redige contexto, problema, solução e impacto
Gerar o plano	Clique em Generate Plan (gerar plano)	O Agent escreve os arquivos do plano do OpenSpec
Revisar o plano	Leia o plano na aba Review	Você confirma ou refina o plano antes de qualquer alteração de código
Executar e arquivar	Execute o plano e depois arquive-o	O Agent executa as tarefas e o plano concluído é arquivado

Etapa 1: Descrever a alteração no painel New Idea

Selecione seu projeto e clique em New Idea (o ícone de broto) na barra de ferramentas acima do quadro de sessões. O painel Create Proposal é aberto.

Percorra o painel:

• Idea Name e Project Name (obrigatórios) – confirme qual projeto é responsável pela solicitação.
• Scope – na aba Vault, marque os vaults que a IA pode editar; os vaults gerenciados pelo sistema são sempre somente de referência. Na aba Projects, adicione outros projetos como contexto.
• Quick Requests – adições com um clique, como No docs / tests, Self commit, Output English, Ask before edit e No backward compatibility.
• You Request – descreva a alteração em linguagem natural, com até 14.000 caracteres. O Combined preview acima dele mostra exatamente o que será enviado à IA.

Clique em Submit idea. Se o trabalho afeta vários repositórios ao mesmo tempo, defina esse limite aqui em vez de acrescentá-lo durante a execução.

Etapa 2: Revisar a proposta na visão de detalhes

Depois de enviar, a ideia aparece como um cartão na raia Proposal & Review com um selo de status. Clique nela para abrir a visão de detalhes da proposta.

A visão mantém o plano, o progresso e a conversa juntos:

• As etapas do fluxo (à esquerda) mostram em que ponto a proposta está. Elas se agrupam em Proposal preparation (Session Created, Auto Optimizing, Drafting Ready), Review and refine (Generating Plan Files, Review Plan), Execution complete (Executing Plan, Execution Completed) e Archive (Archiving, Archived).
• As direções de planejamento (Planning directions) mostram quais direções o plano deve explorar, como mapa de alterações, fluxo de interação ou arquitetura. Ajuste os padrões em Settings → Proposals and planning → Planning Direction.
• A aba Info (à direita) mostra a descrição redigida (Context, Problem, Solution, Impact) e a sua solicitação original em Chief Complaint. As ações rápidas permitem Open Proposal Folder, Optimize Proposal, Open in New Window ou Delete Session.
• As abas Conversation e Review reúnem a discussão com o Agent e a revisão do plano gerado.
• Quick Chat (canto inferior esquerdo) permite enviar uma mensagem ao Agent sem sair da visão.

Se o objetivo, o escopo ou a divisão de tarefas parecerem errados aqui, corrija a proposta antes de seguir em frente. É exatamente esse o objetivo deste fluxo.

Etapa 3: Gerar, revisar, executar e arquivar

Quando o rascunho estiver correto, clique em Generate Plan. O Agent escreve os arquivos do plano do OpenSpec, e a sessão passa para Review Plan para que você confira o resultado antes de qualquer alteração de código. Após a revisão, a sessão continua para Executing Plan e, por fim, para Archiving e Archived.

O HagiCode pede confirmação antes das etapas difíceis de desfazer, como gerar uma proposta, executar imediatamente ou arquivar. Você pode ajustar esses avisos em Settings → General → Confirm Prompts.

Após a execução, use o Super Commit para transformar as alterações finais em mensagens de commit limpas.

Etapa 4: Acompanhar as propostas no quadro de sessões

Quando um projeto tem várias propostas ou uma mistura de propostas e conversas, o quadro de sessões é a visão geral mais clara.

• Proposal & Review reúne as ideias que estão sendo redigidas, geradas e revisadas.
• Execution reúne as sessões que estão em execução ou concluídas.
• Archived mantém o trabalho concluído fora do caminho, mas disponível para consulta.

Cada cartão mostra seu status, como Optimizing, Drafted, Reviewing, Executing ou Execution Complete. Você pode trocar o layout do quadro com o seletor de layout; consulte Sessões.

Quando preferir uma sessão de proposta

Escolha primeiro uma sessão de proposta quando:

• a alteração é complexa e você não quer que a IA improvise cedo demais
• o trabalho será revisado ou compartilhado com outras pessoas depois
• vários repositórios, módulos ou papéis estão envolvidos
• você quer que o histórico de execução e a justificativa continuem reutilizáveis

Se a tarefa ainda é pequena e exploratória, uma sessão de conversa costuma ser o caminho mais leve.

Próximos passos

Criar uma sessão de conversaSe você ainda precisa entender o repositório antes de planejar a alteração, comece pelo fluxo de conversa, que é mais leve.

Super CommitApós a execução da proposta, continue com o guia para gerar mensagens de commit mais limpas a partir das alterações finais.