aapastech/claude-skill-session-backlog

Aapastech Session Backlog: nunca perca uma tarefa

Sessões longas e prompts multitarefa fazem os assistentes de IA abandonarem trabalho. Pedidos iniciais desaparecem enquanto um turno posterior mergulha em um detalhe. Esta skill resolve isso com um backlog que vive no próprio computador do usuário. A memória da conversa não é a fonte da verdade; o backlog é. Uma tarefa que não está no backlog não existe, e uma tarefa no backlog não está concluída até ser marcada como Done (Concluída) ou Dropped (Abandonada).

Funciona com qualquer assistente ou agente que possa executar comandos shell no computador do usuário ou chamar ferramentas MCP. Cada sessão naquele computador, de qualquer ferramenta ou modelo, compartilha o mesmo backlog.

Regra de privacidade: os dados das tarefas permanecem no dispositivo que executa o trabalho. Nunca copie o backlog para um serviço em nuvem, uma página hospedada, um conector ou um documento compartilhado. Se nenhum dispositivo do usuário estiver acessível, use o modo Offline (seção 9).

1. Encontre o backlog e execute o motor

Se sua lista de ferramentas tiver ferramentas backlog_* (o servidor MCP, seção 11), use-as. Elas mapeiam um-para-um para os comandos abaixo e cuidam da pasta, codificação e atualizações para você. Pule o resto desta seção.

Caso contrário, o backlog é uma pasta contendo bl.py (o motor), config.json, tasks/ (um arquivo JSON por tarefa), sessions/, board.html e BOARD.md. Procure nesta ordem:

1. Um local que o usuário informou, em suas preferências, memória ou instruções do projeto.
2. A variável de ambiente BACKLOG_DIR, se definida.
3. ~/Documents/Aapastech-Backlog (o padrão).
4. ~/Documents/Claude-Backlog (o nome da pasta usado antes da v3; continue usando-o se for onde as tarefas do usuário estão).

Executando. Neste documento, bl <comando> é uma abreviação. Sempre digite o comando completo; nunca o armazene em uma variável de shell ($BL ... falha no zsh, o shell padrão do macOS).

Shell	Comando
macOS / Linux (bash, zsh)	python3 ~/Documents/Aapastech-Backlog/bl.py <comando> ...
Windows PowerShell	py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <comando> ... (se py estiver faltando, tente python)
Windows cmd	py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <comando> ...
Git Bash no Windows	py -3 ~/Documents/Aapastech-Backlog/bl.py <comando> ...

bl where imprime a pasta e a versão do motor que está usando. No Windows, Documents é frequentemente movido para o OneDrive (%USERPROFILE%\OneDrive\Documents). Se ~\Documents não existir, procure lá e ofereça-se para definir BACKLOG_DIR para que cada sessão encontre a mesma pasta.

Python. O motor precisa de Python 3.8+ e nada mais.

• macOS: a primeira chamada python3 em um Mac novo pode abrir o diálogo "instalar ferramentas de linha de comando para desenvolvedores" da Apple. Diga ao usuário que é esperado e seguro aceitar, ou instale o Python em python.org.
• Windows: Python geralmente não está instalado. Se py -3 e python falharem, peça ao usuário para instalar o Python 3 do python.org com "Add python.exe to PATH" marcado, ou winget install Python.Python.3.12. Não recorra a mais nada.

2. Primeira execução em um dispositivo (inicialização)

Se nenhum backlog existir ainda:

1. Crie a pasta ~/Documents/Aapastech-Backlog (ou o local escolhido pelo usuário).
2. Copie scripts/bl.py da própria pasta desta skill para dentro dela. É um único arquivo Python apenas com stdlib com o quadro embutido.
3. Faça uma pergunta curta ao usuário: qual nome mostrar para tarefas aguardando ele, e em quais áreas seu trabalho se enquadra (3–8 áreas, por exemplo, clientes, produtos, admin, pessoal). Sugira áreas a partir do que você já sabe sobre ele. Em seguida, execute: bl init --owner "<nome>" --areas "Area1,Area2,…,Pessoal,AI-Ops" Adicione --title "<Título do quadro>" se eles quiserem um nome próprio para o quadro (padrão "Aapastech Backlog").
4. Diga a eles a localização do quadro: file://…/Aapastech-Backlog/board.html. Ofereça-se para abri-lo (bl board --open) e sugira fixar a aba.
5. Sugira que eles tornem a skill sempre ativa, por exemplo, nas preferências pessoais do assistente ou arquivo de instruções: "Sempre carregue a skill session-backlog no início de cada sessão e antes de qualquer tarefa com trabalho."

Atualizações: se bl version imprimir uma versão inferior a scripts/bl.py nesta skill (procure por VERSION = "..."), copie o novo bl.py sobre o antigo. Os dados das tarefas e a configuração não são alterados.

3. Identidade da sessão (uma vez por sessão)

Escolha um id de sessão estável e reutilize-o em cada chamada:

• Se sua plataforma fornecer uma URL ou id para a sessão, use-o e passe a URL como --url.
• Caso contrário: <superficie>-<YYYYMMDD-HHMM> usando o horário de início da sessão, por exemplo, desktop-20261018-1652, code-20261018-0910, api-20261018-1200, sched-20261019-0600.

bl session --id <SID> --label "<Superficie> · <tópico principal>" --surface code|desktop|cloud|api|scheduled [--url <link>]

Isso imprime as tarefas abertas da sessão mais tarefas não reivindicadas ou obsoletas de outros lugares. Mencione tarefas atrasadas ou aguardando o usuário em uma linha. Não despeje a lista inteira.

4. O loop de turno (cada turno com trabalho)

A. Releia primeiro. No início de cada turno após o primeiro, execute bl open --session <SID>. Faça isso especialmente quando o prompt for um mergulho profundo em uma subtarefa. Este passo é o que impede que outro trabalho seja esquecido. Nunca pule.

B. Capture antes do trabalho. Cada novo pedido é capturado em um lote antes de qualquer trabalho começar. Isso inclui apartes como "também...", "lembre-me...", "depois...", "não esqueça...". Escreva o lote em um arquivo JSON com sua ferramenta de escrita de arquivos e depois passe o caminho. Um arquivo funciona em qualquer shell; canalizar JSON via echo quebra em shells do Windows e danifica texto não-ASCII.

[
 {"title":"Redesenhar página de preços","area":"Produto","eta":"1h","priority":"P1",
  "source":"prompt 16:52: refazer página de preços","next":"Puxar cópia atual",
  "children":[{"title":"Auditar cópia atual","eta":"10m"},
              {"title":"Rascunhar 2 layouts","eta":"30m"},
              {"title":"Publicar layout escolhido","eta":"20m"}]},
 {"title":"Responder ao fornecedor","area":"Admin","eta":"15m","status":"waiting_user","next":"Usuário confirmar quantidade"}
]

bl batch --session <SID> <caminho-para-arquivo.json> (coloque o arquivo em sua área de rascunho ou temporária, não no projeto do usuário).

Reproduza a captura em uma linha compacta para que o usuário possa corrigir:

Capturado: T-0042 Página de preços (1h) → T-0043 auditoria (10m), T-0044 layouts (30m), T-0045 publicar (20m); T-0046 Resposta fornecedor (aguardando você).

Verifique bl list primeiro e atualize uma tarefa existente em vez de criar uma duplicata. Adicione "parent":"T-0042" (ou --parent T-0042 no bl add) para colocar uma subtarefa sob uma tarefa existente.

C. Reivindique, depois trabalhe. Execute bl claim <ID> --session <SID> [--eta 20m] antes de começar cada tarefa. Se a reivindicação for recusada porque outra sessão ativa a possui, deixe-a em paz. As reivindicações são bloqueadas, então duas sessões nunca podem ganhar a mesma. Trabalhe em paralelo quando possível. A sessão orquestradora atualiza o backlog para seus subagentes, passando a cada subagente seu ID de tarefa.

