softaworks/session-handoff

O que session-handoff faz?

Cria documentos de transferência abrangentes para transições perfeitas entre sessões de agente de IA. Acionado quando: (1) o usuário solicita handoff/memória/salvamento de contexto, (2) a janela de contexto se aproxima da capacidade máxima, (3) um marco importante da tarefa é concluído, (4) a sessão de trabalho está terminando, (5) o usuário diz 'salvar estado', 'criar handoff', 'preciso pausar', 'o contexto está ficando cheio', (6) retomando o trabalho com 'carregar handoff', 'retomar de', 'continuar de onde paramos'. Sugere proativamente handoffs após trabalho substancial (múltiplas edições de arquivo, depuração complexa, decisões de arquitetura). Resolve a exaustão de contexto do agente em execução longa, permitindo que novos agentes continuem sem ambiguidade.

Visão Geral

O session-handoff gera um documento de transferência detalhado que captura:

• Estado Atual: Marcadores de progresso, tarefas concluídas e pendentes.
• Decisões de Arquitetura: Escolhas de design e suas justificativas.
• Alterações de Arquivos: Lista de arquivos modificados, criados ou excluídos.
• Configuração do Projeto: Versões de dependências, variáveis de ambiente, estado do repositório.
• Contexto da Sessão: Discussões, decisões, e quaisquer notas adicionais.
• Metadados: Timestamp, nome do projeto, ID da sessão.

Plataformas Suportadas

• Claude Code: Acionável via comandos de linguagem natural.
• Cursor: Integra-se com comandos de chat e terminal.
• Codex: Funciona com prompts de código.
• Outros Agentes: Compatível com qualquer agente que suporte instruções markdown.

Como Usar

Disparo Manual

Digite qualquer um dos seguintes comandos durante uma sessão:

salvar estado
criar handoff
preciso pausar
o contexto está ficando cheio

Retomando uma Sessão

Para carregar um handoff:

carregar handoff [caminho/para/handoff.md]
retomar de [caminho/para/handoff.md]
continuar de onde paramos

Disparo Automático

A habilidade sugere automaticamente a criação de um handoff quando:

• Trabalho Substancial: Após 5+ edições de arquivo, depuração complexa, ou decisões de arquitetura.
• Limite de Contexto: Quando a janela de contexto atinge 80% da capacidade.
• Término da Sessão: Quando o usuário indica que a sessão está terminando.
• Marcos Concluídos: Após a conclusão de um marco importante.

Formato de Saída

O documento de handoff é gerado em markdown por padrão. Formatos alternativos (json, yaml) podem ser especificados:

criar handoff formato=json

Exemplo de Estrutura (Markdown)

# Handoff da Sessão - [Nome do Projeto]

## Metadados
- **Timestamp**: 2024-01-01 12:00 UTC
- **ID da Sessão**: sessao-001

## Estado Atual
- [Tarefas concluídas]
- [Tarefas pendentes]

## Decisões de Arquitetura
- [Decisão 1]: [Justificativa]

## Alterações de Arquivos
- `src/main.js`: Adicionada função `calcularTotal`
- `src/utils.js`: Corrigido bug no processamento de dados

## Contexto da Sessão
- [Discussões importantes]
- [Notas adicionais]

Boas Práticas

1. Crie handoffs regularmente: Especialmente após marcos importantes ou antes de pausas.
2. Seja descritivo: Inclua contexto suficiente para que o próximo agente entenda o estado.
3. Use o formato apropriado: Markdown para legibilidade, JSON para integração com ferramentas.
4. Mantenha os handoffs organizados: Salve em um diretório dedicado (handoffs/) com nomes descritivos.

Solução de Problemas

• Handoff não gerado: Verifique se o comando foi digitado corretamente e se a habilidade está ativa.
• Contexto perdido: Certifique-se de que o handoff incluiu todas as alterações de arquivo e decisões.
• Formato incorreto: Use handoff formato=json para saída em JSON, ou handoff formato=yaml para YAML.

Licença

MIT