Fluxo de trabalho diário

Este guia percorre uma rotina diária repetível com o AWR: verifique o estado do seu projeto, faça o claim ou retome uma tarefa, registre o progresso, faça checkpoint e realize o handoff para que você — ou um agente — possa continuar exatamente de onde as coisas pararam.

Antes de começar, certifique-se de que o seu projeto está inicializado e de que você conhece os conceitos básicos (itens de trabalho, sessões, claims, checkpoints) — veja o Quickstart e Conceitos. A mesma rotina funciona via MCP; veja MCP.

Uma nota sobre versões: algumas capacidades abaixo (a view de ação e work edit) refletem a árvore de código atual e podem não estar habilitadas no pacote publicado. Rode awr --help para ver o que a sua instalação suporta.

1. Comece o seu dia: encontre a próxima ação

Rode uma verificação de status antes de qualquer outra coisa:

awr status

awr status e a ferramenta MCP awr_project_status usam por padrão a view de ação (view="action"). Ela separa o seu trabalho aberto em quatro filas, com no máximo cinco entradas por fila mais contagens exatas de totais e de itens omitidos:

Restrinja a seleção com seletores repetíveis — eles se intersectam:

awr status --work GUIDE-1 --goal GOAL-1 --milestone M1

A fila é navegação, não autorização: claims e verificações de conclusão continuam aplicados pelas suas próprias ações. awr ready mantém o seu significado mais estreito — elegível para um novo claim — e omite trabalho em andamento.

2. Faça o claim ou retome a tarefa

Configure uma vez por shell para que todo comando fique vinculado ao projeto e formatado em JSON:

AWR_BIN=/absolute/path/to/awr
AWR_PROJECT=/absolute/path/to/initialized/project
AWR_WORK=EXAMPLE-001
AWR_AGENT=agent-primary
AWR_MODEL=your-current-model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

Trabalho novo, com claim sob uma nova sessão:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

O claim é posse de runtime; ele não reescreve o status do trabalho na fonte. Se já existir uma sessão para o trabalho, inspecione-a com session show e confirme a posse — um agente ou modelo diferente continua por meio de session resume na sua própria sessão.

3. Compile o seu contexto

Antes de editar, monte o pacote de contexto para a sessão:

awrj context bootstrap --session "$AWR_SESSION" --budget 1000 \
  > "$AWR_NOTES/bootstrap.json"
jq -e '.context.complete' "$AWR_NOTES/bootstrap.json"

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

Leia o pacote, não apenas o booleano. Em caso de BudgetExceeded, amplie o orçamento ou reduza o escopo; em caso de SourceStale, rode awr source reindex primeiro.

4. Trabalhe e depois faça checkpoint

Registre o que realmente aconteceu — falhas, contexto ausente e pontos em aberto:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

Algumas coisas para entender sobre checkpoints:

• --agent é uma declaração do chamador. Uma que não corresponda à sessão é rejeitada com orientação de resume; uma correspondente permanece não verificada — a CLI não consegue autenticar o modelo real por trás de um rótulo. Omiti-lo registra a origem como undeclared.
• O resumo e o hash de contexto são afirmações suas. Use o hash real último utilizado; um checkpoint salvo não prova contexto verificado, testes passando nem trabalho concluído.
• Para a proteção de revisão, use o project_revision de topo de session show, não session.revision. Em caso de conflito, inspecione as mudanças intermediárias antes de tentar de novo.
• Um checkpoint nunca reescreve a próxima ação respaldada pela fonte. Para mudar o contrato, edite a fonte autoritativa.

5. Corrija pequenos campos sem editar YAML à mão

Quando o plano-fonte precisa de uma pequena correção — digamos que a fonte diz "Draft the guide", mas o próximo passo real é "Review the conclusion" — pré-visualize a edição:

awr --json work edit GUIDE-1 --request-key guide-next-1 --actor writer \
  --reason 'Clarify the review step' --next-action 'Review the conclusion'

A resposta mostra a localização na fonte, os valores antigo e novo e as impressões digitais para aceitar. Revise-as e depois repita o comando adicionando:

--accept --source-fingerprint SOURCE_FINGERPRINT \
--expected-preview PREVIEW_FINGERPRINT --expected-revision REVISION

Os campos suportados são --title, --summary, --priority e --next-action. Após uma resposta incerta, verifique host status --key guide-next-1; uma edição de campo nunca muda posse, ciclo de vida ou verificação.

6. Encerre a sessão — ou faça o handoff

Quando você parar pelo dia:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

Encerrar libera o claim; não conclui o trabalho da fonte. O seu checkpoint do passo 4 é o que permite que o trabalho seja retomado de forma limpa.

7. Continue de onde você (ou um agente) parou

Mais tarde — ou a partir de um agente diferente — retome a partir da sessão predecessora:

AWR_PREDECESSOR=the-recorded-awr-session-id
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent "$AWR_AGENT" --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

O resume cria uma nova sessão AWR; ele não troca o chat nativo do seu host. Depois, compile o contexto de novo (passo 3) e continue. Após uma compactação do host, se a mesma sessão AWR ainda estiver ativa, basta compilar de novo — reserve session resume para um handoff real.

Para comparar o plano com o que foi registrado por último, verifique o objeto progress exposto por status --view action e work show KEY:

• source_next_action — o texto autoritativo do plano-fonte, com o seu locator, revisão da fonte e frescor.
• latest_checkpoint_next_action — o checkpoint mais recente para exatamente este trabalho, branch e posse, ou null se não houver nenhum.
• differs_from_source — true quando o texto do checkpoint diverge da fonte. Uma observação, não um problema: salvar progresso nunca modifica o contrato original nem estabelece conclusão.

O texto de progresso é limitado a 240 caracteres (sinalizado como truncated); use work show KEY e session show SESSION para o texto completo.

Quando algo dá errado

• Resposta de salvamento incerta → verifique host status --key REQUEST_KEY; use host recover apenas para uma operação pendente inspecionada.
• Conflito de revisão → leia status para obter o project_revision atual e tente de novo com ele.
• Checkpoint suspeito → leia o registro completo com session show SESSION; um salvamento interrompido sem recibo de conclusão não é um checkpoint de recuperação.

Para mais modos de falha, veja Solução de problemas. Para o vocabulário desta rotina, veja Conceitos.