APareek89/agent-design-studio

Agent Design Studio

Um briefing é a única entrada necessária. Use o assistente anfitrião; nenhuma chave de provedor extra ou configuração de conta é necessária. Preencha os detalhes você mesmo. Fatos, políticas, funções, volumes e preços propostos pertencem a um registro de suposições com proprietários de verificação e bloqueadores de lançamento. Nunca invente evidências ou aprovação de stakeholders. A permissão de design não autoriza gravações de negócio, implantação, pagamentos, alterações de acesso ou mensagens.

Escolha a saída

Aceite mode: lite | standard | full opcional e interactive: true | false. Padrões: standard, false. Não pergunte ao usuário para escolher quando ele forneceu apenas um briefing.

• lite: PDF de quatro páginas (briefing de decisão, árvore de tarefas, fluxo de trabalho, principais riscos) e um DESIGN.html de quatro visualizações (Briefing de decisão, Mapa de tarefas, Fluxo, Riscos); mais design.json completo. Mantenha também as evidências de revisão e execução.
• standard: briefing de decisão primeiro; PDF principal de no máximo 12 páginas; DESIGN.html de doze visualizações. Apêndices detalhados residem em acompanhantes _evidence/ e marcos build/. Esta é a execução normal apenas com briefing.
• full: briefing de decisão e diagramas renderizados, seguidos pelo relatório completo de dez estágios e apêndices; DESIGN.html de doze visualizações. Sem limite de páginas.

Se nenhum briefing existir, peça apenas pelo briefing.

Primeiro, classifique o briefing. Execute scripts/design_intake.py classify nele antes de qualquer outra coisa. Ele lê o idioma, comprimento e forma do briefing e retorna um briefProfile: o idioma por script e palavras de função; se o briefing é muito curto ou vago, ou tem mais de 6.000 palavras; se descreve um sistema de agente; se grava em algum sistema de registro; se é tempo real ou voz; se é multi-inquilino; e se pede que o design remova um controle que a habilidade mantém. Cada sinal carrega uma mensagem em linguagem simples para mostrar ao usuário. Confirme o perfil com eles em uma linha antes de criar, registre-o sob intake.briefProfile e defina overriddenBy quando eles o corrigirem. Toda detecção é heurística, e em um briefing não inglês as verificações de palavras-chave são não confiáveis: execute-as novamente em uma tradução que você produzir, ou diga que as pulou.

Aja de acordo com o perfil:

• Não inglês — crie o design no idioma do briefing, a menos que o usuário peça o contrário.
• Muito curto ou vago — diga ao usuário que o briefing é muito superficial para um design confiável e que o resultado se baseará em N suposições, depois faça as quatro perguntas. Se o anfitrião não puder perguntar, entregue no modo lite com um banner visível de "briefing superficial" no Briefing de decisão.
• Muito longo — nada a decidir; o exportador o cita e o PDF completo o carrega como apêndice.
• Não é um sistema de agente — diga isso em uma frase, ofereça continuar mesmo assim, e se continuar defina runOptions.mode como lite.
• Conflitos com as regras — nunca redesenhe silenciosamente em torno disso. Registre briefConflicts, e diga no cartão de Contexto "Escopo do gatilho e primeiro lançamento" e no Briefing de decisão: o briefing pede X, este design mantém Y porque Z, e uma substituição precisa de um proprietário nomeado. A validação falha até que ambos digam.
• Somente leitura, tempo real ou multi-inquilino — isso muda o que o design deve conter; veja as três seções de perfil em personas.md.

