/project-context genera y refresca los artefactos de contexto que las demás skills dan por hechos: los mapas de negocio (datos, features, API), el plan maestro de implementación y el roadmap de desarrollo. También arma una skill de contexto propia del proyecto para un aspecto que los mapas no cubren. Corre un modo por vez, y cuando el artefacto ya existe nunca lo pisa sin mostrarte el diff y esperar tu sí.
El que nombras. Sin modo claro, la IA pregunta; nunca supone refresh-all.
Un gate duro faltante para la corrida. Uno blando queda anotado como hueco.
Código, esquema, contrato, PRD, tracker: lo que pida la referencia del modo, con las rutas y la fuente del esquema que declara stack:.
Si no existe, lo escribe. Si existe, arma el candidato y te muestra el diff.
Escribe solo lo aprobado y relee el resultado con el comando del artefacto.
Cada artefacto que produce es una síntesis: alguien leyó el código, el esquema y el backlog y escribió qué significa. Esta skill es la que hace esa lectura, y la vuelve a hacer cuando las fuentes cambian.
La IA carga solo la referencia del modo elegido y nunca abre una segunda en la misma pasada. No hay comandos de terminal para ellos: los viejos nombres (business-data-map, master-implementation-plan, dev-roadmap) sobreviven solo como frases que disparan el modo.
| Modo | Lee | Escribe |
|---|---|---|
| data | references/data.md | business-data-context/references/business-data-map.html |
| features | references/features.md | business-feature-context/references/business-feature-map.html |
| api | references/api.md | business-api-context/references/business-api-map.html |
| master-plan | references/master-plan.md | .context/master-implementation-plan.md |
| dev-roadmap | references/dev-roadmap.md | .context/dev-roadmap.md |
| context-skill | references/context-skill.md | .agents/skills/<aspect>-context/ |
la tabla canónica es ## Mode routing en .agents/skills/project-context/SKILL.md; las rutas de los mapas son relativas a .agents/skills/
Viven en ## Compact Rules y ## Shared contract de la skill. Las compactas viajan a los subagentes a través de .agents/skills/REGISTRY.md.
El modo CREATE o UPDATE no lo eliges tú: sale del estado del artefacto. Lo que cambia entre artefactos es qué parte se regenera en un UPDATE.
| Artefacto | Cómo detecta el estado | CREATE | UPDATE |
|---|---|---|---|
| Mapa de negocio | bun run context:map <skill> --list: aviso de placeholder o lista de secciones | Construye cada sección desde las fuentes y escribe el archivo una vez | Chequeo de frescura por sección, regenera solo las secciones viejas, muestra un diff por sección y espera. Nunca cambia el id de una sección. |
| Plan maestro | existe .context/master-implementation-plan.md? | Lo genera de cero | Versión nueva, resumen del diff, confirmación. Resalta lo que sube o baja de Master Sprint. |
| Roadmap de desarrollo | existe .context/dev-roadmap.md? | El documento completo | Quirúrgico: regenera solo la sección de execution sprints y conserva lo escrito a mano (columna, aristas, gates, bloqueos locales). |
| Skill de contexto | existe .agents/skills/<aspect>-context/? | El andamio, después del análisis | Candidato, diff, espera. Suma reglas con fecha; nunca reescribe una existente. |
Detecta el estado, lee las fuentes, arma el candidato y lo compara con lo que hay.
Si un mapa cambió, revisa las ## Rules y los gotchas de su skill contra el mapa nuevo.
Si el diff entra. Sin tu sí, el artefacto existente no se toca.
Qué hacer con una regla que el mapa nuevo contradice: la IA la propone para "No longer true", nunca la borra.
Solo lo aprobado, más la sección discovery-gaps, aunque esté vacía: prueba que se buscó.
Cada referencia es dueña de la redacción exacta de su gate. La regla general: si sin la entrada el artefacto sería una lista de deseos, el gate es duro; si solo queda más pobre, es blando y la falta se registra como Discovery Gap.
| Modo | Gate duro (para) | Gates blandos (Discovery Gap) |
|---|---|---|
| data | ninguno: se invoca sola | PRD y SRS bajo .context/ (sugiere /project-foundation) |
| features | ninguno | el mapa de datos |
| api | sin spec OpenAPI, sin backend con rutas para escanear y sin API directa a Supabase | el mapa de datos, el mapa de features |
| master-plan | un mapa de datos generado | el mapa de features |
| dev-roadmap | al menos una épica con historias hijas en el tracker | sus links de dependencia (sin ellos avisa y arma un grafo ralo, con las historias sin arista en un TODO de mapeo), el mapa de datos, master-design-plan.md, master-implementation-plan.md |
| context-skill | lo que la skill va a cubrir tiene que existir: un mapa, un módulo, un contrato | ninguno |
Solo corre si lo pides explícitamente. Cada paso cierra su propia validación y su propia aprobación antes de que se cargue la referencia siguiente.
Primero, porque los demás lo usan: features y api lo leen, el plan maestro lo exige.
Cruza cada entidad del mapa de datos con su cobertura CRUD.
Apunta sus recorridos a entidades del mapa de datos y a features del mapa de features.
Convierte los mapas en un orden de épicas por valor, bloqueo y urgencia.
Baja ese orden a tickets, con el grafo de dependencias del tracker.
Cada mapa responde una pregunta distinta y cita a los otros por id de sección en vez de copiarlos. La regla de oro de todos: sintetizar, no volcar. El esquema lo sirve la base en vivo; el mapa escribe qué significa.
Lee esquema, RLS y migraciones (por la capacidad db o, con schema_source: migrations, desde los archivos de migración), más backend, frontend, PRD y SRS. Escribe entidades con su rol de negocio, quién lee y escribe cada tabla, las migraciones que cambiaron el significado de una entidad, todos los flujos importantes (sin tope), máquinas de estado, procesos automáticos e integraciones.
Una feature es cualquier capacidad: endpoint, acción de UI, proceso de fondo, integración. Escribe el catálogo por dominio con su estado, la matriz CRUD por entidad, rutas, UI, integraciones y flags. Si el PRD y el código discrepan, gana el código y la diferencia va a Discovery Gaps.
Narrativo, no un catálogo de endpoints: modelo de auth por niveles, recorridos de negocio críticos trazados de punta a punta, arquitectura detrás del API e integraciones con su modo de falla visible. Lo que el spec OpenAPI ya expresa se enlaza, no se repite.
Chequeo de la capacidad diagrams en el punto de uso. Cada hecho que muestra una figura también está en el texto: la IA lee solo el texto. Si la skill no está, para; nunca un SVG o un ASCII dibujado a mano en su lugar.
La capa de estrategia que se apoya sobre los mapas. Escrita con voz de ingeniero senior hablándole a un tech lead que recién llega: guía, no catálogo.
Sin mapa de datos generado, para: un plan sin mapa de entidades y flujos es una lista de deseos. Sin mapa de features, avisa y sigue. Suma PRD, SRS, glosario y el log de git para saber qué ya se entregó.
Valor para el usuario × factor de bloqueo × urgencia. El producto ubica cada unidad en Master Sprint 0 (fundacional), 1 (MVP), 2 (posterior) o la deja diferida. La tabla de puntaje no se publica: se publican las conclusiones.
Traza qué destraba cada ítem fundacional y marca siempre las features que comparten una entidad pero viven en épicas distintas: el origen típico de un rediseño de esquema a mitad de sprint.
Ordena cada prioridad citando evidencia: un flujo del mapa de datos, una fila del de features, una prioridad del PRD o una integración con nombre.
Si el orden propuesto entra. En UPDATE, mira primero lo que sube o baja de Master Sprint: son los cambios de más peso.
.context/master-implementation-plan.md, con huecos de implementación escritos como spikes.
La capa de secuencia. Convierte el grafo de links de dependencia del tracker y el contexto de diseño local en un orden de ejecución. Es dueño de las aristas y los gates; nunca del estado vivo de un ticket.
# tres documentos, tres altitudes .context/master-implementation-plan.md épica / estrategia "qué construir y por qué ese orden" ← master-plan .context/dev-roadmap.md ticket / secuencia "qué destraba qué, en qué sprint" ← dev-roadmap .context/PBI/.../implementation-plan.md historia / archivos "cómo se construye un ticket" ← /sprint-development
| Sección | Qué guarda | En un UPDATE |
|---|---|---|
| Columna de épicas | Qué épica va antes de cuál, forzado por la topología de entidades del mapa de datos | Se conserva lo escrito a mano |
| Grafo de historias | Cada arista dura o blanda con su razón: lo que ningún otro lugar guarda | Se conserva; lo nuevo se agrega y un conflicto se marca |
| Execution sprints | Lotes paralelos por orden topológico (Kahn) | Se regenera desde el grafo vivo |
| Gates de mockup | Historias que no arrancan hasta que llegue su mockup | Se conserva |
| Estado vivo | Una receta de consulta, nunca una tabla de estado | Solo se editan a mano las listas locales: bloqueos previos al desarrollo y aristas pendientes de mapear |
Una skill <aspect>-context (billing, auth, una integración como stripe) es la judgment layer sobre ese aspecto. Las fuentes guardan los hechos; la skill guarda las reglas para leerlos sin equivocarse.
Lee completo lo que va a cubrir y lista cada lugar donde una sesión competente leería mal: borrados lógicos, columnas derivadas, RLS que esconde filas a un rol, estados con nombres distintos en base, API y UI, comportamiento que cambia entre staging y producción.
Si se puede regenerar, se queda en el mapa o el código. Si es un hecho, también. Solo el criterio que tiene que llegar sin que nadie lo pida se vuelve regla, con fecha y con cómo se midió. Sin medición, no hay regla.
SKILL.md desde la plantilla de agentic-dev-core/references/skill-scaffold.md, con metadata.kind: context, más references/gotchas.md. Si el builder no está instalado, arma el andamio desde la plantilla y lo dice en el reporte.
El nombre de la skill más el modo. La primera palabra después del nombre elige el modo, y el resto llega intacto a su referencia.
Barra de la skill más el modo. Sin modo, la IA lo saca de la frase o pregunta.
Sin barra: nombras la skill y el modo en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
# un mapa acotado a un módulo /project-context data module=billing # el roadmap de una sola épica (o un nombre de Master Sprint) /project-context dev-roadmap {{PROJECT_KEY}}-12 # una skill de contexto propia, sobre algo que ya existe /project-context context-skill billing # todo, en orden, con una aprobación por paso /project-context refresh-all # leer un mapa ya generado: el reader, nunca el HTML crudo bun run context:map business-data-context --section entities
Al entrar resuelve sus categorías complementarias (backend-db, issue-tracker, meta-skill) desde .agents/skills/REGISTRY.md.
Su fase de Discovery orquesta los modos de esta skill para dejar armado el modelo mental que las demás dan por hecho. Deck: cómo funciona project-foundation.
Siembra las épicas e historias que el roadmap necesita, y le delega la escritura del orden de sprints. Deck: cómo funciona product-management.
Lee los mapas por sección al planear y consulta el roadmap en su Phase 0b. Deck: cómo funciona sprint-development.
El mapa US→Screen de master-design-plan.md alimenta los gates de mockup del roadmap (el contrato de fidelidad de UI de AGENTS.md). Deck: flujo de mockups.
supabase para leer el esquema vivo en los modos de mapa; /acli antes de cualquier lectura de Jira en el roadmap y el plan maestro.
skill-creator construye cada skill de contexto; diagram-design dibuja las figuras de los mapas.