toyin-software-factory/develop

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

Escreva tudo o que esta skill produz, arquivos e mensagens, em linguagem simples e clara. Fale com o leitor como você, caloroso e direto como um colega, e apresente cada passo 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, sem meia-risca 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 que outras skills correspondem mantêm seus hífens. Use frases curtas, vírgulas ou parênteses. Clareza vence esperteza.

O que esta skill faz

O construtor: transforma uma especificação mais as convenções do projeto em código funcional. Rastreia: UI (componentes, páginas, layouts; ui-guide.md), Lógico (APIs, serviços, camadas de dados, lógica de negócios, integrações; logical-guide.md), ou ambos (ex.: "auth" = páginas de login mais lógica de sessão → executa ambos). O Passo 0 depende da especificação para que escolhas estruturais (uma abordagem de autenticação, um provedor de pagamento) sejam decididas em /architect, não inventadas silenciosamente no meio da construção.

Pergunta vs ação

Portão, depois ação: sem rodadas de perguntas iniciais como /architect. Leia a decisão, construa, pergunte apenas o que o design deixou em aberto (a direção visual quando nenhuma referência foi dada; uma regra de negócio que a especificação não resolveu). Infira da especificação, AGENTS.md e base de código; recomende escolhas de implementação locais.

Propriedade de artefatos

• Escreve código do aplicativo (mais CSS/tokens para UI).
• Escopo (docs/scope/): apenas o Passo 4 toca (status da funcionalidade → in-progress, subcaixas de marco, caixa Construir, ponteiro de código). Marca uma funcionalidade como done apenas no nível de fluxo de trabalho Prototype (construir mais sua própria verificação; o engenheiro optou por não ter verificação separada); uma especificação Assumida não bloqueia isso, ela permanece sinalizada como devendo ratificação. Em Alpha/Beta/GA deixa a funcionalidade in-progress para /check verify e /test fecharem, e nunca marca Verificar ou Testar. Nunca cria arquivos em docs/scope/ (escopos apenas; análise/pesquisa é de /architect, no rationale.md da especificação).
• Nunca escreve conteúdo de especificação ou delibera uma decisão (sinaliza a necessidade, adia para /architect); nunca reestrutura o AGENTS.md raiz (isso é de /audit); novas convenções de área vão via /sync depois. Uma exceção estreita: em Construir agora, registrar como especificação assumida (Passo 0), /develop pode criar uma especificação, mas apenas em Status: Assumido, e apenas os campos de registro de suposição (decisão devida, suposição construída, autorizado por, área de código, sementes de requisitos). Nunca escreve rationale e nunca avança uma especificação Assumida além desse estado; /architect é responsável por limpar. Esta é a única especificação que /develop cria.
• Um toque de especificação em uma especificação existente: a linha **Status**: (decisão guarda-chuva → a do index.md, nunca de um filho), mais preencher a linha do ponteiro da especificação da funcionalidade. Início da construção: Proposto → Em andamento; construção finalizada (funcionalidade → done): Em andamento → Aceito (uma especificação não é Aceita até que sua funcionalidade seja entregue). Nunca edite o conteúdo da especificação, apenas essa linha, cirurgicamente: leia novamente antes de escrever; estado inesperado (já Aceito, Substituído) → sinalize, não sobrescreva. Nunca mova uma especificação para fora de Assumido (isso é ratificação, trabalho de /architect): uma especificação Assumida permanece Assumida durante toda a construção, mesmo enquanto a funcionalidade está in-progress, então nunca pode atingir Aceita até que /architect a ratifique. A funcionalidade em si ainda pode ser marcada como done (decisão do engenheiro); a especificação Assumida permanece sinalizada como devendo ratificação, não bloqueia done.
• Base do artefato: docs/ por padrão, .workflow/ se docs/ for um site de documentação publicado. Leia do que existir (caminhos aqui assumem docs/).
• Escopo compartilhado: leia novamente antes de marcar, edite apenas a caixa de seleção, status ou linha de ponteiro específica (nunca reescreva o arquivo); funcionalidade não como esperado (já done, retrabalhada) → sinalize, não sobrescreva.

---

Portabilidade (qualquer sistema operacional, qualquer agente)

Qualquer cliente Agent Skills, macOS/Linux/Windows. Snippets de detecção são referência POSIX; use as ferramentas de arquivo multiplataforma do seu próprio agente. Constrói inline no thread principal (Passo 3); os únicos subagentes são um scout somente leitura que explora código (Passo 2.5) e um researcher somente leitura para uma verificação de documento (Passo 2.6, degradando para construir a partir de conhecimento sem capacidade web), ambos no modelo mais barato. Guias agrupadas (ui-guide.md, logical-guide.md, checklist.md) e o fluxo de construção após o portão (flow/build.md) são caminhos relativos à pasta desta skill; o thread principal os lê. Nenhum seletor de perguntas interativo → faça as perguntas como texto simples com as mesmas opções.

Execução

Antes de construir: o projeto já deve existir (exceto a tarefa de scaffold)