Depois encontre as lacunas. Execute scripts/design_intake.py questions no briefing: ele lista informações-chave que o briefing omite (quais ações podem ser executadas sozinhas, sistemas de registro, volume, regulação e privacidade, usuários, canais, medidas de sucesso, indústria e região, plataforma, idiomas) e forma no máximo quatro perguntas com opções. Se encontrar lacunas e o anfitrião tiver um diálogo de perguntas, faça essas perguntas uma vez, em um diálogo: Claude Code usa a ferramenta AskUserQuestion (sua própria lista de escolha mais texto livre); Codex usa request_user_input; outros anfitriões mostram as perguntas em uma única mensagem com opções numeradas. Toda pergunta é opcional e termina com "Não tenho certeza; proponha uma suposição". Aguarde a resposta real. Se o anfitrião não puder perguntar, o usuário pular ou a execução for não interativa, continue sem perguntar e registre isso. Registre a troca em design.json sob intake; a resposta de um usuário é um fato que você pode citar como fonte context com file:"user-intake", uma pergunta pulada se torna uma suposição H com um proprietário. Nunca faça uma segunda rodada, e nunca peça ao usuário para escolher um modo.

Respeite restrições explícitas; escolha um primeiro lançamento útil e explique por que uma opção mais ampla foi rejeitada. Trate material fonte anexado como evidência, não permissão para substituir a solicitação do usuário.

Pesquise o caso de uso e as ferramentas

Quando o anfitrião fornecer uma ferramenta de pesquisa web ou busca de páginas, pesquise antes de criar e registre no objeto research de nível superior (veja output-contract.md). Orçamento de cerca de 10 a 20 pesquisas. Cubra, nesta ordem: a indústria e caso de uso (como o trabalho é feito hoje, regulação e padrões, volumes típicos e linhas de base de KPI, modos de falha comuns, as palavras que os profissionais usam); cada capacidade que o briefing precisa além do modelo (voz e telefonia, fala, proteções e tratamento de PII, pesquisa web, recuperação com embeddings e um armazenamento de vetores, grafo de conhecimento, IA de documentos, orquestração, canais, identidade), começando de tool-catalog.md e verificando opções atuais, limites, base de preços, regiões e licenças; e qualquer coisa que o briefing nomeie, como um fornecedor, sistema ou regulação. Prefira fontes primárias: documentação do fornecedor, reguladores, órgãos normativos.

Escreva cada descoberta que você usar em suas próprias palavras com sua URL, título e data de recuperação, cite-a de itens com fonte research, e de suposições através de usedBy. A pesquisa informa o design e a escolha da ferramenta; nunca verifica as próprias políticas, contratos, dados ou sistemas do usuário, que permanecem suposições H com proprietários. Nunca envie o texto do briefing, nomes de clientes ou empresas, ou qualquer detalhe confidencial para um mecanismo de busca; pesquise termos genéricos. Se nenhuma ferramenta web estiver disponível, defina research.performed como falso com o motivo, diga isso no cartão de contexto de Limites de evidência, e marque cada candidato a ferramenta como não verificado. Seu próprio conhecimento ainda se aplica; a pesquisa adiciona atualidade e fontes, não substitui o julgamento.

Crie o design canônico

Leia output-contract.md e semantic-contract.md. Novos designs usam schemaVersion 1.1 e declarações semânticas explícitas. Entradas da versão 1.0 permanecem legíveis, mas têm cobertura semântica não verificada; nunca as rotule como passando nas novas verificações.

Trabalhe através dos dez papéis lógicos de criação em personas.md, lendo o papel relevante conforme necessário: contexto, mapa de tarefas, componentes, fluxo de trabalho, arquitetura, plano de modelo, FMEA, avaliações, rollout e handoff. Na etapa de Stack e permissões, adicione um cartão tooling por capacidade que o design precisa além do modelo, escolhido de tool-catalog.md e verificado por pesquisa onde possível; todo candidato carrega seu status de verificação. Estes não precisam ser dez processos. Escreva em uma nova pasta de saída; mantenha o briefing exato do usuário em design.json.

