apache/magpie

configuración

Esta habilidad es el único artefacto del marco de trabajo que un proyecto adoptante compromete. Cada otra habilidad de apache-magpie (seguridad, gestión de PR, issues) es un enlace simbólico ignorado por git hacia la instantánea ignorada por git en <snapshot-dir> que esta habilidad gestiona.

El modelo de adopción es instantánea + anulaciones agénticas + actualizaciones conscientes de desviaciones (no submódulo, no mercado, no copia proveída):

• El marco de trabajo se descarga en <snapshot-dir> y se ignora por git en el repositorio del adoptante. La instantánea es un artefacto de compilación, no código fuente.
• Se admiten tres métodos de instalación (ver docs/setup/install-recipes.md para recetas copiables textualmente):
  • svn-zip — zip firmado y lanzado desde la distribución de ASF (recomendado para producción una vez que los lanzamientos estén disponibles).
  • git-tag — fijado a una etiqueta git específica.
  • git-branch — sigue la punta de una rama (por defecto: main, la ruta de trabajo en curso).
• Dos archivos de bloqueo registran la versión del marco de trabajo. El comprometido declara a qué se fija el proyecto; el local registra lo que cada máquina realmente obtuvo. La desviación entre ellos se detecta y se remedia mediante /magpie-setup upgrade.
• Los enlaces simbólicos hacen que las habilidades del marco de trabajo sean invocables como si vivieran en el repositorio del adoptante. Cada enlace simbólico se nombra magpie-<framework-skill> — cada habilidad del marco se instala bajo un prefijo magpie- para que tenga espacio de nombres y nunca entre en conflicto con las habilidades propias del adoptante (por ejemplo, la skills/pr-management-triage/ de la instantánea se convierte en magpie-pr-management-triage, invocada como /magpie-pr-management-triage). .agents/skills/ es el único lugar canónico: sus entradas magpie-* enlazan a <snapshot-dir>/skills/<framework-skill>/. Cada otro objetivo de agente (.claude/skills/, .github/skills/, …) obtiene un enlace simbólico de relé delgado por habilidad que apunta de vuelta a la entrada canónica (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>) — sin importar qué diseño haya usado anteriormente el proyecto adoptante (ver agents.md). Los enlaces simbólicos se ignoran por git porque sus objetivos desaparecen en un clon nuevo antes de que se ejecute /magpie-setup.
• Las modificaciones específicas del adoptante a los flujos de trabajo del marco se guardan como instrucciones legibles por el agente en .apache-magpie-overrides/<skill-name>.md (comprometido). Invalidan o cambian pasos que la habilidad del marco de trabajo ejecutaría de otra forma. Ver overrides.md para el contrato y docs/setup/agentic-overrides.md para la justificación del diseño.

Auto-adopción local (solo el checkout del marco de trabajo). El único repositorio que no se puede adoptar mediante el mecanismo de instantánea es el propio checkout del marco de trabajo Apache Magpie — una instantánea remota del marco dentro de sí mismo sería circular. En su lugar, se auto-adopta con method:local: cada magpie-<skill> canónico en .agents/skills/ es un enlace simbólico comprometido hacia la fuente ../../skills/<skill>/ dentro del repositorio, y cada otro objetivo de agente activo (agents.md) — .claude/skills/ (Claude Code), .github/skills/ (cargador de habilidades de GitHub), y cualquier rezagado presente — obtiene un enlace simbólico de relé comprometido (magpie-<skill> → ../../.agents/skills/magpie-<skill>) — sin instantánea, sin obtención remota y sin copia. Esto hace que las habilidades propias del marco sean invocables mientras se desarrolla el marco, y cada contribuyente las obtiene activas en un clon nuevo sin ningún paso de configuración. adopt detecta el checkout del marco estructuralmente y se enruta allí automáticamente (ver adopt.md → Auto-adopción local).

Los dos archivos de bloqueo

El modelo de archivo de bloqueo del marco de trabajo divide a lo que el proyecto se fija (comprometido) de lo que esta máquina realmente obtuvo (local). Esta división es la base de la detección de desviaciones y del soporte multinstalador.

<committed-lock> — .apache-magpie.lock

Comprometido en la raíz del repositorio del adoptante. El pin del proyecto. Editado solo por /magpie-setup; no modificar a mano.

# .apache-magpie.lock — comprometido; el pin del proyecto.

method: <git-branch | git-tag | svn-zip>
url:    <ver formato por método abajo>

# Para method=git-branch:
ref:    main

# Para method=git-tag:
ref:    v1.0.0          # el nombre de la etiqueta
commit: <SHA>           # el commit al que apuntaba la etiqueta cuando se comprometió

# Para method=svn-zip:
ref:    1.0.0           # el número de versión
sha512: <hash>          # el SHA-512 del zip lanzado (para verificación al re-obtener)

