Configurar uma fábrica de software baseada em Archon e rever uma tarefa

O repositório AI Software Factory descreve o caminho da missão do produto e de uma tarefa até uma solicitação de integração criada por Archon. O instalador e as verificações dos fluxos são apenas o começo. O guia da primeira hora do responsável pela manutenção diz que a validação real de ponta a ponta ainda precisa ser feita. Este guia acompanha o commit da fábrica 9e2d85298b45497031009597a6ae0811b66fe6d6 e a revisão fixa de Archon fad09169ea1b43512bc7ee88470d47f960a3e0f8. É uma leitura da documentação e do código; não relata uma instalação ou execução feita pela BIG CHANGE.

O procedimento destina-se a uma equipa que controla o repositório de uma aplicação ou um PRD, as permissões GitHub e a conta do fornecedor de modelos. O responsável documenta expressamente a clonagem e instalação da fábrica no seu próprio repositório. A árvore da revisão fixa não contém licença nem aviso; este guia não estabelece direitos mais amplos de reutilização ou redistribuição. A licença MIT de Archon aplica-se ao código separado de Archon. Mantenha os segredos do fornecedor fora das tarefas, dos prompts, dos registos e das provas de revisão.

A grande mudança

• O que mudou: A implementação reúne escopo do produto, planejamento de tarefas, programação, revisão independente e verificações de execução em um pack fixo de fluxos Archon. A fábrica fornece entradas do projeto e inicializador; o pack partilhado contém as etapas de IA.
• Por que importa: A equipa pode rastrear uma proposta da tarefa até alterações, resultado de CI e candidato em execução específicos antes de decidir integrar. As verificações de instalação deixam essa trilha incompleta; o responsável pela manutenção afirma que a integração real ainda precisa de validação.
• O que acompanhar: A primeira prova útil é uma tarefa real cuja revisão entregue passe por jornadas significativas e casos reservados independentes, com custos e histórico de revisão visíveis à equipa. Agendamento e implantação continuam decisões separadas depois dessa revisão.

1. Verificar o repositório, as permissões e a fonte fixa

As instruções de instalação do responsável pela manutenção exigem Git, Python 3.10 ou posterior, gh autenticado com o escopo workflow, um remoto do GitHub, um agente de programação, Bun e uv. Git também precisa conseguir enviar ficheiros de fluxo (gh auth setup-git). Antes de executar o agente, confira os comandos existentes de teste, inicialização e CI, a proteção de branches, o acesso ao GitHub, a autenticação do provedor e a cobrança dos modelos. Conceda somente as permissões necessárias ao repositório e aos fluxos.

Clone a fábrica fora do repositório da aplicação e selecione o commit indicado. Na raiz da aplicação, o comando de instalação documentado é:

git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init

Use python3 se necessário. O instalador copia os modelos de fábrica e projeto e instala a fonte de Archon indicada em pack.json. O README e o pack desse commit especificam fad09169ea1b43512bc7ee88470d47f960a3e0f8. O instalador não autentica um provedor, escolhe categorias de modelos nem inicia um agendamento. Examine as alterações nos ficheiros antes de aceitá-las no repositório.

Configure o provedor escolhido e os identificadores de modelos compatíveis conforme a orientação instalada de Archon. Defina os comandos reais de análise estática e testes unitários em harness/harness.config.json. Quando o GitHub não informar a proteção de branches, indique em required_checks os trabalhos de CI necessários à integração. Reveja protected_paths para exigir uma pessoa nas mudanças da missão, da estrutura de validação e das regras da fábrica. O modelo deixa vazios os comandos comuns de verificação e required_checks; copiá-lo não estabelece um critério de aceitação utilizável.

2. Escrever a missão e as verificações do produto existente

Escreva em MISSION.md o propósito do produto, os limites rígidos e solicitações plausíveis fora do escopo. Em harness/END-TO-END.md, descreva de duas a cinco jornadas que a aplicação atual realmente conclui, incluindo o valor visível ao utilizador. Uma jornada que dependa de uma função ainda não construída bloquearia a primeira entrega. Em .factory/holdout/HOLDOUT.md, crie casos separados que combinem comportamentos ou explorem situações-limite. O nome do diretório não os esconde de quem desenvolve com acesso à mesma cópia; coloque casos realmente privados fora dela e forneça-os apenas à verificação.

Para um repositório com apenas um PRD, o README pede que a missão, as jornadas previstas e os comandos de validação venham do documento. A primeira tarefa proposta deve tornar o produto executável e informar comando de inicialização, caminhos de saúde e identidade da compilação, testes e CI. Reveja a proposta antes de permitir a publicação das tarefas.

Transforme as jornadas nas entradas de cenário esperadas pelos fluxos de execução de Archon. Siga o ficheiro instalado factory/RUNTIME_HOST.md para preparar uma cópia da aplicação a partir do commit entregue, um estado novo, verificações de saúde e identidade e os comandos de inicialização Python ou Node permitidos. O hospedeiro documentado não administra bancos remotos, contentores ou recursos de nuvem como recursos próprios de execução. Uma aplicação que os use precisa de um arranjo de verificação justificado à parte; uma verificação local bem-sucedida não demonstra seu isolamento.

