Kata (型)

Python 3.11+ | CLI + OpenCode Agent + Claude Code Skills | Karpathy Development Cycle + Fable Method

Kata (型, "forma/padrão") é um agente OpenCode, um conjunto de skills para Claude Code e um CLI Python que implementam o ciclo FIT → THINK → SIMPLIFY → INTENT → SURGICAL → VERIFY → TWIN CHECK → ARTIFACT → REPORT, com AUDIT e JUDGE adversarial, inspirado em:

1. Karpathy Development Cycle (Andrej Karpathy): pensar antes de codar, manter o código mínimo, mudanças cirúrgicas e verificação objetiva.
2. The Fable Method (Sahir619/fable-method): classificar a tarefa antes de agir (fit gate), triviality gate, evidência antes de ação, verificação adversarial e relatório outcome-first.

Para a referência técnica completa, consulte DOCUMENTATION.md.

O ciclo completo:

FIT → THINK → SIMPLIFY → INTENT → SURGICAL → VERIFY → TWIN CHECK → ARTIFACT → REPORT
                                                                           ↓ (opcional)
                                                                         JUDGE

Modos adicionais do CLI: --audit (gradua as fases da tarefa como followed / skipped / faked / degraded) e --check-only (só verificação, para CI).

Como um kata marcial, é uma sequência disciplinada e repetível de movimentos: classificar a tarefa, pensar antes de codar, manter o código mínimo, verificar intenção, mudanças cirúrgicas e verificar com critérios objetivos.

Instalação

Agente OpenCode (recomendado)

git clone https://github.com/walternagai/kata.git ~/dev/ninja-apps/kata
cd ~/dev/ninja-apps/kata
make install
# Reinicie o OpenCode

Após reiniciar, use @kata no OpenCode para iniciar o ciclo. O subagente kata-advisor (Hostile Reviewer) é disponibilizado para revisão adversarial semântica.

No Windows PowerShell, use o instalador nativo:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install.ps1
# Para evitar links simbólicos/junctions, use cópias:
# .\scripts\install.ps1 -Copy
# Desinstalar: .\scripts\install.ps1 -Uninstall

O instalador usa OPENCODE_CONFIG_DIR quando definido; caso contrário, usa ~/.config/opencode, o caminho global do OpenCode em todas as plataformas.

Skills Claude Code

git clone https://github.com/walternagai/kata.git ~/dev/ninja-apps/kata
cd ~/dev/ninja-apps/kata
make install-claude-code

Depois de instalado, use a skill kata no Claude Code (ex: /kata, ou descreva a tarefa e deixe o Claude Code acioná-la pela descrição).

No Windows PowerShell:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install-claude-code.ps1
# Para evitar links simbólicos/junctions, use cópias:
# .\scripts\install-claude-code.ps1 -Copy
# Desinstalar: .\scripts\install-claude-code.ps1 -Uninstall

O instalador usa CLAUDE_CONFIG_DIR quando definido; caso contrário, usa ~/.claude, o caminho global do Claude Code em todas as plataformas.

Diferente do agente @kata do OpenCode, a versão Claude Code é só skills (sem subagente): o ciclo do kata é muito interativo — pergunta a cada fase — e isso se encaixa melhor rodando na conversa principal do que em um subagente isolado que só reporta um resumo ao final.

CLI Python (via PyPI ou checkout)

Via PyPI (distribuição kata-dev; o comando continua kata — sem clonar nada):

pipx install kata-dev
kata --install all       # opencode + claude-code (copia as skills empacotadas)
kata --doctor            # confere a instalação
kata --uninstall all     # remove só o que o Kata criou

A partir do checkout (desenvolvimento):

# As extras `dev` trazem o ruff/pytest/pytest-cov que `kata --check-only`
# executa — instalar só `pip install -e .` deixa o entry point de CI sem
# ferramenta e reprovando sempre (R10-32).
pip install -e '.[dev]'

Sem precisar instalar no ambiente (pipx/uv isolam o pacote e o binário na primeira execução):

# Uso pontual — não instala nada permanente (bom para CI/headless)
pipx run --spec . kata --version
uv tool run --from . kata --version

# Instalação permanente (cria um binário `kata` no PATH do runner)
pipx install .
uv tool install . --force

Todas as rotas usam o mesmo entry point kata.cli:main do pyproject.toml — pip, pipx e uv apenas entregam o binário de jeitos diferentes. kata --install copia as skills do wheel e funciona sem clonar o repositório; make install / make install-claude-code (symlinks para o checkout) continuam como fluxo de desenvolvimento local.