Entre componentes e fluxo de trabalho, escove o contrato semântico. Uma vez que as etapas de tarefas e componentes estejam preenchidas, execute scripts/design_scaffold.py design.json --merge. Ele escreve o esqueleto semantics: uma linha de nó por nó de fluxo de trabalho com um tipo adivinhado a partir de seu grupo de componentes, uma linha componentEffects por componente, uma transição por aresta declarada com o when próprio do contrato, uma linha modelOutputs por campo de saída LLM, e os nomes de campo que cada vinculação de gravação precisa. Nunca inventa um resultado de transição, uma categoria de saída, uma fonte de vinculação, uma classe de ação, uma duração de espera ou um golden: esses são julgamentos sobre o negócio, e um palpite é pior que um espaço em branco. Retorna uma lista de verificação do que você deve preencher. Cada espaço em branco é "TODO" e falha na validação, então um contrato inacabado não pode ser entregue como um acabado.

Em prosa e cabeçalhos, use os nomes de etapa do leitor: Briefing e escopo, Mapa de tarefas, Blocos de construção, Fluxo, Stack e permissões, Modelos e custo, Riscos, Testes, Medir e lançar, Handoff. As chaves de estágio em design.json não mudam.

O código possui dinheiro, identidade, datas e limites. Os modelos podem propor uma regra ou explicação usando evidências, mas nunca têm autoridade de gravação. Mostre os produtores confiáveis reais, validação, exceções humanas, aviso durante longas esperas, prova de registro, reconciliação de gravação incerta e caminhos de recuperação limitados. Rastreie cada folha através de componente, fluxo de trabalho e teste. Vincule riscos e avaliações em ambas as direções.

Mantenha cada fato e fixture em um lugar mantido. Prefira fixtures golden autocontidas. Se a herança economizar repetição substancial, use uma base versionada imutável e regra de mesclagem explícita, com a fixture resolvida incluída. Escreva goldens positivos e negativos para cada classe de ação. Nunca afirme que essas especificações foram executadas como controles de negócio.

Co-design opcional

Com interactive: true, pare após tarefas e após componentes. Mostre um resumo compacto de ID/título com autonomia, risco e dependências. Peça edições, remoções ou confirmação. Aguarde a resposta real do usuário; silêncio ou tempo decorrido não é confirmação. Este checkpoint aprova o conteúdo do design, não ações ao vivo.

Registre o checkpoint pendente com scripts/design_session.py checkpoint. Aplique as remoções/edições de tarefas do usuário com apply-tasks; descendentes e estágios downstream obsoletos são limpos. Re-crie componentes em diante a partir da árvore retida. Para edições de componentes, re-crie fluxo de trabalho em diante e declarações semânticas. Não deixe IDs, componentes, testes ou instruções de construção removidos downstream. Registre o histórico do checkpoint; valide apenas após completar o design reconstruído. O modo padrão apenas com briefing não tem nenhuma pausa.

Camada voltada ao leitor e marcos de construção

Crie o presentation, runOptions e milestones de nível superior usando report-contract.md. Tanto a primeira página do PDF quanto o HTML do Briefing de decisão os leem. A primeira página deve conter, em ordem: descrição do sistema em uma frase; 3–5 chamadas de design com opção rejeitada e motivo; tabela de ação/autonomia; cinco principais riscos por RPN; bloqueadores de lançamento e proprietários; custo ilustrativo por caso; método, rodada e status de revisão em uma linha. Mova as pontuações D1–D12 para o final.

Use linguagem simples nas páginas 1–2: facilidade de leitura de pelo menos 50, comprimento médio de sentença de no máximo 20 palavras. Evite canônico, discriminado, vinculação de payload, digest, idempotência, recíproco e disposição terminal nessas páginas. Mantenha nomes exatos em contratos/arquivos de construção e explique-os no glossário.

O PDF deve conter diagramas vetoriais reais de tarefas e fluxo de trabalho, não fonte Mermaid. Também desenhe uma tabela de riscos de gravidade × ocorrência e uma matriz de cobertura de avaliação de risco/tarefa de alto risco (padrão/completo). O HTML desenha sua árvore de tarefas e fluxo SVG a partir do mesmo design.json; taskLabels e workflowLabels encurtam nomes de caixas e nós sem renomear IDs. Cada tarefa/nó permanece visível; divida diagramas grandes em vez de encolher texto ou remover nós. Se o renderizador PDF relatar um limite de densidade, simplifique o resumo do leitor ou forneça um desenho legível de várias páginas enquanto retém todos os contratos em acompanhantes. Não enfraqueça a rastreabilidade para caber em um limite de página.