Antes de confiar no avaliador, estabeleça uma referência aprovada que exercite valor real ao utilizador, mostre que uma falha deliberada relevante reprova e confira que a identidade errada do candidato produz um veredito inconclusivo. O guia do hospedeiro fornece as entradas e os campos exatos esperados, incluindo expectations_passed: true e baseline_verified: true. Guarde o retorno nativo real e a identidade do candidato como evidência. Verificar apenas o carregamento de uma página ou criar diretamente o estado final do teste é insuficiente.

3. Verificar a instalação e escolher uma tarefa

Execute na raiz da aplicação:

python factory/consumer.py doctor
python factory/consumer.py list

doctor verifica a fonte fixa, os recursos dos comandos e os fluxos disponíveis. list mostra os fluxos encontrados. Nenhum prova que um provedor conclui uma tarefa, que a CI passa ou que a aplicação funciona. Resolva as falhas informadas antes da entrega; mantenha o agendamento desativado.

Em uma base de código existente, escreva uma tarefa pequena com resultado claro e critérios de aceitação. O README documenta este comando para passar por triagem, entrega e revisão até uma solicitação de integração:

python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json

Substitua a URL por uma tarefa sob seu controle. A opção explícita discovery_publication=preview impede que descobertas próximas feitas na revisão sejam publicadas como tarefas; o fluxo fixo archon-ship usa auto por predefinição. Use archon-lifecycle somente com as entradas de cenário de execução e casos reservados prontas. Passe a tarefa como target, os caminhos de entrada como scenario e holdout, além de merge_mode=approve e discovery_publication=preview. Forneça também um merge_method aprovado pelo projeto: merge, squash ou rebase. Por exemplo, use merge_method=squash somente se o repositório permitir. Esse fluxo inclui verificação de execução e casos reservados, reparo e controle de integração. O modo de aprovação mantém uma decisão humana antes de integrar; uma indicação de pronto do fluxo não é essa decisão. Com o hospedeiro de execução da fábrica, a opção documentada --runtime-host funciona apenas em primeiro plano e não pode acompanhar --detach nem --resume.

Para um PRD, o comando documentado de backlog é:

python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve

Substitua docs/PRD.md, entre aspas no comando, pelo caminho real do PRD relativo à cópia da aplicação. Reveja as tarefas ordenadas propostas antes da publicação. Configure o hospedeiro de execução conforme o início da aplicação e o contrato de identidade declarados na primeira tarefa; depois processe-a com archon-lifecycle, usando jornadas e casos reservados preparados. A primeira tarefa exige o mesmo cuidado que as seguintes.

4. Avaliar as alterações e o resultado em execução antes de aprovar

Guarde o identificador retornado. O programa de controle oferece get <run-id> --json --events e status --all --json para acompanhar progresso e evidências. Compare a tarefa e o plano com MISSION.md; leia as alterações reais da solicitação e a revisão independente da versão atual; verifique a CI exigida e o relatório de caminhos protegidos. Execute as jornadas na revisão entregue e examine os resultados nativos de execução e casos reservados, incluindo a identidade do candidato. Compare o resultado observado pelo utilizador com os critérios de aceitação. Quem revisa deve devolver uma solicitação deficiente para reparo; o README descreve archon-deliver --adopt <run id> para uma entrega retida na fila de integração.

Somente uma pessoa com autoridade no repositório deve aprovar a integração após esses controles passarem. A implantação exige seus próprios comandos de implantação, saúde e identidade, além de uma releitura da revisão após implantar; uma solicitação integrada não prova que houve implantação. Deixe o agendamento desativado durante essa primeira tarefa e decida separadamente se haverá execuções recorrentes.

A orientação de custos do responsável pela manutenção não informa preço fixo por execução. Recomenda medir tokens desde o primeiro dia e observar chamadas de modelos em uma tarefa pequena antes de ativar um ciclo. As cobranças dependem do provedor, dos modelos e das condições da conta. A BIG CHANGE não mediu o gasto dessa fábrica.

Uma execução ativa também precisa de uma decisão explícita de parada. No código do programa de controle, halt bloqueia novos inícios e continuações; cancel <run-id> se dirige ao trabalho ativo. pause interrompe os inícios do temporizador, mas permite reativar trabalhos em andamento. Nenhum comando substitui verificar o estado atual da execução e as alterações no repositório remoto.

Fontes e leituras adicionais

• README da fábrica na revisão fixa: instalação, comandos, entradas do produto, escolhas de fluxos e limites declarados. Descrição do responsável pela manutenção, não evidência de execução pela BIG CHANGE.
• Manifesto do pack fixo e código do programa de controle: revisão de Archon, fluxos expostos e diferenças entre status, halt, cancel e pause.
• Guia da primeira hora e guia do hospedeiro de execução: ressalva do responsável pela manutenção sobre validação e requisitos de verificação vinculada ao candidato.
• Reportagem relacionada da BIG CHANGE sobre agentes de programação e trabalho concluído: contexto para verificar resultados terminados. Trata de um estudo separado, não de uma continuação datada dessa implementação.