groundfast para Pi

Pacote Pi do toolkit de engenharia da Groundfast. Skills, scripts e references/ são gerados pelo gf-build a partir do corpo canônico em skills/ na raiz do repo (preâmbulo em host.md); aqui mora só o host.md, o package.json e uma extensão fina. Não edite o gerado. O pipeline de issues está incluído.

Instalar

pi install npm:groundfast     # versão publicada
pi install ./plugins/pi       # clone local, path relativo à raiz do repo

No path local o Pi adiciona às settings sem copiar. Depois de editar a extensão, /reload na sessão.

Verificar

bun install --frozen-lockfile
bun run typecheck
bun test/extension.smoke.ts   # ExtensionAPI falso: catálogo real e fixtures quebradas
npm pack --dry-run    # a lista tem de trazer skills/*/scripts/ e references/

Publicar

tools/release.sh publica junto com a tag e a GitHub Release, depois de confirmar no terminal (runbook: alvo plugin do ship). À mão, só quando o release parou em NPM PULADO:

cd plugins/pi && npm publish

Os arquivos são reais (gerados pelo gf-build, sem symlink) e o campo files do package.json decide o que entra no tarball: extensions/, skills/, scripts/ e references/, mais README e manifest.

Comandos

Um comando por diretório em skills/ (/pr, /babysit, …), montado do frontmatter do SKILL.md gerado: a primeira frase de description vira a descrição, metadata.bootstrap é o script que roda e cuja stdout é injetada (dado, não instrução) antes do corpo, e um metadata.argument-hint com rótulo ([alvo: a | b]) vira completion. Skill sem bootstrap manda só o corpo. Única exceção nomeada: /pipeline repassa ao issue-queue.sh só os tokens #N e owner/name. Skill com frontmatter inválido fica sem comando e aparece num aviso no session_start. Skill sem disable-model-invocation também aparece no system prompt, e /skill:nome continua válido para todas.

O que muda em relação ao plugin Claude

• Não há !`${CLAUDE_SKILL_DIR}/…`. O comando injeta o estado; no /skill:nome o modelo corre o script no diretório da skill.
• AskUserQuestion vira a tool ask_user.
• Aprendizados do wrap vão para o arquivo de instruções que o repo-state.sh nomeia (AGENTS.md, ou CLAUDE.md quando ele é o dono), num arquivo só.
• Sem memória nativa em ~/.claude/projects. Retomada: HANDOFF.md + .remember/remember.md (a extensão injeta o espelho no session_start).
• pr, babysit e drain não abrem subagente — review, triagem, diagnóstico de CI e conflito na própria sessão.
• pipeline pode fan-out apenas no Pi TUI, depois de medir RAM e dentro do limite da casa; o pacote não abre terminal extra.
• allowed-tools do Claude não vale aqui. A garantia continua nos wrappers bash (push-pr.sh, stage.sh, gh-thread.sh, merge-pr.sh, …).

Scripts, references/ e skills/*/SKILL.md são gerados: edite skills/ na raiz do repo e rode o gf-build.

Plugins oficiais do Claude (mattpocock, firecrawl, …) não entram neste pacote — vivem no host, em ~/.pi/agent/vendor/ + packages do settings.json, filtrados para não explodir description always-on. Railway já está em ~/.agents/skills/use-railway. Cloudflare, remember, MCP (serena, browser-use) e commands Anthropic (code-review) ficam de fora desta leva.

Layout

plugins/pi/
├── package.json
├── bun.lock
├── tsconfig.json
├── extensions/index.ts
├── host.md                     # preâmbulo do Pi, colado antes do corpo canônico
├── scripts/                    # gerado
├── references/                 # gerado
└── skills/<nome>/              # gerado
    ├── SKILL.md
    ├── scripts/
    └── references/