xp-stack

Stack metodológico XP/Akita para agentes de IA — TDD absoluto, pair programming, pesquisa formal triangulada, task decomposition rigorosa, conventional commits e orquestração multi-agent nativa via Agent View (Claude Code) com fallbacks opt-in.

Versão atual: v2.0.0 (2026-05-13). Status: estável, pronto pra adoção em qualquer stack (TypeScript, Python, Go, bash, etc.). Veja CHANGELOG.md pro migration guide v1.x → v2.0.

O que mudou na v2.0.0

Breaking release. Parallelization pattern shifts from manual TERMINAL-PROMPTS.md (N terminals + copy-paste) to Claude Code Agent View native. Mais detalhes em CHANGELOG.md.

• ✅ Novo template canônico TEMPLATE-orchestrator-prompt.md (substitui TEMPLATE-terminal-prompts.md removido)
• ✅ Padrão Sonnet+caveman+worktree pra workers dispatched pelo orchestrator
• ✅ Nova skill opt-in debugging-discipline — instala PR template + PreToolUse hook + settings deep-merge pra forçar disciplina em commits fix:
• ✅ akita-xp-rules, task-decomposition atualizadas pra refletir Agent View
• ✅ local-waves marcada como [LEGACY] (segue funcional como fallback)

Instalação

Forma primária — npm CLI

npx xp-stack init

Detecta engines disponíveis (Claude Code, Antigravity, Cursor, Codex, etc.), instala dual mirror em .claude/skills/ + .agents/skills/, cria manifest SHA-256, scaffolda CLAUDE.md, AGENTS.md (symlink), docs/tasks/_template/, docs/pesquisas/_template/, .claude/settings.json e .gitignore atualizado. Nunca sobrescreve nada que já exista.

Forma alternativa — plugin marketplace (backward compat)

/plugin marketplace add RNobre1/xp-stack
/plugin install xp-stack@xp-stack
/xp-stack:bootstrap

Recomendação: prefira a forma npm. O plugin marketplace está sujeito ao issue #35989 do claude-code — skills somem do cache de plugins em algumas versões do CLI.

Quick start

cd meu-projeto
npx xp-stack init                              # scaffold + dual mirror
npx xp-stack status                            # estado atual (engines, features ativas, drift)
npx xp-stack add-skill db-archaeologist        # agent opt-in pra análise de DB
npx xp-stack add-skill debugging-discipline    # gates de fix-workflow (PR template + hook)

Subcomandos disponíveis (10 + version flag)

Atualizando

npx xp-stack update
# ou plugin marketplace:
/plugin marketplace update RNobre1/xp-stack
/plugin install xp-stack@xp-stack

O que está incluído

Skills regulares (auto-disponíveis após install)

Skills opt-in (invocadas via xp-stack add-skill)

Agents

Templates

• CLAUDE.md.template — skeleton para CLAUDE.md de projeto novo, com nota sobre symlink AGENTS.md + seções pré-prontas pra "Mandatory skill integration" (refletindo Agent View pattern), "Optional multi-agent dispatch", "Archival policy".
• claude-settings-project.json — permissões razoáveis pra .claude/settings.json.
• docs-tasks-template/ (5 arquivos): README, TEMPLATE-overview, TEMPLATE-progress, TEMPLATE-task, TEMPLATE-orchestrator-prompt (novo em v2.0 — substitui TEMPLATE-terminal-prompts).
• docs-pesquisas-template/TEMPLATE-pesquisa.md.

Workflows típicos

1. Projeto novo, sem orquestração paralela

Cobre 80% dos casos. É o que o init entrega de cara.

cd meu-projeto-novo
npx xp-stack init

# Você ganha CLAUDE.md, AGENTS.md (symlink), .claude/settings.json,
# docs/tasks/_template/, docs/pesquisas/_template/, .gitignore atualizado.
# Edite CLAUDE.md preenchendo a stack do seu projeto.

# Daí em diante:
# - features não-triviais → /xp-stack:task-decomposition (instrui como)
# - decisões arquiteturais → /xp-stack:research-cycle
# - bug → invoque superpowers:systematic-debugging antes de propor fix
# - PR pronto → invoque superpowers:verification-before-completion
# - workflow CI → optimizing-github-actions auto-roda

2. ⭐ Paralelização nativa via Agent View (padrão v2.0.0)

Pra waves com 2+ T-files independentes, o orquestrador dispara workers Sonnet via Agent tool nativo do Claude Code. Status em UI única (claude agents). Substitui completamente o T*-PROMPT.md manual.

