toyin-software-factory/sync

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

Escreva tudo que esta habilidade produz, arquivos e mensagens, em linguagem simples e clara. Fale com o leitor como você, de forma calorosa e direta como um colega, e apresente cada passo como uma recomendação que pode ser executada ou ignorada, nunca uma ordem. Mantenha os 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 curto, sem travessão longo 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 nos quais outras habilidades fazem correspondência mantêm seus hífens. Use frases curtas, vírgulas ou parênteses. Clareza vence esperteza.

O que esta habilidade faz

Fecha o ciclo de uma alteração concluída: sincroniza os arquivos AGENTS.md, o escopo e as linhas **Status**: das especificações vinculadas ao que o repositório agora mostra, e sinaliza o que não deve editar (especificações obsoletas, prosa curada). A tabela Limites abaixo é o contrato exato.

agent-prompt.md é a fonte única da verdade para as regras de manutenção; o SKILL.md cobre apenas orquestração. A thread principal o lê e faz a manutenção por conta própria (veja Passo 3).

Arquivo canônico: o contexto durável vive no AGENTS.md agnóstico de ferramenta; CLAUDE.md é apenas um ponteiro para ele. /sync edita/cria ambos, tratando-os apenas como alvos, nunca como fonte de alteração.

Limites

Ação	/sync	Proprietário
Editar AGENTS.md raiz/aninhado existente	✅ mantém	/sync
Reconciliar a linha ## Build approach do AGENTS.md raiz com a abordagem do cabeçalho de escopo (edição cirúrgica de linha única, como a pilha)	✅ mantém; sinaliza uma divergência curada	/sync
Adicionar uma linha de ponteiro para design.md (o sistema de design de UI) no AGENTS.md mais próximo quando uma alteração estabelece um	✅ mantém (apenas ponteiro)	/sync
Criar <area>/AGENTS.md aninhado para uma área nova nesta alteração	✅ cria (diff = contexto completo da área) + adiciona ponteiro raiz	/sync
Criar documento aninhado para uma área já existente não documentada (apenas cortada pelo diff)	❌ sinaliza "execute /audit"	/audit
Criar ou reestruturar o raiz AGENTS.md	❌ sinaliza "execute /audit"	/audit
Reconciliar a linha **Status**: de uma especificação com o status do escopo de sua funcionalidade (planned→Proposed, in-progress→In Progress, done→Accepted; uma especificação Assumed é a exceção: deixe-a como Assumed e a exiba, nunca a reconcilie para Accepted)	✅ Apenas linha de Status	/sync
Limpar uma especificação Assumed (movê-la para fora de Assumed)	❌ sinaliza como dívida de decisão "execute /architect para ratificar" (nunca reconciliada com o status da funcionalidade; apenas a ratificação a limpa)	/architect
Editar o conteúdo de uma especificação / substituí-la	❌ sinaliza como obsoleta	/architect
Reconciliar o escopo, apenas para o arquivo de escopo do workspace relevante (não todo docs/scope/), marcar qualquer subtarefa concluída a partir de evidências do repositório (código, testes, AGENTS.md), avançar status	✅ corrige	/sync
Adicionar / reordenar funcionalidades ou subtarefas no escopo	❌ deixa como está	/scope
Sobrescrever ou reescrever prosa curada do AGENTS.md	❌ sinaliza conflito em vez disso	humano

A linha divisória na criação é contexto, não política: crie apenas quando esta alteração mostra a área inteira; delegue a /audit quando a área pré-data a alteração e você viu apenas um pedaço. Quando estiver em dúvida, sinalize em vez de criar.

Pergunta vs ação

Age. Pausa apenas quando não há nada para sincronizar (conjunto de alterações vazio). Cada edição em arquivos curados é listada no relatório para que você possa revisar ou reverter.

Propriedade do artefato

