Un repo donde la IA trabaja dentro del plano.

El repo tiene una única fuente de reglas, AGENTS.md con sus secciones en .agents/instructions/, y una única carpeta de workflows, .agents/skills/. Claude Code, OpenCode y Codex leen las dos. AGENTS.md es el núcleo que carga en cada sesión; cada sección se lee cuando el pedido la necesita. Claude Code entra por CLAUDE.md, que es solo un import de una línea (@AGENTS.md), y por .claude/skills, un alias generado. Nada se duplica: lo que difiere entre harnesses (formato de MCP, API de hooks) vive en adaptadores finos.

La segunda idea es la del nombre de la casa, Planos: el agente escribe un plan antes de escribir código. Un plan de implementación por historia, un plan maestro de diseño, un desglose de épica. El plan se revisa, después se construye.

bun setup es el instalador: primero un chequeo previo que no escribe nada, después elegís los harnesses, cablea el .env para cada servidor que declara .mcp.json, instala las skills de la comunidad y genera las superficies por harness. Cuando la terminal tiene pantalla, la corrida se ve en una página local que abre sola: las fases en una línea de tiempo, cada pregunta como una tarjeta y un reporte final con lo que quedó pendiente. La terminal muestra siempre el log completo, y bun setup --headless deja todo en la terminal. Si algo queda a medias, bun run setup:doctor te dice qué falta y dónde se arregla. Para abrir el agente corré su propio binario en la carpeta del proyecto (claude, opencode o codex) o usá su app de escritorio. No hay script envoltorio: nada carga el .env en el proceso del agente, así que ningún secreto llega al shell de la IA. Cada servidor MCP lo lee por su cuenta con el loader de .env.

Un proyecto creado desde el boilerplate se mantiene al día con bun sync. El updater sincroniza lo que es del boilerplate y nunca pisa lo que es del proyecto: junta todas tus respuestas antes de escribir el primer archivo, y su reporte final (en la misma página local, o en la terminal con --headless) trae la tabla por superficie y un prompt de paridad para las filas que necesitan tu decisión.

No hay archivos de comando. Una skill con varios modos los lista en su propia sección ## Mode routing, y esa sección es la única lista. Muchas skills se cargan solas cuando tu pedido coincide con su descripción: "abrí un PR" carga /git-flow-master sin que la nombres. La decisión está registrada en ADR-0006.

La lista de skills cambia con cada release, así que no se copia acá. El catálogo es .agents/skills/REGISTRY.md, generado por bun run skills:registry: una entrada por skill con su propósito y sus reglas compactas. En tu proyecto, abrí tu propia copia; la del boilerplate está en GitHub. El ruteo por tarea (qué skill para qué pedido) está en .agents/instructions/agent-context-map.md y .agents/instructions/agent-skills-and-mcps.md.

Para leer el registro conviene saber que hay cuatro clases de skill: de workflow (conducen una fase entera, como /sprint-development), de contexto (guardan un mapa del negocio), utilitarias (envuelven una CLI, como /acli) y el núcleo agentic-dev-core, que no se invoca: guarda la doctrina que citan las demás.

Alrededor del ciclo hay skills de apoyo que no son una fase: /unit-testing para TDD dentro de una historia, /testability-guide para la página que recibe QA, /pr-review-lead para revisar el PR de otra persona, /project-adoption para que el agente entienda una app que ya existía, /jira-administration para la configuración de Jira y /autonomous-delivery para corridas programadas sin nadie en la línea. Qué hace cada una, en REGISTRY.md.

Lo conduce /sprint-development. Cada etapa alimenta a la siguiente, así que nunca corren en paralelo; el paralelismo vive adentro de una etapa. El merge nunca es automático: lo pedís vos. Bajo una estrategia sin rama de integración (como solo-main), el "staging" de la etapa 4 es el Preview deployment de la rama del PR.