// Dentro da sessão Claude Code orchestrator (Opus):
Agent({
  description: "T1 — feature-slug",
  subagent_type: "general-purpose",
  model: "sonnet",
  isolation: "worktree",
  prompt: `Antes de qualquer outra coisa, invoque a skill caveman:caveman pra ultra-compressar comunicação.

Leia e execute integralmente docs/tasks/{feature-slug}/T1-*.md.
Branch: feat/{feature-slug}-T1.
TDD absoluto. Conventional commits. Files ALLOWED/FORBIDDEN são lei.`,
})

Repita o tool call pra cada T independente na MESMA mensagem do orchestrator → correm em paralelo.

Padrão completo + coordination rules em docs/tasks/_template/TEMPLATE-orchestrator-prompt.md (instalado pelo init).

3. Instalar gates de fix-workflow

Pra projetos com alta taxa de fix: commits sem evidência de systematic-debugging:

npx xp-stack add-skill debugging-discipline
# Depois invoque a skill no Claude Code pra rodar o setup:
# /xp-stack:debugging-discipline

Instala:

• .github/PULL_REQUEST_TEMPLATE.md (seções obrigatórias pra fix: PRs)
• .claude/hooks/pre-tool-use.sh (lembra skill systematic-debugging em todo Edit/Write)
• Hook registrado em .claude/settings.json via deep-merge

4. Você + co-pilot async, ou multi-projeto, ou quer review queue 24/7

Use Paperclip orchestrator (remoto, droplet, async).

npx xp-stack add-skill paperclip-orchestrator
# /xp-stack:paperclip-setup

5. Headless / CI / fallback (Agent View ausente)

Use local-waves (worktrees + claude -p headless).

npx xp-stack add-skill local-waves
# /xp-stack:local-waves-setup

Note: marcado como [LEGACY — pré-Agent View 2026-05-11]. Funcional, mas se você roda interativo no Claude Code, prefira o pattern Agent View (workflow 2 acima).

Decisão de paralelização

Convenção AGENTS.md ↔ CLAUDE.md

Antigravity, Codex e Cursor leem AGENTS.md por convenção. Claude Code lê CLAUDE.md. O init cria um symlink relativo AGENTS.md → CLAUDE.md (e AGENTS.local.md → CLAUDE.local.md se você tiver o .local). Como são o mesmo arquivo no disco, drift entre os dois é impossível — toda edição em CLAUDE.md propaga instantaneamente.

Não edite AGENTS.md diretamente. Não quebre o symlink. Pra desabilitar (caso seu projeto tenha um AGENTS.md próprio que conflita), passe "no-symlink" como 6º argumento ao scaffold.sh.

.gitignore reservado

O init adiciona entries no .gitignore do seu projeto (idempotente, sem sobrescrever):

# xp-stack
.xp-stack/state/
local/
.claude/wave-runs/
scripts/orchestrate/

Mesmo se você não usar Paperclip ou local-waves agora, essas pastas ficam reservadas — caso um agente futuro escreva lá por engano (ou você ative depois), nada vaza pra git.

Testes

npm test                          # vitest — 185 tests (28 files)
npm run test:bash                 # bash suite — 55+ tests across 6 scripts

CI roda em PRs (.github/workflows/validate-plugins.yml). 100% verde em main desde v1.0.0.

Testar localmente em outro projeto

# Via npm (recomendado — sempre versão publicada):
cd /caminho/para/outro-projeto
npx xp-stack@2.0.0 init

# Via plugin marketplace (backward compat):
claude --plugin-dir /caminho/para/xp-stack/plugins/xp-stack

Histórico de versões

Detalhes completos em CHANGELOG.md. ADRs em CLAUDE.md (raiz do repo).

Princípios

O pacote transporta metodologia universal — TDD, pair programming, pesquisa formal, decomposição de tasks, conventional commits, multi-agent dispatch. Não transporta convenções de stack (frameworks específicos, paths de teste, entidades de domínio). Os agents lêem o CLAUDE.md do projeto receptor pra entender a stack.

Origem: extraído iterativamente do ecossistema Meteora Digital conforme padrões se mostram universais. Cada release passa por:

1. Validação empírica em projeto real upstream (TDD red → green → empirical → release).
2. Anonimização de templates (remoção de refs hardcoded a stack-específico, nomes, IPs, IDs).
3. Self-test em projeto receptor antes de release.

Veja CLAUDE.md (raiz) seção "ADRs" pra trilha completa de decisões.

Contribuindo

PRs bem-vindos. O fluxo do próprio repo segue o método Akita/XP — veja docs/tasks/ (decomposição das releases) e CLAUDE.md (raiz) pra entender o ciclo. Cada release segue 6 fases (T0 setup → T1 RED → T2-N GREEN → T(N+1) empirical → T(N+2) release).

Licença

MIT — ver LICENSE.