Os dois modos convivem, e kata --install migra o fluxo dev para o de cópia quando pedido: symlinks do Kata são adotados — substituídos pela cópia, sem --force e sem deixar .bak. Se um link aponta para uma skill editada localmente (conteúdo diferente do empacotado), ele não é adotado: kata --doctor mostra o estado como MISTO e nomeia quais são link e quais são cópia.

O que o projeto alvo precisa

O kata é aplicado a um projeto (não a este repositório). Para o --check-only e o JUDGE descobrirem o que verificar, o projeto alvo deve ter:

• pyproject.toml — o kata lê [tool.coverage.run] source para saber o que medir no coverage. Sem ele, cai no fallback src.
• .kata/config.yaml (opcional) — declara os comandos de lint/test/ coverage do projeto quando não são Python (ex.: eslint, vitest, go test). Sem ele, valem os defaults Python (ruff/pytest/pytest-cov).
• .kata/<task>.yaml — criado por kata --init <nome>; é o registro da tarefa que o ciclo lê e grava a cada fase.

Sem pyproject.toml nem .kata/config.yaml, o kata assume um projeto Python com src/ e tests/ — se o seu projeto não é assim, declare o config.

Uso

No OpenCode

Comando	Ação
@kata	Ciclo interativo completo
@kata --init nome-da-tarefa	Cria tarefa e executa FIT + THINK
@kata --check-only	Só verificação (CI/snapshot)
@kata --plan nome-da-tarefa	Modo planejamento: FIT + THINK, para sem modificar código
@kata --task nome	Retoma tarefa existente
@kata --task nome --judge	Verificação adversarial (caça fraudes)
@kata --task nome --report	Relatório outcome-first
@kata --task nome --audit	Gradua as fases: followed / skipped / faked / degraded

No Claude Code

A skill kata recebe os mesmos argumentos que o agente OpenCode, passados como texto após o nome (ex: /kata --init nome-da-tarefa):

Comando	Ação
/kata	Ciclo interativo completo
/kata --init nome-da-tarefa	Cria tarefa e executa FIT + THINK
/kata --check-only	Só verificação (CI/snapshot)
/kata --plan nome-da-tarefa	Modo planejamento: FIT + THINK, para sem modificar código
/kata --task nome	Retoma tarefa existente
/kata --task nome --judge	Verificação adversarial (caça fraudes)
/kata --task nome --report	Relatório outcome-first
/kata --task nome --audit	Gradua as fases: followed / skipped / faked / degraded

CLI Python

kata --init minha-tarefa       # Cria .kata/minha-tarefa.yaml
kata                            # Ciclo interativo completo
kata --check-only               # Só VERIFY (lint + test + coverage)
kata --plan                     # Modo planejamento: FIT + THINK, para
kata --plan --task minha-tarefa # Planeja tarefa específica
kata --task minha-tarefa        # Retoma tarefa específica
kata --task minha-tarefa --report  # Relatório outcome-first
kata --doctor                      # As skills de fase estão instaladas?
                                   # (parcial sai 1; domain adapters ausentes e o
                                   # subagente kata-advisor ausente só avisam)
kata --install all [--force]       # Instala skills + agente + subagente advisor
                                   # (opencode, claude-code ou all)
kata --uninstall all               # Remove só o que o --install criou
kata --task minha-tarefa --audit   # Gradua fases (followed/skipped/faked/degraded)
kata --task minha-tarefa --judge   # Verificação adversarial (caça fraudes)

Argumentos do CLI

Flag	Default	Descrição
--plan	False	Modo planejamento: FIT + THINK, não modifica código
--judge	False	Verificação adversarial (re-executa checks, caça fraudes); exige tarefa com status: approved
--report	False	Gera relatório outcome-first de tarefa concluída
--audit	False	Gradua as fases da tarefa: followed / skipped / faked / degraded
--doctor	False	Confere as skills de fase por frontend (e mostra o modo: link, cópia ou misto); domain adapters e o subagente kata-advisor ausentes só avisam
--install	(nenhum)	Copia as skills empacotadas, o agente orquestrador e o subagente advisor: opencode, claude-code ou all (sem clone do repo)
--uninstall	(nenhum)	Remove as skills do --install (só o que o Kata criou)
--force	False	Só com --install: guarda personalização existente em .bak e substitui
--ruff-paths	src/ tests/	Caminhos para ruff check
--test-paths	tests/	Caminhos para pytest
--ignore	(nenhum)	Caminhos para ignorar no pytest
--cov-source	auto-detectado	Pacote fonte para coverage: lê [tool.coverage.run] source do pyproject.toml, com fallback src
--gate	verify.gate, senão 70	Gate mínimo de coverage (%)
--trusted-base	(nenhum)	Só com --judge: ref que o agente não controla (ex.: origin/main no CI); o piso do diff vira merge-base(ref, HEAD) e o teto do YAML é ignorado; sem merge-base (ex.: clone raso) sai 1 sem julgar

