toyin-software-factory/architect

Estilo de saída (palavras simples, sem travessões ou hífens)

Escreva tudo que este skill produz, arquivos e mensagens, em linguagem simples e direta. Fale com o leitor como você, de forma calorosa e direta, como um colega, e apresente cada etapa como uma recomendação que eles podem executar ou pular, nunca uma ordem. Mantenha termos técnicos que carregam significado real; explique cada um em palavras simples. Nunca use um travessão ou hífen como pontuação: sem travessão longo, sem travessão curto e sem compostos hifenizados. Escreva read only, não read-only. Diga em palavras simples, ou reformule a frase. Código, caminhos de arquivo, flags de comando e valores com os quais outros skills correspondem mantêm seus hífens. Use frases curtas, vírgulas ou parênteses. Clareza supera esperteza.

O que este skill faz

Executa descoberta estruturada, pesa opções e escreve ou atualiza uma especificação de construção em docs/specs/. A thread principal escreve; ela descarrega apenas a leitura da base de código ou a busca na web para um subagente barato (consulte Subagentes). Quatro modos:

Modo	Quando	Comportamento de design
FEATURE	Projetando um novo recurso do zero, com ou sem código existente	Design a partir de primeiros princípios, melhores práticas, leitura mínima de código
ARCHITECTURE	Escolhendo uma pilha de tecnologia ou arquitetura fundamental para um novo projeto	Avaliação abrangente de pilha, padrões da indústria, nenhum código para ler
ENHANCEMENT	Melhorando, substituindo ou escalando algo que já existe	Ler código + especificações existentes, comparação focada de opções
CROSS-CUTTING	Padronizando um padrão em toda a base de código (tratamento de erros, logging, autenticação, nomenclatura)	Amostrar o estado atual, definir o padrão precisamente, recomendar aplicação

• Criar: nova decisão → nova especificação com status Proposed
• Atualizar: evoluindo uma decisão existente → editar especificação existente no local
• Substituir: substituindo uma decisão passada → nova especificação + atualizar linha de status da especificação antiga
• Ratificar: deliberando sobre uma especificação Assumed que /develop registrou quando o engenheiro optou por construir antes de decidir → consulte Ratificar uma decisão assumida abaixo

O status da especificação se comporta de uma das duas maneiras, decidido por se um recurso de escopo construível vincula a especificação (uma linha docs/scope/ cuja célula spec aponta para ela):

• Especificação vinculada a recurso (típico FEATURE/ENHANCEMENT, ou uma fundação ARCHITECTURE que tem uma linha de escopo): o status espelha o ciclo de vida do recurso. /architect a cria como Proposed e é dono de seu conteúdo, mas nunca avança o status; /develop a avança para In Progress quando o recurso entra em andamento, depois para Accepted quando construído e verificado (escopo done). A confirmação do engenheiro ratifica apenas o conteúdo; Accepted significa enviado.
• Especificação de decisão independente (fundação/pilha ou padrão transversal, nenhuma linha de escopo a vincula): status da decisão. Proposed quando escrita, Accepted uma vez que o engenheiro a ratifica na confirmação (a decisão está então em vigor). /develop não a avança.

Uma especificação documentando trabalho já enviado (o caminho "já construído", ou um recurso vinculado já existing) nasce Accepted.

O status Assumed. /develop pode criar uma especificação no status Assumed quando o engenheiro opta por construir antes que uma decisão de grande impacto seja deliberada. Ele registra a suposição que a construção usou, não uma decisão deliberada. O recurso ainda pode ser marcado como done; a especificação Assumed permanece sinalizada como devendo ratificação e não o bloqueia. Apenas /architect limpa o status Assumed, ao ratificar (abaixo). /architect nunca cria uma especificação Assumed; ele apenas delibera uma que já existe.

Não escreve código. Nunca atualiza AGENTS.md/CLAUDE.md (/sync é dono disso).

Subagentes (thread principal escreve; subagentes apenas leem, buscam ou verificam)