El fin de la etapa 1 mueve la historia a In Progress; abrir el PR la lleva a In Review; el deploy verde a staging la deja en Ready For QA. Si la automatización de Jira no dispara la transición, la skill la dispara y vuelve a leer el estado. Ninguna skill de desarrollo mueve una historia más allá de Ready For QA: probarla y liberarla es de QA y de quien hace el release. La tabla completa por tipo de issue vive en .agents/skills/agentic-dev-core/references/artifact-lifecycle.md.

La sesión con la que hablás es el centro de mando. Leer muchos archivos, editar varios, correr verificaciones o hablar con Jira se delega a subagentes, cada uno con un briefing completo: objetivo, documentos a leer, reglas del proyecto resueltas desde REGISTRY.md, skills a cargar, instrucciones exactas, formato del reporte y reglas críticas. La plantilla es .agents/skills/agentic-dev-core/references/briefing-template.md. Un subagente ve solo su briefing, así que una regla que no viaja ahí no lo obliga.

Los workers supervisados los coordina /orca-orchestration y solo existen si el runtime de Orca está disponible; si no, el repo ni los menciona y el trabajo corre en subagentes. Dos piezas más para trabajo largo:

• Worktrees. Para aislar trabajo en paralelo: git worktree add, después bun run worktree:provision (copia .env, instala dependencias, crea el alias de skills), y antes de borrarlo bun run worktree:audit con --rescue.
• Relevo de sesión. Cuando la ventana de contexto se llena, /session-handoff escribe un documento de relevo y lanza la sesión sucesora en el mismo worktree y el mismo harness.

El titular abre directo con el valor, sin frase de enganche antes. El agente responde en el idioma en que le escribís; el código, los commits, los PR y los tickets van siempre en inglés. Para volver a un tono detallado alcanza con pedirlo ("habla normal"). El espejo humano del contrato es docs/ai-personality.md, y hay un deck sobre la capa comportamental.

Cómo se ramifica, se integra y se publica lo decide el bloque git_strategy de .agents/project.yaml. Toda operación de git pasa por /git-flow-master, que lee ese bloque y adapta ramas, commits, pushes y PR. El bloque llega con solo-main como valor por defecto; si nadie lo eligió para tu proyecto, la skill te ofrece la configuración inicial la primera vez que hagas algo con git.

• Push a una rama protegida: lo resuelve git_strategy.policy.direct_push_to_protected. Con forbidden va por PR, con confirm pregunta cada vez, con allowed empuja sin preguntar.
• Política contra el host: bun run git:policy verify compara lo declarado con lo que GitHub aplica de verdad (protección clásica y rulesets).
• Commits forenses: todo commit de un agente termina con Worktree: y Session:, que dicen qué checkout y qué sesión lo produjeron. Ninguna línea nombra a una herramienta de IA.
• Historia intocable: nunca se reescribe lo que ya está pusheado, nunca se fuerza un push sobre una rama compartida, y un PR nunca se mergea solo.

Una skill no pide "el servidor X": declara la capacidad que necesita (library-docs, web-search, db, automation-flows, diagrams) y el agente la resuelve por el sufijo del nombre de la herramienta, con el prefijo que sea. Los servidores comprometidos en el repo son los que declara .mcp.json, con su equivalente en opencode.jsonc y .codex/config.toml. La búsqueda web se conecta a nivel del harness, nunca en esos archivos.

Las credenciales viven en .env (plantilla en .env.example). Cada servidor MCP que las necesita arranca con el loader de .env (varlock run --filter), que lee el .env al arrancar el servidor y le pasa solo sus variables, también en un lanzamiento sin línea de comandos (app de escritorio, worker supervisado). Nada se copia a otro archivo. El host de Atlassian no es una variable de entorno: vive en issue_tracker.atlassian_url del project.yaml y se imprime con bun run jira:url.

Y hay una memoria que cruza sesiones: Engram, instalado por bun setup, guarda decisiones, bugs resueltos y hallazgos para que la próxima sesión no arranque a ciegas. El deck la caché PBI de Jira explica por qué .context/PBI/ no se commitea.