session-handoff

Files (7)

• SKILL.md
• handoff-template.md · references/
• resume-checklist.md · references/
• check_staleness.py · scripts/
• create_handoff.py · scripts/
• list_handoffs.py · scripts/
• validate_handoff.py · scripts/

SKILL.md (first lines)

# Handoff de Sessao

Cria documento de handoff que permite a um agente novo (ou a voce mesmo, numa
sessao futura) continuar o trabalho sem ambiguidade. Resolve o problema de
esgotamento de contexto em tarefa longa.

## Quando usar esta skill x as outras duas de handoff do HAOS

| Skill | Escopo | Quando usar |
|---|---|---|
| `session-handoff` (esta) | ENTRE SESSOES do mesmo trabalho, retomada por qualquer agente/dia | "salva isso pra eu continuar amanha", contexto ficando cheio, pausa de trabalho longo |
| `session-full-dump` | Dump EXAUSTIVO e deterministico de tudo que uma sessao fez (ferramenta, arquivo, comando, sub-agente) | Auditoria, "o que essa sessao fez de A a Z", nao precisa de curadoria |
| `haos-handoff-artefato` | Handoff de ARTEFATO entre AGENTES na MESMA tarefa (diretor-criativo -> dev, copy -> designer) | Encadeamento de sub-agente dentro do Rito ou de uma delegacao, artefato vai pro disco em `workspace/_handoff/` |

Esta skill e a mais "leve" das tres: um documento curado e legivel, nao um
dump bruto nem um artefato tecnico para outro especialista.

## Ajustes de doutrina HAOS

- Guardar handoff em `memory/handoffs/`, nunca em `.claude/handoffs/`.
- Em trabalho de sistema HAOS, criar handoff em
  `<SEU_CAMINHO>/memory/handoffs/` (raiz canonica do seu repo).
- Em trabalho de projeto/cliente especifico, criar handoff em
  `memory/handoffs/` daquele projeto quando existir; senao usar o workspace
  atual.
- Nunca escrever segredo, valor de token, cookie, senha, chave privada ou
  conteudo de `.env` num handoff. Registrar so o NOME da variavel de ambiente
  (MASTER.env, CLAUDE.md §11).
- Se a tarefa mencionar HAOS, Rito, Mega Brain, agente, seguranca, deploy,
  servidor ou Cloudflare, carregar o CLAUDE.md (usuario + projeto) antes de
  criar ou retomar um handoff.
- Acao externa sensivel continua bloqueada sem OK explicito do dono; um
  handoff pode DOCUMENTAR uma aprovacao pendente, mas nunca executa-la
  (CLAUDE.md §3, item 6).

## Selecao de modo

**Criando um handoff?** O dono quer salvar o estado atual, pausar o trabalho,
ou o contexto esta ficando cheio.
- Seguir: Fluxo CRIAR abaixo.

**Retomando de um handoff?** O dono quer continuar trabalho anterior, carregar
contexto, ou menciona um handoff existente.
- Seguir: Fluxo RETOMAR abaixo.

**Sugestao proativa?** Depois de trabalho substancial (5+ edicoes de arquivo,
debug complexo, decisao arquitetural grande), sugerir:
> "Fizemos progresso significativo. Considere criar um handoff para preservar
> esse contexto para sessoes futuras. Diga 'cria handoff' quando quiser."

## Fluxo CRIAR

### Passo 1: Gerar o scaffold

```bash
python scripts/create_handoff.py [slug-da-tarefa]
```

Exemplo: `python scripts/create_handoff.py implementando-auth-usuario`

**Para handoff de continuacao** (encadeado com trabalho anterior):
```bash
python scripts/create_handoff.py "auth-parte-2" --continues-from 2026-09-15-auth.md
```

O script:
- Cria `memory/handoffs/` se nao existir.
- Gera nome de arquivo com timestamp.
- Pre-preenche: timestamp, caminho do projeto, branch git, commit recente,
  arquivo modificado.
- Adiciona link de cadeia de handoff, se for continuacao.
- Mostra o caminho do arquivo gerado para edicao.

### Passo 2: Completar o documento

Abrir o arquivo gerado e preencher toda secao `[TODO: ...]`. Priorizar:

1. **Resumo do Estado Atual**, o que esta acontecendo agora.
2. **Contexto Importante**, informacao critica que o proximo agente PRECISA
   saber.
3. **Proximos Passos Imediatos**, claro e acionavel.
4. **Decisoes Tomadas**, escolha com motivo, nao so o resultado.

Usar a estrutura de [references/handoff-template.md](references/handoff-template.md)
como guia.

### Passo 3: Validar o handoff

```bash
python scripts/validate_handoff.py <arquivo-do-handoff>
```

O validador checa:
- [ ] Nenhum placeholder `[TODO: ...]` restante.
- [ ] Secao obrigatoria presente e preenchida.
- [ ] Nenhum segredo potencial detectado (chave de API, senha, token).
- [ ] Arquivo referenciado existe.
- [ ] Score de qualidade (0-100).

**Nao finalizar um handoff com segredo detectado ou score abaixo de 70.**

### Passo 4: Confirmar o handoff

Reportar ao dono:
- Local do arquivo de handoff.
- Score de validacao e alerta, se houver.
- Resumo do contexto capturado.
- Primeiro item de acao para a proxima sessao.

## Fluxo RETOMAR

### Passo 1: Listar handoff disponivel

```bash
python scripts/list_handoffs.py
```

Mostra todo handoff com data, titulo e status de conclusao.

From simtransforma/HAOS-CC-Model, MIT.

More from simtransforma/HAOS-CC-Model