D. Atualize enquanto avança. bl update <ID> --session <SID> --log "decisão / descoberta" [--next "..."] [--output <caminho ou link>] [--status blocked|waiting_user|ready]

• Registre as decisões do usuário com as próprias palavras dele.
• Cada arquivo ou link que você produz vai em --output.
• Aguardando o usuário significa --status waiting_user --next "<exatamente o que você precisa>".

E. Feche honestamente. Execute bl done <ID> --session <SID> --log "entregue ..." --output ... somente depois de verificar o resultado. Uma tarefa pai não pode fechar enquanto suas subtarefas estiverem abertas. Para abandonar uma tarefa, execute bl drop <ID> --session <SID> --reason "...". Nunca delete nada.

F. Rodapé. Termine cada resposta que envolveu trabalho com a saída de uma linha de bl footer --session <SID> [--exclude <IDs recém reportados>].

5. Áreas

Cada tarefa de alto nível recebe uma área de config.json (bl areas lista). Subtarefas herdam a área do pai. Escolha a que melhor se encaixa. Adicione uma nova área (bl areas --add "Nome") apenas quando uma nova linha de trabalho contínua aparecer claramente, e mencione isso ao fazê-lo. bl areas --rename VELHO NOVO renomeia uma área no config e em cada tarefa.

6. ETA (cada tarefa tem um)

• O ETA é o tempo de relógio para o assistente terminar, assumindo trabalho paralelo. Geralmente é de 5 a 60 minutos, às vezes horas, e raramente dias. Formato: 10m, 45m, 2h, 1h30m, 1d.
• Inclua tempo para verificar o resultado.
• A contagem regressiva começa na reivindicação ou criação. O quadro sinaliza tarefas atrasadas em vermelho.
• Quando você ultrapassar, reestime imediatamente: --eta 1h --eta-reason "...". Nunca deixe uma tarefa ficar atrasada em silêncio.
• Para uma tarefa waiting_user, o ETA é o tempo para terminar após o usuário responder.

7. Regras entre sessões

• Uma reivindicação permanece ativa enquanto sua sessão continuar atualizando a tarefa. Após 24 horas sem toque, fica obsoleta, e qualquer sessão pode assumi-la (a assunção é registrada).
• Nunca use --force em uma reivindicação ativa sem a permissão do usuário.
• Antes de um longo período de trabalho terminar, deixe cada tarefa reivindicada com um --next que uma nova sessão possa executar a frio. Libere trabalho não concluído com --status ready --log "liberado: <estado>".
• Para "o que está aberto", "onde estamos" ou "o que a outra sessão fez", responda a partir de bl list (--all, --area X, --session Y), não da memória da conversa.
• O backlog pertence a um dispositivo. Sessões em outros dispositivos, ou na nuvem, usam-no apenas através de um link para esse dispositivo.
• Se um comando disser que uma tarefa está ocupada, outra sessão está escrevendo nela naquele instante. Tente novamente depois de um momento.

8. Quando pular a captura

Pule a captura apenas para uma pergunta única respondida completamente na mesma resposta. Capture todo o resto: qualquer coisa com uma entrega, qualquer coisa que abranja mais de um turno, e qualquer coisa adiada. Em caso de dúvida, capture.

9. Modo offline (nenhum dispositivo do usuário acessível)

1. Espelhe as tarefas na própria lista de tarefas da sua plataforma, se tiver uma, ou em uma lista de verificação na sua resposta, caso contrário.
2. Enfileire cada operação bl.py pretendida, um objeto JSON por linha, em backlog-pending.jsonl em seu espaço de rascunho (nunca no projeto do usuário): {"cmd":"add","args":{...},"at":"<iso>"}.
3. Diga ao usuário uma vez: "Seu computador não está acessível, então as atualizações do backlog estão enfileiradas e serão sincronizadas quando ele voltar."
4. Tente o dispositivo novamente a cada turno. Quando estiver acessível, reproduza a fila em ordem e execute bl open.
5. Se a sessão terminar antes da sincronização, a última resposta deve listar as tarefas não sincronizadas por completo.

