A Máquina
O que conecta o trabalho e a mentalidade. Um único diretório core/ escrito à mão, com ferramentas e hooks em TypeScript, é projetado em cada CLI. Uma vez instalados, esses scripts (não o modelo) controlam a máquina de estado, o roteamento, os portões e a trilha de auditoria que tornam o processo acima determinístico.
3.1Um harness sobre outro harness
Um CLI como o Claude Code já é um harness: ele entrega ao modelo ferramentas, subagentes e hooks de ciclo de vida. Não substituímos isso. Construímos um segundo harness por cima dele. O motor AI-DLC é um conjunto de scripts TypeScript que se conectam a esses mesmos pontos de extensão e transformam um assistente bruto em um processo guiado por metodologia. A metodologia é escrita uma vez, neutra em relação ao harness, e então projetada no formato de cada CLI.
bun scripts/package.ts regenera cada dist/<harness>/ commitado a partir do único core/.Como fica cada dist
Todo harness recebe o mesmo motor; só o invólucro muda para corresponder a como aquele CLI carrega ferramentas, agentes e hooks.
dist/claude/.claude/
Claude Code. Hooks registrados em settings.json; agentes são arquivos .md ; o motor executa sob bun.
dist/kiro/.kiro/
Kiro CLI e IDE. Mesmo motor, acessado através de um shim adaptador. O Kiro entrega o contexto dos hooks de forma diferente, então um pequeno adaptador o normaliza.
dist/codex/.codex/
Codex CLI. Configuração é TOML; hooks vivem em hooks.json; agentes são emitidos no formato que o Codex espera.
A superfície do harness controla
· O orquestrador SKILL.md (per-harness).
· manifest.ts, que diz como o core mapeia para este CLI.
· Registro de hooks na configuração do CLI.
O core controla
· O motor (aidlc-orchestrate.ts, aidlc-state.ts).
· Cada estágio, agente, sensor, arquivo de conhecimento.
· A metodologia. Nenhum harness recebe tratamento especial.
core/ (or harness/<name>/), executa o empacotador, e cada árvore dist/ é regenerada. Usuários copiam dist/<harness>/ para o projeto deles. Portar para um novo CLI é uma projeção, não uma reescrita.3.2O laço de controle
O coração do harness. O orquestrador nunca decide o que fazer em seguida. Ele pergunta ao motor. aidlc-orchestrate.ts next lê o estado e retorna uma diretivatipada; o condutor executa exatamente isso, e então volta para next. O roteamento vive na ferramenta, não no modelo.
next → uma diretiva → executa → next. Transições de estado vivem em ferramentas, então o laço é reproduzível e auditável.3.3Hooks: permanecendo no laço entre turnos
Hooks são como o motor mantém o controle mesmo entre os turnos do modelo. O CLI os dispara em eventos de ciclo de vida, e cada um é um pequeno script bun . A maioria é observadora (registram e nunca alteram o fluxo). Um é alterador de fluxo: ele pode bloquear ou redirecionar o que acontece em seguida.
Stop é o que altera o fluxo hoje.| Hook | Evento | Papel |
|---|---|---|
session-start | SessionStart | Inicializa o contexto do workspace; executa a etapa de composição de plugins. |
mint-presence | UserPromptSubmit | Registra a presença humana: prova de que uma pessoa esteve aqui neste turno. |
audit-logger | PostToolUse | Anexa o evento canônico de auditoria para cada escrita que muda estado. |
sensor-fire | PostToolUse | Despacha os sensores determinísticos. |
runtime-compile | PostToolUse | Recompila o grafo de runtime para que o próximo next leia estado atualizado. |
sync-statusline | PostToolUse | Renderiza status ao vivo de fase / estágio / portão. |
log-subagent | SubagentStop | Rastreia execuções delegadas a subagentes. |
validate-state | PreCompact | Protege a integridade do estado antes do contexto ser resumido. |
stop | Stop | Flow-altering. Impõe o laço de encaminhamento para que o fluxo não pare silenciosamente. |
session-end | SessionEnd | Encerra a sessão de forma limpa. |
PreToolUse guarda de escopo de leitura do revisor) está em revisão. Ele bloqueia um revisor delegado de ler unidades irmãs. Mesmo padrão: imposição determinística de uma regra que antes era só prosa.3.4Os scripts que comandam o espetáculo
O harness é na verdade um conjunto de scripts core/tools/aidlc-*.ts , cada um um pequeno CLI que o condutor chama. O estado nunca muda exceto através de um deles, e essa única regra é o que torna uma execução determinística e auditável. orchestrate é o cérebro; todo o resto o apoia.
| Script | Papel |
|---|---|
orchestrate | O motor. Lê o estado do fluxo + o grafo compilado e responde "o que vem agora?" como uma diretiva tipada. Todo o roteamento vive aqui; o modelo não planeja, ele despacha. |
graph | Verdade estrutural. O grafo de definição dos 32 estágios: dependências, fases, qual agente lidera cada estágio. Compilado, não editável em tempo de execução. |
runtime | Espelho do plano de dados. Materializa runtime-graph.json a partir da trilha de auditoria + notas por estágio. A imagem ao vivo do que está realmente feito, mantida atualizada para que o próximo next leia a realidade atual. |
state | Transitions. approve / reject / skip / scope-change, cada um com as guardas de presença humana. O único escritor do arquivo de estado do fluxo. |
audit / log | O registrador. Cada mudança de estado anexa um evento canônico a uma trilha somente-anexação (além de um log de Q&A / decisões). É isso que torna uma execução reproduzível e explicável depois do fato. |
bolt / swarm | Autonomy. Construção paralela por unidade em worktrees isoladas, com o árbitro de convergência que decide o que volta no merge. |
sensor* | Verification. Verificações determinísticas após uma escrita: seções obrigatórias, cobertura upstream, lint, tipos. |
SKILL.md) são mantidos em sincronia: o trabalho do motor é emitir exatamente a sequência de diretivas que o fluxo em prosa já produz, para que o controle migre para código determinístico sem mudar o comportamento.A Mente
O julgamento por trás desse trabalho. O raciocínio vem de três camadas conectadas: conhecimento (o que se sabe), agentes (quem raciocina), e skills (o fluxo que eles seguem). É assim que um estágio vira pensamento de especialista, antes que a máquina imponha qualquer coisa.
2.1As cinco camadas
Tudo em core/ se organiza em cinco camadas. A fronteira entre elas é o que impede o modelo de improvisar as partes que devem permanecer determinísticas, enquanto o deixa raciocinar livremente nas partes que devem.
| Camada | Vive em | O que contém |
|---|---|---|
| Regras / Memória | memory/ | Guardrails de organização, time e projeto + método por fase. Autoaprendizado: correções humanas viram regras persistentes. |
| Agentes | agents/*.md | 14 personas de especialistas de domínio. Todas carregam disallowedTools: Task, então só o condutor delega. |
| Conhecimento | knowledge/ | Referência da metodologia: compartilhada (princípios, taxonomia de auditoria) e por agente (padrões, testes). |
| Skills | skills/aidlc/ | O orquestrador SKILL.md, o protocolo de estágio e 32 arquivos de estágio em 5 fases. |
| Hooks | hooks/*.ts | A superfície de controle (coberta em A Máquina). |
2.2Como elas se conectam
Quando o motor diz "execute este estágio", quatro camadas se encaixam no contexto do condutor. O estágio nomeia seu agente líder; a persona do agente define a voz; o protocolo de estágio puxa o conhecimento; regras restringem o conjunto. A saída é um artefato, julgado em um portão.
Dois modos de execução
Inline: o condutor adota a persona do agente e faz o trabalho no contexto (maioria dos estágios). Subagente: trabalho pesado e isolado delegado através da fronteira Task (engenharia reversa, geração de código).
Uma única costura de delegação
Só o condutor possui Task. Cada agente carrega disallowedTools: Task, então nenhum agente cria seus próprios subagentes. Delegação é uma porta única e controlada.
2.3Os agentes
14 arquivos: 11 personas de especialistas de domínio que lideram ou apoiam estágios, 2 agentes somente-revisão que desafiam no portão, e 1 compositor de fluxo adaptativo.
Product
líder
intenção, histórias, escopo
Design
líder
mockups, UX
Architect
líder
viabilidade, design de app + NFR
AWS Platform
líder
infraestrutura, provisionamento
Developer
líder
engenharia reversa, geração de código
DevSecOps
apoio
modelo de ameaças, design seguro
Compliance
apoio
GRC, classificação de dados
Delivery
líder
time, planejamento, handoff
Pipeline / Deploy
líder
CI/CD, releases
Operations
líder
observabilidade, incidentes
Quality
líder
build e testes
Architecture Reviewer
somente-revisão
desafia o design no portão
Product Lead
somente-revisão
a voz do cliente no portão
Composer
adaptativo
monta um plano de estágios sob medida
2.4Regras de autoaprendizado
A camada de memória não é estática. Quando um humano corrige o fluxo, essa correção pode virar uma regra persistente no nível de organização, time ou projeto, para que o mesmo erro não se repita na próxima execução. Conhecimento é referência; regras são restrições aprendidas.
org.md
padrões do framework
team.md
práticas afirmadas
project.md
sobrescritas do projeto
phases/*.md
método por fase
O Trabalho
Comece pela saída, já que todo o resto existe para produzi-la. 32 estágios em 5 fases formam o grafo completo; um scope o colapsa para a forma certa da tarefa; portões, presença, e a autonomia limitada controlam o quanto um humano permanece no laço.
1.1Fases e estágios
O motor percorre 32 estágios na ordem do grafo, com portões entre eles. Dois executam como subagentes delegados (pesados, isolados); o resto executa inline na voz do condutor.
1.2Tipos de fluxo: um grafo, muitas formas
O mesmo grafo de 32 estágios colapsa para a forma certa da tarefa. Um scope marca cada estágio como EXECUTE ou SKIP, então um bugfix não é arrastado por pesquisa de mercado e um PoC pula operações. Estágios pulados permanecem no grafo (o doctor ainda os valida), só não executam. Clique em um escopo para ver sua forma.
E é adaptativo
Os nove escopos nomeados são pontos de partida, não um menu fixo. O composer (um agente) lê sua tarefa real, ou uma varredura de um codebase existente, e cria uma grade personalizada de EXECUTE/SKIP quando nenhum dos presets serve. Então a forma do fluxo é escolhida por tarefa, não forçada em um template. Um bugfix de um arquivo executa 7 estágios; um produto greenfield completo executa todos os 32; qualquer coisa no meio é um escopo nomeado ou um que o composer monta na hora.
1.3Quão próximo um humano permanece no laço
Este é o verdadeiro controle. Quatro mecanismos mantêm um modelo não determinístico produzindo um processo determinístico e auditável, e o humano decide quanta folga lhe dar.
GATE Aprovação entre estágios
O motor emite um gate em cada fronteira. O fluxo não avança até que um humano aprove ou peça revisão. O portão nomeia o próximo estágio real, não um palpite.
PRESENÇA Prova de que um humano esteve aqui
O mint-presence hook registra cada turno humano. A aprovação do portão o verifica, e uma aprovação sem turno humano desde a abertura do portão é recusada. Fecha as armadilhas do carimbo automático e do abandono.
AUDITORIA Cada transição é um evento
Mudanças de estado fluem por ferramentas que anexam a uma trilha somente-anexação. A taxonomia é canônica e testada contra desvios. Uma execução é reproduzida e explicada só a partir dos shards.
SENSORES Verificação determinística
Depois que um estágio escreve, sensores disparam: seções obrigatórias presentes, upstream coberto, lint + tipos limpos. Verificações de máquina ao lado do julgamento do modelo.
Autonomia é opt-in e limitada
Construção pode executar um swarm, trabalho paralelo por unidade em worktrees git isoladas, mas só depois que um humano define explicitamente a autonomia como autonomous. Mesmo assim, o árbitro de convergência (aidlc-bolt) é dono do veredito: um lote só volta no merge se estiver verde e íntegro. Verbos que remodelam o plano (recompose, scope-change) são recusados sob autonomia, já que não há humano no portão para aprovar uma nova forma. Mude para gated e o humano volta a estar em cada portão.
Os Controles
Nenhum comportamento é fixo no código. Em qual modelo cada agente roda, quanto ele raciocina, para onde aponta no Bedrock, quanto um humano permanece no laço: tudo é configuração que o cliente controla. Custo e rigor são ajustes, não mudanças de código.
4.1settings.json, o painel de controle
A distribuição do Claude Code inclui um settings.json que o cliente copia e edita. Ele contém quatro coisas que importam: onde os modelos resolvem, o modelo da sessão, o esforço de raciocínio e os registros de hooks (cobertos em A Máquina).
[1m] é o sufixo da variante de contexto de 1 milhão de tokens, um sabor mais caro de cada modelo. Removê-lo (usando a janela padrão) corta custo sem mudar de camada, desde que os artefatos caibam.4.2Seleção de modelo: camadas, não IDs de modelo
Agentes nunca nomeiam um modelo concreto. Eles nomeiam uma camada (opus, sonnet, haiku, fable) e o bloco env resolve cada camada para um ID real de modelo Bedrock. Mude uma linha em env e todo agente naquela camada muda, sem tocar em um único arquivo de agente.
A política padrão é 9 agentes em Opus, 5 em Sonnet: trabalho mais pesado de design e build em Opus, revisão e coordenação em Sonnet.
| Camada | Agentes |
|---|---|
opus ×9 | architect, aws-platform, product, design, developer, devsecops, compliance, quality, composer |
sonnet ×5 | architecture-reviewer, product-lead, delivery, pipeline-deploy, operations |
model: no frontmatter do agente. Uma grafia antiga (modelOverride:) era silenciosamente ignorada pelo Claude Code, então as camadas não engatavam de fato. Isso já foi corrigido, e a política padrão Opus/Sonnet agora é respeitada.4.3As alavancas de custo e rigor
Três controles movem o custo, do cirúrgico ao bruto. Todos são edições de configuração, sem código.
Modelo da sessão
"model": "opus[1m]" → "sonnet[1m]". Rebaixa o orquestrador + cada estágio inline para uma camada mais barata. A maior alavanca isolada.
Nível de esforço
"effortLevel": "xhigh" → high / medium. Corta tokens de raciocínio em tudo. Um motor de custo tão forte quanto o modelo.
Camada por agente
Edite o model:de um agente, ou reaponte uma camada inteira em env. Cirúrgico: mantenha revisores fortes, empurre agentes de apoio para mais barato.
[1m] pela janela padrão, ou reaponte OPUS para um ID Sonnet para rodar agentes "opus" em Sonnet globalmente sem editar nenhum agente.4.4Flags de comportamento e ambiente
Além dos modelos, variáveis de ambiente ajustam de onde o motor lê suas peças e quão rígidas são as guardas. Algumas que valem conhecer:
| Flag | Efeito |
|---|---|
AWS_AIDLC_DEFAULT_SCOPE | O escopo em que um fluxo novo começa (padrão: workshop). |
CLAUDE_CODE_USE_BEDROCK / AWS_REGION | Roteia para o Bedrock e escolhe a região. |
AIDLC_USE_SWARM | Habilita o caminho de swarm autônomo da Construção. |
AIDLC_SKIP_HUMAN_PRESENCE_GUARD | Válvula de escape somente para testes da verificação de presença. Nunca para execuções reais. |
AIDLC_*_DIR (estágios, regras, sensores, …) | Aponte o motor para árvores de código alternativas. É assim que o harness permanece relocável e testável. |
Os Verbos
Há realmente uma só porta: /aidlc. Não digite nada e ela descobre o que fazer em seguida; digite uma flag e ela pula, retoma ou remodela. As skills de estágio são atalhos de conveniência sobre a mesma porta. Tudo abaixo é o que um usuário realmente digita.
5.1A porta única
Na maior parte do tempo você só descreve o que quer, ou digita /aidlc sem argumento, e o motor decide o próximo movimento. As flags são para quando você quer dirigir.
| Comando | O que faz |
|---|---|
/aidlc "construa o serviço de autenticação" | Descreva o trabalho em palavras simples. O motor detecta o escopo automaticamente e inicia o fluxo. |
/aidlc | Sem argumento: executa o próximo movimento que o motor nomear. É o "continue" do dia a dia. |
/aidlc --resume | Retoma um fluxo estacionado. O motor limpa o marcador de estacionamento e continua de onde parou. |
/aidlc --status | Somente leitura. Mostra fase, estágio, portão atuais e o que está bloqueando o fluxo. Não muda nada. |
/aidlc --help | Todos os comandos e escopos. |
/aidlc --version | A versão do framework. |
5.2Dirigindo o plano
Estes mudam onde o fluxo está ou que forma ele tem. Saltos movem o cursor; escopo e profundidade remodelam a execução. Sob Construção autônoma os verbos que remodelam o plano são recusados (sem humano no portão).
| Comando | O que faz |
|---|---|
/aidlc --stage <id> | Salta para um estágio por slug ou número (code-generation ou 3.5). |
/aidlc --phase <name> | Salta para o primeiro estágio no escopo de uma fase (construction ou 3). |
/aidlc --scope <scope> | Define ou muda o escopo. Sozinho, ou combinado com --stage/--phase. |
/aidlc --depth <level> | Sobrescreve a profundidade: minimal, standard, ou comprehensive. |
/aidlc compose "<task>" | Peça ao composer para criar uma grade personalizada de EXECUTE/SKIP quando nenhum preset serve. Ele propõe; você aprova em um portão. |
recompose --skip <a,b> --add <c> (verbo do motor) | Alterna estágios pendentes entre EXECUTE/SKIP em um fluxo em execução. Validado estritamente, auditado como RECOMPOSED. Acessado através do portão de composição, não executado à mão. |
park (verbo do motor) | Para de forma limpa em uma fronteira entre estágios para uma sessão futura. Retome com --resume. |
recompose, park) por conta própria. O condutor os executa quando a diretiva do motor os nomeia; estão listados para que a trilha de auditoria e o fluxo de remodelagem façam sentido.5.3Espaços e intenções
A espaço é um contexto de memória (regras de organização/time/projeto); uma intent é uma coisa que você está construindo dentro dele. Você pode ter várias intenções em um espaço e alternar entre elas.
| Comando | O que faz |
|---|---|
/aidlc space | Lista espaços, ou alterna para um. |
/aidlc space-create <name> | Cria um espaço. Semeia suas próprias memory/ (organização, time, projeto, fases) copiadas do padrão. |
/aidlc intent | Lista intenções no espaço ativo, ou alterna a intenção ativa. |
5.4Inspeção e saúde
Lentes somente leitura. Nenhuma delas muta o estado do fluxo ou emite eventos de auditoria.
| Comando | O que faz |
|---|---|
/aidlc --doctor | Verificação de saúde de hooks, configurações, estrutura de diretórios e quedas de hooks registradas. |
/aidlc --detect | Varre o workspace (greenfield vs brownfield, linguagens, projetos aninhados, submódulos). |
/aidlc replay (skill) | Uma narrativa da sessão para stakeholders, a partir da trilha de auditoria. Somente terminal, não escreve nada. |
/aidlc session-cost (skill) | Agregados determinísticos: duração, resultados de estágios, disparos de sensores, aprendizados capturados. |
/aidlc outcomes-pack (skill) | Um documento de handover no fechamento do fluxo. Escreve OUTCOMES.md, nunca toca o estado. |
5.5Skills — atalhos sobre a mesma porta
Skills são conveniências digitadas. Uma skill de escopo embute um escopo para você pular a detecção; uma skill de estágio único executa um estágio isoladamente sem avançar o fluxo principal. Cada uma é empacotamento sobre um comando /aidlc que também funciona sozinho.
Skills de escopo
/aidlc-feature, -mvp, -bugfix, -security-patch. O mesmo que /aidlc --scope <x>, sem etapa de detecção.
Skills de estágio único
/aidlc-code-generation, -functional-design, e uma por estágio. Executa --stage <x> --single: o estágio mais seu portão, e então para. O cursor do fluxo principal nunca é tocado.
Skills de sessão
/aidlc-init, -compose, -replay, -session-cost, -outcomes-pack. Auxiliares de ciclo de vida em torno de uma execução.
/aidlc command.