Essas flags configuram os defaults Python. Um papel declarado em .kata/config.yaml roda verbatim, e as flags de caminho daquele papel deixam de valer.

Projetos que não são Python

Quem sabe verificar um projeto é o projeto. Declare os comandos em .kata/config.yaml, ao lado dos arquivos de tarefa:

verify:
  lint: npx eslint src tests
  test: npx vitest run
  coverage: npx vitest run --coverage
  coverage_pattern: 'All files\s+\|\s+([\d.]+)'
  gate: 80

advisor:
  enabled: true                        # ativa revisão adversarial semântica (Estágio 2)
  model: anthropic/claude-opus-4#high  # modelo frontier opcional
  effort: high                         # nível de thinking
  skip_trivial: true                   # bypass automático se fit.trivial == true

Cada papel aceita string ou lista, e todo papel é opcional: o que for omitido cai no default Python (ruff/pytest/pytest-cov), então dá para trocar só o linter e manter o pytest. Sem o arquivo, nada muda.

O JUDGE segue a mesma linha: ele conhece a sintaxe de teste de Python, JS/TS, Go, Ruby, Rust, Java/Kotlin, C#, PHP e Swift. Linguagem fora dessa lista (ex.: Elixir .exs) vira ponto cego declarado, não silêncio.

Fases do Ciclo

0. FIT (classificação da tarefa)

Inspirado no fit gate do The Fable Method. Classifica a tarefa antes de investir esforço:

• Triviality gate: 1 arquivo, <10 linhas, sem busca → vá direto a VERIFY
• Rotas: code-loop, plan-first, question, research, inference

1. THINK

Declarar problema, assumptions, alternativas e unknowns antes de codar — e o critério de sucesso (done), declarado antes da evidência (Fable Step 1). Budget de investigação: 2 buscas sem resultado → pare e pergunte ao usuário.

2. SIMPLIFY

Verificar se o código é mínimo — sem abstrações especulativas (YAGNI) ou configurabilidade não solicitada.

2.5 INTENT

Verificar que código, teste e spec concordam antes de mudar comportamento. Ordem de autoridade em conflito: usuário > spec > testes > código. Não edite até resolver o conflito.

3. SURGICAL

Validar arquivo-por-arquivo que cada mudança rastreia direto ao pedido, sem efeitos colaterais.

4. VERIFY

Rodar lint + teste + coverage (gate >= 70%) e confrontar o critério done declarado no THINK com o resultado final. Os comandos vêm de .kata/config.yaml quando o projeto os declara; senão, são os defaults Python (ruff, pytest, pytest-cov com --cov-fail-under). Hard bound (Fable Step 5): após 3 tentativas falhas, a tarefa é devolvida ao usuário (hand back) com o que foi tentado, o output real e a hipótese atual — em vez de repetir o fix-verify indefinidamente.

4.2 TWIN CHECK

Defeito corrigido? O mesmo padrão costuma existir em outros lugares — busque no projeto inteiro e registre o resultado. "Sem defeito" ≠ "não chequei".

4.5 ARTIFACT

Verificar que as linhas devidas estão no relatório: INTENT (comportamento mudou), AUTH (ação irreversível), PENDING (follow-up prescrito e não tomado), TWINS (defeito corrigido e varredura registrada).

5. REPORT

Relatório outcome-first documentando o que foi feito, com caveats honestos.

AUDIT (modo CLI)

kata --audit gradua as fases da tarefa como followed / skipped / faked (afirmado sem observação — o padrão R7-1), nomeando o risco concreto de cada skip/fake. Equivalente ao /fable-method audit.

JUDGE (opcional)

Verificação adversarial em dois estágios complementares:

1. Estágio 1: Verificação Mecânica (Determinística): O CLI Python (kata --judge) re-executa as verificações afirmadas, confronta o diff com o relatório e caça fraudes em 7 categorias (weakened checks, false completion, scope creep, unauthorized action, spec betrayal, debris, baseline tampering). Se reprovado ou com falha, o ciclo para imediatamente.
2. Estágio 2: Verificação Semântica Adversarial (Advisor): Se o Estágio 1 for aprovado e a tarefa não for trivial (fit.trivial == false), um modelo mais robusto ou com thinking elevado atua como Hostile Reviewer para caçar fraudes conceituais (testes tautológicos, desvios sutis de especificação, complexidade YAGNI e edge cases).
   • No OpenCode: subagente kata-advisor (mode: subagent, somente leitura);
   • No Claude Code: comando /advisor ou /effort high|max;
   • Configurado via .kata/config.yaml (advisor:).