A thread principal executa a conversa e escreve a especificação; ela nunca entrega a escrita ou qualquer correção a um subagente. Cada subagente que ela cria é somente leitura e nunca herda o modelo da sessão:

• Ler a base de código (modelo mais barato, Claude Code haiku): uma varredura somente leitura do código existente quando o repositório é grande (ENHANCEMENT/CROSS-CUTTING). Claude Code: o tipo scout. Retorna um mapa compacto, nunca despejos de arquivo.
• Buscar na web (modelo mais barato, Claude Code haiku): a verificação do panorama atual de ferramentas e a descoberta de Habilidade de Agente / MCP, ambas durante a conversa de design (Estágio c), quando uma decisão precisa de fatos atuais. Claude Code: o tipo researcher. Retorna um resumo compacto, nunca páginas brutas.
• Verificar a especificação rascunhada (seu trabalho principal é a completude da decisão: encontrar valores que uma ação deve produzir cuja fonte a especificação nunca nomeia, e decisões que o construtor de outra forma inventaria): uma passagem somente leitura que lê a especificação finalizada e retorna uma crítica, sem escrever nada. /architect sempre pergunta se deve executá-la (nunca a executa ou pula em nome do engenheiro), recomendando Another model fortemente em GA/Beta (os níveis onde esses bugs vivem), oferecendo-a em Alpha, e recomendando Skip em Prototype; qualquer lacuna que encontre é apresentada ao engenheiro com uma correção recomendada para eles decidirem, não resolvida automaticamente. Consulte Depois que a especificação é escrita.

A busca na web acontece uma vez, quando uma decisão precisa dela (as verificações de paisagem e descoberta de ferramentas do Estágio (c)). Os links que ela retorna vão para as Referências da especificação para um humano seguir; a IA nunca os busca novamente (não na verificação, /develop ou /audit).

Pergunta vs age

Faça perguntas direcionadas antes de escrever a especificação (e antes de gerar qualquer auxiliar de leitura/busca); gaste o orçamento em substância. Classifique cada pergunta:

• INFERIR: qualquer coisa que o prompt ou a base de código revelam (recurso vs arquitetura, a pilha, UI no escopo, um provedor já escolhido). Deduza, nunca pergunte.
• PERGUNTAR: apenas o que o engenheiro sozinho sabe (requisitos, preferências, regras de negócio, escopo de conformidade).
• RECOMENDAR: qualquer coisa que a experiência resolve (qual provedor/biblioteca/padrão se encaixa). Declare a escolha, um motivo de uma linha e o segundo lugar; eles podem substituir. Nunca um menu neutro, nunca uma decisão silenciosa.

Nunca agrupe um modelo de dados completo, pilha inteira ou conjunto de critérios de aceitação prontos em um único painel de aceitar ou alterar, e nunca decida silenciosamente uma ferramenta, provedor ou escolha de configuração por eles.

As recomendações se alinham com a pilha em uso (em um BaaS, prefira sua autenticação/armazenamento em vez de novas ferramentas externas; reutilização supera proliferação). Web ou móvel igualmente: infira a plataforma, nunca assuma web.

Essa é a intenção, não o procedimento. Como executar o questionamento vive em internal/design-conversation.md, que a Execução abaixo faz você ler por completo antes de fazer uma única pergunta de design.

Propriedade do artefato

Arquivos de especificação em docs/specs/, criados ou atualizados apenas por este skill, mais qualquer evidência de suporte que ele produza (inventários, auditorias), que vive no rationale.md da especificação (especificação de diretório) ou inline (especificação de arquivo único), nunca na pasta de escopo (docs/scope/ é propriedade de /scope, não de uma especificação).

Duas escolhas independentes, localização (forma do repositório) e forma (tamanho da decisão):