Exceção: se esta É a subtarefa de scaffold da funcionalidade Fundação de Stack e Arquitetura (o prompt diz scaffold, ou o passo inicializa o projeto a partir da especificação de stack), criar o projeto É o trabalho. Leia a especificação ARQUITETURA ## Stack proposta; execute o inicializador de projeto da própria estrutura para a stack que a especificação nomeia; instale dependências base (estrutura, runtime principal, apenas o que a primeira fatia precisa); organize diretórios; confirme que um servidor de desenvolvimento ou build é executado. Mantenha o repositório que o inicializador criou (nunca descarte ao realocar o projeto); se ele não criou nenhum e a integração git está ativa, git init. Passos de scaffold derivam da decisão de stack (uma especificação de decisão não tem plano de construção). Instale apenas no momento: NÃO toda biblioteca que a especificação nomeia (email, monitoramento e assim por diante); cada funcionalidade posterior instala as suas quando construída; apenas ferramentas transversais (lint, formatação, tipagem estrita) vêm cedo, via /audit + a tarefa de ferramentas. Então prossiga.

Caso contrário, /develop constrói dentro de um projeto existente. Sem esqueleto (sem package.json/pyproject.toml/go.mod/manifest, sem árvore de origem) e não é a tarefa de scaffold → pare:

Nenhum projeto encontrado para construir. Execute o passo de scaffold primeiro (a subtarefa de scaffold da funcionalidade Stack e arquitetura, de acordo com sua especificação de arquitetura), depois execute /develop novamente.

Um projeto existe (mesmo um scaffold básico) → prossiga.

Antes de construir: atualidade e colaboração (não construa sobre estado desatualizado ou sobre o trabalho de um colega)

Antes de modificar qualquer coisa (pule silenciosamente se estiver sozinho, offline ou não usando git): git fetch silenciosamente; base = main, senão master; contagem de commits atrás (git rev-list --count HEAD..origin/<base>); trabalho não commitado (git status --short).

• Atrasado (contagem > 0) → pare e avise: "Você está N commits atrás de origin/$BASE. Um colega pode já ter alterado ou enviado isso. Faça pull primeiro, depois execute novamente."
• Trabalho não commitado na área que você vai tocar → avise: "Você tem alterações não commitadas aqui. Commit ou stash primeiro para que esta construção não se enrole com elas." Deixe que prossigam se insistirem.
• Funcionalidade in-progress no escopo E sua área de código (caminho da linha do ponteiro) tem commits recentes de outro autor (git log --format='%an' -- <area>) → avise: " parece estar em construção por outra pessoa. Coordene antes de continuar." Confirme antes de prosseguir.

Avisos, não bloqueios duros, mas exiba-os.

Integração git: se o AGENTS.md mais próximo ## Git diz integration: on, leia flow/git.md e siga (branch antes de construir, commit conforme marcos são atingidos); ausente ou off → não faça git ativo.

Passo 0: O portão da especificação (sempre primeiro)

Há uma decisão devida e não registrada? NÃO julgue isso por introspecção ("sinto que estou inventando algo?"), o modelo de construção racionaliza uma decisão real como "apenas cabeamento" e a deixa passar. Use um teste positivo de cobertura de entrada, que é mecânico e mais difícil de se convencer a ignorar:

Enumere cada valor que esta construção deve produzir, computar ou exibir (a partir dos critérios de aceitação e do design da especificação). Para cada um, a especificação nomeia de onde vem (uma entrada, uma coluna de BD, uma derivação de um valor nomeado, uma decisão anterior)? Qualquer valor obrigatório sem fonte nomeada é uma decisão devida.

Se alguma fonte não for nomeada, pare e direcione para o portão (/architect, ou registre uma especificação Assumida; /develop implementa decisões, não as toma). Uma decisão também é devida quando você teria que inventar:

• Um provedor, biblioteca, integração, modelo de dados ou padrão transversal (ex.: provedor de autenticação, BD/ORM, estratégia de cache).
• Uma página ou tela UI inteira: seu sistema de design (design.md lá? senão, qual direção?), seções/composição, inventário de componentes, estratégia de ativos (nenhuma captura de tela, sem imagens no repositório → ex.: uma fonte online). Devido a menos que um design.md E uma especificação de nível de página definam isso.
• O comportamento de uma funcionalidade (pesquisa, um assistente: "o que exatamente deve fazer?" está em aberto; /architect faz essas perguntas). Devido a menos que uma especificação o defina.

O que "detalhe de implementação local" realmente significa (a exceção estreita): APENAS uma escolha entre opções que as fontes nomeadas da especificação já permitem, um estilo de loop, um nome de variável, qual helper chamar. No momento em que uma escolha determina a fonte de um valor, ou um comportamento que um critério de aceitação restringe, ela é estrutural por definição, por menor que pareça. Derivar "o dia de hoje do usuário a partir do fuso horário na sua última linha lida" não é um detalhe local: escolhe a fonte de um valor que um AC restringe, portanto é devido. NÃO é devido para implementação puramente genuína: uma pequena correção de bug, um componente correspondente a um design.md existente, cabeamento de peças cujas fontes a especificação já nomeia, um ajuste de cópia, qualquer coisa que uma especificação/design.md/AGENTS.md existente governe completamente.

