Agentic QA · Skill de workflow

/jira-administration

Dos tareas de administración que tocan a todo el proyecto: alinear los Components de Jira con los módulos reales de la app, y repuntar el repo a un sitio nuevo de Atlassian después de una migración. En las dos, la IA lee primero, te muestra el plan y no escribe nada hasta que digas que sí.

Un modo por corrida Lee antes de tocar Escribe solo con tu OK

Deck de la skill jira-administration. Reúne lo que antes eran dos comandos sueltos, jira-components y jira-instance-migration, que sobreviven solo como frases que la activan. Las dos tareas son raras y de alto impacto: un error se nota recién semanas después, en un filtro que no discrimina o en un campo que recibió datos que no eran suyos. Pulsá → para avanzar, S para modo presentador, O para overview, F para pantalla completa.

Decidir · 2 de 15

Cambia algo de la estructura de Jira?

Usala para

Reconciliar los Components del proyecto con los módulos funcionales de la app: crear los que faltan y renombrar los viejos.
Repuntar el repo a otra instancia de Atlassian tras una migración de sitio, y regenerar los catálogos que esa migración invalidó.

Se activa también con "sync Jira components", "cambió la URL de Jira", "repoint jira" o "migrar la instancia de jira".

No es para esto: va a

Ponerle un component a un issue puntual	la skill de testing que crea el issue, vía /acli
Operar tickets: crear, transicionar, comentar	/acli
Refrescar catálogos sin cambio de instancia	bun run jira:sync-*, directo
Provisionar Jira por primera vez	docs/core/setup/jira-xray.html (sitio de docs)

Cada modo tiene su propio "no es para esto". Components no toca catálogos ni la instancia; la migración no da de alta un Jira nuevo.

Fuentes: la descripción del SKILL.md y los "Do NOT use for" de references/components.md y references/instance-migration.md. Que cada skill de testing complete los components de los issues que crea viene de la doctrina de defectos: components es obligatorio en cada bug, defect, improvement y Test.

Mapa · 3 de 15

Un modo por corrida, y el mismo sello en los dos

El primer token elige el modo; si no nombra ninguno, pregunta

Router

Qué modo?

components
instance-migration

→

Siempre

Carga /acli

y valida credenciales
antes de operar

→

Nunca

Los dos juntos

ni cae de uno
en el otro

Modo components

Fase 1

Mapa de módulos

código + backlog

→

Fase 2

Components vivos

--list con issues

→

Fase 3

Plan + dry run

esperar tu OK

→

Fase 4

Aplicar y verificar

--apply · --list

Modo instance-migration

Fase 0

Las dos instancias

confirmadas

→

Fase 1

Auditoría

tabla antes de editar

→

Fases 2 y 3

Aplicar y verificar

yaml · acli

→

Fase 4

Catálogos

regenerar y probar

→

Fase 5

Commit

push con tu OK

Fuente: Mode routing y Compact Rules del SKILL.md, más las fases de cada reference. Los recuadros amarillos son los puntos donde decidís vos. Cada modo carga solo su propia reference y corre solo sus propias verificaciones: nunca las del otro.

Contrato · 4 de 15

Leer, mostrar, esperar, recién ahí escribir

Sin credenciales, parada total