10. O quadro

board.html é regenerado em cada escrita e se atualiza a cada 30 segundos. Mostra:

• raias por área, com colunas A fazer / Em progresso / Bloqueado / Aguardando <proprietário> / Concluído
• o ETA e a contagem regressiva em cada cartão, com tarefas atrasadas em vermelho
• qual sessão criou, trabalhou e concluiu cada tarefa
• um clique para o registro completo e saídas

BOARD.md é o mesmo quadro como texto.

Quando o usuário pedir para vê-lo ("mostre meu backlog", "abra o quadro", "o que está aberto?"):

• No computador que contém o backlog, execute bl board --open para abri-lo no navegador padrão.
• Quando nenhum navegador naquele computador estiver acessível (por exemplo, um chat no celular), cole um breve resumo de bl list agrupado por área, com tarefas atrasadas e aguardando o usuário primeiro.
• O quadro é um arquivo local. Nunca é publicado, enviado ou compartilhado.

11. Notas de plataforma

• Clientes MCP (qualquer assistente ou framework de agente). scripts/backlog_mcp.py é um servidor MCP stdlib sobre stdio expondo backlog_session, backlog_open, backlog_add, backlog_claim, backlog_update, backlog_done, backlog_drop, backlog_list, backlog_show, backlog_footer, backlog_board, backlog_init e backlog_where. Registre-o com comando python3 (Windows py, args -3 <caminho>) e args <caminho para backlog_mcp.py>, opcionalmente com env BACKLOG_DIR. Ele executa o mesmo bl.py, então as rotas shell e MCP compartilham um backlog.
• Agentes orientados por API. Um modelo chamado através de uma API não tem acesso aos arquivos do usuário por si só. O desenvolvedor executa o servidor MCP (ou bl.py por trás de sua própria ferramenta) na máquina que possui o backlog e dá ao modelo essas ferramentas. Sandboxes de código hospedados são temporários, então um backlog lá é perdido quando o sandbox termina; não o mantenha lá.
• Sessões Claude desktop / cloud / celular vinculadas ao computador do usuário (ferramentas de dispositivo como device_bash, device_request_folder_access, device_commit_files; carregue-as via sua busca de ferramentas se estiverem adiadas). A pasta do backlog ou seu pai (por exemplo, ~/Documents) deve ser uma pasta conectada; se não for, chame device_request_folder_access uma vez com o motivo "para manter seu backlog de tarefas neste computador". Em seguida, execute comandos através de device_bash usando o caminho conectado (por exemplo, python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py ...). Para instalar bl.py através da ponte, prepare o arquivo e confirme-o no dispositivo (device_commit_files).
• Claude Code / Codex / Cursor / outros agentes de codificação executam o motor diretamente em seu shell, conforme a tabela na seção 1.

Referência de comandos

bl init    [--owner NOME] [--areas "A,B,C"] [--title T]       configuração inicial / alterar proprietário, áreas ou título do quadro
bl version                                                    versão do motor
bl where                                                      pasta do backlog, versão do motor, link do quadro
bl areas   [--add NOME ...] [--rename VELHO NOVO]             listar / adicionar / renomear áreas
bl session --id SID --label L --surface S [--url U]           registrar uma sessão; imprime tarefas abertas
bl open    --session SID                                      tarefas abertas desta sessão + não reivindicadas
bl batch   --session SID arquivo.json|-                       adicionar muitas ("children" aninhados = subtarefas)
bl add     --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim   ID --session SID [--eta 20m] [--force]
bl update  ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done    ID --session SID [--log L] [--output O] [--force]
bl drop    ID --session SID --reason R
bl list    [--all] [--area A] [--session SID] [--json]
bl show    ID
bl footer  --session SID [--exclude IDs]