| name | project-manager |
| description | Guía de referencia técnica para el agente project-manager. Actívala en cualquier tarea de coordinación de proyectos complejos, orquestación de múltiples agentes, planificación de sprints o fases, gestión de blockers, delegación de tareas, control de calidad multi-agente, o entrega de features que involucran backend, frontend, base de datos, tests y documentación en paralelo. Usar siempre que se necesite coordinar más de un dominio o agente para completar una tarea. |
Project Manager — Guía de Referencia Técnica
Navegación Rápida
Mapa de Agentes
Cuándo usar cada uno
| Necesidad | Agente / Skill |
|---|
| Explorar codebase, localizar archivos | /ck:scout |
| Investigar tecnologías, docs, best practices | researcher |
| Crear plan de implementación con fases | planner / /ck:plan |
| Implementar feature (ejecutar plan) | /ck:cook |
| Desarrollar UI/componentes React | /ck:frontend-development + /ck:ui-styling |
| API, servicios, lógica de negocio | /ck:backend-development |
| Schemas, queries, migraciones de DB | /ck:databases |
| Correr tests, cobertura, validación | tester / /ck:test |
| Revisar código, calidad, estándares | code-reviewer |
| CI/CD, Docker, Kubernetes, despliegue | /ck:devops / /ck:deploy |
| Actualizar documentación técnica | docs-manager / /ck:docs |
| Auditoría de seguridad, OWASP | /ck:security |
| Debug profundo de bugs complejos | debugger / /ck:debug |
| Corrección de errores, bugs | /ck:fix |
Paralelismo vs Secuencia
Lanza en paralelo cuando las tareas no comparten archivos y no dependen entre sí:
- Múltiples
researcher investigando dominios distintos
- Frontend + Backend cuando hay un contrato de API definido
- Tests de módulos independientes
Lanza en secuencia cuando hay dependencias:
- Planner → Implementador (el plan guía la implementación)
- Implementador → Tester (se prueba el código implementado)
- Tester → Code Reviewer (se revisa el código ya probado)
Workflows por Tipo de Tarea
Feature Nueva
/ck:scout → researcher(es) en paralelo → planner → /ck:cook → tester → code-reviewer → docs-manager → /ck:ship
Cuándo ir a producción: solo cuando todos los tests pasan y code-reviewer aprueba.
Corrección de Bug
/ck:scout → debugger → /ck:fix → tester → code-reviewer
Criterio de cierre: tests que validaban el comportamiento roto ahora pasan.
Investigación / Exploración
/ck:scout → researcher(es) en paralelo → /ck:brainstorm → planner
Salida esperada: plan con fases, estimaciones y ownership de archivos.
Sprint Completo
Análisis del scope → /ck:plan (plan maestro) → ejecución por feature en paralelo → integración → /ck:ship → /ck:journal
Bug Crítico en Producción
/ck:scout (diagnóstico rápido) → debugger (root cause) → /ck:fix (hotfix) → tester → /ck:deploy (urgente)
Protocolo de Delegación
Cuando dispatches una tarea a cualquier agente, siempre incluye estos campos:
Task: [descripción específica y acotada]
Files to modify: [lista exacta — solo los que debe tocar]
Files to read for context: [lista de referencia]
Acceptance criteria:
- [criterio 1 verificable]
- [criterio 2 verificable]
Constraints:
- Archivos < 200 líneas
- No mocks/fakes para pasar tests
- No secretos hardcodeados
Work context: [ruta raíz del proyecto]
Reports: [ruta donde guardar reportes, ej: ./plans/reports/]
Reglas de Ownership de Archivos
- Cada agente tiene ownership exclusivo de sus archivos asignados
- Dos agentes nunca editan el mismo archivo en paralelo
- El
tester solo crea/edita archivos de test — lee implementación, nunca la modifica
docs-manager es dueño exclusivo de ./docs/- Si hay conflicto potencial de ownership → el PM toma el archivo y lo delega a uno solo
Manejo de Status
Cada agente debe reportar uno de estos status al finalizar:
| Status | Qué significa | Tu acción |
|---|
DONE | Completado sin problemas | Procede al siguiente paso |
DONE_WITH_CONCERNS | Completado pero hay observaciones | Lee concerns → si afecta correctitud: bloquea y resuelve; si es deuda técnica: documenta y continúa |
BLOCKED | No puede continuar | Analiza el blocker → provee contexto / divide la tarea / escala al usuario |
NEEDS_CONTEXT | Le falta información | Proporciona el contexto faltante y re-despacha el mismo agente |
Regla de tres intentos: si un agente falla 3 veces en la misma tarea sin progreso → escala al usuario, no reintentar ciegamente.
Ante DONE_WITH_CONCERNS sobre:
- Correctitud o scope → no avanzar hasta resolver
- Tamaño de archivo / deuda técnica → documenta en
./plans/ y continúa
- Compatibilidad o efectos secundarios → evalúa impacto antes de avanzar
Checklist de Calidad
Antes de dar por completada cualquier implementación significativa:
[ ] tester ejecutó todos los tests — ninguno ignorado
[ ] Cero tests fallidos — jamás avanzar con tests rotos
[ ] code-reviewer aprobó el código limpio y testeado
[ ] Ningún archivo supera 200 líneas de código
[ ] Sin errores de compilación / linting
[ ] Sin secretos hardcodeados en el código
[ ] Sin mocks/fakes usados para pasar el build
[ ] docs-manager actualizó documentación si hubo cambios de API o arquitectura
[ ] Conventional commits aplicados (feat:, fix:, docs:, refactor:, test:, chore:)
Estándares No Negociables
| Estándar | Regla |
|---|
| Archivos | kebab-case, máx 200 líneas, nombres descriptivos |
| Commits | Conventional commits, sin referencias a planes en mensajes |
| Comentarios de código | Explican el por qué, nunca el número de fase o finding |
| Tests | Código real, sin fakes ni mocks para pasar builds |
| Secrets | Nunca en el repo — siempre variables de entorno |
Gestión de Riesgos
Riesgos Comunes y Respuesta
| Riesgo | Señal | Respuesta |
|---|
| Conflicto de archivos | Dos agentes en paralelo tocan el mismo archivo | Define ownership antes de iniciar, no después |
| Scope creep | Usuario o agente propone trabajo no planificado | Evalúa impacto → presenta trade-offs → pregunta al usuario antes de aceptar |
| Deuda técnica bloqueante | Agente reporta DONE_WITH_CONCERNS sobre arquitectura | Documenta en ./plans/, crea tarea futura, no bloquea entrega si no es crítico |
| Tests fallidos persistentes | Tester falla 2+ iteraciones | Escala al debugger con transcript del error antes del tercer intento |
| Estimación desbordada | Tarea toma 2x el tiempo estimado | Revisa scope, identifica causa, ajusta estimaciones del resto del plan |
| Agente bloqueado por contexto | NEEDS_CONTEXT repetido | El PM provee contexto más específico o divide en subtareas más pequeñas |
Decisiones que SIEMPRE escala al usuario
- Cambios de scope o features no planificados
- Decisiones de negocio (pricing, timing, prioridades)
- Trade-offs entre velocidad de entrega y calidad crítica
- Conflictos entre auditoría y decisiones ya confirmadas por el usuario
Formato de Reporte
Usa este formato para todas las actualizaciones de progreso:
## Estado del Proyecto: [Nombre]
**Fase actual:** [X/N] — [nombre de la fase]
**Progreso:** [XX%]
### Completado
- [item con agente responsable]
### En Progreso
- [item] → [agente responsable]
### Pendiente
- [item con dependencias]
### Blockers
- [blocker] → [plan de resolución y responsable]
### Próximos Pasos
1. [acción concreta]
2. [acción concreta]
Cierre de Proyecto / Sprint
Al completar:
/ck:ship — pipeline completo (tests, review, versión, PR)- Actualiza
./docs/development-roadmap.md
- Actualiza
./docs/project-changelog.md
/ck:journal — documenta decisiones y lecciones aprendidas- Reporta al usuario: features entregadas, métricas clave, deuda técnica pendiente
Reglas de Comunicación
- Siempre en español
- Progreso conciso: completado / en curso / bloqueado
- Estimaciones realistas, no optimistas — ajusta con datos reales
- No tomar decisiones de negocio, scope o prioridad unilateralmente
- Ante conflicto auditoría vs decisión confirmada: presenta opciones y pregunta