Si falta ATLASSIAN_EMAIL o ATLASSIAN_API_TOKEN, te nombra la variable, te señala .env y .env.example y pide reiniciar la sesión. Sin atajos, sin corrida parcial (Regla #10).

El host vive en un solo lugar

.agents/project.yaml → issue_tracker.atlassian_url. Un ATLASSIAN_URL viejo en .env o en el entorno es contaminación: se borra, no se actualiza.

Repo sin onboarding

Si project.project_name es null, el repo es un template: atlassian_url y project_key quedan en null y lo dice en el reporte.

Fuente: Compact Rules del SKILL.md. La regla del host único viene del ancla de identidad de instancia de AGENTS.md: una segunda copia del host es justamente la que se pone vieja. En un template, la skill no fabrica un commit para tapar que el valor está vacío.

Modo components · 5 de 15

Un component es un módulo de la app

La convención

Un component = un módulo funcional de la aplicación que corre, derivado de su superficie real (rutas, features). No sale de la taxonomía de planificación: un Epic es una unidad de trabajo, un component es una unidad del sistema.

Por qué importa

Es obligatorio en cada bug, defect, improvement y Test, y es la clave de agrupación de los tableros de cobertura. Un filtro sirve en la medida en que discrimina.

Por qué un script y no acli

acli no puede crear, renombrar ni borrar components. Por eso el modo maneja scripts/sync-jira-components.ts, que habla con la API REST directo (también bun run jira:components).

Por qué un plan y no autodetección

Decidir qué rutas son un mismo módulo y con qué nombre es juicio, no mecánica. La IA escribe el plan, una persona lo aprueba y el script ejecuta solo lo aprobado.

Rename no es create

Borrar y recrear con otro nombre deja huérfanos todos los issues asignados. El rename conserva cada asignación: así migra un component viejo a la convención sin editar issues en masa.

Fuentes: el encabezado de scripts/sync-jira-components.ts, el "Hard gate" de references/components.md y la Parte 3 de agentic-qa-core/references/defect-management-doctrine.md. El deck de gestión de defectos de sprint-testing muestra el mismo modelo de tres ejes desde el lado del que reporta.

Modo components · 6 de 15

Lo que existe, lo que viene y lo que ya hay

Fase 1 · La IA propone, no decide

1a · El código	La superficie real de la app. En Next.js App Router: app//page.tsx y app/api//route.ts; en otros stacks, su router o sus controllers. Agrupa con el vocabulario del producto: /checkout/cart y /checkout/payment son Checkout.
1b · El backlog	Epics y Stories con áreas que el código todavía no tiene. Un component se puede declarar antes del código: una feature en refinamiento ya tiene Stories y Tests que lo necesitan.
1c · La propuesta	Cada módulo con lo que absorbe (rutas o Epic), marcado como existente o adelantado, para que corrijas la agrupación.

Usar solo el código es el error fácil: borra en silencio todo lo planificado.

Choque de nombres

Si el producto tiene Tests, Runs o Bugs como features, choca con el vocabulario de QA. Propone prefijar con el nombre del producto (Bunkai Tests), y el prefijo entra en el plan que aprobás: nunca se aplica solo.

Fase 2 · Components vivos

bun scripts/sync-jira-components.ts \ --list --project {{PROJECT_KEY}}

Lista cada component con su cantidad de issues, que es lo que está en juego. Cada módulo propuesto queda como: ya existe (skip), existe con otro nombre (rename) o falta (create).

Fuente: Fases 1 y 2 de references/components.md. Adelantar un component es barato y seguro: create es aditivo, rename re-etiqueta sin tocar asignaciones, y el modo se vuelve a correr cuando el mapa cambia. Si el módulo sale con otro nombre es un rename; si nunca sale, es una fila sin uso. El backlog se lee con bun run jira:sync-issues pull --dry-run o con lo ya sincronizado en .context/PBI/epics/.

Modo components · 7 de 15

Un plan en JSON, un dry run y un sí

Fase 3 · El plan, en .context/reports/jira-components-plan.json

{ "project": "<KEY>", "rename": [{ "from": "Bugs & Defect Heatmap", "to": "Bunkai Bugs" }], "create": [{ "name": "Bunkai Auth", "description": "Login, registration, sessions" }] }

Te lo muestra como tabla: renames separados de creates, y cada rename con su cantidad de issues.

Dry run, por defecto

Sin --apply el script solo muestra lo que resolvería. Un rename cuyo origen ya no está, o cuyo destino ya existe, queda como skip documentado: re-correr un plan aplicado a medias es normal.

Esperar la aprobación

Podés cambiar la agrupación, los nombres o el prefijo. Regenera el plan y lo vuelve a mostrar hasta que lo apruebes.

Fase 4 · Aplicar y verificar

bun scripts/sync-jira-components.ts \ .context/reports/jira-components-plan.json --apply bun scripts/sync-jira-components.ts \ --list --project {{PROJECT_KEY}}

La lista viva tiene que coincidir con el plan aprobado, con los renames mostrando sus issues intactos.

Fuente: Fases 3 y 4 de references/components.md y el uso documentado en el encabezado del script. El reporte final trae la lista de components resultante, qué se renombró, qué se creó, qué se salteó y cualquier skip cuyo motivo convenga revisar.

Modo instance-migration · 8 de 15

La falla no es un 404: es un 200 OK

La mitad fácil

Repuntar la URL del sitio. Es una línea en .agents/project.yaml y un login de acli.

La mitad que evita la corrupción

Regenerar los catálogos de .agents/. Una migración de sitio reasigna los ids de los custom fields en vez de conservarlos.

Antes, del lado de Xray

Una mudanza completa entre sitios sigue el runbook de /xray-cli y cierra con este modo.

Fuente: "Why this is not a find-and-replace" de references/instance-migration.md. El slug del diagrama es ilustrativo: cualquier campo del catálogo corre el mismo riesgo. El cierre de la mudanza de Xray con este modo está en xray-cli/SKILL.md y en su references/migration-runbook.md.

Modo instance-migration · 9 de 15

De dónde a dónde, y qué no se toca

Fase 0 · Resolver las dos instancias

Origen	Lo detecta, no lo pregunta primero: atlassian_url del yaml, la sesión de acli y bun run --silent jira:url. Si no coinciden, el repo ya está a medio migrar: es una reparación y te pregunta cuál es el "antes" real.
Destino	Nunca lo adivina. Si no vino en la invocación, pregunta: un sitio que el repo nunca contactó no se puede detectar.
Sondas	Dos sondas que no abren el .env: test -n "${ATLASSIAN_URL+x}" tiene que decir unset y bunx varlock load --agent --filter ATLASSIAN_URL tiene que imprimir {}. Un hit es contaminación a limpiar, nunca evidencia.

Confirma <origen> → <destino> en una línea, espera, y prueba /rest/api/3/myself en el destino: cualquier cosa distinta de 200 frena el modo.

Fase 1 · Auditar antes de editar

Barre el repo buscando el host de origen y clasifica cada hit en "cambia" o "no cambia". La tabla se te muestra antes de tocar nada.

No cambia

Un dominio alias que redirige al sitio activo. Pero no se ve desde el repo: confirmalo a mano.
Registros históricos: reescribirlos falsifica el pasado.
Código cuyo patrón ya generaliza (una regex, no un literal).
.context/PBI/: el sync lo reconstruye.

Ni en una lista ni en la otra

Un workflow de CI, un README, .mcp.json: pregunta antes de tocarlo.

Fuente: Fases 0 y 1 de references/instance-migration.md. Migrar a una instancia vacía o a medio provisionar regenera catálogos vacíos y los publica, que es peor que no hacer nada: por eso la prueba de alcance va antes de cualquier cambio. Los dos hosts se normalizan al host pelado, sin esquema ni barra final.

Modo instance-migration · 10 de 15

Repuntar en orden y probarlo en el destino

Fase 2 · Aplicar

1	atlassian_url: https://<destino> en .agents/project.yaml, primero: es lo que todo lo demás lee. bun run --silent jira:url tiene que devolver el destino.
2	Borrar cualquier ATLASSIAN_URL viejo que hayan encontrado las sondas, y lo que lo exporte al proceso.
3	Re-login de acli con el sitio que da bun run --silent jira:url --slug: si el yaml quedó mal, el login falla fuerte.

La sesión de acli es de la máquina

Vive en ~/.config/acli. El re-login repunta todos los repos de esta máquina, no solo este. Si todavía necesitás el sitio viejo para otro repo, te avisa antes.

Fase 3 · Verificar, como tabla

El yaml, bun run --silent jira:url y la sesión de acli nombran el destino.
La sonda test -n "${ATLASSIAN_URL+x}" dice unset.
/rest/api/3/myself en la URL resuelta devuelve 200.

Si algo no coincide, la migración falló: lo dice y frena.

Higiene de secretos

Nunca abre el .env, ni filtrado por clave (ni cat, grep o source): hasta un grep exacto deja ATLASSIAN_API_TOKEN en la terminal y en el transcript. Usa el par por nombre dentro de bunx varlock run y comprueba presencia con bunx varlock load --agent (valores redactados). Tampoco guarda un backup del .env dentro del repo, porque el .gitignore suele cubrir el nombre exacto y no los sufijos.

Fuente: Fases 2 y 3 de references/instance-migration.md. El chequeo del resolver no es redundante con el del yaml: es el único que prueba que la herramienta coincide con el archivo, y avisa por stderr si una variable vieja lo contradice. Para cazar un ATLASSIAN_URL heredado: bun run vars:env:check o bun run setup:doctor. En un repo template, atlassian_url queda en null.

Modo instance-migration · 11 de 15

La parte que se saltea es la que corrompe

Catálogo	Se regenera con
.agents/jira-fields.json	bun run jira:sync-fields --force sin --force frena: catálogo ya poblado
.agents/jira-link-types.json	bun run jira:sync-link-types no tiene --force, y lo traga en silencio
.agents/jira-workflows.json	bun run jira:sync-workflows idempotente: --force no suma nada

Antes de sincronizar: el manifiesto

.agents/jira-required.yaml no tiene ids, pero es la entrada: jira:sync-workflows cataloga solo los work types que declara. Si quedó atrás, el catálogo sale amputado y con exit 0. Lo compara con upstream (bun run jira:baseline avisa) y te deja decidir por work type.

Probar que los ids se movieron

El diff de .agents/ tiene que mostrar ids cambiados. Y un id cambiado no es un id correcto: dos slugs pueden intercambiarse. Pregunta al sitio vivo qué es cada id y lo compara con el nombre catalogado.

Lo que más se escapa

Campos de selección con options vacías, ids literales de customfield_, de status o de transición fuera de .agents/, y variables que fijan un id por encima del catálogo.

--upex casi nunca

Baja el catálogo de referencia de los autores del boilerplate, con ids de su sitio. Para tu migración, nunca: es un andamio para quien no tiene permiso de Administer.

Fuente: Fase 4 de references/instance-migration.md. Si el manifiesto necesita cambios, va primero y después los syncs: en el otro orden los catálogos se regeneran dos veces. jira:sync-workflows pide el project key si el yaml lo tiene en null y lo persiste; en un template hay que revertir esa línea. El updater nunca pisa jira-required.yaml, por eso se queda atrás en silencio.

Modo instance-migration · 12 de 15

Commits separados y lo que solo una persona puede ver

Fase 5 · Commit

chore(jira): sync jira-required.yaml work types with upstream chore(jira): point atlassian_url at the <target> instance chore(jira): refresh field, workflow and link-type catalogs for <target>

El del manifiesto va primero y solo si hubo cambio. .env nunca se commitea. En un template el commit del yaml no tiene contenido: se saltea y lo dice, sin commit vacío.

Push con confirmación

Sigue la estrategia de git vía /git-flow-master y no hace push sin tu OK: en un boilerplate, publicar catálogos afecta a cada proyecto que después corra --upex.

El reporte de cierre

Config	antes y después de cada punto, y el id de un campo como prueba
Verificación	cuántos ids se contrastaron con el sitio vivo y cuántos no coinciden
A mano	el dominio alias ya resuelve al destino?
A mano	si el manifiesto estaba atrás, lo que lo atrasó lo va a volver a atrasar
Al equipo	cada persona repite el login de acli en su máquina: una sesión vieja devuelve datos del sitio viejo sin error

Fuente: Fase 5 y "Closing report" de references/instance-migration.md. La configuración del repo y el refresco de catálogos son responsabilidades distintas, por eso son commits distintos. Si el equipo consume el catálogo de referencia con --upex, nadie debería correrlo hasta que upstream publique sus catálogos post-migración.

Salvaguardas · 13 de 15

Lo que nunca hace

#	Regla
R1	Escribir en Jira, en el repo o en la sesión de acli sin tu aprobación explícita, dada en la misma corrida.
R2	Combinar los dos modos, o adivinar uno a partir de un "arreglá Jira" sin más.
R3	Borrar y recrear un component con issues asignados: para eso está el rename.
R4	Actualizar un ATLASSIAN_URL en .env o en el entorno: se borra, porque una segunda copia es la que se pone vieja.
R5	Adivinar el sitio de destino, o seguir si no responde 200.
R6	Usar --upex para migrar tu propia instancia.
R7	Escribir un host o un project key en un repo template, o fabricar un commit para tapar que está vacío.

Sin atajos: credenciales faltantes, parada total.

Sin éxito falso: un exit 0 no prueba que el catálogo esté completo.

Sin push solo: los catálogos publicados viajan.

Reglas tomadas de las Compact Rules del SKILL.md y de los hard gates de cada reference. Se apoya en las Reglas críticas #10 (credenciales de MCP: parar), #5 (push a ramas protegidas según la política de git del proyecto) y #16 (un código de éxito describe la llamada, no el resultado: por eso cada modo verifica en el destino).

Entradas y salidas · 14 de 15

Qué lee, qué deja

Lee

.agents/project.yaml: el host, el project key y si el repo ya tiene onboarding.
ATLASSIAN_EMAIL y ATLASSIAN_API_TOKEN, por nombre dentro de bunx varlock run; el .env no se abre nunca.
components: el código de la app objetivo y su backlog (.context/PBI/epics/).
migración: .agents/jira-required.yaml contra el de upstream, y el sitio vivo para verificar cada id.

Deja

components: .context/reports/jira-components-plan.json y, con tu OK, los components en Jira.
migración: atlassian_url en el yaml y los catálogos jira-fields.json, jira-workflows.json y jira-link-types.json.
Una sesión de acli repuntada en esta máquina.
En el chat: el reporte, con lo que requiere una persona marcado aparte.

Herramientas: /acli antes de cualquier operación de Jira, scripts/sync-jira-components.ts, los bun run jira:* que declara package.json, y /git-flow-master para commitear.

Fuentes: Compact Rules del SKILL.md, los Prerequisites de references/components.md, las Fases 2, 4 y 5 de references/instance-migration.md, y la tabla de reportes de .context/reports/README.md, que atribuye el plan de components a este modo.

Cierre · 15 de 15

Invocación y handoffs

Cómo se invoca

Claude Code: /jira-administration components o /jira-administration instance-migration. Lo que sigue al modo pasa tal cual: components BK ../bunkai, instance-migration old.atlassian.net new.atlassian.net.
OpenCode y Codex: cargá la skill jira-administration, modo components o instance-migration.

Antes

Al adoptar el repo, después de bun run jira:sync-fields, jira:sync-workflows y jira:sync-link-types, viene el modo components.
/xray-cli: una mudanza de sitio de Xray cierra con instance-migration.

Después

Las skills de testing completan el component de cada issue que reportan: gestión de defectos.
/git-flow-master: commitea y abre el PR de la migración.

Lo que te llevás

Components que reflejan la app real sin perder una sola asignación · una migración que no escribe en silencio en el campo equivocado · cada cambio visto y aprobado antes de existir.

Canon: .agents/skills/jira-administration/SKILL.md y sus references/. La convención de components la fija agentic-qa-core/references/defect-management-doctrine.md.

Fin del recorrido. El orden de adopción (catálogos primero, components después) viene de la tabla de proyecto nuevo de agentic-qa-onboard/SKILL.md. El modo sin argumentos también funciona: components resuelve el key desde .agents/project.yaml y pregunta por el repo objetivo; instance-migration detecta el origen y pregunta el destino.