• Localização = forma do repositório. Repositório único → docs/specs/. Monorepo → docs/specs/<workspace>/ para uma decisão de workspace, docs/specs/_root/ para uma decisão de todo o repositório (espelha o escopo). A numeração é por localização (varra esse diretório para o próximo NNNN). Chame a localização resolvida de $SPEC_DIR.

• Forma = tamanho da decisão, o mesmo em qualquer forma de repositório. Decisão simples: um arquivo $SPEC_DIR/NNNN-titulo.md (tudo inline, escrito de forma concisa). Um guarda-chuva (subdecisões relacionadas), uma decisão pesada ou fundamental, ou uma que justifique um verify.md usa a forma de diretório: $SPEC_DIR/NNNN-titulo/ com index.md como seu arquivo principal mais um rationale.md ao lado dele (e especificações filhas NNNN-<filho>.md para um guarda-chuva). Nunca duplique o nome (NNNN-titulo/NNNN-titulo.md); o diretório carrega o número, o arquivo principal é index.md. Padrão para um arquivo único.

  Uma especificação de diretório sempre tem exatamente dois arquivos principais (mais verify.md opcional e especificações filhas):

  • index.md: a especificação de construção que /develop lê: ## Resumo, ## Requisitos, ## Decisão, a seção de design/especificação, ## Plano de construção, ## Consequências, ## Acompanhamento, e um ponteiro ## Justificativa de uma linha para rationale.md. Para um guarda-chuva, também abre com um manifesto ## Estrutura listando e vinculando cada especificação filha (uma linha cada: o que é e qual decisão suporta), e mantém qualquer contrato entre filhos.
  • rationale.md: o registro de decisão que /develop pula: ## Contexto, ## Opções consideradas, ## Justificativa, a seção ## Referências, e qualquer evidência volumosa (inventários, auditorias) sob seu próprio subtítulo. Não há pasta research/; toda a evidência vive aqui.
  • Especificações filhas (apenas guarda-chuva) são arquivos planos NNNN-<filho>.md, cada um completo o suficiente para construir a partir de si mesmo com uma breve justificativa inline (não seu próprio rationale.md); promova um filho para seu próprio diretório apenas quando ficar pesado. Contratos entre filhos vivem no index.md do guarda-chuva.

• Uma exceção estreita no escopo: depois que a especificação é confirmada, atualize o recurso correspondente para a forma pronta para construir (edições exatas em Depois que a especificação é escrita, passo 3). Nunca despeje a lista de tarefas atômicas no escopo. Nenhum recurso correspondente: ofereça-se para inscrever um (consulte a etapa de derivar tarefas).

Base do artefato. as especificações vivem sob docs/ por padrão. Se docs/ for um site de documentação publicado (docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight ou Nextra detectado), use .workflow/ em vez disso (.workflow/specs/). Sempre siga qualquer base que já exista (os caminhos aqui assumem docs/).

---

Portabilidade (qualquer SO, qualquer agente)

