/project-adoption le enseña la capa agéntica a una aplicación que ya tiene código, schema, CI y convenciones propias. Lee la app sin escribir nada, propone un solo plan, espera tu aprobación y recién ahí completa las superficies agénticas, para que cada skill trabaje con el stack real de la app y no con los defaults del boilerplate. El código, el schema, el CI y las dependencias de la app no cambian.
La herramienta llega sin pisar nada de la app. Se commitea como un solo cambio.
Stack, scripts, schema, CI, hooks, tracker y la línea de base de la app.
Un archivo, PENDING APPROVAL, y la IA espera.
Solo superficies agénticas, y la app tiene que salir igual que entró.
Es la puerta de entrada de una app existente. Un proyecto nuevo entra por otra, y cada cosa que viene después tiene su propia skill.
Instalar la herramienta y entender la app son trabajos distintos. El primero lo hace un comando que no pregunta nada sobre la app; el segundo lo hace esta skill, que pregunta todo lo que los archivos no contestan.
# desde la raíz del repo de la app, con el árbol limpio bunx create-agentic-dev@latest --doctor --preflight # solo lectura: se puede adoptar? bunx create-agentic-dev@latest --adopt # le pasa la posta al updater con --adopt # con pantalla, el updater abre su página local (la terminal sigue con el log completo); # revisar la tabla de paridad de su reporte final, bun install, commitear la adopción; # después, en una sesión: /project-adoption
Entre las dos hay una sola puerta: tu aprobación explícita del plan, dentro de la misma corrida. Un plan de una corrida anterior se retoma, nunca se reescribe.
| Modo | Frases que lo disparan | Escribe |
|---|---|---|
| adopt | "adopta esta app" · "adopción" · "after --adopt" · "project adoption" | solo después de aprobar el plan, solo superficies agénticas |
| check | "adoption drift check" · "is the adoption still accurate" | nada: tabla de señales más la sección de stack de setup:doctor |
un modo por corrida; check con señales pendientes termina nombrando adopt, nunca lo arranca
El sello se mide, no se promete: después de la fase 2, git status --porcelain solo puede diferir del de la fase 0 por el archivo del plan.
Si hay una corrida a medias, ofrece reanudar, reiniciar o abortar, y espera. La puerta exige que .template/installer.lock.json diga adopted: true y que el árbol esté limpio. Sin lock, los archivos nunca se instalaron; con un lock greenfield, el repo fue scaffoldeado y le toca a /project-bootstrap.
Después corre las señales de detección: cada subsistema queda PENDING o ADOPTED. Las pendientes son la lista de trabajo de esta corrida.
La huella del stack sale de bun run agents:setup --stack --dry-run --non-interactive: cada valor trae el archivo de donde se leyó, y lo que no se detecta queda ausente, nunca adivinado. Fuera de V1_SUPPORTED, la corrida para aquí sin escribir ni siquiera el plan.
Lee las convenciones del repo (paridad de la adopción, hooks, aislamiento de la herramienta, archivos de entorno solo por nombre, CI, branches), prueba el tracker en solo lectura y corre los scripts de la app para la línea de base. Lo que los archivos no contestan va en un solo cuestionario.
Escribe .context/reports/project-adoption-plan.md con cabecera Status: PENDING APPROVAL, verifica el sello y se detiene. Un cambio que pidas edita el plan y vuelve a preguntar.
Corre las señales, despacha tres analistas de solo lectura y mide la línea de base.
Arma el plan con los hechos de los analistas y tus respuestas.
Identidad del proyecto, entornos, tracker y qué app cubre la adopción en un monorepo.
Si el test de la app es seguro de correr para la línea de base.
El sí que pasa el plan a APPROVED.
La tabla de señales y el plan en .context/reports/, que lee todo el equipo.
Lo que quedó sin respuesta, como ## Discovery Gaps.
Un escritor por fase, cada uno con las filas aprobadas de su fase y nada más. Cada escritura se verifica leyendo el destino.
bun run agents:setup --stack escribe el bloque stack: con los valores del plan; bun run agents:setup completa identidad y entornos. Cada colisión que la app ya poseía entra en updater.protected_paths, con un empalme que deja el resto del yaml byte por byte. Una skill del framework que la app había copiado a mano se reemplaza por la copia de upstream que guardó la adopción (.agents/prompts/adopt-upstream/), solo si su fila tiene su propia línea de aprobación y con respaldo previo en .backups/project-adoption/; si el equipo la conserva, queda en las rutas protegidas.
Solo .env, solo valores que tú das en esta corrida, sin repetirlos nunca. Después, reiniciar la sesión: cada servidor MCP lee el .env con su loader cuando arranca.
Carga /acli y sincroniza los catálogos contra la instancia propia de la app, nunca con la bandera de referencia de UPEX. Un campo faltante no se crea: el plan nombra el fallback y que crearlo es decisión de un admin de Jira. Y la adopción no hidrata el proyecto entero: el caché del backlog se llena por historia.
Si el instalador dejó una fusión de instrucciones pendiente, se aplica tal cual, con su propia línea de aprobación y respaldo previo; el texto de la app nunca se resume ni se reordena. La skill <app>-context que escribió la adopción solo cambia en su description, reescrita desde el análisis para que enrute por el dominio real de la app; el texto preservado de la app nunca se toca. El contrato de API se sincroniza solo si la app sirve una spec y las rutas de salida no existían antes.
Relee el plan aprobado antes de cada fase y escribe solo sus filas.
Re-lee el yaml, re-corre la señal, re-parsea el archivo: un "listo" no alcanza.
Los valores de credenciales, que se tipean solo en .env.
La fusión de instrucciones, con una aprobación aparte de la del plan.
.agents/project.yaml con la app descrita, los catálogos .agents/jira-*.json y el AGENTS.md fusionado.
La verificación es fail-fast y en orden: para en el primer fallo, lo reporta con su salida, propone el arreglo y espera. Nunca arregla sola.
# fase 8, en este orden bun run agents:compat:check bun run vars:check bun run vars:env:check bun run harness:env:check bun run jira:check # salteado si el plan registró "sin tracker" bun run setup:doctor # sección stack: sin issues, sin drift bun run tooling:types:check # el alcance propio de la herramienta, nunca el tsconfig de la app bun run tooling:lint:check build / lint / types / test de la app # exit codes == línea de base de la fase 1
La capa agéntica vive dentro del árbol de la app, así que no alcanza con "el repo destino es de solo lectura". La lista de rechazos viaja literal en cada briefing de subagente.
Sin modo, la skill lo saca de la frase y, si no puede, corre adopt.
Barra de la skill. Para el chequeo de drift: /project-adoption check.
Sin barra: nombras la skill y el modo en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
Al cerrar, la skill te deja cada paso siguiente con la frase que lo dispara. Ninguno arranca por su cuenta.
Los mapas de negocio leídos del código y el schema de la app. Van en una sesión aparte porque pesan en tokens. Deck: Project context.
La guía de desarrollo y el glosario del dominio, que completan los documentos de producto de la app. Deck: Project foundation.
La estrategia de branches propia del proyecto y la protección del host, en solo lectura primero. Deck: Git flow master.
DESIGN.md escrito desde el tema vivo de la app. Deck: Design system.
La página /qa dentro de la app y el artefacto de credenciales. Deck: Testability guide.
Los tipos de la base en stack.database.types_path cuando faltan. Las fases base de bootstrap no corren sobre una app adoptada. Deck: Project bootstrap.