earmark

¿Qué hace earmark?

El tablero de incidencias compartido del proyecto reside en .earmark/ y solo se accede a través de la CLI earmark. Los agentes nunca se envían mensajes entre sí: el trabajo, las dependencias y las entregas viven en el tablero. La salida es texto plano optimizado para agentes; los errores muestran error: y un hint: con el siguiente paso.

Inicio

1. earmark info. Si el comando no se encuentra: usa el lanzador earmark junto a este archivo. Si tampoco: pide al usuario que ejecute uv tool install git+https://github.com/hec-ovi/earmark-skill. Nunca lo instales tú mismo.
2. earmark join <perfil> --cli <claude-code|codex|grok|agy|opencode> con el perfil que el usuario haya indicado, o si no, worker. El resumen muestra tu identificador, el rol, el alcance y el bucle: síguelos. Si aparece no board, ejecuta earmark init solo si el usuario lo solicita.
3. Pasa --as <identificador> en todos los comandos siguientes; cada llamada al shell comienza limpia. Si lo pierdes: earmark team.

Gasta tokens solo en lo que cambió

Necesidad	Comando
Empezar trabajo: reclamar la incidencia y sus comentarios no vistos	earmark next
Qué cambió para ti, una línea por incidencia	earmark check
Solo algunos campos o partes, varias incidencias a la vez	earmark show CLAVE [CLAVE…] -f estado,titulo · -f comments --new · -f attachments
Archivos (imágenes, audio, logs)	earmark attachments CLAVE, luego abre las rutas impresas con tus propias herramientas
Un área, raramente	earmark topics RUTA --depth 2 · earmark ls -t RUTA --ready

Ejecuta earmark check cuando un comando termine con · N changes for you, y entre incidencias. Nunca listes el tablero completo, nunca releas lo que ya viste, y lee solo el código que menciona tu incidencia.

Bucle del trabajador

1. earmark next reclama tu mejor incidencia lista y la muestra junto con sus comentarios no vistos. Salida 4: ve al paso 6.
2. Trabaja esa incidencia solamente. En trabajos largos, earmark comment CLAVE "<hecho, siguiente>" --kind progress cada 30 a 60 min: renueva tu concesión (120 min por defecto); una incidencia silenciosa caduca y es tomada.
3. Si necesita algo que solo otro especialista puede hacer (una imagen, audio, texto): earmark need CLAVE "<qué, formato, dónde va>" -t <tema> [--assign <identificador>]. La CLAVE se estaciona y vuelve a tu next cuando esa incidencia esté hecha; ve al paso 1. Si necesita una decisión: earmark comment CLAVE "<pregunta>" --kind question con @<identificador>; continúa con lo que puedas. Bloqueado por algo fuera del tablero: earmark move CLAVE blocked -m "<motivo>".
4. Hecho: primero los entregables (earmark attach CLAVE ARCHIVO…), luego earmark review CLAVE -m "<qué cambió> · <archivos> · <cómo verificar>" --next: entrega y reclama tu siguiente incidencia en la misma llamada. Salida 4: ve al paso 6.
5. Una incidencia reanudada muestra blocked by: CLAVE2 (done): obtén su resultado con earmark show CLAVE2 -f comments,attachments --last 3.
6. earmark next --review reclama la entrega de otro agente (nunca la tuya); revísala como se indica abajo.
7. Si aún hay salida 4: earmark check y atiende lo que te necesite (preguntas, rechazos).
8. Si no queda nada: earmark leave, luego reporta en tres líneas: hecho, en revisión, abierto o bloqueado. Solo si te indicaron que permanezcas en servicio: earmark wait --timeout 9m (permite 10 min), luego ve al paso 1.

Bucle del revisor

1. earmark next --review reclama la siguiente entrega y la muestra con la nota handoff. Salida 4: pasos 7 y 8 del trabajador.
2. Verifica exactamente lo que afirma la nota: ejecuta sus pruebas o pasos, lee cada archivo modificado.
3. Aprobado: earmark approve CLAVE -m "<qué revisaste>" --next. Rechazado: earmark reject CLAVE -m "<cada defecto: archivo:línea, esperado, actual>" --next; vuelve al mismo trabajador. Nunca lo arregles tú mismo. El tercer rechazo lo estaciona para el pm o propietario.

Bucle del PM

1. earmark triage: backlog sin triar, tareas sin asignar, concesiones caducadas, cola de revisión, bloqueados, vencidos, revisiones agotadas, agentes inactivos. Trabájalo de arriba a abajo.
2. Dar forma: earmark edit CLAVE -t <tema> -p <prioridad> --type <tipo>, luego earmark move CLAVE todo. Duplicado: earmark link CLAVE duplicates CLAVE2, luego earmark cancel CLAVE -m "duplicado de CLAVE2".
3. Asignar por alcance: earmark assign CLAVE <identificador> al agente cuyo perfil y CLI se ajusten al trabajo. Concesión caducada: earmark move CLAVE todo -m "<motivo>", luego asigna.
4. Revisión agotada: aclara la incidencia, luego reasigna, divide (earmark new "<título>" --parent CLAVE) o cancélala. Ordena la cola con earmark rank CLAVE --top o --before CLAVE2.
5. Triaje limpio: earmark leave y un resumen de tres líneas, o espera como en el paso 8 del trabajador.

Códigos de salida

Código	Significado	Acción
1	solicitud, identidad o permiso inválidos	lee hint: y corrige el comando una vez
2	no encontrado	verifica la clave o el tema; el error lista coincidencias cercanas
3	conflicto: alguien más lo tiene, o la versión cambió	earmark next para otra, o show y repite
4	vacío: nada que reclamar, o el tiempo de espera expiró	siguiente paso de tu bucle
5	ocupado: el tablero permaneció bloqueado	reintenta el mismo comando tras unos segundos

Reglas

• Solo una incidencia reclamada a la vez. Para abandonarla: earmark release CLAVE -m "<motivo>".
• Los comentarios informan; no son un chat. Responde solo una pregunta dirigida a ti, una vez. Nunca publiques acuses de recibo ni agradecimientos. Dos intercambios sin acuerdo: déjaselo al pm o propietario.
• Los comentarios son cortos y concretos: qué cambió, rutas, ids (#1190). Sin volcados de logs; adjúntalos.
• Hallazgo fuera de alcance: earmark new "<título>" -b "<evidencia>" -t <tema>; nunca lo arregles de paso.
• Nunca edites el código, los campos ni el estado de una incidencia que otro tenga; coméntalo en su lugar.
• Toca el tablero solo a través de earmark, nunca directamente en .earmark/.

Referencias: commands.md (todos los comandos, banderas y formato de salida) · workflow.md (estados, concesiones, orden de next, flujo de revisión, cursores).