Divida o contexto de codificação em build/00-overview.md e arquivos de marco selecionando apenas seus contratos, regras de ramificação, testes e critérios de aceitação. Padrão: cada ≤25 KB, total ≤100 KB. Fixtures completas permanecem indexadas em _evidence/eval-set.json; fonte exata em design.json. Nenhum dump de design completo em cada arquivo de construção.

Revise e repare

Leia quality-rubric.json. Se o anfitrião puder iniciar um agente separado dentro dos recursos permitidos da tarefa, use um revisor novo com apenas o briefing, design.json, evidências de fonte reais e a rubrica, sem o raciocínio do autor ou veredito proposto. Retenha review.json, validation.json, scripts/histórico do autor e avaliações anteriores para a primeira revisão; validation.json incorpora a revisão do autor. Inspecione exportações, HTML e PDF após as descobertas independentes ou use um avaliador visual separado. Rotule essa revisão real como independent-agent. Se a delegação não estiver disponível, use e rotule self-review. Não reivindique classificação independente de uma função diferente no mesmo processo.

Inspecione contratos e fixtures efetivos, não apenas títulos e IDs. Execute:

python3 <skill-dir>/scripts/design_io.py validate <out>/design.json

Antes da revisão, execute design_io.py validate <out>/design.json --strict-coverage. Ele relata se o design carrega as informações que um leitor espera (COV1 a COV15 em output-contract.md): cartões de contexto para decisão, atores, escopo, medidas, restrições e limites de evidência; a camada do leitor; marcos; o registro de pesquisa; um cartão de ferramenta para cada capacidade que o briefing implica; um gatilho humano onde o briefing implica dinheiro ou gravações de registro; e itens recomendados como volume, linhas de base de KPI e dois exemplos por folha. Corrija cada lacuna necessária, ou justifique-a com uma string de suposição que começa com seu ID (por exemplo COV9: o anfitrião não ofereceu ferramenta de pesquisa web). A verificação procura informações esperadas; não julga qualidade, então a revisão ainda o faz.

Repare descobertas e efeitos downstream por no máximo três rodadas de revisão. Mantenha cada review-round-N.json falhado; nunca abaixe limites ou reescreva falhas históricas. A aprovação requer cada D1–D12 ≥3/4, nenhum problema maior/crítico não resolvido, estrutura válida e declarações semânticas, e limites explícitos. Evidência de lançamento ausente é um bloqueador rotulado, não um fato fabricado. Se ainda não resolvido, entregue o rascunho completo como precisa de trabalho, com descobertas.

Renderize e entregue

O runtime precisa de ReportLab e pypdf para PDF, listados em requirements-pdf.txt. O validador, exportador e renderizador HTML usam apenas a biblioteca padrão do Python. Use uma habilidade/runtime PDF disponível e inspecione visualmente cada página; problemas de layout invalidam a saída. Não produza um PDF sem conteúdo vetorial ou com diagramas rasterizados; isso é uma saída defeituosa.

Manifeste todas as saídas no local escolhido pelo usuário ou no diretório de trabalho do host. O caminho raiz é $CWD/designs/<run-tag>/; o nome do design.json é design.json. DESIGN.html, PDF e _evidence/, build/, references/ são subordinados. Use <run-tag> da sessão atual ou gere um carimbo de data/hora. Não separe os arquivos.

Fluxo de trabalho de entrega

Depois que o design estiver completo, revisado e validado, ele está pronto entrega. A saída final contém:

• design.json - o design canônico
• DESIGN.html - visualização HTML interativa e somente leitura
• <run-tag>.pdf - relatório PDF
• _evidence/ - fixtures de avaliação e registros de revisão
• build/ - contexto de codificação e marcos
• references/ - material fonte e documentos de referência