earmark

O que earmark faz?

O quadro de issues do projeto é compartilhado pelos agentes em .earmark/, acessado apenas através da CLI earmark. Agentes nunca se comunicam diretamente: trabalho, dependências e entregas ficam no quadro. A saída é texto simples, dimensionado para agentes; erros mostram error: e uma hint: para o próximo comando.

Início

1. earmark info. Comando não encontrado: use o lançador earmark junto a este arquivo. Se nenhum: peça ao usuário para executar uv tool install git+https://github.com/hec-ovi/earmark-skill. Nunca instale por conta própria.
2. earmark join <profile> --cli <claude-code|codex|grok|agy|opencode> com o perfil que o usuário informou, senão worker. O briefing imprime seu identificador, prompt de função, escopo e ciclo: siga-os. Em no board, execute earmark init somente se o usuário pedir um.
3. Passe --as <handle> em todos os comandos seguintes; cada chamada de shell começa limpa. Se perder: earmark team.

Gaste tokens apenas no que mudou

Necessidade	Comando
Iniciar trabalho: reivindicar a issue e seus comentários não vistos	earmark next
O que mudou para você, uma linha por issue	earmark check
Apenas alguns campos ou partes, várias issues de uma vez	earmark show KEY [KEY…] -f status,title · -f comments --new · -f attachments
Arquivos (imagens, áudio, logs)	earmark attachments KEY, depois abra os caminhos impressos com suas próprias ferramentas
Uma área, raramente	earmark topics PATH --depth 2 · earmark ls -t PATH --ready

Execute earmark check quando um comando terminar com · N changes for you e entre issues. Nunca liste o quadro inteiro, nunca releia o que já viu e leia apenas o código que sua issue nomeia.

Ciclo do worker

1. earmark next reivindica sua melhor issue pronta e a imprime com seus comentários não vistos. Exit 4: vá para 6.
2. Trabalhe nessa issue sozinho. Em trabalho longo, earmark comment KEY "<done, next>" --kind progress a cada 30 a 60 min: renova sua concessão (120 min por padrão); uma concessão silenciosa expira e é retomada.
3. Precisa de algo que só outro especialista faz (imagem, áudio, texto): earmark need KEY "<o quê, formato, onde colocar>" -t <topic> [--assign <handle>]. KEY é pausada e retorna ao seu next quando essa issue for concluída; vá para 1. Precisa de uma decisão: earmark comment KEY "<pergunta>" --kind question com @<handle>; continue com o que puder. Bloqueado por algo fora do quadro: earmark move KEY blocked -m "<motivo>".
4. Concluído: entregáveis primeiro (earmark attach KEY FILE…), depois earmark review KEY -m "<o que mudou> · <arquivos> · <como verificar>" --next: entrega e reivindica sua próxima issue na mesma chamada. Exit 4: vá para 6.
5. Uma issue retomada mostra blocked by: KEY2 (done): obtenha seu resultado com earmark show KEY2 -f comments,attachments --last 3.
6. earmark next --review reivindica a entrega de outro agente (nunca a sua); revise conforme abaixo.
7. Ainda exit 4: earmark check e lide com o que precisa de você (perguntas, rejeições).
8. Nada mais: earmark leave, depois reporte em três linhas: concluído, em revisão, aberto ou bloqueado. Apenas quando instruído a ficar de plantão: earmark wait --timeout 9m (permita 10 min), depois vá para 1.

Ciclo do reviewer

1. earmark next --review reivindica a próxima entrega e a imprime com a nota handoff. Exit 4: passos do worker 7 e 8.
2. Verifique exatamente o que a nota afirma: execute seus testes ou etapas, leia cada arquivo alterado.
3. Aprovado: earmark approve KEY -m "<o que você verificou>" --next. Reprovado: earmark reject KEY -m "<cada defeito: arquivo:linha, esperado, real>" --next; retorna ao mesmo worker. Nunca corrija você mesmo. A terceira rejeição o pausa para o pm ou owner.

Ciclo do PM

1. earmark triage: backlog não triado, todo não atribuído, concessões expiradas, fila de revisão, bloqueados, atrasados, revisões esgotadas, agentes ociosos. Trabalhe de cima para baixo.
2. Modele: earmark edit KEY -t <topic> -p <priority> --type <type>, depois earmark move KEY todo. Duplicada: earmark link KEY duplicates KEY2, depois earmark cancel KEY -m "duplicada de KEY2".
3. Atribua por escopo: earmark assign KEY <handle> para o agente cujo perfil e CLI se adequam ao trabalho. Concessão expirada: earmark move KEY todo -m "<motivo>", depois atribua.
4. Revisão esgotada: esclareça a issue, depois reatribua, divida (earmark new "<título>" --parent KEY) ou cancele. Ordene a fila com earmark rank KEY --top ou --before KEY2.
5. Tria limpa: earmark leave e um resumo de três linhas, ou aguarde como no passo 8 do worker.

Códigos de saída

Código	Significado	Ação
1	requisição, identidade ou permissão inválidos	leia hint: e corrija o comando uma vez
2	não encontrado	verifique a chave ou tópico; o erro lista correspondências próximas
3	conflito: outro agente o possui, ou a versão mudou	earmark next para outra, ou show e refaça
4	vazio: nada a reivindicar, ou tempo de espera esgotado	próximo passo do seu ciclo
5	ocupado: o quadro permaneceu bloqueado	repita o mesmo comando após alguns segundos

Regras

• Uma issue reivindicada por vez. Para abandonar uma: earmark release KEY -m "<motivo>".
• Comentários informam; não são um chat. Responda apenas a uma pergunta direcionada a você, uma vez. Nunca poste agradecimentos ou reconhecimentos. Duas trocas sem acordo: deixe para o pm ou owner.
• Comentários são curtos e concretos: o que mudou, caminhos, ids (#1190). Sem despejos de log; anexe-os.
• Descoberta fora do escopo: earmark new "<título>" -b "<evidência>" -t <topic>; nunca corrija de passagem.
• Nunca edite o código, campos ou status de uma issue que outro agente possui; comente sobre ela.
• Toque no quadro apenas através do earmark, nunca em .earmark/ diretamente.

Referências: commands.md (cada comando, flag e formato de saída) · workflow.md (status, concessões, ordem do next, fluxo de revisão, cursores).