apache/magpie

configuração

Este skill é o único artefato do framework que um projeto adotante commit. Cada outro skill do apache-magpie (segurança, gerenciamento de PR, issues) é um symlink ignorado pelo git para o snapshot ignorado em <snapshot-dir> que este skill gerencia.

O modelo de adoção é snapshot + sobreposições agentivas + atualizações conscientes de descompasso (não submódulo, não marketplace, não cópia versionada):

• O framework é baixado em <snapshot-dir> e ignorado pelo git no repositório adotante. O snapshot é um artefato de build, não código-fonte.
• Três métodos de instalação são suportados (veja docs/setup/install-recipes.md para receitas copiáveis e coláveis):
  • svn-zip — zip liberado e assinado da distribuição ASF (recomendado para produção assim que os releases forem publicados).
  • git-tag — fixado em uma tag git específica.
  • git-branch — segue a ponta de um branch (padrão: main, o caminho WIP).
• Dois arquivos de lock registram a versão do framework. O commitado declara a qual versão o projeto está fixado; o local registra o que cada máquina realmente baixou. O descompasso entre eles é detectado e corrigido por /magpie-setup upgrade.
• Symlinks tornam as habilidades do framework chamáveis como se estivessem no repositório adotante. Cada symlink é nomeado magpie-<framework-skill> — toda habilidade do framework é instalada sob um prefixo magpie- para ser namespaced e nunca colidir com as próprias habilidades do adotante (ex.: o snapshot's skills/pr-management-triage/ torna-se magpie-pr-management-triage, invocado como /magpie-pr-management-triage). .agents/skills/ é o único lar canônico: suas entradas magpie-* linkam para <snapshot-dir>/skills/<framework-skill>/. Cada outro alvo de agente (.claude/skills/, .github/skills/, …) recebe um symlink relé por habilidade que aponta de volta para a entrada canônica (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>) — não importa qual layout o projeto adotante usava anteriormente (veja agents.md). Os symlinks são ignorados pelo git porque seus alvos desaparecem em um clone novo antes que /magpie-setup seja executado.
• Modificações específicas do adotante para fluxos de trabalho do framework residem como instruções legíveis por agente sob .apache-magpie-overrides/<skill-name>.md (commitado). Elas invalidam ou alteram etapas que o skill do framework executaria. Veja overrides.md para o contrato e docs/setup/agentic-overrides.md para a fundamentação do design.

Autoadoção local (apenas o checkout do framework). O único repositório que não pode ser adotado via mecanismo de snapshot é o próprio checkout do framework Apache Magpie — um snapshot remoto do framework dentro de si mesmo seria circular. Em vez disso, ele se autoadota com method:local: cada magpie-<skill> canônico em .agents/skills/ é um symlink commitado para a fonte no repositório ../../skills/<skill>/, e cada outro alvo de agente ativo (agents.md) — .claude/skills/ (Claude Code), .github/skills/ (carregador de skills do GitHub) e qualquer holdout presente — recebe um symlink relé commitado (magpie-<skill> → ../../.agents/skills/magpie-<skill>) — sem snapshot, sem busca remota e sem cópia. Isso torna as próprias habilidades do framework chamáveis durante o desenvolvimento do framework, e todos os contribuidores as obtêm ativas em um clone novo sem nenhuma etapa de configuração. adopt detecta o checkout do framework estruturalmente e roteia automaticamente para lá (veja adopt.md → Autoadoção local).

Os dois arquivos de lock

O modelo de lock do framework divide o que o projeto fixa (commitado) do que esta máquina realmente baixou (local). Esta divisão é a base da detecção de descompasso e do suporte a múltiplos instaladores.

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

Commitado na raiz do repositório adotante. O pino do projeto. Editado apenas por /magpie-setup; não modifique manualmente.

# .apache-magpie.lock — commitado; o pino do projeto.

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

# Para method=git-branch:
ref:    main

# Para method=git-tag:
ref:    v1.0.0          # o nome da tag
commit: <SHA>           # o commit para o qual a tag apontava quando foi commitada

# Para method=svn-zip:
ref:    1.0.0           # o número da versão
sha512: <hash>          # o SHA-512 do zip liberado (para verificação de nova busca)

O próximo adotante que executar /magpie-setup adopt lê este arquivo e reinstala a mesma versão que o projeto declarou. Esta é a essência da promessa "adote uma vez, todos os usuários subsequentes obtêm a mesma coisa".

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

Ignorado pelo git na raiz do repositório adotante. A impressão digital do snapshot local. Registra o que esta máquina baixou e quando.

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

source_method:    <git-branch | git-tag | svn-zip>
source_url:       <URL da qual o snapshot foi realmente baixado>
source_ref:       <branch / tag / versão realmente baixada>
fetched_commit:   <SHA do commit no disco agora>
fetched_at:       <carimbo de data/hora ISO-8601>

A verificação de descompasso em toda invocação de skill do framework compara isso com <committed-lock> e exibe qualquer incompatibilidade como uma proposta de /magpie-setup upgrade.

Arquivos de detalhe neste diretório

Arquivo	Propósito
adopt.md	Passo a passo de adoção inicial — reconhecer snapshot existente vs necessidade de bootstrap, escrever os dois arquivos de lock, perguntar ao usuário quais famílias de skills conectar, criar os symlinks ignorados pelo git, estruturar .apache-magpie-overrides/, instalar o hook de pós-checkout, atualizar documentação do projeto. A sub-ação padrão.
upgrade.md	Atualizar o snapshot ignorado pelo git de acordo com o lock commitado, reconciliar quaisquer sobreposições agentivas + symlinks contra a nova estrutura do framework, exibir conflitos. Conduz o fluxo de correção de descompasso.
verify.md	Verificação de saúde somente leitura — snapshot presente + intacto, ambos os locks sincronizados, symlinks apontando para alvos ativos, .gitignore correto, .apache-magpie-overrides/ existente, status de descompasso (commitado vs local), o próprio skill setup está atualizado.
agents.md	O registro de alvos de agente — quais diretórios os symlinks de skills do framework pousam em diferentes fornecedores, e o modelo canônico-mais-relé: .agents/skills/ é o único lar canônico (linka para o snapshot/fonte); cada outro alvo (claude-code, github, natives holdout como Windsurf / Goose) obtém um symlink de relé por skill para .agents/skills/. Define seleção de alvo ativo, portabilidade de formato SKILL.md e a camada somente Claude Code (sandbox/hooks). A fonte da verdade que toda sub-ação consulta para o conjunto de alvos.
overrides.md	Gerenciamento de arquivos de sobreposição agentiva — abrir / estruturar uma sobreposição para um skill do framework, listar sobreposições existentes, ajudar a reconciliar quando o framework altera a estrutura do skill subjacente no upgrade.
unadopt.md	Reverter a adoção — remover snapshot, locks, symlinks, hook de pós-checkout, entradas .gitignore, seções de adoção em README.md / AGENTS.md / CONTRIBUTING.md e o próprio skill setup commitado. Preserva .apache-magpie-overrides/ por padrão; --purge-overrides também o remove. Exibe o plano de remoção completo antes de qualquer gravação.

Regras de ouro

Regra de ouro 1 — nunca modifique o snapshot. O <snapshot-dir> é um artefato de build, ignorado pelo git e somente leitura da perspectiva de um adotante. Toda modificação que um adotante deseja deve ir para .apache-magpie-overrides/ (onde é commitada e sobrevive ao próximo upgrade). O skill, e qualquer outro skill do framework que consulte sobreposições em tempo de execução, nunca escreve em <snapshot-dir>.

Regra de ouro 2 — <committed-lock> é o pino do projeto; <local-lock> é a verdade por máquina. Eles servem a propósitos diferentes e vivem em lugares diferentes:

• <committed-lock> declara qual versão o projeto usa. Editado pelo adotante que executa /magpie-setup adopt primeiro (ou que depois executa /magpie-setup upgrade e aceita o novo pino). Aumentá-lo é uma ação deliberada em nível de projeto; o aumento aparece no git diff do PR que o propôs.
• <local-lock> registra o que esta máquina instalou. Atualizado silenciosamente por /magpie-setup adopt e /magpie-setup upgrade. Por desenvolvedor, por checkout, por worktree.

Regra de ouro 3 — o descompasso aparece, o descompasso é corrigido. Todo skill do framework (e /magpie-setup verify) verifica <committed-lock> vs <local-lock> no início de sua execução. Em caso de incompatibilidade, o skill exibe a lacuna e propõe /magpie-setup upgrade. O usuário aceita ou adia; se aceitar, upgrade:

1. Exclui <snapshot-dir> completamente.
2. Reinstala de acordo com o lock commitado (a nova versão que o projeto escolheu).
3. Atualiza os symlinks de skills do framework ignorados pelo git — adiciona quaisquer novos skills do framework que a escolha de família do usuário cobre, remove quaisquer skills do framework que foram renomeados ou removidos.
4. Reconcilia as sobreposições agentivas contra a nova estrutura do framework (exibe conflitos; nunca reescreve automaticamente).
5. Atualiza <local-lock> para a nova busca.

Regra de ouro 4 — .gitignore mantém o repositório adotante limpo. Três coisas ignoradas pelo git no repositório adotante:

• <snapshot-dir> (todo o snapshot do framework — gigabytes potencialmente).
• <local-lock> (estado por máquina).
• Os symlinks magpie-* que setup adopt cria em todo diretório de alvo ativo — os canônicos em .agents/skills/ (eles apontam para o snapshot ignorado) e os relés em .claude/skills/ / .github/skills/ / holdouts (eles apontam para as entradas canônicas) — ambos estariam quebrados em um clone novo. A única exceção não ignorada em cada diretório é magpie-setup.

Commitado: este skill (setup, como o canônico .agents/skills/magpie-setup/ mais seus relés), o <committed-lock>, o diretório .apache-magpie-overrides/, as próprias entradas .gitignore, quaisquer atualizações de documento do projeto que a sub-ação adopt faz.

Regra de ouro 5 — .agents/skills/ é canônico; tudo o mais apenas releia para ele. Independentemente de como um projeto adotante organizou anteriormente seus .claude/skills/ ou .github/skills/, adopt sempre conecta o framework da mesma forma: os links canônicos magpie-* vivem em .agents/skills/, e cada outro alvo ativo (.claude, .github, holdouts) obtém symlinks de relé por skill apontando de volta para as entradas canônicas (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). Os próprios skills nativos (não-magpie-) do adotante nesses diretórios permanecem intocados. Veja agents.md.

Regra de ouro 6 — copie este skill, symlink o resto; todos sob o prefixo magpie-. Este skill (fonte skills/setup/) é o único skill do framework que é copiado para um repositório adotante — commitado como o canônico .agents/skills/magpie-setup/, com symlinks de relé commitados para ele de .claude/skills/magpie-setup e .github/skills/magpie-setup. Todos os outros skills do framework são symlinkados (link canônico para o snapshot ignorado, mais relés), cada um nomeado magpie-<framework-skill> (ex.: magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/). O prefixo magpie- namespaces todo skill do framework para que nunca colida com os próprios skills do adotante. Misturar cópia e symlink — copiar um skill de segurança, por exemplo — cria um risco de manutenção: as cópias divergem da fonte-verdade do framework, e o mecanismo de detecção de descompasso (que assume que a versão do framework é aquela em <snapshot-dir>) silenciosamente se aplica incorretamente.

Regra de ouro 7 — sobreposições agentivas são lidas em tempo de execução. Todo skill do framework que suporta sobreposições inicia sua execução verificando .apache-magpie-overrides/<this-skill>.md por instruções específicas do adotante e aplicando-as antes de executar o comportamento padrão. O arquivo de sobreposição é markdown simples que o agente interpreta — sem mecanismo de modelo, sem ferramenta de patch. Veja docs/setup/agentic-overrides.md para o contrato.

Regra de ouro 8 — duas famílias são sempre instaladas; o resto é opcional. Duas famílias de skills são conectadas incondicionalmente em toda execução de adopt / upgrade / worktree-init e o usuário nunca é perguntado sobre elas:

• setup-* — todo skill do framework cujo nome de fonte começa com setup- exceto o próprio setup de bootstrap (que é copiado como magpie-setup conforme a Regra 6, não symlinkado). Concretamente: setup-isolated-setup-install, setup-isolated-setup-update, setup-isolated-setup-verify, setup-override-upstream, setup-shared-config-sync, mais qualquer novo skill setup-* que o framework venha a ter no futuro — cada um symlinkado como magpie-setup-*.

• list-* — a família de descoberta; todo skill do framework cujo nome de fonte começa com list-*. Hoje é apenas list-skills (symlinkado como magpie-list-skills); o prefixo permite que o framework cresça com um sistema de descoberta.

  ...

[truncado para tradução]