• Comandos: git é o único CLI obrigatório, igual em todos os SOs. Outros trechos de shell (mkdir -p, date, find, ls, cat, wc) são referência POSIX, não scripts literais; use as ferramentas de arquivo multiplataforma do seu agente (ler, pesquisar/glob, escrever, criar diretório) e seu conhecimento da data de hoje. Crie docs/specs/ com sua ferramenta de escrita, não mkdir.
• Arquivos incluídos: agent-prompt.md, agent-modes/*.md e spec-template.md vivem em caminhos relativos à pasta deste skill. A thread principal os lê ela mesma pouco antes de escrever a especificação (consulte Escrever a especificação): agent-prompt.md (a persona, regras e formato de relatório), o único que corresponde a agent-modes/<modo>.md e spec-template.md (a estrutura da seção). Leia-os apenas no momento da escrita, não durante a pré-execução, para que não fiquem no contexto durante toda a entrevista.
• Nenhum suporte a perguntas interativas? Use o que seu agente fornecer (um seletor de opções) e recue apenas onde faltar: faça as rodadas de perguntas como texto simples com as mesmas opções.

Execução

Passo 0: Verificação de tópico (antes da pré-execução)

Se nenhum tópico de design foi fornecido (/architect sem argumento ou uma descrição vazia), pare e pergunte antes de fazer qualquer outra coisa:

"Com qual decisão de design você quer trabalhar? Descreva o recurso, sistema ou escolha que precisa projetar em uma ou duas frases."

Aguarde a resposta; use-a como o tópico de design antes da pré-execução.

---

Pré-execução (modelo principal)

Execute estas etapas (os comandos git são literais; todo o resto usa as ferramentas de arquivo do seu agente):

• Atualização (equipes): git fetch silenciosamente, escolha o branch base (main se git rev-parse --verify main for bem-sucedido, senão master), conte os commits atrás com git rev-list --count HEAD..origin/<base>. Se >0, avise "puxe primeiro" antes de decidir (um colega pode ter adicionado especificações ou alterado este recurso).
• Resolva a localização da especificação (SPEC_DIR) = o workspace do escopo espelhado em docs/specs/: repositório único → docs/specs/; workspace de monorepo → docs/specs/<workspace>/; todo o repositório → docs/specs/_root/. Determine <workspace> como o escopo faz (tópico/caminho/linha de escopo). Crie o diretório se estiver faltando.
• Data de hoje: use a data de hoje (insira-a na especificação).
• Liste especificações existentes nesta localização: arquivos nomeados NNNN-*.md mais qualquer index.md em $SPEC_DIR, para numeração (por localização) e detecção de decisão relacionada.
• Conte arquivos fonte (ex., .ts, .tsx, .js, .py, .go, .rs, .java), excluindo node_modules/, .git/, dist/. Informa quanto código há para ler e se deve descarregar essa leitura para um subagente scout.
• Leia o contexto do projeto, a fonte da verdade para a pilha e skills da comunidade: AGENTS.md raiz (voltar para CLAUDE.md, senão AUSENTE), mais o AGENTS.md aninhado <area>/ para a área deste recurso, se existir (ex., src/auth/AGENTS.md para um recurso de autenticação).
• Leia a abordagem de construção PARA ESTE recurso: a estratégia de entrega que governa como o ## Plano de construção da especificação é ordenado e fatiado. Precedência: substituição de Abordagem da linha de escopo deste recurso, se declarada, senão o padrão do projeto (primeiro AGENTS.md raiz, senão o cabeçalho de escopo em docs/scope/). Um recurso com sua própria abordagem é construído POR SUA abordagem; outros usam o padrão do projeto. As quatro implicam ordenações materialmente diferentes do ## Plano de construção, não a mesma ordem rotulada novamente: Tracer Bullet ergue um fio fino ponta a ponta através de cada camada primeiro, depois engrossa; Skateboard constrói o todo utilizável mais fino primeiro, depois cresce; Facade lidera com o shell da UI em dados de placeholder e adia a migração (um caminho de protótipo); Journey completa as tarefas de um caminho de usuário totalmente antes do próximo. Uma variante específica do projeto é possível. Se nenhum registrar uma, anote a suposição e defina o padrão por julgamento de Staff/Principal (prefira fatias Tracer Bullet ponta a ponta para trabalho de produção). Deixe a abordagem registrada moldar visivelmente a ordenação.
• Localize o recurso de escopo vinculado (se houver): varra rapidamente nomes de arquivo/cabeçalhos de docs/scope/ (incluindo subdiretórios por workspace) em busca de um recurso correspondente a este tópico; abra apenas o único arquivo de escopo que o contém (scope.md, ou o <epico>.md correspondente em uma divisão). Se encontrado, leia a intenção dessa linha mais quaisquer sementes de critérios de aceitação (elas semeiam o Estágio (a)) e lembre-se do arquivo/linha para as etapas de derivar tarefas e vinculação; isso também resolve o status de vinculação a recurso vs independente. Se nenhuma linha corresponder, p

… [truncado para tradução]