adopt-existing-project
Adecuar un proyecto Python YA EXISTENTE (legacy o con motor viejo embebido) al motor portable, orquestando las skills y scripts existentes en el orden correcto. Usar cuando se incorpora un repo con co
SKILL.mdskills/adopt-existing-project/SKILL.md
GitHubadopt-existing-project
Protocolo de adecuación de un proyecto Python que ya existe (con código,
datos, posiblemente una copia vieja del motor embebida y/o sin Git) para que pase
a consumir el motor portable orquestador_de_agentes como repo_destino.
Es pegamento operativo, NO un sistema paralelo. No reimplementa la instalación,
el bootstrap ni la planificación: los invoca en el orden correcto para el caso
"proyecto preexistente", y solo añade lo que ninguna skill cubre hoy (cierre de
WPs legacy como históricos, .gitignore anti-fuga en raíz externa, sincronización
de entrypoints, verificación de portabilidad).
Diferencia con skills hermanas (frontera explícita)
setup-agent-system(/agent-setup): instala/sincroniza el link motor↔destino. Esta skill lo INVOCA en la Fase 2; no lo duplica.setup-agent-systemasume un proyecto limpio o nuevo;adopt-existing-projectasume legacy con fricción.scaffold-python-project(/scaffold): crea un proyecto Python nuevo desde cero. Si el proyecto no existe aún, usa esa, no esta.secure-existing-project(/secure): migra credenciales aprivada/. Esta skill la INVOCA en la Fase 1 si hay secretos hardcodeados.orchestrator_destination_bootstrap.md: arranca una sesión en un destino ya adecuado. Es el paso SIGUIENTE a esta skill, no parte de ella.manager-create-work-plan/orchestrate-pipeline: ejecutan los tickets de desarrollo. Vienen DESPUÉS de adecuar.
Cuándo usarla
- Tienes un proyecto Python que funciona pero no consume el motor actual.
- El proyecto tiene una copia vieja/embebida del motor (
agent_system/,agent_controllerlegacy) que hay que integrar sin descartar el trabajo válido. - El proyecto no tiene Git, o lo tiene pero nunca se publicó.
- Quieres dejarlo listo para abrir tickets
<PREFIX>formales después.
Cuándo NO usarla
- Proyecto nuevo desde cero →
scaffold-python-project. - Destino ya adecuado y solo quieres operarlo →
orchestrator_destination_bootstrap.md. - Solo actualizar un destino ya instalado al motor actual →
setup-agent-system --sync.
Checklist canónica de adecuación (5 fases)
Las fases son secuenciales con gates. NO avances de fase con el gate en rojo.
MOTOR= raíz deorquestador_de_agentes.DEST= raíz del proyecto a adecuar. Todas las operaciones de estado del destino usan--project-root <DEST>oAGENT_PROJECT_ROOT=<DEST>. El motor permanece pristine (verificable conscripts/check_motor_pristine.py --snapshotantes y--checkdespués).
FASE 1 — Inventario y seguridad (pre-flight)
- Topología: confirma qué será
DEST(la raíz externa real, no una subcarpeta de código). Decide elTicket prefix:(3 letras, p.ej.EXF).WOT-es SOLO del motor/dogfooding, nunca de un destino. - Inventario de sensibles: localiza datos reales (config con credenciales,
datos personales, Excels, logs). Anótalos: son lo que el
.gitignoreraíz DEBE excluir. Si hay secretos hardcodeados en código → invocasecure-existing-project(/secure) para moverlos aprivada/. - Backup del legacy: si hay motor viejo embebido (
agent_system/u otro), cópialo FUERA deDESTantes de tocar nada. No se borra (decisión de integración, no de descarte): se ignora en Git en la Fase 4. - Git preexistente: ¿
DESTya tiene.git? Barrido:git -C <DEST> rev-parse --git-dir+ búsqueda recursiva de.git. Si hay historia previa, hay que auditarla por secretos ANTES de cualquier push (Fase 5), no asumir que está limpia.
Gate F1: topología decidida, sensibles inventariados, legacy respaldado, estado Git conocido.
FASE 2 — Instalación del motor (INVOCA setup-agent-system)
- Retira
.agentresidual si existe uno parcial de exploraciones previas (el instalador aborta si.agent/ya existe sin ser una instalación válida): muévelo a backup y confirmaTest-Path <DEST>/.agent== False antes de instalar. - Instala vía la skill canónica
setup-agent-system(/agent-setup):python <MOTOR>/scripts/install_agent_system.py --install --dest <DEST> --prefix <XXX> --yes(corre--dry-runprimero). Dejamotor_destination_link.json,agents.jsonconactive_profile: host-project,PROJECT.mdconTicket prefix: <XXX>. - Rellena
PROJECT.mdcon la realidad del proyecto (stack real, topología código/datos, rutas críticas). Es el source-of-truth quevalidateinspecciona y lo que leerá un agente nuevo. No dejar placeholders.
Gate F2: motor_destination_link.json apunta al motor correcto; perfil
host-project; PROJECT.md con prefijo correcto y sin placeholders.
FASE 3 — Integración del legacy + validate 0/0
- Cierra los WPs legacy como históricos, NO los re-implementes si su código ya
vive en
src/. Un sistema motor viejo (v3.2 u otro) es incompatible con el bus nuevo: el cierre es documental, en<DEST>/.agent/collaboration/_archive/HISTORIC_<WP-ID>.md, con evidencia ejecutable (comandos + exit codes), no prosa. No intentes--manager-approvesobre un WP legacy: no es un ticket del bus nuevo. - Si los tests legacy están en rojo por acoplamiento a la máquina (rutas
hardcodeadas tipo
/nonexistent, dependencia de unidadesZ:), arréglalos bajo un ticket<PREFIX>formal (no parche suelto), desacoplándolos contempfile/uuid. Evidencia = salida de la suite verde determinista. - Bootstrap + validate del destino:
python <MOTOR>/scripts/destination_context.py --bootstrap --project-root <DEST>python <MOTOR>/.agent/agent_controller.py --validate --json --project-root <DEST>
Gate F3: validate --json → 0 errores (warnings de prefijo aceptables solo
si justificados); WPs legacy archivados con evidencia; suite del destino verde
corriendo desde la raíz del código real.
FASE 4 — Git anti-fuga (commit local, sin push)
git initen la raíz externaDEST(si no existía). NOgit addaún..gitignoreen la RAÍZ EXTERNA (gate anti-fuga crítico). Si el proyecto tenía un.gitignoreen una subcarpeta de código, NO cubreprivada/cuandoprivada/es hermana de la subcarpeta en la raíz externa. Debe ignorar al menos:privada/, el config real con credenciales, los datos reales,.claude/settings.local.json, el bundle legacy (agent_system/),.agent/runtime/,.agent/context/, venvs, caches, logs.- Verificación seca de exclusión ANTES de stagear:
git -C <DEST> check-ignore -v <config-real> <datos-reales> .claude/settings.local.jsonPARAR sicheck-ignoreNO matchea cualquier archivo sensible (fuga garantizada). - Commit local solo si 13 está limpio. Sin
git remote add, singit push.
Gate F4: check-ignore matchea TODOS los sensibles; git status no muestra
ningún sensible como staged; commit local hecho en main.
FASE 5 — Auditoría de publicación (si se va a publicar)
- Auditoría dry-run sobre la historia (ya con HEAD, tras el commit de F4):
invoca
audit-git-publication(/audit-git-publication) =python <MOTOR>/scripts/classify_publication.py --repo-root <DEST> --out <...>- doble pasada adversarial de
prompts/audit_git_publication.md. El JSON es[RELATO], no evidencia: re-deriva cadaPUBLISH/DECIDEpor contenido.
- doble pasada adversarial de
- Gate de estado operativo:
python <MOTOR>/scripts/check_destino_publish_ready.py --project-root <DEST> --motor-root <MOTOR> - Publicación (acción humana):
git remote add+git push. Repo privado si hay cualquier duda sobre datos. Si la auditoría detecta un secreto ya commiteado en F4, rehacer el commit (reset + corregir gitignore/redacción): borrarlo del tree no lo saca de la historia local.
Gate F5 (publicación): check-ignore + scan manual limpios; auditoría sin
secretos en árbol/historia; PII personal redactada; check_destino_publish_ready
sin drift. El veredicto humano de la Pasada B prevalece sobre el exit-code del script.
Fricciones conocidas del motor al adecuar (workarounds verificados)
Estas son limitaciones REALES observadas. Cada una tiene un follow-up o workaround. Documentarlas aquí evita que cada adecuación las redescubra a tropezones.
classify_publication.pyy los fixtures de seguridad de tests → los archivos de test de redacción/publicación (p.ej.tests/test_redact.py,tests/test_classify_publication.py) embeben marcadores de secreto FALSOS a propósito para ejercitar el scanner. Resuelto por la allowlistSECURITY_FIXTURE_PATHSenclassify_publication.py: esos paths nombrados se eximen tanto en el tree-scan como en el history-scan, sin perder fail-closed para cualquier otro path (un blob mixto fixture+no-fixture NO se exime). Placeholder seguro en docs: usaAPI_KEY=<API_KEY>, no un valor opaco largo.Mecánica real de
.gitignoreen el tree-scan (corrige una nota previa imprecisa):_collect_repo_filesusagit ls-files --others --exclude-standard, así que SÍ respeta los archivos untracked ignorados (no los escanea). PERO escanea los archivos tracked aunque estén gitignored (un secreto ya commiteado se detecta aunque luego se añada al.gitignore). El history-scan recorre blobs de toda la historia. Workaround para tracked-ignored legítimos: la Pasada B refuta cada flag congit check-ignore+git ls-filesconfirmando que el archivo no es publicable y, si procede, rehaciendo el commit.run_pytest_safe.pyasume pytest instalado → falso rojo (No module named pytest) en destinos que usanunittestaunque la suite pase. Workaround:uv pip install pytestsolo en el.venvdel destino (pytest corre los tests unittest nativamente), sin tocarpyproject/uv.lock. (Registrado como follow-up del motor: detectar runner pytest|unittest.)El cierre canónico de un ticket cuyo checkpoint toca
.agent/collaboration/(markdowns de orquestación, no código) puede requerir--mark-ready --scope-override "<razón>"porque el scope-gate los trata como cambio fuera de los Files Likely Touched. Workaround: usar--scope-overridecon razón auditable (artefactos de orquestación, no código productivo).project_scanner.pyno regenera el project-map del destino (escanea porcwd/__file__, no por--project-root). Workaround: usardestination_context.py --bootstrap --project-root <DEST>para eldestination_map.md; el project-map JSON del destino se corrige a mano si hace falta.Múltiples entrypoints/lanzadores legacy (
.bat, wrappers Espanso, accesos directos) se desincronizan al cambiar el entrypoint. Barrera: tras cambiar cualquier lanzador,greppor el nombre del entrypoint viejo en TODO el repo y actualizar todos. En.bat,%~dp0YA termina en\: no añadir.ni/.Aplanado que mueve el producto a la raíz (rutas hardcodeadas en lanzadores). Cuando un destino se aplana (el producto sube de
publica/repo/oz_automatizacion/publica/repo/a la raíz), TODO lanzador con ruta absoluta o relativa al subdirectorio viejo se rompe SILENCIOSAMENTE. Check obligatorio, antes y después del aplanado:grep -rl "publica/repo\|z_automatizacion" --include="*.bat" --include="*.ps1" --include="*.sh" <dest>y actualizar cada ruta a la nueva ubicación (en.batusarcd /d "%~dp0"para la raíz, sin añadir.//). (Verificado:fiscal.baten Contabilidad apuntaba a...\z_automatizacion\publica\repoy se habría roto al aplanar.) Sin este check, el aplanado deja el proyecto sin punto de entrada funcional.
Contrato de fallo
- Si
check-ignoreno matchea un archivo sensible, detente: no se hacegit addhasta resolverlo. - Si
validate --jsontiene errores, no avances a Git ni a publicación. - Si el motor deja de estar pristine (
check_motor_pristine.py --checkfalla), detente y revierte en el motor: el destino no debe escribir en el motor. - Si la raíz operativa apunta al motor en vez del destino, detente.
- Si un WP legacy "no cierra" por gates del sistema viejo, NO fuerces el bus nuevo: ciérralo como histórico documental.
Referencias
skills/setup-agent-system/SKILL.md— instalación/sync (invocada en F2).skills/secure-existing-project/SKILL.md— migración de secretos (F1 si aplica).skills/audit-git-publication/SKILL.md— auditoría de publicación (F5).prompts/orchestrator_destination_bootstrap.md— arranque de sesión (paso siguiente).prompts/audit_git_publication.md— protocolo de doble pasada de publicación.scripts/install_agent_system.py,destination_context.py,check_destino_publish_ready.py,classify_publication.py,check_motor_pristine.py— herramientas invocadas.