Possui exatamente o que a tabela Limites concede e não escreve nada mais. Como o reconciliador universal de subtarefas, marca qualquer subtarefa do escopo que pode verificar a partir de evidências do repositório (varrendo as subtarefas /test//audit//sync que outras habilidades não marcam) e avança o status da funcionalidade; regras exatas em agent-prompt.md.

Base do artefato. Especificações e o escopo vivem sob docs/ por padrão, ou .workflow/ se docs/ for um site de documentação publicado; use a base que existir no repositório (caminhos aqui assumem docs/).

---

Portabilidade (qualquer SO, qualquer agente)

• Comandos: git é o único CLI necessário e se comporta da mesma forma em qualquer SO; execute as linhas git como mostrado. Outros trechos de shell são referência POSIX, não scripts literais: não assuma que find, grep, sed, cat, test/[ ], ls ou xargs existem; use as ferramentas de arquivo multiplataforma do seu agente e aplique a lógica de ramificação você mesmo, em vez de if/variáveis/redirecionamentos do shell.
• Arquivos empacotados: referenciados por caminhos relativos à pasta desta habilidade. Resolva a pasta para um caminho absoluto (você já resolve esses caminhos relativos) e leia agent-prompt.md você mesmo no momento da escrita (Passo 3), não durante os passos anteriores.
• Toda a manutenção é executada inline na thread principal, seguindo as regras exatas em agent-prompt.md (autoritativo).

Execução

1. Escopo do conjunto de alterações (barato, com status por arquivo)

Frescor primeiro (equipes): git fetch --quiet; se git rev-list --count HEAD..origin/$BASE > 0 você está atrás de origin/$BASE, avise o engenheiro para puxar primeiro, um colega pode já ter sincronizado esses documentos.

Base: main se git rev-parse --verify main for bem-sucedido, senão master. Branch atual: git rev-parse --abbrev-ref HEAD. Use --name-status (não --name-only); a lógica de área nova e limpeza de órfãos precisa de status por arquivo: Adicionado vs Modificado vs Excluído.

• Branch atual é a base, modo uncommitted: git diff --name-status HEAD.
• Caso contrário, modo branch: git merge-base "$BASE" HEAD, então git diff --name-status <merge-base>.

De qualquer forma, adicione arquivos não rastreados de git ls-files --others --exclude-standard, cada um prefixado com um status A (correspondendo ao formato --name-status). Anote o modo, a base e a base de merge para a etapa de escrita.

Remova duplicatas, então filtre para arquivos fonte a serem sincronizados de:

• Descarte documentação e configuração (AGENTS.md em qualquer nível, docs/**, *.md, test-preferences.json, arquivos de trava, saída gerada); /sync lê estes como alvos/contexto, nunca como fonte de alteração.
• Descarte arquivos de teste (*.test.*, *.spec.*, __tests__/, etc.); testes não são convenções de área duráveis.
• Mantenha as entradas D (excluídas) em uma lista separada; elas conduzem a limpeza de órfãos (Passo 3), embora não sejam sincronizadas de.
• Mantenha as alterações de manifesto de dependências em uma lista separada para descoberta de ferramentas, mesmo se forem configuração em vez de fonte: package.json, pyproject.toml, requirements*.txt, go.mod, Cargo.toml, composer.json, Gemfile, pubspec.yaml, mix.exs, *.csproj e manifestos de pacote equivalentes. Arquivos de trava são apenas sinais; não passe o conteúdo de arquivos de trava.

Se nenhum arquivo fonte e nenhuma alteração de manifesto de dependências restarem (apenas documentos/testes/trava/saída gerada foram alterados), pare, nada para sincronizar. Não inicie.

2. Localize os arquivos de contexto e especificações (apenas caminhos, NÃO os leia aqui)

Usando as ferramentas de pesquisa/glob de arquivo do seu agente:

• Anote se um AGENTS.md raiz existe.
• Encontre todos os AGENTS.md (raiz + aninhados), excluindo node_modules/ e .git/.
• Encontre todas as especificações sob docs/specs/ cujos nomes começam com um dígito, ordenadas.
• Encontre o(s) arquivo(s) de escopo cujo workspace/funcionalidades o diff realmente toca (em um monorepo, o workspace apps/<x>/… de um arquivo alterado seleciona docs/scope/<x>/); nunca leia ou passe todo docs/scope/.

Anote os caminhos mais a lista de arquivos alterados e o comando diff; leia os arquivos no momento da escrita. Leia o conteúdo do AGENTS.md raiz agora (curto e útil para ancorar). Para cada arquivo alterado, anote seu diretório envolvente mais próximo com um AGENTS.md (raiz ou aninhado); esse é o arquivo de contexto com maior probabilidade de precisar de uma atualização.

2.5 Descubra Habilidades de Agente e MCPs opcionais para ferramentas recém-adicionadas

Execute apenas quando manifestos de dependências mudaram ou o diff claramente adiciona uma ferramenta externa significativa. Pule bibliotecas utilitárias comuns, a menos que definam um fluxo de trabalho ou integração durável.

• Identifique pacotes/ferramentas significativos recém-adicionados a partir do diff do manifesto, não do arquivo de trava completo: framework, roteador, kit de estilo/UI, banco de dados, ORM/camada de consulta, auth/sessão, pagamentos, email/notificações, armazenamento/uploads, busca, fila/trabalhos em segundo plano, provedor de IA/banco vetorial, teste de navegador/tempo de execução, observabilidade, hospedagem/implantação. Inclua nomes de pacotes e aliases comuns a partir de manifestos. Não pare após a primeira tecnologia.

• Filtre qualquer coisa já coberta por habilidades instaladas, MCPs conectados ou entradas recusadas em AGENTS.md.

• Pergunte antes de pesquisar.

  Perguntar é obrigatório. Pesquisar não é. Nada é pesquisado, buscado, instalado ou iniciado para descoberta de Habilidade de Agente e MCP até que o engenheiro tenha escolhido. Ofereça quatro opções: encontre para mim, eu nomearei as que quero, não e registre a recusa, ou não agora. Apenas a primeira pode executar um comando de pesquisa. Nunca pule silenciosamente a oferta e nunca execute uma pesquisa antes que o engenheiro concorde com uma.

  Nomeie as ferramentas que esta alteração adicionou, diga em uma linha que uma Habilidade de Agente dá ao agente as convenções reais dessa ferramenta e um servidor MCP dá a ele acesso ao vivo ao sistema real, então pergunte: "Quer que eu encontre Habilidades de Agente e servidores MCP para as ferramentas que esta alteração adicionou?" (cabeçalho Habilidades de agente), com Sim, encontre para mim (recomendado) · Eu nomearei as que quero · Não, pule · Agora não, depois. Em Sim continue abaixo. Em Eu nomearei as que quero, pegue a lista e vá direto para a etapa de instalação, sem pesquisar nada. Em Não, pule não execute nada e registre a recusa. Em Agora não, depois não execute nada e anote as ferramentas candidatas no relatório.

• Isole as pesquisas em um subagente somente leitura (capacidade primeiro, apenas após Sim). Entregue o conjunto restante a um subagente de descoberta em vez de pesquisar na thread principal: inicie-o em segundo plano (ele não bloqueia) se seu agente suportar, senão bloqueante; defina seu modelo explicitamente para um nível rápido e de baixo custo (não herde o modelo da sessão; no Claude Code inicie-o como o tipo de subagente researcher, que fixa o modelo); ele retorna apenas a lista compacta de candidatos. Isso mantém a saída da pesquisa fora do contexto limitado de /sync. Sem subagente → pesquise inline; sem capacidade de pesquisa → pule e anote. O painel de oferta permanece na thread principal.

• Para cada item restante, execute npx skills find <ferramenta-ou-pacote>; se fraco, tente novamente aliases a partir de nomes de pacotes/orgs. Colete todos os candidatos a Habilidade de Agente críveis e confirme com npx skills add <proprietario>/<repo> --list quando prático. Se o CLI for interativo/indisponível, pesquise "<ferramenta>" "agent skill" e confirme antes de oferecer.

• Pesquisa MCP é opcional: primeiro lista de conectores, senão "<ferramenta>" "MCP server" por item. MCP é um benefício recomendado, não obrigatório.

• Mantenha a descoberta limitada e armazenável em cache: no máximo 5 pesquisas web e 8 páginas buscadas no total, registros oficiais/documentação primeiro. Reutilize docs/.agent-cache/tool-discovery/<slug>.md quando tiver menos de 30 dias, após filtrar itens instalados/recusados.

• Ofereça todas as correspondências de Habilidade de Agente em um painel de seleção múltipla, agrupadas por tecnologia: "Instalar Habilidades de Agente relevantes para ferramentas recém-adicionadas?" mais pular/recusar. Então ofereça MCPs separadamente: "Servidores MCP opcionais que podem ajudar estas ferramentas" mais pular/recusar. Nunca instale ou conecte automaticamente.

• Instale habilidades selecionadas com npx skills add <proprietario>/<repo> -y. Para MCPs, aponte para as configurações de conector/MCP do usuário; uma vez conectadas, as ferramentas são usadas automaticamente.

• Carregue o resultado como INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE e DECLINED_TOOLS_OR_NONE e registre linhas duráveis no arquivo AGENTS.md certo quando você escrever. Se nada foi encontrado ou nenhuma capacidade existe, trate como none.

3. Faça a manutenção (thread principal)

A thread principal faz a manutenção por conta própria; ela nunca entrega as edições de AGENTS.md / escopo / status de especificação a um subagente. Leia agent-prompt.md agora (apenas agora, no momento da escrita) e siga-o exatamente; ele é autoritativo para as regras de manutenção. A leitura do diff é a única coisa que você pode delegar, e apenas para um conjunto de alterações grande, para um subagente scout somente leitura no modelo mais barato (Claude Code: haiku) que retorna um mapa compacto. Permaneça dentro dos mesmos limites que a antiga concessão de ferramenta expressava: Edit documentos existentes, escopo e linhas **Status**: de especificação; Write estritamente para um AGENTS.md aninhado de área nova; nenhuma criação raiz, nenhuma edição de conteúdo de especificação (apenas linha de Status), nenhum documento aninhado superficial para áreas estabelecidas (estas são regras em agent-prompt.md).

As entradas a aplicar:

1. MODE, BASE, MERGE_BASE, CHANGED_FILES (lista de fonte alterada com status de nome), DIFF_COMMAND (comando git diff exato)
2. DELETED_PATHS (caminhos excluídos, para limpeza de órfãos)
3. ROOT_AGENTS_MD (conteúdo do AGENTS.md raiz), NESTED_PATHS (caminhos de AGENTS.md aninhados)
4. SPEC_PATHS (todos os caminhos de especificação, para reconciliação da linha de Status e sinalização de obsolescência)
5. FILE_TO_CONTEXT_MAP (arquivo alterado → arquivo de contexto mais próximo)
6. SCOPE_PATH_OR_NONE (caminho(s) de escopo do workspace relevante, não todo docs/scope/; também a fonte do status de cada funcionalidade vinculada para reconciliação da linha de Status da especificação)
7. INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, DECLINED_TOOLS_OR_NONE do Passo 2.5

4. Relate o resultado

Se a manutenção falhou ou não produziu um resumo analisável, relate isso e faça novamente, não invente um resultado (um NOTHING_TO_SYNC genuíno é um sucesso válido; uma falha ou saída vazia não é). Caso contrário, relate o resumo compacto:

Comece com o que reconciliou em uma linha; então liste apenas o que precisa do engenheiro (conforme docs/conventions.md). As edições em si estão nos arquivos. Modelo:

## /sync completo · reconciliou <N> arquivos alterados

**Atualizou <arquivos AGENTS.md · funcionalidades do escopo · status de especificações> para corresponder ao diff.**   (ou "tudo já atual, nada para sincronizar")
Atenção (precisa de você):
- Especificação obsoleta → /architect: `<arquivo>` (<por que, ou uma incompatibilidade de status que /sync não pôde reconciliar com segurança>)
- ...

Importante: nunca anexe ou faça engenharia reversa de uma lista de alterações completa; o diff já existe. Declare apenas o que /sync mudou e o que precisa do engenheiro após revisão.