Skip to Content
ConceitosSessões de Trabalho

Sessões de Trabalho

Uma work session é o contexto de execução para implementar um ticket. Iniciar, implementar, completar — com suporte completo para pausar, retomar, bloquear e validação no final.

O Que É uma Work Session?

Quando um agente (ou um humano) começa a implementar um ticket, uma work session é aberta. Ela rastreia tudo que acontece durante a implementação: quais passos foram completados, quais arquivos foram criados ou modificados, o que foi descoberto pelo caminho, e se o resultado final passa na validação.

Uma work session é escopo de um único ticket. Um ticket, uma sessão por vez. A sessão é dona do contexto de implementação — e quando ela fecha, as mudanças de status do ticket se propagam pelo grafo de dependência.

Ciclo de Vida da Sessão

Início

start_work_session({ ticketId: "tkt_abc123" })

O ticket deve estar em status ready — todas as dependências satisfeitas, sem bloqueios externos. Iniciar uma sessão:

  • Transiciona o ticket de ready para active
  • Retorna o contexto completo do ticket: passos de implementação, critérios de aceite, expectativas de arquivo, outputs de dependência e quaisquer blueprints vinculados
  • Se a especificação pai está em estado ready, ela transiciona para in_progress

O contexto retornado é tudo que o agente precisa para implementar sem fazer perguntas. Passos descrevem ações concretas. Critérios de aceite definem o pronto. Expectativas de arquivo listam o que deve ser criado ou modificado.

💡 O contexto retornado por start_work_session é deliberadamente auto-contido. Um agente deve ser capaz de implementar o ticket usando apenas este contexto, sem precisar consultar outros tickets ou ler a especificação completa. É isso que torna a execução paralela segura — cada worker opera em isolamento.

Rastreamento de Progresso

Durante a implementação, o agente reporta progresso através de action_work_session:

{
  "ticketId": "tkt_abc123",
  "steps": [
    { "index": 0, "completed": true },
    { "index": 1, "completed": true }
  ],
  "files": [
    { "path": "src/auth/jwt.service.ts", "action": "created" },
    { "path": "src/auth/jwt.service.test.ts", "action": "created" }
  ],
  "notes": "Used jose library instead of jsonwebtoken for Edge Runtime compatibility."
}

O rastreamento de progresso é incremental. O agente pode reportar com a frequência que quiser — após cada passo, após um lote, ou tudo de uma vez antes de completar. Cada relatório atualiza o estado do ticket no painel.

Você também pode reportar:

  • Resultados de critérios de aceite — Marcar critérios individuais como atendidos ou não atendidos com evidência
  • Resultados de teste — Submeter resultados de execução de teste (contagem de pass/fail, falhas específicas)
  • Descobertas — Novas informações encontradas durante a implementação que não estavam no plano original (ex.: um comportamento de API não documentado, uma coluna de banco de dados faltando)

Pausa

Um agente pode pausar uma work session sem completar ou abandonar. Isso é útil quando:

  • A janela de contexto do agente está ficando cheia e precisa compactar
  • O desenvolvedor quer revisar manualmente o progresso antes de continuar
  • Um ticket relacionado precisa de atenção primeiro (mas não é uma dependência formal)
  • A work session abrange múltiplas sessões de código ao longo do tempo

Pausar preserva todo progresso reportado até então. Passos completados, arquivos rastreados, notas registradas — tudo persiste. O ticket permanece em status active.

ℹ️ Pausar é implícito na prática. Se a sessão do agente termina (reset de janela de contexto, desenvolvedor fecha o terminal), a work session permanece aberta. A próxima sessão do agente pode retomar chamando start_work_session no mesmo ticket, que detecta a sessão existente e continua de onde parou.

Retomada

Retomar uma sessão pausada retorna o contexto do ticket mais todo o progresso reportado anteriormente. O agente vê:

  • Quais passos já estão completados
  • Quais arquivos já foram criados ou modificados
  • Quaisquer notas da sessão anterior
  • Critérios de aceite restantes a satisfazer

Isso significa que um agente pode continuar exatamente de onde o agente anterior (ou o mesmo agente em uma nova sessão) parou. Sem trabalho duplicado, sem contexto perdido.

Bloqueio

Durante a implementação, um agente pode descobrir um bloqueador externo — algo fora do escopo do ticket que impede a conclusão. Reporte:

{
  "ticketId": "tkt_abc123",
  "blockReason": "The user_accounts table doesn't have a last_login_at column. Ticket tkt_def456 should create this migration but isn't in the current specification."
}

