grahama1970/agent-status

O que agent-status faz?

Use esta skill sempre que um agente de projeto estiver realizando trabalho de várias etapas e o humano precisar saber o que está realmente acontecendo.

Esta skill é intencionalmente não um gerador de painéis. Ela produz uma superfície de verdade apoiada por artefatos legíveis por máquina:

.plan-iterate/<campaign-id>/status/
  status.json
  events.jsonl
  proof_manifest.json
  STATUS.html

O HTML apenas renderiza o artefato de status atual. Ele não deve inventar progresso, porcentagens ou alegações de conclusão.

Princípio central

artefato de status primeiro → HTML renderiza o artefato → humano pode inspecionar a prova

Nunca faça isso:

página bonita primeiro → linguagem verde vaga → humano infere progresso

Respostas obrigatórias na primeira visualização

Uma página de status gerada deve responder:

1. O que o agente está tentando terminar?
2. Onde exatamente estamos?
3. O que acabou de passar?
4. O que ainda não está comprovado?
5. Qual é a próxima ação?
6. O agente está executando, bloqueado, ocioso ou esperando pelo humano?
7. Qual prova sustenta a afirmação atual?
8. O que o agente não deve fazer em seguida?

Modelo de estados

Estados permitidos:

• not_started
• running
• needs_attention
• blocked
• failed
• passed_scoped_gate
• done
• idle

Distinção importante:

passed_scoped_gate != done

Use done apenas quando o objetivo final declarado tiver um artefato de prova final explícito.

Comandos comuns

Inicializar uma campanha:

./run.sh init \
  --campaign refactor-harness-e2e \
  --goal "Terminar prova E2E do harness de refatoração com escopo"

Marcar uma porta como em execução:

./run.sh update \
  --campaign refactor-harness-e2e \
  --state running \
  --current-step "Executar porta de resumo LLM + OpenCode concorrente endurecida"

Registrar uma porta com escopo aprovada:

./run.sh gate-passed \
  --campaign refactor-harness-e2e \
  --label "A01-A18 LLM + OpenCode concorrente endurecido com resumo" \
  --verdict PASS_SPEC \
  --proof ".plan-iterate/refactor-harness-e2e/proof/refactor-concurrent-mixed.json" \
  --next-action "Iniciar pacote de revisor + fase de fan-in do revisor" \
  --not-proven "UI da Sala B1 de Transporte" \
  --not-proven "build_review_packet fan-in do revisor" \
  --not-proven "Entrega completa de mensagens OpenCode"

Perguntar ao humano por uma decisão:

./run.sh needs-human \
  --campaign refactor-harness-e2e \
  --question "Qual próxima campanha o agente deve executar?" \
  --option "A=Continuar harness: pacote de revisor + fan-in do revisor" \
  --option "B=Interface de Transporte: iniciar Sala B1 de Transporte" \
  --option "C=Estabilizar apenas: checkpoint e parar"

Renderizar a página de status novamente:

./run.sh render --campaign refactor-harness-e2e

Regras anti-teatro de painel

1. Sem porcentagens.
2. Sem "completo" em verde, a menos que exista prova do objetivo final.
3. Cada PASS deve nomear seu artefato de prova.
4. Cada status deve mostrar o que não está comprovado.
5. Cada estado ocioso deve dizer por que o agente está ocioso.
6. Cada estado de espera pelo humano deve incluir um menu de decisão.
7. Cada estado bloqueado deve nomear o artefato, serviço, porta ou decisão ausente.
8. A atualização automática é permitida apenas se a página ler status.json.
9. Se status.json estiver desatualizado, a página deve dizer desatualizado.
10. Vereditos do revisor são recibos, não prova de conclusão.

Quando usar

Use esta skill para:

• /plan-iterate
• /orchestrate
• /review-design
• /review-code
• /debugger
• /ask deep-review
• /code-runner
• /subagent-runner
• qualquer trabalho de agente de projeto de várias etapas que dure mais de um comando focado

Expectativas dos artefatos

status.json é a fonte da verdade.

events.jsonl é somente anexação e registra transições de estado.

proof_manifest.json lista artefatos de prova nomeados pelas afirmações de status.

STATUS.html é gerado, ciente de desatualização e seguro para abrir em um navegador.

Padrão de conclusão

Uma resposta final para trabalho de agente de longa duração deve resumir o artefato de status atual e vincular ou citar o caminho STATUS.html quando disponível.

Não reivindique conclusão a menos que:

• o estado seja done;
• last_completed.proof_path aponte para um artefato de prova final;
• not_proven esteja vazio ou explicitamente fora do escopo;
• os bloqueadores estejam vazios.