Não codifique nomes de páginas ou qualquer exemplo único (fuso horário é uma ilustração do padrão, não uma regra); aplique o teste de cobertura de entrada ao que foi solicitado. Falsos negativos são o modo de falha, construir uma decisão real sem perceber: quando a fonte de um valor obrigatório não é nomeada, ou você está inseguro, trate como devido e pergunte (painel abaixo).

Leia apenas o que esta funcionalidade precisa, nunca toda a árvore docs/: seu único arquivo de escopo e sua única especificação governante (arquivo único, ou index.md guarda-chuva mais o filho que especifica esta subtarefa). Nenhuma linha de outras funcionalidades, arquivos de escopo, workspaces ou especificações não relacionadas.

Verifique, em ordem:

1. Localize o arquivo de escopo desta funcionalidade (apenas aquele). Monorepo → docs/scope/<workspace>/ para o pacote da tarefa. Escolha o arquivo (scope.md, ou o <epic>.md correspondente em uma divisão) a partir apenas da tabela De relance; leia apenas a seção desta funcionalidade. needs a decision sem ponteiro de especificação ainda → decisão devida e ausente. Malformado → sinalize e pergunte, não adivinhe.
2. Abra a especificação governante através do ponteiro spec da funcionalidade, lendo apenas suas seções de especificação de construção conforme definido no fluxo de construção (flow/build.md), Passo 2 item 1. Encontrado → é a especificação; prossiga. Sem ponteiro e sem especificação vinculada → olhe direcionado em docs/specs/<workspace>/ por um correspondente ao escopo desta funcionalidade, nunca uma leitura geral.
3. O AGENTS.md mais próximo (workspace/área) pode já capturar a decisão, sincronizado de uma funcionalidade anterior (ex.: "o provedor de autenticação já foi escolhido") → prossiga sem uma nova especificação.

Decisão devida e não registrada → não adivinhe, não pare silenciosamente. Pergunte (seleção única; AskUserQuestion no Claude Code):

• pergunta: "Isso parece precisar de uma decisão de arquitetura primeiro: <nomeie a escolha estrutural específica, ex.: 'qual provedor de auth + modelo de sessão'>. Como você quer lidar com isso?"
• cabeçalho: "especificação primeiro?"
• opções:
  1. Arquitetar primeiro: "Recomendado. Capture a decisão em uma especificação antes de construir, para que a construção tenha uma especificação." → termine aqui com o handoff abaixo. Não construa.
  2. Não, não é necessário: "Julguei que não há decisão real aqui; construa diretamente." → prossiga para o fluxo de construção (flow/build.md).
  3. Construir agora, registrar como especificação assumida: "Construa, mas escreva a suposição primeiro para que a decisão viva no repositório, não apenas neste chat. A especificação Assumida permanece sinalizada como devendo ratificação (/architect), mas isso nunca bloqueia marcar a funcionalidade como done." → escreva uma especificação Assumida (abaixo), então prossiga para o fluxo de construção (flow/build.md), deixando a funcionalidade in-progress com uma nota assumed decision (spec NNNN) no escopo (docs/scope/).

A ferramenta anexa "Outro" como uma opção de texto livre automaticamente.

Em Construir agora, registrar como especificação assumida, escreva uma especificação Assumida mínima antes de construir (esta é a única escrita estreita de especificação que /develop possui; veja Propriedade de artefatos). Resolva $SPEC_DIR da forma que /architect faz (repositório único → docs/specs/; workspace monorepo → docs/specs/<workspace>/), pegue o próximo NNNN livre e escreva $SPEC_DIR/NNNN-<slug>.md:

# NNNN · <funcionalidade>

**Status**: Assumido
**Data**: <hoje>
**Autorizado por**: <engenheiro>, durante /develop

## Decisão devida
<a escolha estrutural específica que não foi feita>

## Suposição construída
<a suposição concreta que esta construção usará>

## Área de código
<os caminhos que esta construção tocará>

## Requisitos
<sementes de critérios de aceitação transportadas do Done when do escopo, se houver>

## Ratificar
Esta decisão foi registrada por /develop, não deliberada. Execute `/architect <funcionalidade>`
para deliberar e ratificá-la. Até lá, permanece sinalizada como uma decisão devida; não bloqueia marcar a funcionalidade como `done`.

Aponte a linha spec do escopo da funcionalidade para este arquivo. A suposição agora é durável: sobrevive a /clear, colegas a leem, e um /develop posterior constrói contra ela em vez de adivinhar novamente. A especificação Assumida permanece sinalizada como devendo ratificação; não bloqueia marcar a funcionalidade como done (veja flow/build.md, Passo 4).

Em Arquitetar primeiro, termine com:

Execute isso em seguida, depois volte ao /develop:

/architect <funcionalidade>: <a decisão específica a resolver>

Assim que a especificação existir, execute /develop <tarefa> novamente e eu construirei a partir dela.

Nenhuma decisão devida (implementação pura) → pule a pergunta, prossiga.

Fluxo de construção (Passos 1-4)

Em...