Reportar um motivo de bloqueio força o ticket de volta ao status pending independente do estado de dependência. O bloqueio aparece no painel e nos resultados de get_blocked_tickets. O motivo do bloqueio é visível para o orquestrador, outros agentes e humanos monitorando o painel.

Para desbloquear, o motivo do bloqueio deve ser limpo — manualmente pela webapp ou pelo agente resolvendo a questão e chamando action_work_session sem um blockReason.

⚠️ Bloqueio é apenas para questões externas — coisas que não podem ser resolvidas dentro do escopo do ticket. Se os passos do próprio ticket são mais difíceis que o esperado, isso não é um bloqueio. Se o ticket depende de algo que ainda não existe e não foi capturado como dependência, isso é um bloqueio.

Conclusão

{
  "ticketId": "tkt_abc123",
  "summary": "Implemented JWT token generation service with RS256 signing and configurable expiration. All tests passing.",
  "actualHours": 1.5,
  "validation": {
    "tests": true,
    "lint": true,
    "typeCheck": true,
    "build": true
  }
}

Completar uma sessão:

  • Transiciona o ticket de active para done
  • Registra o resumo, horas reais e resultados de validação
  • Dispara recálculo em cascata (veja abaixo)

O resumo é importante — é o que aparece em relatórios e o que revisores veem durante o Implementation Review. Um bom resumo descreve o que foi construído, quaisquer desvios do plano, e por quê.

Resultados de validação (tests, lint, typeCheck, build) são opcionais mas alimentam a pontuação do Implementation Review. Se seu projeto exige evidência de testes, submeter validação aqui economiza um round-trip de review.

Efeitos em Cascata

É aqui que as work sessions se conectam ao sistema mais amplo. Quando um ticket completa, três coisas acontecem automaticamente:

1. Tickets Dependentes São Desbloqueados

Todo ticket que lista o ticket completado no seu array dependsOn é recalculado. Se todas as suas dependências agora estão done, ele transiciona de pending para ready — imediatamente disponível para o próximo agente pegar.

É assim que waves funcionam. Tickets da Wave 1 não têm dependências e começam como ready. Quando a Wave 1 completa, tickets da Wave 2 desbloqueiam. Quando a Wave 2 completa, a Wave 3 desbloqueia. O grafo de dependência dirige todo o fluxo de execução.

2. Auto-Conclusão do Épico

Quando todo ticket dentro de um épico alcança done, o épico é automaticamente marcado como completo. Nenhuma ação manual necessária.

3. Especificação Avança

Quando o último épico de uma especificação completa (todos os tickets em todos os épicos estão done), a especificação transiciona para ready_for_review — ou diretamente para completed se o Implementation Review está desabilitado nos Padrões de Qualidade do seu projeto.

Esta é a cadeia completa: ticket completa → dependentes desbloqueiam → épico auto-completa → especificação avança para review. Uma única chamada complete_work_session pode disparar tudo isso.

Reset

Tickets completados podem ser resetados de volta a um estado trabalhável:

{
  "specificationId": "spec_xyz789",
  "ticketIds": ["tkt_abc123", "tkt_def456"]
}

Reset limpa dados de sessão (conclusões de passos, notas, resultados de critérios de aceite) mas preserva commits e pull requests vinculados. O ticket recalcula para pending ou ready baseado no estado atual de suas dependências.

⚠️ Reset cascateia para baixo. Se o ticket B depende do ticket A e você reseta o ticket A, o ticket B também reverte para pending — mesmo se estava ready ou done. O grafo de dependência é sempre consistente.

Work Sessions e Agent Teams

Na implementação autônoma com Agent Teams, work sessions são a unidade atômica de distribuição de trabalho:

  1. O orquestrador chama get_next_actionable_tickets para encontrar tickets com todas as dependências satisfeitas
  2. Ele atribui tickets aos workers fazendo cada worker chamar start_work_session
  3. Cada worker implementa seu ticket, reporta progresso e chama complete_work_session
  4. O validador verifica o trabalho completado contra critérios de aceite
  5. A cascata desbloqueia a próxima wave de tickets
  6. O orquestrador atribui os tickets recém-desbloqueados aos workers disponíveis
  7. Repete até que todos os tickets estejam done

A work session garante que cada worker opere em isolamento com seu próprio contexto. Sem estado compartilhado entre workers. Sem conflitos de arquivo (o grafo de dependência previne dois workers de tocar a mesma área simultaneamente). Sem overhead de coordenação além do próprio grafo.

Veja Também

Gates de QualidadeBlueprints