Se o juiz mecânico não encontrar fraude mas também não tiver tido como observar — nada re-executado (o caso de todo toolchain que não é Python), ou teste numa linguagem cujos padrões ele não lê — o veredito é UNVERIFIABLE, não VERIFIED, e os pontos cegos vêm listados. "Não consegui olhar" não é reportado como "está tudo certo".

Diretório de Trabalho

O kata usa .kata/ na raiz do projeto. Cada tarefa é um arquivo YAML:

.kata/
  minha-tarefa.yaml
  bug-fix-123.yaml

Desenvolvimento

make build-skills          # gera opencode/, claude-code/ e src/kata/assets/ de phases/+domains/
make check-skills          # falha se o gerado estiver desatualizado
make test                  # pytest + coverage
make package               # constrói o wheel/sdist e confere contra src/kata/assets/
make lint                  # ruff check
make format                # ruff format
make format-check          # reprova drift de formatação (o lint não vê)
make install                # instala agente + skills no OpenCode
make uninstall               # remove symlinks do OpenCode
make install-claude-code     # instala skills no Claude Code
make uninstall-claude-code   # remove symlinks do Claude Code
make paper                   # compila paper/jserd/paper.pdf (exige TeX Live)

Para publicar uma versão no PyPI, siga RELEASING.md.

Compatibilidade

O schema .kata/<task>.yaml é compatível com o .karpathy/ do mushin — um agente local anterior ao kata, de repositório privado do autor, que não faz parte deste pacote nem é distribuído com ele. A nota existe apenas para quem já tinha tarefas nesse formato; quem instala kata-dev do zero não precisa dela. Para migrar tarefas existentes:

ln -s .karpathy .kata   # symlink preserva acesso ao legado

Tarefas podem declarar um domínio (coding, devops, data-analysis, research, docs). O domínio padrão é coding; os demais carregam um adapter de domains/ (fonte única, gerado para OpenCode e Claude Code). Domínio sem adapter conhecido roda com aviso, sem o adapter — ver domains/TEMPLATE.md para criar um novo.

Estrutura

kata/
├── phases/                            ← FONTE ÚNICA dos prompts (11 arquivos:
│                                         kata.md + as 10 skills de fase —
│                                         9 fases + JUDGE + QUESTION). É aqui
│                                         que se edita; o resto é gerado.
├── opencode/                          ← GERADO (make build-skills)
│   ├── agent/kata.md                  ← Agente @kata (OpenCode)
│   └── skills/kata-*/SKILL.md         ← 14 skills (10 de fase + 4 domain
│                                         adapters; TWIN CHECK vive no orquestrador)
├── claude-code/                       ← GERADO (make build-skills)
│   └── skills/kata-*/SKILL.md         ← 15 skills (orquestrador kata + as 14 acima)
├── domains/                           ← FONTE ÚNICA dos domain adapters
│   ├── TEMPLATE.md                    ← schema de um adapter (não gera skill)
│   ├── kata-devops.md                 ← adapters (um .md por skill kata-*)
│   ├── kata-data-analysis.md
│   ├── kata-research.md
│   └── kata-docs.md
├── MANIFEST.in                        ← sdist leva só o pacote (poda tests/, eval/, paper/)
├── src/kata/
│   ├── cli.py                  ← CLI (orquestra as 9 fases + audit + judge + install)
│   ├── install.py              ← `kata --install`: copia as skills empacotadas
│   ├── assets/                 ← GERADO (make build-skills): espelho do gerado
│   │                             que viaja no wheel (lido via importlib.resources)
│   ├── report.py               ← I/O de relatório/auditoria (S7-refactor)
│   ├── fit.py                  ← Lógica do fit gate (diff_stats, is_trivial)
│   ├── config.py               ← .kata/config.yaml (comandos do projeto alvo)
│   ├── skills.py               ← Preflight: as skills de fase estão instaladas?
│   ├── verify.py               ← Lógica de verificação (lint/teste/coverage)
│   ├── judge.py                ← Lógica adversarial (caça fraudes)
│   ├── __init__.py             ← Versão do pacote
│   └── __main__.py             ← Entry point para `python -m kata`
├── eval/                       ← Cenários de trap adversarial (python3 eval/run_traps.py)
├── scripts/
│   ├── build_skills.py                                 ← Gera os frontends a partir de phases/
│   ├── install.sh / install.ps1                        ← Instalação no OpenCode
│   └── install-claude-code.sh / install-claude-code.ps1 ← Instalação no Claude Code
└── tests/                      ← Testes pytest (ver `make test` para cobertura)

Licença

MIT