El siguiente adoptante que ejecute /magpie-setup adopt lee este archivo y reinstala a la misma versión que el proyecto había declarado. Esta es la esencia de la promesa "adoptar una vez, todos los usuarios posteriores obtienen lo mismo".

<local-lock> — .apache-magpie.local.lock

Ignorado por git en la raíz del repositorio del adoptante. La huella digital de la instantánea local. Registra lo que esta máquina obtuvo y cuándo.

# .apache-magpie.local.lock — ignorado por git; por máquina.

source_method:    <git-branch | git-tag | svn-zip>
source_url:       <URL de la que realmente se obtuvo la instantánea>
source_ref:       <rama / etiqueta / versión realmente obtenida>
fetched_commit:   <SHA del commit en disco ahora>
fetched_at:       <marca de tiempo ISO-8601>

La comprobación de desviaciones en cada invocación de habilidad del marco compara esto con <committed-lock> y muestra cualquier discrepancia como una propuesta de /magpie-setup upgrade.

Archivos detalle en este directorio

Archivo	Propósito
adopt.md	Guía de adopción por primera vez — reconocer instantánea existente vs necesita bootstrap, escribir los dos archivos de bloqueo, preguntar al usuario qué familias de habilidades conectar, crear los enlaces simbólicos ignorados por git, preparar .apache-magpie-overrides/, instalar el hook post-checkout, actualizar la documentación del proyecto. La sub-acción por defecto.
upgrade.md	Refrescar la instantánea ignorada por git según el bloqueo comprometido, reconciliar cualquier anulación agéntica + enlaces simbólicos contra la nueva estructura del marco, mostrar conflictos. Conduce el flujo de remediación en caso de desviación.
verify.md	Verificación de salud de solo lectura — instantánea presente + intacta, ambos archivos de bloqueo sincronizados, enlaces simbólicos apuntan a objetivos vivos, .gitignore correcto, .apache-magpie-overrides/ existe, estado de desviación (comprometido vs local), la habilidad setup misma está actualizada.
agents.md	El registro de objetivos de agente — qué directorios reciben los enlaces simbólicos de habilidades del marco entre proveedores, y el modelo canónico más relé: .agents/skills/ es el único hogar canónico (enlaces a la instantánea/fuente); cada otro objetivo (claude-code, github, nativos rezagados como Windsurf / Goose) obtiene un enlace simbólico de relé por habilidad hacia .agents/skills/. Define la selección de objetivos activos, la portabilidad del formato SKILL.md, y la capa solo para Claude Code (sandbox/hooks). La fuente de verdad que cada sub-acción consulta para el conjunto de objetivos.
overrides.md	Gestión de archivos de anulación agéntica — abrir/preparar una anulación para una habilidad del marco, listar anulaciones existentes, ayudar a reconciliar cuando el marco cambia la estructura de la habilidad subyacente en una actualización.
unadopt.md	Revertir la adopción — eliminar instantánea, bloqueos, enlaces simbólicos, hook post-checkout, entradas de .gitignore, las secciones de adopción en README.md / AGENTS.md / CONTRIBUTING.md, y la habilidad setup comprometida en sí misma. Conserva .apache-magpie-overrides/ por defecto; --purge-overrides también lo elimina. Muestra el plan de eliminación completo antes de cualquier escritura.

Reglas de oro

Regla de oro 1 — nunca modificar la instantánea. El <snapshot-dir> es un artefacto de compilación, ignorado por git, y de solo lectura desde la perspectiva de un adoptante. Toda modificación que un adoptante desee debe ir a .apache-magpie-overrides/ (donde está comprometida y sobrevive a la próxima upgrade). La habilidad, y cualquier otra habilidad del marco que consulte anulaciones en tiempo de ejecución, nunca escribe en <snapshot-dir>.

Regla de oro 2 — <committed-lock> es el pin del proyecto; <local-lock> es la verdad por máquina. Sirven para propósitos diferentes y viven en lugares diferentes:

• <committed-lock> declara qué versión usa el proyecto. Editado por el adoptante que ejecuta /magpie-setup adopt primero (o que luego ejecuta /magpie-setup upgrade y acepta el nuevo pin). Aumentarlo es una acción deliberada a nivel de proyecto; el aumento aparece en el git diff del PR que lo propuso.
• <local-lock> registra lo que instaló esta máquina. Actualizado silenciosamente por /magpie-setup adopt y /magpie-setup upgrade. Por desarrollador, por checkout, por worktree.

Regla de oro 3 — la desviación se muestra, la desviación se remedia. Cada habilidad del marco (y /magpie-setup verify) comprueba <committed-lock> vs <local-lock> al inicio de su ejecución. En caso de discrepancia, la habilidad muestra la brecha y propone /magpie-setup upgrade. El usuario acepta o pospone; si acepta, upgrade:

1. Elimina <snapshot-dir> por completo.
2. Reinstala según el bloqueo comprometido (la nueva versión que el proyecto eligió).
3. Refresca los enlaces simbólicos de habilidades del marco ignorados por git — añade cualquier nueva habilidad del marco que cubra la selección de familia del usuario, elimina cualquier habilidad del marco que haya sido renombrada o eliminada.
4. Reconoce las anulaciones agénticas contra la nueva estructura del marco (muestra conflictos; nunca reescribe automáticamente).
5. Actualiza <local-lock> a la nueva obtención.

Regla de oro 4 — .gitignore mantiene limpio el repositorio del adoptante. Tres cosas ignoradas por git en el repositorio del adoptante:

• <snapshot-dir> (toda la instantánea del marco — gigabytes potencialmente).
• <local-lock> (estado por máquina).
• Los enlaces simbólicos magpie-* que setup adopt crea en cada directorio de objetivo activo — los canónicos en .agents/skills/ (apuntan a la instantánea ignorada por git) y los relés en .claude/skills/ / .github/skills/ / rezagados (apuntan a las entradas canónicas) — ambos colgarían en un clon nuevo. La única excepción no ignorada en cada directorio es magpie-setup.

Comprometido: esta habilidad (setup, como la canónica .agents/skills/magpie-setup/ más sus relés), el <committed-lock>, el directorio .apache-magpie-overrides/, las propias entradas de .gitignore, cualquier actualización de documentación del proyecto que haga la sub-acción adopt.

Regla de oro 5 — .agents/skills/ es canónico; todo lo demás simplemente relea hacia él. Independientemente de cómo un proyecto adoptante haya organizado anteriormente sus .claude/skills/ o .github/skills/, adopt siempre conecta el marco de la misma manera: los enlaces canónicos magpie-* viven en .agents/skills/, y cada otro objetivo activo (.claude, .github, rezagados) recibe enlaces simbólicos de relé por habilidad apuntando de vuelta a las entradas canónicas (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). Las habilidades nativas propias del adoptante (no magpie-) en esos directorios se dejan intactas. Ver agents.md.

Regla de oro 6 — copiar esta habilidad, enlazar simbólicamente el resto; todas bajo el prefijo magpie-. Esta habilidad (fuente skills/setup/) es la única habilidad del marco que se copia en el repositorio del adoptante — comprometida como la canónica .agents/skills/magpie-setup/, con enlaces simbólicos de relé comprometidos hacia ella desde .claude/skills/magpie-setup y .github/skills/magpie-setup. Todas las demás habilidades del marco se enlazan simbólicamente (enlace canónico a la instantánea ignorada por git, más relés), cada una nombrada magpie-<framework-skill> (ej. magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/). El prefijo magpie- da espacio de nombres a cada habilidad del marco para que nunca entre en conflicto con las habilidades propias del adoptante. Mezclar copia y enlace simbólico — copiar una habilidad de seguridad, por ejemplo — crea un riesgo de mantenimiento: las copias se desvían de la fuente de verdad del marco, y el mecanismo de detección de desviaciones (que asume que la versión del marco es la de <snapshot-dir>) se aplica incorrectamente en silencio.

Regla de oro 7 — las anulaciones agénticas se leen en tiempo de ejecución. Cada habilidad del marco que soporta anulaciones comienza su ejecución verificando si existe .apache-magpie-overrides/<this-skill>.md para obtener instrucciones específicas del adoptante y las aplica antes de ejecutar el comportamiento por defecto. El archivo de anulación es markdown simple que el agente interpreta — sin motor de plantillas, sin herramienta de parches. Ver docs/setup/agentic-overrides.md para el contrato.

Regla de oro 8 — dos familias se instalan siempre; el resto es optativo. Dos familias de habilidades se conectan incondicionalmente en cada ejecución de adopt / upgrade / worktree-init y al usuario nunca se le pregunta sobre ellas:

• setup-* — toda habilidad del marco cuyo nombre fuente comience con setup- excepto el bootstrap setup mismo (que se copia como magpie-setup según la Regla 6, no se enlaza simbólicamente). Concretamente: setup-isolated-setup-install, setup-isolated-setup-update, setup-isolated-setup-verify, setup-override-upstream, setup-shared-config-sync, más cualquier nueva habilidad setup-* que el marco añada en el futuro — cada una enlazada simbólicamente como magpie-setup-*.
• list-* — la familia de descubrimiento; toda habilidad del marco cuyo nombre fuente comience con list-. Hoy esto es list-skills solamente (enlazada simbólicamente como magpie-list-skills); el prefijo permite que el marco añada un di…

… [truncado para traducción]