🐮 Moo Tasks

Motor de orquestación y gestión de tareas agénticas construido para agentes de codificación de IA (Claude Code, Cursor, Windsurf, Antigravity, Copilot) y programación en pareja con intervención humana.

Inicio rápido • Configuración del agente • Protocolo del agente • Arquitectura • Herramientas MCP

🌟 ¿Por qué Moo Tasks?

Los agentes de codificación de IA estándar suelen sufrir de:

1. Desviación del alcance: Alejarse de la intención original del usuario hacia refactorizaciones interminables de bajo valor.

2. Sobreplanificación: Generar 40 tareas superficiales sin ejecutar ninguna de ellas.

3. Bucles / Thrashing: Intentar repetidamente la misma corrección fallida sin detenerse.

4. Trabajo no verificable: Afirmar que el código está completo sin ejecutar pruebas ni producir evidencia.

5. Reabrir decisiones: Volver a discutir decisiones arquitectónicas ya establecidas en cada reinicio de contexto.

Moo Tasks resuelve esto proporcionando un motor SQLite local (modo WAL), una interfaz web enriquecida en tiempo real y un servidor del Model Context Protocol (MCP) que aplica invariantes empresariales estrictas en tiempo de ejecución.

Related MCP server: pith

✨ Capacidades clave y matriz de funciones

🎯 1. Control de objetivos y alcance

• Indicaciones humanas textuales: Se sitúa por encima de las tareas, preservando la solicitud original exacta del usuario.

• Cobertura de objetivos y cabos sueltos: Métricas en vivo sobre el porcentaje de finalización de tareas y tareas abiertas pendientes.

• Detección de desviación del alcance: Identifica y marca automáticamente tareas huérfanas sin objetivo vinculado.

• Límites de objetivos abiertos: Tope máximo de tareas abiertas por objetivo (predeterminado: 10), evitando que los agentes sobreplanifiquen.

• Operaciones en cascada: Eliminar, matar o reabrir atómicamente todas las tareas bajo un objetivo con razones obligatorias.

📋 2. Ciclo de vida de tareas y dependencias DAG

• Restricción de anidamiento de subtareas: Exactamente 1 nivel de subtareas bajo una tarea principal.

• Máquina de estados finitos: todo, doing, blocked-on-dependency, waiting-on-human, done, dropped.

• Grafo de dependencias DAG: Detección automática de ciclos y desbloqueo automático de tareas posteriores.

• Protección de cierre de tareas principales: Evita cerrar tareas principales mientras quede alguna subtarea abierta.

• Deshacer estado e historial: Revertir transiciones de estado accidentales utilizando el historial completo de auditoría de transiciones.

🛡️ 3. Finalización, verificación y prueba de trabajo

• Criterios de aceptación: Criterios obligatorios escritos en Markdown antes de comenzar el trabajo.

• Requisito de evidencia: Cerrar una tarea requiere una prueba verificable (comandos ejecutados, salida de stdout, pruebas de test).

• Verificación en dos fases: Distingue agent_completed de verified_done humano.

• Rechazo con motivo: Los humanos u otros agentes pueden rechazar trabajo completado con comentarios; la tarea vuelve a todo e incrementa el contador de reaperturas.

🙋 4. Colaboración humana y bloqueo

• Cola de espera humana: Los agentes pausan los bloqueadores con preguntas adjuntas (clarification, approval, credential, decision).

• Reanudación reactiva: Responder a una pregunta a través de la interfaz web o MCP transiciona automáticamente la tarea de vuelta a la cola de listas sin reiniciar agentes.

• Bandeja de entrada humana dedicada: Cola en tiempo real de todo lo que necesita atención humana.

🔍 5. Trabajo descubierto

• Captura de trabajo a mitad de tarea: Capturar nuevo trabajo encontrado en plena ejecución sin renunciar a la reclamación de la tarea actual.

• Debe corregirse vs diferido: Marcar como must-fix-now (insertado como bloqueador) o deferred (pila de backlog).

🤖 6. Propiedad, concurrencia y concesiones

• Reclamaciones exclusivas de tareas: Concesiones con tiempo de espera automático (predeterminado: 5 minutos) cuando los agentes quedan en silencio.

• Mecanismo de heartbeat: Extender las concesiones durante tareas de larga duración.

• Límites de concurrencia de agentes: Tope de tareas simultáneas por agente (predeterminado: 1).

• Advertencias de conflicto de archivos: Los archivos declarados se comprueban para detectar solapamientos con otras reclamaciones activas.

🔄 7. Detección de estancamiento y thrashing

• Contador de intentos: Se incrementa en cada reclamación/intento.

• Autoescalado: Después de $N$ intentos (predeterminado: 3), pausa automáticamente la tarea a waiting-on-human en lugar de bucles infinitos.

• Seguimiento del tiempo en estado: Audita el tiempo invertido en doing y detecta reaperturas repetidas.

🏛️ 8. Decisiones arquitectónicas establecidas (ADR)

• Registro a nivel de proyecto: Preserva decisiones y justificaciones que sobreviven a las tareas.

• Consulta previa a la planificación: Los agentes leen las decisiones establecidas antes de planificar.

• Soporte de sustitución: Actualizar y vincular limpiamente las decisiones sustituidas con motivos obligatorios.

