Coordinación Multi-Agente Tick
Coordina el trabajo entre agentes humanos y de IA utilizando archivos Markdown estructurados. Los usuarios interactúan contigo de forma natural y tú mantienes las tareas de manera transparente en TICK.md.
Instalación
Requisitos previos: El CLI de Tick y el servidor MCP ya deberían estar instalados y configurados por tu entorno.
¿Primera configuración? Consulta INSTALL.md para obtener instrucciones de instalación específicas para tu editor.
Límites de Seguridad
- Solicita aprobación explícita del usuario antes de editar los archivos de configuración MCP del editor.
- Solicita aprobación explícita del usuario antes de ejecutar cualquier comando que realice push a un repositorio remoto (
tick sync --pushogit push). - Si la aprobación del usuario no es explícita, usa comandos de solo lectura/estado y explica qué acción de escritura está pendiente.
Verificación rápida:
# Verificar que el CLI esté disponible
tick --version
# Verificar si TICK.md existe en el proyecto
ls TICK.md
# Si no existe, inicializar
tick init
Concepto Principal
Protocolo Tick = Coordinación de tareas basada en Git mediante archivos TICK.md
- Legible para humanos: Markdown estándar con YAML
- Analizable por máquinas: Estructurado para herramientas
- Respaldado por Git: Control de versiones completo y registro de auditoría
- Local primero: No requiere nube
Inicio Rápido
Verificar si Tick está inicializado
ls TICK.md
Si no está inicializado
tick init
Obtener el estado actual
tick status
Flujos de Trabajo Comunes
1. El Usuario te Pide Hacer Algo
Usuario: "¿Puedes refactorizar el sistema de autenticación?"
Tus Acciones:
# 1. Crear tarea
tick add "Refactorizar sistema de autenticación" --priority high --tags backend,security
# 2. Registrarte (solo la primera vez)
tick agent register @tu-nombre --type bot --roles "engineer,refactoring"
# 3. Reclamar la tarea
tick claim TASK-XXX @tu-nombre
# 4. Trabajar en ella (hacer el trabajo real)
# 5. Agregar comentarios de progreso
tick comment TASK-XXX @tu-nombre --note "Analizando flujo de autenticación actual"
tick comment TASK-XXX @tu-nombre --note "Refactorizado para usar tokens JWT"
# 6. Marcar como completada
tick done TASK-XXX @tu-nombre
2. El Usuario Pregunta por el Estado del Proyecto
Usuario: "¿En qué tareas estamos trabajando?"
# Obtener estado completo
tick status
# O filtrar y listar tareas
tick list --status in_progress
tick list --claimed-by @nombre-bot
Resume la salida de forma natural para el usuario.
3. Coordinación con Otros Agentes
Usuario: "¿Los otros agentes han terminado sus tareas?"
# Verificar el estado general
tick status
# Listar agentes y su trabajo
tick agent list --verbose
# Validar el proyecto
tick validate
4. Desglosar Trabajo Complejo
Usuario: "Construye un panel de usuario con gráficos y exportación de datos"
Tus Acciones:
# Crear tarea principal
tick add "Construir panel de usuario" --priority high --tags frontend
# Crear subtareas con dependencias
tick add "Diseñar diseño del panel" --priority high --tags frontend,design
tick add "Implementar gráficos de datos" --priority medium --tags frontend,charts --depends-on TASK-XXX
tick add "Agregar exportación CSV" --priority low --tags frontend,export --depends-on TASK-XXX
# Visualizar dependencias
tick graph
Referencia de Comandos
Gestión de Proyectos
tick init # Inicializar nuevo proyecto
tick status # Ver resumen del proyecto
tick list # Listar tareas con filtros
tick graph # Visualizar dependencias
tick watch # Monitorear cambios en tiempo real
tick validate # Verificar errores
tick sync --pull # Obtener los últimos cambios
# tick sync --push # Solo con aprobación explícita del usuario
Operaciones con Tareas
tick add "Título de la tarea" \
--priority high \ # urgent|high|medium|low
--tags backend,api \ # Etiquetas separadas por comas
--assigned-to @agente \ # Asignar a un agente
--depends-on TASK-001 \ # Dependencias
--estimated-hours 4 # Estimación de tiempo
tick claim TASK-001 @agente # Reclamar tarea (establece in_progress)
tick release TASK-001 @agente # Liberar tarea (vuelve a todo)
tick done TASK-001 @agente # Completar tarea
tick reopen TASK-001 @agente # Reabrir tarea completada
tick delete TASK-001 # Eliminar una tarea
tick comment TASK-001 @agente \ # Agregar nota
--note "Actualización de progreso"
tick edit TASK-001 \ # Editar campo directamente
--title "Nuevo título" \
--priority high \
--status in_progress
Correcciones y Recuperación
tick reopen TASK-001 @agente # Reabrir tarea completada
tick reopen TASK-001 @agente \ # Reabrir y rebloquear dependientes
--re-block
tick delete TASK-001 # Eliminar tarea, limpia dependencias
tick delete TASK-001 --force # Eliminar incluso si tiene dependientes
tick edit TASK-001 --title "X" # Cambiar título
tick edit TASK-001 --priority high # Cambiar prioridad
tick edit TASK-001 --status todo # Cambiar estado directamente
tick edit TASK-001 --tags a,b,c # Reemplazar etiquetas
tick edit TASK-001 --add-tag new # Agregar etiqueta
tick edit TASK-001 --remove-tag old # Quitar etiqueta
tick edit TASK-001 \ # Editar dependencias
--depends-on TASK-002,TASK-003
tick undo # Deshacer la última operación de tick
tick undo --dry-run # Vista previa de lo que se desharía
Operaciones Masivas
tick import tasks.yaml # Importar tareas desde archivo YAML
tick import - < tasks.yaml # Importar desde stdin
tick import tasks.yaml --dry-run # Vista previa de la importación
tick batch start # Iniciar modo lote (sin auto-commit)
tick batch status # Verificar estado del lote
tick batch commit # Confirmar todos los cambios en lote
tick batch abort # Descartar cambios en lote
Listado Avanzado de Tareas
tick list # Todas las tareas, agrupadas por estado
tick list --status blocked # Solo tareas bloqueadas
tick list --priority urgent # Tareas de alta prioridad
tick list --assigned-to @alice # Tareas para un agente específico
tick list --tag backend # Tareas con etiqueta
tick list --json # Salida JSON para scripts
Visualización de Dependencias
tick graph # Árbol de dependencias ASCII
tick graph --format mermaid # Diagrama de flujo Mermaid
tick graph --show-done # Incluir tareas completadas
Monitoreo en Tiempo Real
tick watch # Observar cambios
tick watch --interval 10 # Intervalo de sondeo personalizado
tick watch --filter in_progress # Mostrar solo un estado específico
Gestión de Agentes
tick agent register @nombre \ # Registrar nuevo agente
--type bot \ # human|bot
--roles "dev,qa" \ # Roles separados por comas
--status idle # working|idle|offline
tick agent list # Listar todos los agentes
tick agent list --verbose # Información detallada
tick agent list --type bot # Filtrar por tipo
tick agent list --status working # Filtrar por estado
Herramientas MCP (Alternativa al CLI)
Si usas el Protocolo de Contexto de Modelo (MCP), usa estas herramientas en lugar de los comandos del CLI:
Estado e Inspección
tick_status- Obtener el estado del proyecto (agentes, tareas, progreso)tick_validate- Validar la estructura de TICK.mdtick_agent_list- Listar agentes con filtros opcionales
Gestión de Tareas
tick_add- Crear nueva tareatick_claim- Reclamar tarea para un agentetick_release- Liberar tarea reclamadatick_done- Completar tarea (desbloquea automáticamente dependencias)tick_comment- Agregar nota a una tarea
Correcciones y Recuperación
tick_reopen- Reabrir tarea completadatick_delete- Eliminar una tareatick_edit- Edición directa de campo (omite la máquina de estados)tick_undo- Deshacer la última operación de tick
Operaciones con Agentes
tick_agent_register- Registrar nuevo agente
Ejemplo MCP:
// Crear tarea mediante MCP
await tick_add({
title: "Refactorizar autenticación",
priority: "high",
tags: ["backend", "security"],
assignedTo: "@nombre-bot"
})
// Reclamarla
await tick_claim({
taskId: "TASK-023",
agent: "@nombre-bot"
})
Mejores Prácticas
1. Conversación Natural Primero
✅ Bien: El usuario dice "refactoriza la autenticación", tú creas la tarea automáticamente ❌ Mal: Hacer que el usuario cree tareas explícitamente
2. Usa Siempre tu Nombre de Agente
Regístrate una vez:
tick agent register @tu-nombre-bot --type bot --roles "engineer"
Luego usa consistentemente:
tick claim TASK-001 @tu-nombre-bot
tick done TASK-001 @tu-nombre-bot
3. Proporciona Contexto en los Comentarios
# ✅ Bien - explica qué y por qué
tick comment TASK-005 @bot --note "Cambiado de REST a GraphQL para mejor seguridad de tipos y reducir la sobrecarga de datos"
# ❌ Mal - demasiado vago
tick comment TASK-005 @bot --note "API actualizada"
4. Desglosa Tareas Grandes
Crea subtareas con dependencias:
tick add "Configurar pipeline CI/CD" --priority high
tick add "Configurar GitHub Actions" --depends-on TASK-010
tick add "Agregar scripts de despliegue" --depends-on TASK-011
tick add "Configurar entorno de staging" --depends-on TASK-011
5. Verifica el Estado Antes de Reclamar
# Asegúrate de que la tarea exista y no esté reclamada
tick status
# Luego reclama
tick claim TASK-XXX @tu-nombre
Entendiendo la Estructura de TICK.md
El archivo tiene tres secciones:
- Frontmatter (YAML): Metadatos del proyecto
- Tabla de Agentes (Markdown): Quién está trabajando en qué
- Bloques de Tarea (YAML + Markdown): Tareas individuales con historial
Ejemplo:
---
project: mi-app
schema_version: "1.0"
next_id: 5
---
# Agentes
| Nombre | Tipo | Roles | Estado | Trabajando en |
|--------|------|-------|--------|---------------|
| @alice | human | owner | working | TASK-003 |
| @bot | bot | engineer | idle | - |
# Tareas
\```yaml
id: TASK-001
title: Construir autenticación
status: done
priority: high
claimed_by: null
# ... más campos
history:
- ts: 2026-02-07T10:00:00Z
who: @bot
action: created
- ts: 2026-02-07T14:00:00Z
who: @bot
action: done
\```
Implementada autenticación basada en JWT con renovación de tokens...
Funcionalidades Avanzadas
Desbloqueo Automático de Dependencias
Cuando completas una tarea, las tareas dependientes se desbloquean automáticamente:
# TASK-002 depende de TASK-001
# Estado de TASK-002: blocked
tick done TASK-001 @bot
# TASK-002 cambia automáticamente a: todo
Detección de Dependencias Circulares
La validación detecta dependencias circulares:
tick validate
# Error: Dependencia circular detectada: TASK-001 → TASK-002 → TASK-003 → TASK-001
Mensajes de Commit Inteligentes
# Solo ejecutar con aprobación explícita del usuario
tick sync --push
# Genera automáticamente: "feat: completar TASK-001, TASK-002; actualizar TASK-003"
Reapertura de Tareas Completadas
Si una tarea se marcó como completada prematuramente:
tick reopen TASK-001 @bot
# Establece el estado de nuevo a in_progress, registra en el historial
tick reopen TASK-001 @bot --re-block
# También rebloquea cualquier tarea que dependa de esta
Corrección de Errores
# Deshacer la última operación de tick
tick undo
# Vista previa de lo que se desharía primero
tick undo --dry-run
# Ediciones directas de campo (omite la máquina de estados)
tick edit TASK-001 --status todo --priority urgent
Operaciones en Lote
Para múltiples cambios sin commits individuales:
tick batch start
# Ahora realiza múltiples cambios...
tick add "Tarea 1" --priority high
tick add "Tarea 2" --priority medium
tick claim TASK-001 @bot
# ...
tick batch commit # Un solo commit para todos los cambios
# O: tick batch abort # Descartar todos los cambios
Monitoreo en Tiempo Real
tick watch
# [10:23:45] ✓ Agregada: TASK-015 - Implementar búsqueda de usuarios
# [10:24:12] 🔒 TASK-015 reclamada por @bot
# [10:26:33] ⟳ TASK-015: in_progress → done
Tarjeta de Referencia Rápida
Flujo de trabajo: init → add → claim → work → comment → done → sync
Esencial: status | add | claim | done | list | graph
Correcciones: reopen | delete | edit | undo
Masivo: import | batch start/commit/abort
Coordinación: agent register | agent list | validate | watch
Git: sync --pull | sync --push (requiere aprobación explícita del usuario)
Recordatorios Clave
- Los usuarios interactúan CONTIGO, no directamente con Tick
- TÚ mantienes el TICK.md de manera transparente
- El panel es para inspección, no para interacción principal
- Usa siempre el nombre de tu agente de forma consistente
- Comenta con frecuencia para mostrar el progreso
- Valida antes de sincronizar
- Verifica el estado antes de reclamar
- Desglosa el trabajo complejo en subtareas
Recursos
- GitHub: https://github.com/your-org/tick-md
- Documentación: https://tick-md.dev/docs
- CLI npm: https://npmjs.com/package/tick-md
- Servidor MCP npm: https://npmjs.com/package/tick-mcp-server
Licencia
MIT