🚀 Inicio rápido e instalación

Opción A: Instalación global (recomendada para el comando moo)

Instala moo-tasks globalmente para acceder al comando corto moo desde cualquier lugar:

npm install -g moo-tasks
# or: pnpm add -g moo-tasks | bun add -g moo-tasks

Una vez instalado, puedes usar moo directamente:

moo init       # Initialize .moo workspace in current project
moo start      # Launch real-time Web UI (http://127.0.0.1:4242)
moo ws         # List registered global workspaces
moo status     # Show Where-Did-I-Leave-Off context
moo search     # Full-text SQLite search

💡 Nota sobre moo vs npx:

• El comando moo <command> funciona cuando se instala globalmente mediante npm install -g moo-tasks.

• Si se ejecuta sin instalación global, usa npx moo-tasks <command> (no uses npx moo, ya que moo en el registro npm es un paquete no relacionado).

• Si aparece moo: command not found después de la instalación global, asegúrate de que el directorio bin global de npm esté en tu $PATH:

  export PATH="$(npm prefix -g)/bin:$PATH"

Opción B: Bajo demanda con npx moo-tasks

Ejecuta directamente sin instalación global:

1. Inicializar el espacio de trabajo y los protocolos del agente

Ejecuta en la raíz de tu proyecto:

npx moo-tasks init

Esto:

• Inicializa la base de datos SQLite .moo/tasks.db con modo WAL.

• Genera AGENTS.md, CLAUDE.md, .cursorrules y .windsurfrules.

2. Iniciar la interfaz web local

npx moo-tasks start

Abre http://127.0.0.1:4242 en tu navegador.

Para acceder a la interfaz web desde otro dispositivo o tableta en tu red local (LAN):

npx moo-tasks start --lan
# Automatically logs: http://192.168.x.x:4242/

🔌 Configuración del agente y MCP

Instalador multiagente de un comando

# Configure all detected agent IDEs at once:
npx moo-tasks install all

# Or configure specific clients:
npx moo-tasks install claude       # Updates ~/.claude.json
npx moo-tasks install cursor       # Generates .cursor/mcp.json
npx moo-tasks install windsurf     # Updates ~/.codeium/windsurf/mcp_config.json
npx moo-tasks install antigravity  # Generates .gemini/settings.json

Configuración manual

{
  "mcpServers": {
    "moo-tasks": {
      "command": "npx",
      "args": ["moo-tasks", "mcp"]
    }
  }
}

🤖 Protocolo obligatorio del agente

Se instruye a todos los agentes de codificación de IA a seguir este ciclo de vida de 6 pasos:

1. SESSION RESUME  → Call moo_session_resume() & moo_list_decisions()
2. ANCHOR GOAL     → Call moo_create_goal(title, verbatimPrompt)
3. PLAN & CRITERIA → Call moo_create_task() with markdown criteria BEFORE code
4. EXCLUSIVE CLAIM → Call moo_claim_task(taskId, agentId, sessionId)
5. IMPLEMENTATION  → If blocked, call moo_ask_human() or link blockers
6. VERIFIED PROOF  → Call moo_complete_task() with test proof & output snippet
7. ADR RECORD      → Call moo_record_decision() for architectural choices

🛠️ Referencia de herramientas MCP

🏛️ Arquitectura y Código Limpio

src/
├── domain/                    # Pure Enterprise Domain Rules & Invariants
│   ├── types.ts              # Domain interfaces & value types
│   ├── errors.ts             # Domain-specific typed error classes
│   ├── dependency.ts         # DAG cycle detector & unblocked evaluator
│   ├── conflict.ts           # File touch overlap conflict detector
│   └── similarity.ts         # Duplicate task similarity detector
│
├── infrastructure/            # Persistence & External Integrations
│   ├── db/database.ts        # SQLite manager (WAL mode, busy timeout)
│   ├── db/migrations.ts      # Schema DDL and versioning
│   ├── git/git-context.ts    # Git branch, commit, dirty status extractor
│   └── repositories/         # SQLite Repository Implementations
│
├── services/                  # Application Services (Use Cases)
│   ├── goal-service.ts        # Goal lifecycle & cap enforcement
│   ├── task-lifecycle-service.ts # State machine, ready queue, undo
│   ├── claim-service.ts       # Exclusive claims, leases, dead-agent timeout
│   ├── verification-service.ts# Proof of work & two-phase verification
│   ├── human-collab-service.ts# Human Q&A queue & reactive resume
│   ├── discovered-work-service.ts # Mid-flight discovered work
│   ├── decision-service.ts    # ADR logs & supersede linking
│   ├── duplicate-merge-service.ts # Idempotency & task merging
│   ├── session-service.ts     # Where-did-I-leave-off session resume
│   ├── housekeeping-service.ts# Archiving & multi-format export
│   └── index.ts               # Dependency Injection Container
│
├── mcp/                       # Model Context Protocol Stdio Server
├── server/                    # Fastify HTTP + Server-Sent Events (SSE) Engine
├── cli/                       # CLI Commands (start, init, install, mcp)
└── ui/                        # Vanilla JS + Tailwind + Lucide Icons Web UI

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para la configuración de desarrollo, pruebas y pautas de PR.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.