deck

Um agente de codificação escreve o código. O que ele não tem como saber é como a sua equipe entrega esse código: quais repositórios uma mudança realmente alcança, até onde esta entrega em particular precisa ser verificada antes que alguém a chame de pronta, quais máquinas ela pode tocar, o que a equipe decidiu meses atrás e o que ainda precisa ser perguntado.

Esse conhecimento mora na cabeça das pessoas, em hábitos e numa página de wiki que ninguém abre — que é exatamente por que a saída de um agente é irregular e por que revisá-la cansa. O deck é onde uma equipe escreve isso: uma vez, sob controle de versão, num formato contra o qual um agente consegue agir e que um revisor consegue conferir depois.

1.O problema#

Peça uma funcionalidade a um agente num sistema de vários repositórios e três modos de falha aparecem. Nenhum deles é um problema do modelo.

Nada disso é conhecimento que um modelo consiga derivar do código. É conhecimento sobre o seu sistema, e precisa estar escrito em algum lugar. O deck é esse lugar — e nada além disso.

Três coisas vêm de você

O deck entrega um motor e nenhum conhecimento de domínio. Três coisas são suas, e nenhuma delas é uma lacuna da ferramenta:

• As arestas — quais repositórios uma mudança obriga você a tocar. Um manifesto declara um checkout, nunca uma propagação, então nenhum importador consegue derivá-las.
• Os comandos — como o seu projeto compila, implanta e testa. O deck executa as strings que o seu pack declara; ele nunca ouviu falar de bitbake nem de helm.
• As decisões — as escolhas que a sua equipe refaz toda semana, escritas uma vez.

2.As quatro naturezas, e a regra que decide entre elas#

Esta é a espinha dorsal de tudo. Se você levar só uma coisa desta página, leve esta seção.

Uma equipe quer segurar uma lista longa de coisas: arquitetura, padrões, estilo, formatação, diretrizes, segurança, qualidade, métricas, testes, build, deploy, release. Toda coisa dessa lista é uma de quatro naturezas. Acertar a natureza é a maior parte do trabalho, porque cada uma tem um custo diferente e um modo de falha diferente.

Regras são para o que nenhum comando consegue decidir: para que lado uma dependência pode apontar, por que esta fronteira existe, o que quebra se você atravessá-la. Uma regra de arquitetura ganha o seu lugar quando nomeia a consequência: “handlers validam na borda; nada abaixo reconfere formatos” vale contexto. “Este diretório contém handlers” não vale — o agente consegue ver isso sozinho.

A mesma regra ordena as decisões: se existe uma resposta certa, não é uma decisão — escreva como regra ou imponha como gate. Um toggle cujo valor ninguém jamais mudaria é uma pergunta que você vai obrigar pessoas a responder para sempre.

Quando nenhuma das quatro serve, é uma pergunta

Uma decisão tem mais de uma resposta e você consegue dizer o que defende cada uma. Quando você não consegue — dois trechos de código discordam e ninguém sabe se aquilo foi decidido ou se derivou —, nenhuma das quatro naturezas serve, e forçar uma delas destrói a única coisa que valia a pena guardar. Arquivada como toggle, aquilo passa a ler-se como “nós escolhemos”. Arquivada como regra, lê-se como “nós exigimos”. As duas são mentiras sobre algo que ninguém explicou.

Para isso existe a consulta: deck ask registra a pergunta, uma pessoa responde, e a resposta sobrevive à sessão que a levantou. Veja §16.

3.Vocabulário#

Termos próprios do deck, usados no resto desta página. Introduzidos aqui para que nenhuma seção adiante dependa de você adivinhar.

4.Motor e pack: onde o deck fica#

O motor conhece a forma das coisas. Todo específico — um comando de build, um passo de implantação, uma decisão de domínio, um marcador de detecção — chega de um pack de extensão, como dado declarativo.

   deck (motor, MIT)                 pack (seu, privado ou compartilhado)
   ─────────────────────             ──────────────────────────────────────
   como uma escada funciona   ←───   quais degraus, e seus comandos
   como toggles se resolvem   ←───   quais decisões existem neste domínio
   como um workspace é achado ←───   quais arquivos identificam um
   como artefatos são colocados ←─   quais artefatos, e onde se aplicam

A regra que mantém isso honesto: se atender a uma organização exige editar o motor, a funcionalidade está na camada errada. Uma palavra de domínio aparecendo no código do motor é um bug, e a regra do próprio projeto (_workspaces/all/default/rules/design-line.md (em deck-ai-packs)) diz isso.

Quatro camadas, cada uma mais específica

   deck                    o motor, e um catálogo universal de decisões
     │                     vem com a ferramenta · sem conhecimento de domínio
     ▼
   foundations pack        DRY, SRP, coesão, fail-fast, testabilidade…
     │                     publicado, agnóstico de linguagem · opcional
     ▼
   organisation pack       sua arquitetura, seu build, sua postura de segurança,
     │                     seus comandos, seus hosts, suas convenções
     ▼
   project / repo pack     o que este produto ou este repositório acrescenta

Recusar é melhor que adivinhar

Dois packs reivindicam o mesmo nome; dois gates compartilham um id; uma variável não resolve; um repositório não está no descriptor. Em todos os casos o deck reporta e para. Ele não ranqueia, não assume um padrão, não escolhe o provável. Uma ferramenta que adivinha sobre uma mudança em vários repositórios é uma ferramenta que ninguém consegue auditar depois.

5.O que o deck deliberadamente não constrói#

Esta é a metade importante do projeto. O Claude Code já entrega boa parte do que um “sistema multiagente de entrega” reinventaria.

O que sobra é a parte que nenhum runtime de agente tem como saber: este workspace. É toda a área de atuação do deck.

6.Instalação#

git clone https://github.com/devfilipe/deck.git ~/tools/deck
ln -s ~/tools/deck/plugins/deck/bin/deck ~/.local/bin/deck
deck --help

Python 3.10+ e PyYAML. git para quase tudo; tmux só para deck ui. Sem passo de build e sem virtualenv: o ponto de entrada roda o pacote a partir do clone.

As opções globais

Instalar também como plugin do Claude Code

claude plugin marketplace add ~/tools/deck      # ou a URL do GitHub
claude plugin install deck@deck

Isso adiciona onze skills — workspace, toggles, gates, metrics, board, bundle, mount, packs, asking, cost, doctor — que ensinam o Claude a consultar o plano de controle em vez de adivinhar, mais dois hooks: SessionStart, que registra a sessão como seguradora do que está montado, e SessionEnd, que devolve o que ficou montado.

Isso é pago em toda sessão. claude plugin details deck imprime o custo do que você instalou, que é o único número que vale citar. Instalar habilita em escopo user — todo projeto, use deck ou não. A maioria das equipes quer o contrário:

claude plugin disable deck@deck --scope user      # não em todo lugar
cd ~/work/projs
claude plugin enable deck@deck --scope project   # aqui, e para a equipe

Do zero a um workspace utilizável

cd ~/work/projs
deck setup --packs-root ../ai-packs --create-packs

Um comando: lê como a sua árvore está montada, escreve o descriptor, cria um pack esqueleto por projeto, liga os dois, e termina nas duas ou três coisas que só uma pessoa pode decidir.

O que é uma coleção, e onde ela fica

Uma coleção é um diretório — nada além disso. O que a torna uma coleção é o que ela tem no topo: _workspaces/ ou _repos/. Um diretório apontado por packs_root que não tem nenhum dos dois o deck recusa, dizendo exatamente isso.

O repositório não é a coleção. O repositório dá versionamento, revisão e permissões; a coleção é o subdiretório que o deck lê. Por convenção ela se chama packs/:

   xyz-ai-packs/            ← o REPOSITÓRIO: versionado, revisado, com permissões
   └── packs/               ← a COLEÇÃO: é para cá que packs_root aponta
       ├── _workspaces/
       │   └── all/default/     vale para todo repositório, sempre
       └── _repos/
           ├── api/             vale só para o repositório `api`
           └── web/

Os nomes fazem a ligação — não há tabela de mapeamento, porque tabela de mapeamento é arquivo que ninguém mantém atualizado.

   projs/                       xyz-ai-packs/packs/
   ├── group1/                  ├── _workspaces/
   │   ├── proj1/               │   └── all/default/    ← todo repositório
   │   └── proj2/               └── _repos/
   └── group2/                      ├── proj1/  ◄──────── casado pelo nome
       ├── proj3/                   ├── group1/proj2/  ← grupos espelhados
       └── proj4/                   └── group2/proj3/
                                    (proj4 não tem pack — o deck diz isso
                                     em vez de ficar quieto)

Dois eixos, e eles são independentes

Onde a coleção mora é só um caminho em packs_root. Um repositório separado, um diretório dentro de um repositório de produto, qualquer lugar do disco — o deck não distingue. Esse eixo decide quem revisa o conhecimento, e nada mais.

A que o pack se aplica vem de onde ele está. _repos/<nome>/ é aquele repositório e nenhum irmão. _workspaces/<nome>/<escopo>/ é uma camada sobre o workspace: all e default sempre existem e são a base, e uma camada sob outro nome ou outro escopo se sobrepõe a ela, arquivo a arquivo.

   ordem de mesclagem, do mais geral para o mais específico:

   _workspaces/all/default   →   _workspaces/all/<escopo>
                             →   _workspaces/<nome>/default
                             →   _workspaces/<nome>/<escopo>
                             →   _repos/<repo>

   o mais específico tem a última palavra

Quando os dois eixos discordam sobre um mesmo arquivo, o nome vence: um workspace é um lugar e um escopo é uma fase, e a fase é a coisa temporária.

Os quatro fluxos, em uma página

Tudo abaixo é composto destes quatro. Se você ler só uma coisa desta página, leia esta.

A · Começar um workspace — uma vez por checkout.

   você                    deck                         disco
   ────                    ────                         ─────
   deck setup          ──► lê como a árvore está     ──► X/_workspaces/<nome>/default/
     --packs-root X        montada, deriva o registry        workspace.yaml (versionado)
     --workspace <nome>                                 ──► ~/.deck/workspaces/<nome>/
     --create-packs        cria o esqueleto da coleção        machine.yaml (só seu)
                                                          ──► X/_repos/<cada repo>/
                           │
                           └─► e para nas duas coisas que só você decide:
                               as arestas `impacts:`  ·  a allowlist `targets:`

B · Uma tarefa, do início ao fim — o laço do dia a dia.

   deck mount --task T --repos api --brief "..."
        │
        ├─► expande pelo grafo: api força server? server entra também
        ├─► camada de workspace  ──► <raiz>/.claude/  +  CLAUDE.local.md
        └─► pack de cada repo     ──► <repo>/.claude/
        │
        ▼
   ┌─ abrir a sessão Claude AQUI, e não antes ────────────────────┐
   │  skills, agents e CLAUDE.local.md são lidos no lançamento    │
   │  regras com `paths:` carregam quando um arquivo casa         │
   └──────────────────────────────────────────────────────────────┘
        │
        ▼
   deck gate run --task T        a escada, e a evidência em disco
        │
        ▼
   deck save --task T            o que a IA corrigiu volta à coleção
        │                        (deck doctor avisa se você esquecer)
        ▼
   deck bundle --task T          o que o revisor lê em vez do diff
        │
        ▼
   deck unmount --task T         a árvore volta ao que era

C · Uma mudança que atravessa repositórios — por que o deck existe.

   deck impact api-schema
   ┌──────────────────────────────────────────────────────────┐
   │ a change in api-schema reaches 3 repositories            │
   │                                                          │
   │   1. api-schema     build api-schema     ◄── você mexeu  │
   │   2. api-server     build api-server     ◄── tem que     │
   │   3. web-client     build web-client         acompanhar  │
   │   4. e2e-suite      (downstream — não produz artefato)   │
   └──────────────────────────────────────────────────────────┘
        │
        └─► deck mount --task T --repos api-schema
            monta os quatro, não um — esquecer um deles é o
            erro que a expansão existe para impedir

D · O conhecimento se acumula — o que separa a segunda tarefa da primeira.

   tarefa 1        a IA descobre algo, ou uma regra estava errada
       │
       │  deck save
       ▼
   COLEÇÃO         você revisa o diff e commita     ← vira do time AQUI
       │
       │  deck mount
       ▼
   tarefa 2        a IA já começa sabendo
   tarefa 3
   ...

   sem o save, cada tarefa recomeça do zero e a mesma
   correção é feita de novo, por outra pessoa, na semana seguinte

7.O mapa — onde está tudo, e o que uma mudança alcança#

O conceito: um registry de unidades de mudança e as arestas entre elas. O registry o deck consegue derivar de como a sua árvore já está montada. As arestas, não — e é por isso que existem comandos separados para as duas coisas.

Dois tipos de aresta

impacts: é direcional e ordenada. Ela responde duas perguntas com uma aresta: o que preciso revisitar e em que ordem. É a forma certa para a maior parte de um workspace, e é o que torna possível a ordem topológica, a cadeia de build e a checagem de ciclos.

É a forma errada para uma relação que responde à primeira pergunta e não tem resposta para a segunda. Um repositório de schema semeia uma configuração que um repositório de scripts lê, e o repositório de scripts é dono da linha de comando que o primeiro chama em tempo de execução: cada lado quebra o outro, com evidência de arquivo e linha nos dois, e nenhum vem primeiro. Havia três formas de segurar isso e só uma preserva as duas metades:

couples: é lida por deck impact, que a lista separada da cadeia ordenada, e por deck mount, que coloca os packs de um repositório que o trabalho talvez tenha de editar. Ela é lida por nada que ordena: a ordem topológica e a checagem de ciclos nunca a olham, que é exatamente por que um acoplamento nunca consegue tornar o grafo cíclico. É simétrica — declarar de um lado basta — e não é transitiva, porque “força uma mudança em” compõe e “se puxam mutuamente” não.

A regra que decide onde ela aparece: uma superfície que reporta lê couples:; uma superfície que ordena, agenda ou exclui, não.

$ deck impact schema
a change in schema reaches 1 repository

execution order:
  1. schema
  2. gen  build gen-all

coupled with, in no order:
  - runtime   (declared by schema)

  A coupling is mutual and carries no order: revisit these, do not sequence them.
  They take no part in the execution order above, and never in a build order.

Saída real, de um workspace sintético de três repositórios.

Os comandos do mapa

Imprime a raiz do workspace resolvida. Sem opções. A resolução da raiz tem quatro fontes e nunca adivinha; este comando diz qual venceu.

Resumo: raiz, de qual fonte ela veio, se o descriptor existe, quais packs estão em jogo, os repositórios e os targets.

O caminho absoluto de um repositório. Existe para que um script ou um gate não precise saber onde a sua árvore está montada.

Um campo do descriptor, por chave pontuada: deck get repos.schema.path. É o acesso de leitura ao descriptor sem escrever um parser de YAML no seu script.

Mostra quais packs estão em jogo, em ordem de merge (do mais geral para o mais específico) e quem sobrescreve quem. Estender uma entrada que o núcleo define exige repetir o id com overrides: true; uma colisão sem essa flag é recusada, para que ninguém sombreie uma decisão do núcleo por acidente.

Os diretórios nomeados que o workspace usa mas não muda. O deck faz uma pergunta sobre cada árvore que fica fora do workspace: você a edita ou só a invoca? Algo que você edita é um repositório, mesmo morando fora da raiz — ganha arestas, um pack e um lugar na escada. Algo que você só invoca é um path: não carrega arestas, não declara gates, nunca recebe mount. Um gate se refere a ele como ${path.scripts}, que é o que mantém o pack portátil — o pack nomeia scripts, e o seu descriptor, que não é versionado, diz onde está o seu.

A allowlist de implantação: as máquinas que o deck deixa qualquer coisa alcançar. Uma lista vazia significa nenhuma implantação e nenhum gate de comportamento, o que é um começo perfeitamente razoável. Veja §19 para o que essa allowlist de fato impede hoje.

scopes lista os subconjuntos nomeados do registry; scope <name> abre um: seus repositórios, seu quadro, sua postura. O relatório de um scope diz o que a iniciativa alcança e não contém, pelos dois caminhos por onde ela vaza: a cadeia ordenada que seus impacts: alcançam, e qualquer par couples: do qual ela segura um lado só. As duas metades são impressas separadas e nunca fundidas numa lista — só uma delas carrega ordem, e uma lista única emprestaria essa ordem à outra.

O que uma mudança naquele repositório alcança, em ordem de execução, mais os acoplamentos, separados. Esta é a pergunta que o agente não consegue responder sozinho, e é o motivo de o deck existir.

A ordem topológica para um conjunto de repositórios. Editar o backend antes do schema produz um build que passa e um comportamento que não existe; este comando é o que diz a ordem certa a um script.

Cria .deck/ a partir dos templates disponíveis. Se um pack traz templates/workspace/workspace.yaml, o deck usa esse em vez do genérico, e diz que usou — é assim que a segunda pessoa a montar o mesmo tipo de workspace recebe a mesma forma sem que ninguém lhe explique qual é.

Monorepo

O motor não se importa se uma unidade de mudança é um checkout ou um diretório. repos: é um registro de unidades; path: é onde cada uma mora. Nada no grafo de impacto, na escada, no escopo dos packs ou no quadro depende de a unidade ter um .git próprio. deck setup encontra as unidades por evidência: um diretório com um manifesto de pacote — pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml e afins — declara-se uma unidade.

O que de fato difere é do git, não do deck: há um .git só, um .git/info/exclude compartilhado, e a raiz do workspace é o próprio repositório do produto. As duas consequências são estruturais — os padrões de exclusão precisam estar ancorados na raiz da árvore de trabalho, e cada bloco precisa ser marcado por tarefa e caminho, senão a escrita de uma unidade substitui a da anterior. Erre isso e um agente rodando git add -A comita os artefatos do deck dentro do produto.

8.As decisões — toggles#

Um toggle é uma decisão com mais de uma resposta defensável, escrita uma vez, com o raciocínio junto. O catálogo do núcleo traz 27 decisões e 5 perfis; um pack acrescenta as do seu domínio.

Três estados, e um deles não é um valor

Um toggle tem um valor, ou tem o valor especial ask. ask não é um valor: é uma instrução para apresentar ao operador a pergunta que está escrita no próprio catálogo, no estágio declarado. O texto vem do pack, não do agente que perguntou — que é o que faz a mesma tarefa, pedida por uma pessoa sênior e por alguém na primeira semana, produzir a mesma pergunta com as mesmas palavras.

Sete camadas de precedência

   mais forte ──────────────────────────────────────────────────► mais fraca

   task file   DECK_<ID>    repos:         scopes:      values:    profile   catálogo
               no ambiente  bloco          bloco        bloco                padrão
   ─────────   ──────────   ──────         ───────      ───────    ───────   ───────
   uma tarefa  um comando   um repositório uma          esta       uma       a política
                                           iniciativa   máquina    postura   da equipe

Cada camada é mais larga que a anterior: esta tarefa, este comando, este código, esta iniciativa, esta máquina. A mais estreita que tem um valor vence.

Por que este valor, e não só de onde ele veio

Uma camada diz quem decidiu; ela não diz por quê. Um gate_level foi rebaixado de deploy para build num workspace real porque a entrega passava por um caminho de atualização de firmware que ninguém tinha ligado ao deck. O valor estava certo e a frase que o explicava vivia num histórico de chat — então, meses depois, nada o distinguia de um valor que ninguém tinha revisitado.

deck toggle set gate_level build --at workspace \
  --why "a entrega passa por um caminho de firmware que ninguém ligou ao deck ainda"

--why é registrado num mapa reasons: ao lado do mapa values: que ele explica, no mesmo arquivo. É um irmão, e não um valor mais rico, para que values: continue sendo a lista de duas colunas que uma pessoa edita à mão, e para que um arquivo antigo sem reasons: se leia como “não tem nenhuma” em vez de “tem metade”.

deck toggle explain imprime duas frases separadas, porque elas têm dois autores: por que o toggle existe é o rationale do catálogo, revisado por quem é dono do domínio; por que este valor foi escolhido é de quem escolheu, e pertence a este workspace apenas. Um valor sem nada registrado diz isso, e nomeia o comando que registraria — em vez de ficar debaixo do parágrafo do catálogo e passar por justificado.

Uma razão pertence ao valor para o qual foi escrita, então definir um valor sem --why descarta a razão anterior e avisa que descartou: uma frase deixada para trás continuaria justificando uma decisão que não está mais no arquivo.

Os comandos das decisões

$ deck toggle list --stage plan
-- Quality and verification
    gate_level             deploy         catalog default (core)
    unit_tests             opportunistic  catalog default (core)
  ? api_compat             ask            catalog default (pack)

-- Delivery
    plan_approval          always         catalog default (core)
  ? requirement_link       ask            catalog default (core)

  ? = will be asked when it matters

Saída real de ./docs/tour.sh, recortada. O ? não é um valor faltando: é uma pergunta esperando o momento certo.

O valor efetivo de um toggle, e só isso. É a forma que um script ou um gate usa: deck toggle get gate_level.

Significado, valor efetivo, de qual camada ele veio, risco, estágios, as duas frases de raciocínio, o impacto de cada valor, e todas as camadas da mais forte para a mais fraca. É o comando para quando alguém pergunta “por que estamos fazendo assim?”.

$ deck toggle explain target
target — Deployment target
  Which host from the allowlist receives the deployment.

  effective  : bancada.example.com
  source     : workspace
  risk       : high
  depends on : {'gate_level': ['deploy', 'behavior']} → satisfied

  why this value was chosen (workspace):
    a única bancada declarada

  layers (strongest first):
    bancada.example.com   workspace   (why recorded)
    ask                   catalog default (core)

Um perfil move a postura inteira numa frase — perguntar mais e verificar até o fim para quem é novo, pegar o caminho curto num hotfix — em vez de discutir isso por tarefa. O núcleo traz cinco: standard, guided, autonomous, hotfix e offline.

Emite as perguntas pendentes já em formato de pergunta pronta — cabeçalho, opções e descrições — para o Claude Code desenhar a caixa. O deck fornece o texto; o runtime desenha.

$ deck toggle ask-plan --stage plan --files services/api-schema/openapi.yaml

  May this change alter the published API contract?   [high risk]
    Additive only      Clients in the field keep working.
    May break          Needs a migration note and a version bump.

Confere o catálogo, os perfis e as escolhas gravadas. Entre outras coisas, ele recusa um catálogo em que um toggle do grupo security tenha padrão ask: política de segurança se decide de antemão, não se negocia no meio da tarefa com um agente com pressa.

9.O contexto — mount#

Mount é colocar os artefatos certos nos diretórios certos para um pedaço de trabalho, e retirá-los depois. O deck não inventa um carregador de contexto: ele escreve nas superfícies que o Claude Code já lê, na seguinte ordem de preferência.

   pack (fora do repositório)                repositório (de outra pessoa)
   ───────────────────────                   ───────────────────────────
   config/mount.yaml          ──plugin──►    .claude/settings.local.json
   rules/api-contract.md      ──rule────►    .claude/rules/deck-api-contract.md
   (gerado para esta tarefa)  ──cópia───►    CLAUDE.local.md

                          manifesto ──► .deck/mounts/<task>.json
                          exclusões ──► .git/info/exclude   (nunca .gitignore)

Duas garantias

Ele só remove o que colocou. Cada entrada carrega um hash. Uma regra que alguém editou, um arquivo de settings onde outra pessoa acrescentou um plugin, um briefing que foi estendido — cada um é reportado e deixado em paz.

Ele não suja o git status. As exclusões são locais, em .git/info/exclude, nunca em .gitignore — que é um arquivo versionado do repositório de outra pessoa. Nada que o deck escreve pertence a um repositório de produto, e nada que ele coloca lá sobrevive a um unmount.

Um mount é segurado, não possuído

Quem monta toma o primeiro hold, e toda sessão de agente que começa sob a mesma tarefa toma um também. Quando uma sessão termina, ela libera o seu próprio hold, e o mount só é desfeito quando não sobra nenhum. Fechar um painel não pode tirar as regras do painel que ainda está trabalhando na tarefa.

Os comandos do contexto

$ deck unmount --task TOUR-1
  removed  .../services/api-schema/.claude/rules/deck-api-contract.md
  removed  .../CLAUDE.local.md

  2 removed · 0 left alone

Saída real de ./docs/tour.sh. “0 left alone” é a contagem do que foi encontrado modificado e por isso preservado.

Registra esta sessão como seguradora do que está montado aqui. Sem opções. Você nunca digita este comando: o hook SessionStart do plugin o executa.

O que está montado agora neste workspace. deck doctor reporta um mount que sobreviveu à sua sessão.

Onde cada artefato pousa, e quando o Claude o lê

O mount copia — nunca link simbólico. Um link em .claude/rules/ falha em silêncio: o mount reporta sucesso, o ls -l parece certo, e a regra nunca chega ao agente.

   COLEÇÃO                              ÁRVORE DE TRABALHO

   _workspaces/all/default/
     CLAUDE.md          ──────────────► <raiz>/CLAUDE.local.md
     rules/house.md     ──────────────► <raiz>/.claude/rules/deck-house.md
     skills/rev/        ──────────────► <raiz>/.claude/skills/deck-rev/
     agents/qa.md       ──────────────► <raiz>/.claude/agents/deck-qa.md

   _repos/api/
     rules/contract.md  ──────────────► <raiz>/api/.claude/rules/deck-contract.md

A camada de workspace pousa uma vez, na raiz; o pack de um repositório pousa naquele repositório e em nenhum irmão. O prefixo deck- existe para o .git/info/exclude poder nomear os arquivos do deck sem reivindicar um diretório que o repositório também usa.

   SKILL:     sim    .claude/skills/<nome>/SKILL.md, na listagem de skills
   AGENT:     sim    .claude/agents/<nome>.md, como tipo do Agent
   CLAUDE_MD: sim    CLAUDE.local.md na raiz, nas instruções
   RULE:      não    .claude/rules/<nome>.md — e então SIM, depois que a
                     sessão leu um arquivo que o `paths:` dela casa

O ciclo inteiro, e por onde o conhecimento volta

O mount leva conhecimento para fora da coleção. O deck save é a volta, e sem ele o que a IA aprendeu morre com o diretório de trabalho.

        ┌──────────────────────────────────────────────────┐
        │  COLEÇÃO  (xyz-ai-packs/packs)  — versionada      │
        └──────────────────────────────────────────────────┘
              │                                    ▲
              │ 1. deck mount                      │ 3. deck save
              │    --task X --repos api            │    --task X
              │    --brief "..."                   │
              ▼                                    │
        ┌──────────────────────────────────────────────────┐
        │  ÁRVORE DE TRABALHO  — .claude/, CLAUDE.local.md │
        │                                                  │
        │        2. a sessão Claude trabalha aqui          │
        │           lê as regras · corrige uma             │
        │           escreve uma nova                       │
        └──────────────────────────────────────────────────┘
              │
              │ 4. deck unmount --task X     (a árvore volta ao que era)
              ▼
        ┌──────────────────────────────────────────────────┐
        │  5. você revisa o diff na coleção e commita      │
        │     — o único momento em que vira do time        │
        └──────────────────────────────────────────────────┘

1 · deck mount — antes de abrir a sessão

--task <id>        sob que id tudo é registrado. Sem ele, o id da sessão —
                   que dentro do tmux vem da JANELA, então dois painéis de
                   uma janela são uma tarefa só.
--repos a b c      o que está em jogo. Vírgula ou espaço. EXPANDE pelo grafo
                   de impacto: montar o pack do schema e não o do servidor
                   que ele força a mudar é como um agente acaba editando um
                   repositório sobre o qual não sabe nada.
--no-expand        só o que você nomeou.
--brief "texto"    escreve o CLAUDE.local.md na raiz. Com `-`, lê do stdin.
                   Numa tarefa já montada, substitui só o enunciado — porque
                   o enunciado normalmente chega DEPOIS do mount.
--dry-run          o plano, sem escrever nada.

3 · deck save — o que a IA mudou volta

--task <id>        qual tarefa. Sem ele, o id da sessão.
--dry-run          o que escreveria, escrevendo nada.

Para onde volta não é adivinhação: o manifesto do mount gravou a origem de cada artefato, então a edição volta para o arquivo de onde veio, na camada de onde veio. Três situações, e a terceira é a mais conservadora:

   changed   a cópia não bate mais com a fonte     → escreve de volta na fonte
   new       arquivo que ninguém colocou           → vai para o pack dono do
                                                     lugar, SEM o prefixo deck-
   gone      artefato colocado que sumiu           → REPORTA e não propaga

Remover uma regra de um pack é uma edição ao pack — não algo a inferir de uma cópia de trabalho que sumiu.

4 · deck unmount — tira de volta exatamente o que colocou

--task <id>        aquela tarefa. É o que você digita.
--session          tudo que ESTA sessão montou. É o que o hook SessionEnd
                   chama — e ele solta apenas o hold dela: fechar um painel
                   não arranca as regras do painel que ainda trabalha.
--all              todo mount deste workspace. A vassoura.

Ele nunca apaga o que alguém editou. Um arquivo que não bate com o gravado fica, com a razão dita, e o relatório conta os dois lados: 12 removed · 0 left alone. Também desfaz o que não é arquivo — a entrada em settings.local.json, o bloco no .git/info/exclude — e poda os diretórios que ele mesmo criou, só enquanto vazios.

Depois de um save, o que atravessou é retirado: deixou de ser trabalho não salvo. Uma edição feita depois do save continua protegida.

E se você esquecer o save?

O deck doctor avisa. Ele vigia as duas direções da deriva:

$ deck doctor
mounted artifacts
  OK C2  1 artifact(s), this session
  !! C2  stale: all/default changed house.md since it was placed
         ↑ o PACK andou à frente das cópias — remonte
  !! C2  unsaved: 1 edited, 1 written here — nothing in the collection holds them yet
         ↑ as CÓPIAS andaram à frente do pack — deck save --task C2

10.Os packs — onde o conhecimento da equipe mora#

Um pack é um diretório versionado e revisado como qualquer outro código. Ele é, ao mesmo tempo, um plugin do Claude Code: o mesmo diretório carrega skills/, agents/ e hooks/, que o Claude Code lê diretamente, mais um config/ que só o deck lê.

Mais rules/ (invariantes, escopadas por paths:), skills/ (procedimentos com passos) e templates/workspace/workspace.yaml — a forma do descriptor que a equipe compartilha.

Os comandos dos packs

Cria o esqueleto inteiro com todos os comentários intactos — eles explicam o que vai em cada arquivo e por quê, e são a documentação de referência de fato.

O que cada pack custa, e o que parou de merecer esse custo. Ele cruza o que o pack declara com a evidência que este workspace guardou: quantas vezes cada gate rodou, quantas vezes pegou alguma coisa, quantas vezes foi pulado. Um gate que roda sempre e nunca pega nada é um custo sem retorno; uma regra que nenhum arquivo casa é contexto que nunca chega.

$ deck pack review
gate history, from the evidence this workspace kept
  deploy-remoto    ran   3  caught   3  skipped   2
  build            ran   2  caught   2  skipped   0
  lint             ran   3  caught   0  skipped   0

Os packs em jogo e o que cada um contribui — toggles, gates, regras.

Sem flags, lista fontes conhecidas de skills e agents. O texto de cada uma diz também quando não vendorizar — uma metodologia que você vendorizou é uma metodologia que parou de receber as correções do autor.

Confere se um pack se sustenta, e reporta como aviso o que está faltando ou malformado — por exemplo um .claude-plugin/plugin.json ausente, que faria o Claude Code não carregar o pack como plugin. Padrão: o diretório atual. A redação do catálogo é conferida separadamente, por deck toggle validate --strict.

11.A prova — a escada de gates#

Um gate é um comando que passa ou falha, num degrau da escada. A escada do núcleo tem quatro degraus, e um pack pode inserir os seus estendendo o toggle gate_level — não editando o motor.

   gate_level:  static ──► contract ──► build ──► deploy ──► behavior
                                ▲
                                └── um pack inseriu este degrau estendendo o
                                    toggle gate_level, não o motor

   cada gate declara:  from_level · per_repo ou once · only_repos · when · timeout
                       · measures  (opcional: um número a extrair da saída)
   cada resultado é:   passed · failed · could-not-run · not-applicable
                       └─ os dois últimos sempre carregam o motivo

Os quatro degraus, e o que cada um acrescenta

Cada degrau inclui os anteriores — a escada é cumulativa, não uma escolha entre alternativas. Estas quatro linhas não são invenção desta página: são o campo impact: do toggle no catálogo do núcleo, e você as lê sem abrir arquivo nenhum com deck toggle explain gate_level.

Baixar o degrau é permitido e é sempre visível: o relatório sempre diz até onde chegou, e a decisão fica no registro em vez de virar um silêncio. É a diferença entre “verificamos até o build, de propósito” e “achamos que estava verificado”.

Três propriedades foram escolhidas no lugar de funcionalidades

1. Um gate que não rodou nunca é reportado como tendo passado.
2. Um comando com uma variável não resolvida não roda.
3. Toda execução deixa evidência em disco, passando ou falhando.

Isso não é uma promessa em prosa. É o que a saída mostra:

$ deck gate run --task T-2 --level build; echo $?
task T-2 · level build · 3 repositories

  ok   lint         schema                     0.0s
  ok   lint         gen                        0.0s
  ok   lint         runtime                    0.0s
  ??   build        schema                     unresolved: ${repo.build_target}
  ??   build        gen                        unresolved: ${repo.build_target}
  ??   build        runtime                    unresolved: ${repo.build_target}
  --   deploy-remoto gate_level is `build`; this gate starts at `deploy`

  1 gate(s) passed in 6 run(s) · 1 could not run · 1 not applicable
  evidence: .deck/gates/T-2.json

  A gate that did not pass is never reported as passed. Fix it, or lower
  `gate_level` deliberately — the report will say which rung was reached.
1

Saída real de um workspace sintético. Três coisas aconteceram e as três estão na tela: três execuções passaram, três não puderam rodar (e o motivo é a variável exata que faltou), e uma não se aplica (e o motivo é o degrau). O código de saída é 1.

E quando não há gate nenhum declarado, o deck se recusa a reportar sucesso:

$ deck gate run --task T-1; echo $?
deck: no gate is declared, so nothing was verified.
Gates come from a pack's config/gates.yaml — check `deck packs`
resolves the pack you expect.
1

Saída real. Isso já foi diferente: a CI do próprio deck imprimia 0 gate(s) passed e saía com 0 — um checkmark verde sobre nada.

A allowlist de máquinas

Um agente com acesso ao shell alcança qualquer host que um comando nomeie. O bloco targets: do descriptor é uma allowlist, e o toggle target só aceita um valor que esteja nela:

$ deck gate run --task T-3 --level deploy; echo $?
deck: target `fora-da-lista` is not in the allowlist. Declare it under
`targets:` in the descriptor, or pick one that is.
1

Saída real. Leia §19 para o que essa allowlist não cobre — a diferença importa.

Os comandos da prova

Quais gates se aplicam a esta mudança, e por quê. Ele imprime também os que não se aplicam, com o motivo — porque a lista dos que ficaram de fora é metade da resposta.

Lê de volta a evidência de uma tarefa, depois — possivelmente muito depois, e numa outra sessão. É a diferença entre “passou” como afirmação e “passou” como registro: os logs de cada execução ficam em .deck/gates/logs/<task>/.

12.A tendência — o que o gate mediu#

Um gate é um limiar, e um limiar tem um ponto cego: tudo que está dentro dele parece igual. Cobertura escorregando de 86% para 81% sob um piso de 80% passa em toda execução, e a execução que finalmente falha é a de depois que a queda terminou.

   o gate              a série
   ─────────           ──────────────────────────────────────────────
   passa / falha  +    86.1 → 84.0 → 82.7 → 81.2  em quatro execuções
   contra um           todas passaram; esse é o achado
   número que          └─ um bundle carrega isso como uma ressalva, nunca
   alguém escolheu        como um bloqueio: uma tendência sobre a qual
                          ninguém pôs um limite não pode virar um limite
                          que ninguém escolheu

Um gate declara measures: — um id, uma expressão regular, uma unidade e, opcionalmente, qual direção é melhor. O motor aplica isso aos bytes que o comando já imprimiu, nunca a uma segunda execução, que poderia discordar da primeira. Um padrão que não casa com nada não registra nada e diz isso: uma amostra faltando nunca é um zero, porque um zero pareceria uma medição que alguém tomou.

Onde a série vive é uma decisão, não um padrão silencioso: metrics_store vale workspace, shared ou off, e shared sem um diretório declarado é recusado em vez de escrito por máquina.

Os comandos da tendência

Toda métrica, declarada ou já registrada, e a sua tendência. Uma métrica declarada e ainda sem amostra é listada assim mesmo, dizendo quando será medida.

$ deck metrics list
store    workspace · .deck/metrics
declared 1 measurement(s), by 1 gate(s)

  cobertura.cobertura  (gen)         cobertura
       one sample, 82.7 % on T-9 — a trend needs a second

Saída real de um workspace sintético. “a trend needs a second” é o deck se recusando a chamar uma amostra de tendência.

As amostras por trás de uma tendência, cada uma com a tarefa e o degrau em que foi tomada, mais o arquivo de onde vieram. Os arquivos são append-only: um histórico que pode ser reescrito não é evidência.

$ deck metrics show cobertura.cobertura
  when                  task             rung            value
  2026-09-07T03:10:45   T-9              build            82.7

  one sample, 82.7 % on T-9 — a trend needs a second
  Nothing here failed anything. A gate reports a threshold; this reports a direction.

13.O quadro — onde está o trabalho, e o que pode rodar junto#

Não existe protocolo de sincronização no deck, e não deveria existir. O trabalho de uma equipe já vive num rastreador que é auditado, tem permissões e sobrevive a qualquer laptop — então o rastreador é o estado compartilhado, e o deck lê dele. Jira, GitLab, GitHub, Gerrit ou um arquivo.

O que o deck acrescenta é a única coisa de que a coordenação precisa e que um rastreador não impõe: a reivindicação. deck board claim atribui uma tarefa e recusa uma que outra pessoa já segura, porque dois agentes editando a mesma cadeia produzem um merge que ninguém consegue revisar.

$ deck board claim EX-2 "outra pessoa" --yes; echo $?
deck: EX-2 is already claimed by <quem já segurava>.
  Two agents on one task produce a merge nobody can review.
  Use --force only after talking to them.
1

Saída real de um quadro em arquivo, num workspace sintético.

Uma reivindicação vale o que o rastreador diz que ela vale

O GitHub responde 201 a uma atribuição para um login que ele está prestes a descartar: o status diz que a requisição estava bem formada e só o corpo diz que ninguém foi atribuído. Foi assim que deck board claim passou a reportar uma atribuição que nunca aconteceu. A escrita agora é lida de volta: cada backend reporta o assignee que a resposta diz ter sido gravado, um nome que o rastreador descartou vira um erro que o nomeia, e uma resposta que não presta contas de nada é reportada como isso — não presumida como sucesso.

Agrupamento: o que pode rodar ao mesmo tempo

   tarefas ──► fecho de edição por tarefa ──► grafo de conflito ──► grupos ordenados

   conflito quando:  os fechos de edição se cruzam
                     as duas precisam do mesmo target  (uma bancada é exclusiva)
                     qualquer uma está marcada exclusive
                     uma tarefa não nomeia repositório  (poderia tocar em tudo)

   NÃO é conflito:   as duas apenas *alcançarem* um repositório downstream

Aquela última linha é toda a sutileza, e ela veio de ter errado primeiro. A regra inicial conflitava por alcance, e num quadro de cinco tarefas produziu cinco grupos de uma: toda tarefa alcançava a suíte fim a fim, então todo par colidia. Hoje o fecho de edição de uma tarefa é: os repositórios que ela nomeia, mais tudo que esses alcançam por impacts:, menos os que estão marcados downstream: true e que ela não nomeia diretamente.

couples: deliberadamente não é lido aqui: um acoplamento diz “revisite antes de entregar”, e uma revisita que não muda nada não colide com nada.

$ deck board plan
3 open task(s) · parallelism 2

  group 1 (parallel)
    EX-2                     ajustar o gerador
      reaches: gen
    EX-3                     revisar o runtime
      reaches: runtime, schema, gen

  group 2 (alone)
    EX-4                     manutenção da bancada
      reaches: (no repository named)

  !! EX-3 reaches gen, which EX-2 edits. If EX-3 has to update it too, name it
     in its `repos`.

  This is a plan, not a run. deck does not orchestrate agents: Claude Code
  already does that.

Saída real de um workspace sintético. Note o aviso !!: o deck não serializa por causa de um alcance, mas também não fica calado sobre ele.

Os comandos do quadro

As tarefas que as fontes declaradas seguram, com os repositórios que cada uma nomeia. Uma leitura de rastreador segue as páginas do serviço em vez de pegar só a primeira, tem um teto (uma consulta que ninguém quis não deve segurar a CLI por centenas de requisições) e uma leitura que atingiu o teto é reportada como parcial ao lado das tarefas que trouxe.

Uma tarefa: status, os repositórios que ela nomeia, o que ela alcança, e os critérios de aceite com quantos foram aceitos.

Toda decisão que o quadro aberto está esperando, perguntada de uma vez só. É o oposto de interromper alguém uma vez por tarefa.

Um item de quadro bem formado, para copiar. Sem opções. Ele traz o briefing — as_a, so_that — que é o que um agente precisa para escolher entre duas maneiras plausíveis de fazer a mesma coisa, e os acceptance, que são a definição de pronto nas palavras de quem vai julgar.

$ deck board done EX-1; echo $?
deck: no gate evidence for EX-1 — nothing has been verified under that name.
  Run it:      deck gate run --task EX-1
  Or say so:   --force, for a task the ladder does not cover
1

Saída real.

O que o deck reporta é a url ou a chave que o rastreador deu à tarefa nova — nunca uma palavra substituta para algo que ele não nomeou.

Para cada fonte, qual conta agiria, qual nome seria escrito, e de onde esse nome veio. Sem opções. Ele nunca imprime o token.

$ deck board whoami
  type       host or repo             token     from            user
  tasks      docs/board.yaml          n/a       git user.name   ...

  A token is resolved at call time: $DECK_TOKEN_<TYPE>, then the
  conventional variable, then ~/.netrc, then a `token_command` the
  descriptor names. It is never read from the descriptor itself.

Por que duas tarefas não podem rodar juntas — ou a confirmação de que podem. Existe porque um agrupamento sem explicação é uma decisão que ninguém consegue contestar.

$ deck board why EX-1 EX-3
EX-1 and EX-3 must not run together: both would edit gen, schema

$ deck board why EX-2 EX-3
EX-2 and EX-3 can run at the same time

14.A entrega — o bundle de prontidão para merge#

deck bundle é a última coisa porque lê todas as outras. Ele monta numa página o registro dos gates, a cadeia de impacto, as camadas de toggle com a razão gravada ao lado de cada uma, as consultas e o git. Ele deriva tudo e afirma nada: cada alegação nomeia o arquivo de onde veio.

O que ele diz, explicitamente:

• quais repositórios a mudança alcançou, e quais deles terminaram sem commit nenhum;
• qual degrau a escada alcançou, quais degraus ela nunca tentou, e quais não têm gate algum — um degrau ao qual a escada subiu e encontrou vazio é uma lacuna de cobertura, não um degrau alcançado;
• e, separadamente, os degraus cujos gates foram todos pesados contra esta mudança e considerados não aplicáveis, com o motivo que cada um deu — porque no primeiro caso ninguém declarou um gate e no segundo alguém declarou, e isso é uma diferença;
• quais decisões estavam em vigor, de onde veio cada valor, e por que quem escolheu escolheu — ou que ninguém escreveu razão nenhuma;
• o que continua sem commit ou ainda colocado num diretório de trabalho;
• e, para cada um desses, o arquivo de onde a alegação veio.

Ele sai com código diferente de zero enquanto qualquer coisa estiver no caminho, para que um pack que queira prontidão de merge imposta possa declarar um gate que o execute.

$ deck bundle --task T-9
T-9

  NOT READY — 2 things in the way

  !! nothing has been verified under this name
       deck gate run --task T-9
  !! no commit is attributable to this task, so the change set is unknown
       — not empty
       commit naming T-9 in the message, or pass --since <timestamp>

  .. no declared board holds T-9, so nothing says which repositories it names

what was decided
    target                 bancada.example.com   from workspace
       why  a única bancada declarada

where each claim comes from
  the change set           git log, in each repository listed above
  verification             nothing recorded under this task
  decisions                deck toggle explain <id>
  what it cost             deck cost --task T-9

Saída real. Repare em “the change set is unknown — not empty”: o deck se recusa a reportar ausência de commits como ausência de mudanças.

15.A conta — quanto custou#

   transcript (~/.claude/projects/<project>/<session>.jsonl)
        │  uso por mensagem: input · output · cache write · cache read
        │  deduplicado por id de mensagem — uma mensagem em streaming aparece duas vezes
        ▼
   tokens  ──── exato ─────────────────────────────► reportado como fato
        │
        └── × tabela de preços ── estimativa a preço de tabela ──► rotulada como estimativa
                                       ▲
   status line ── cost.total_cost_usd ──┘ mostrada ao lado, e sinalizada
                  (o número do próprio Claude Code)  quando as duas divergem >10%

Os tokens são exatos, lidos do transcript da sessão. Os dólares são uma estimativa a preço de tabela, e o relatório diz que são. Onde o número do próprio Claude Code está disponível, o deck o trata como autoritativo e mostra a sua estimativa ao lado.

A janela de uma tarefa vem do que o deck já registra: um mount a abre, uma execução de gates a fecha. Nenhum dos dois existe para medir custo — que é exatamente por que a medição é confiável.

Quando não há transcript, o deck diz isso em vez de reportar zero:

$ deck cost --task TOUR-1
deck: no session of this workspace has a transcript yet (~/.claude/projects/...)
  Sessions opened elsewhere are not counted. Use --any-project to widen,
  which reports what other projects spent and is almost never what you want.

Saída real de ./docs/tour.sh. Uma janela vazia é a resposta honesta; um zero não seria.

16.As perguntas — consultas#

Uma consulta é a quinta saída de §2: algo que não é fato, nem invariante, nem decisão, nem prova. Um agente escreve a pergunta, continua trabalhando, e uma pessoa responde depois. A resposta sobrevive à sessão que a levantou e é citada no bundle que um revisor lê.

Uma consulta inteira: a pergunta, o contexto, as opções, quem perguntou e quando, e — se houver — a resposta, quem respondeu e quando.

Ao responder, o deck diz o que aquilo provavelmente quer virar — e diz também por que ainda não virou:

$ deck ask resolve <id> "renovar o token no início do job"
  This answer is a transcript until someone writes it down.
  It probably wants to become: toggle — it had named options, so it may be
  a decision that recurs

  Fold it:   deck ask fold <id> --as <rule|toggle|gate> --into <pack>
  Until then the next run has to ask again.

Saída real.

Escreve uma consulta respondida dentro de um pack, carregando a pergunta e a resposta, para que o raciocínio sobreviva à sessão que o produziu. Qual das três naturezas ela vira continua sendo julgamento de uma pessoa — se uma resposta recorre não é algo que se saiba de uma única ocorrência, e esse julgamento é a diferença entre conhecimento e transcrição. O deck nunca dobra uma consulta por conta própria.

Uma regra dobrada sai assim, com a proveniência em comentários:

---
paths: ["servicos/**"]
---

# renovação do token antes do job

renovar o token no início do job

<!-- Folded from consultation 20260907-... -->
<!-- Question: o refresh token expira antes do job noturno; renovar ou alongar? -->
<!-- Answered 2026-09-07T03:10:22 by equipe de plataforma: ... -->

Arquivo real gerado por deck ask fold --as rule num workspace sintético.

17.Onde o modelo entra, e onde não entra#

A pergunta mais comum sobre o deck é se ele conduz um agente. Não conduz, e a linha vale ser traçada com precisão, porque “uma ferramenta de IA” é exatamente a descrição que deixa as pessoas sem saber o que instalaram.

    o que um parser deriva              o que só julgamento produz
    ────────────────────────            ────────────────────────────
    quais repositórios existem          quais repositórios uma mudança
    o que um manifesto faz checkout       obriga você a tocar
    qual é o comando de um gate         como redigir uma decisão para que
    qual pack reivindica um nome          um colega consiga respondê-la
    quanto uma sessão custou            o que o código deve ser

    o deck computa isso.                Uma pessoa decide isso — ou, para
    Determinístico, auditável,          os dois primeiros apenas, pede um
    a mesma resposta duas vezes.        RASCUNHO a um modelo.
                                        O terceiro nunca é do deck.

O deck chama um modelo em exatamente um lugar no código-fonte, assist.py, alcançado por exatamente três comandos. Não existe um quarto. O deck nunca pede a um modelo que escreva o seu código, rode o seu build, edite o seu descriptor ou decida qualquer coisa.

As quatro restrições sobre essa única chamada

1. Desligado por padrão. O toggle ai_assist vale off (recusa), ask (recusa sem --yes) ou allow. É um toggle, e não uma flag, deliberadamente: um comando dedicado a ele seria o caso especial que mina o mecanismo do qual as outras 26 decisões do catálogo dependem. Ele carrega askable: false — é política, e política não é algo que um agente apresenta a você no meio de uma tarefa.
2. Somente leitura, imposto pelo runtime. A execução recebe Read, Grep e Glob, e nada mais. Sem Write, sem Edit, sem Bash. Um prompt é uma sugestão; isto não é.
3. Com teto de custo. --budget, cujo padrão é US$ 1.50. Um laço descontrolado não pode faturar em cima de você.
4. Escreve uma proposta, nunca uma edição. O resultado vai para .deck/proposals/, nunca para o descriptor. Uma ferramenta que reescreve em silêncio o arquivo que descreve como o seu sistema propaga mudança é uma ferramenta que ninguém deveria instalar.

Um rascunho não pode transformar uma pergunta em decisão

deck propose pack classifica o que encontra em gates, regras e toggles. Existe um quarto desfecho, e deixá-lo de fora custou algo real: um rascunho encontrou dois caminhos de código devolvendo códigos de status diferentes para a mesma classe de recusa, escreveu nas próprias notas que não sabia dizer se aquilo era intencional ou deriva, e arquivou como toggle. Arquivado como toggle, aquilo se lê como “nós escolhemos”, e a dúvida desapareceu no momento em que ela valia mais.

Por isso um rascunho de pack tem uma lista questions ao lado de toggles, e deck propose apply registra cada entrada como uma consulta. O toggle de um rascunho carrega um bloco defends, uma linha por valor dizendo por que uma equipe escolheria aquele — e apply recusa o rascunho inteiro quando um toggle não defende todos os valores que nomeia, ou quando o mesmo achado aparece como toggle e como algo que o rascunho não soube explicar.

Os comandos da proposta

O rascunho de impacts tem os dois tipos de aresta para escrever, e o que os separa não é gosto: um acoplamento custa uma citação por direção, em dois campos da proposta, porque ele não reivindica ordem e seria de outro modo a resposta cômoda para todo par que o rascunhista não conseguiu decidir. Evidência de um lado e palpite do outro é uma aresta comum mais uma nota unsure, e o palpite volta para você. Um rascunho que nomeia o mesmo par nas duas direções é aplicado como o acoplamento que é — enquanto as mesmas duas arestas impacts: escritas à mão continuam sendo um ciclo, porque alguém pode digitá-las e querer dizer aquilo.

Aplicar é um comando separado, com piso de confiança, executado por uma pessoa que leu a proposta — inclusive a lista unsure, onde o modelo registra o que não conseguiu verificar.

18.Diagnóstico e superfícies#

A primeira coisa a chamar quando algo está estranho. Ele nunca conserta nada sozinho, e todo problema que ele reporta vem com o comando ou a edição que o resolve — uma mensagem que nomeia uma condição sem um próximo passo está inacabada.

$ deck doctor
workspace
  OK root ...  ($DECK_ROOT)
  OK descriptor present  4 repositories, 0 target(s)

impact graph
  OK references  every target exists in the descriptor
  OK acyclic  topological order computable

targets (allowlist)
  !! none declared  gate_level = deploy needs one — deployment and behaviour
                    gates are unavailable

toggles
  OK catalog  28 toggles, 5 profiles

5 warning(s):
  !! api-schema: no origin remote
  ...
  !! no target declared

Saída real de ./docs/tour.sh, recortada. “28 toggles” ali são as 27 do núcleo mais a que o pack do tour acrescenta.

doctor também reporta o caso de auto-hospedagem: quando o deck em execução resolve para dentro do workspace que ele está administrando. Um agente editando o motor muda o binário que está rodando, incluindo o que rodaria os gates que pegariam a quebra — e uma edição pela metade não falha alto, ela desabilita a coisa que teria avisado.

Um REPL do plano de controle. Aceita os mesmos comandos sem o prefixo deck.

Precisa de tmux. É a única parte do deck que precisa.

Duas ou três linhas dentro da própria janela do Claude: qual workspace, qual perfil, até onde esta entrega verifica, e o que ainda está esperando ser perguntado.

19.O que o deck impõe, e onde ficam suas fronteiras#

Uma regra chega ao agente como texto no contexto, e um agente pode ignorá-la. Isso vale para toda ferramenta que instrui um modelo, e não é o que separa uma da outra. O que separa é o que é imposto por código, e essa lista é curta e verificável:

Registrar a arquitetura, e não calculá-la, é escolha

O deck registra como uma mudança se propaga — impacts:, couples:, role, downstream — e não a calcula. Não pode: o motor nunca ouviu falar de um import, de um alvo Bazel ou de uma receita, e dar-lhe esse conhecimento seria exatamente o que a separação motor/pack existe para manter de fora. Uma palavra de domínio no código do motor é bug.

Isso não deixa a imposição de fora — deixa-a no seu domínio. O comando de um gate resolve ${repo.impacts}, então um pack roda o que quer que calcule dependências de verdade no seu ecossistema e reprova quando a aresta declarada e a observada discordam:

gates:
  - id: arestas-reais
    title: o grafo declarado bate com o observado
    from_level: static
    per_repo: "import-linter --config .importlinter --target ${repo.impacts}"

go list, bitbake -g, madge, jdeps — o mecanismo é o mesmo. O deck não sabe qual é o seu; o seu pack sabe.

Critérios de aceite são texto livre

O deck confere que um critério foi marcado como aceito, comparando a string exata — não que ele foi cumprido. E uma tarefa vinda de um rastreador não carrega critério nenhum, então a guarda não tem o que segurar. O bundle diz isso em vez de silenciar: “the task declares no acceptance criteria, so nothing states what it was for”.

Onde o deck ainda não foi

Três coisas que nenhuma quantidade de teste substitui, e que dizem mais sobre a idade do projeto do que sobre o desenho:

O que é defeito ou lacuna acionável não mora nesta página — mora no issue tracker, onde pode ser discutido, priorizado e fechado. Uma página que lista pendências envelhece; um tracker é feito para isso.

Três coisas que são propriedade, não pendência

20.Estado do projeto#

A tabela abaixo separa o que foi construído e exercitado do que foi escrito e ainda não provado, e do que está desenhado e não construído. É a única distinção que importa para decidir se vale o seu tempo.

Quantas issues estão abertas, e de que tipo, está no tracker — que é onde isso vive e onde está sempre certo. Um número escrito aqui envelheceria sozinho, e um número errado numa página é pior que nenhum.

Como o projeto se verifica

O deck se verifica com o próprio mecanismo. São seis gates, em ordem de escada — commit-shape, lint, catalog, docs, smoke, tour — declarados em _workspaces/all/default/config/gates.yaml de deck-ai-packs:

./plugins/deck/bin/deck gate run --task <sua-branch>

A suíte constrói workspaces sintéticos em diretórios temporários, então roda em qualquer lugar e não toca em nada que seja seu:

$ ./ci/smoke.sh
-----------------------------------------------
711 checks, 0 failures

Número lido da execução, não de memória. É o total no commit em que esta página foi escrita.

Um dos seis gates é sobre esta documentação: ci/docs-cover.py reprova quando um documento nomeia um comando que a CLI não tem, quando a CLI tem um comando que documento nenhum nomeia, quando um documento aponta para um arquivo que não existe, ou quando um documento declara um total de checagens diferente do que a suíte tem. Foi escrito porque este projeto publicou um total errado quatro vezes num único dia de trabalho — é um número, é conferível, e pela regra do próprio projeto isso faz dele um gate e não um hábito.

As regras que o deck impõe a si mesmo

Elas moram em _workspaces/all/default/rules/ de deck-ai-packs e são o melhor retrato do que a ferramenta acredita:

• Nunca declare um número que você não mediu. Nada de “tipicamente três repositórios”, nada de porcentagem inventada. Se não foi contado, do código ou de uma execução, não entra.
• Diga o que não aconteceu. Um gate que nunca rodou é reportado, não omitido. Um stub é rotulado como stub. Um resultado parcial é parcial na primeira frase, não numa ressalva no fim.
• Comentários carregam a razão, não a repetição. Um comentário dizendo o que a próxima linha faz é ruído. Escreva o que um leitor não consegue recuperar: por que isto e não a alternativa óbvia, o que quebrou quando foi feito do outro jeito.
• Um defeito corrigido vem com a checagem que o teria pego, no mesmo commit — e a checagem tem de ser mostrada falhando sem a correção.
• Leia o código de saída, não o do pipe. cmd | tail -3; echo $? devolve o status do tail, que é sempre 0. Toda afirmação falsa de “sai com 0” na história deste repositório veio dessa linha.
• Nada de um workspace que não é seu para publicar. O deck é desenvolvido contra workspaces reais de empregadores e clientes; nada disso entra numa issue pública — nem nomes de organização ou produto, nem hostnames internos, chaves de projeto, ids de ticket ou nomes de usuário. Até o idioma conta: uma mensagem de erro no idioma errado identifica uma instância tão bem quanto um hostname.

21.É para você?#

O que fazer em seguida

1. Rode o tour. Ele constrói um workspace de quatro repositórios e um pack do zero num diretório temporário, e caminha de deck pack new até uma entrega verificada com a evidência em disco. Não precisa de configuração e não toca em nada que é seu.

   git clone https://github.com/devfilipe/deck.git ~/tools/deck
   ~/tools/deck/docs/tour.sh

2. Classifique o material que você já tem pelas quatro naturezas de §2. A maioria dos guias de estilo é três documentos em um: uma configuração de formatador que ninguém extraiu, um punhado de invariantes de verdade, e uma lista de decisões que nunca foram escritas como tal.
3. Mova tudo que é mecânico para gates primeiro. É a vitória mais barata e faz você parar de pagar contexto por isso.
4. Escreva as arestas. Sem elas o grafo não responde nada, e o grafo é o que um agente não consegue descobrir sozinho.
5. Estenda a escada toda vez que algo passar por ela. Um defeito que um gate não pegou é um gate que você ainda não tem. Este é o passo que importa ao longo de um ano: uma escada que nunca cresce é uma escada que mede menos a cada mês.

22.Casos de uso, com os comandos de cada um#

Sete situações que aparecem de verdade. Cada uma traz a sequência exata, e o que muda em relação às outras — porque o que separa os casos não é o comando, é a decisão que vem antes dele. Comece pelo caso 0 se o seu projeto ainda não usa deck.

0 · Trazer um projeto que não usa deck

O caso mais importante, e aquele em que quase todo mundo erra pela mesma razão: tenta escrever o pack inteiro antes de rodar qualquer coisa. Não escreva. O laço do caso 5 preenche o pack sozinho, tarefa a tarefa. O que você tem que fazer no primeiro dia é bem menos que parece.

Passo 1 — deixe o deck ler o que já existe.

   mkdir ~/work/xyz-ai-packs && git -C ~/work/xyz-ai-packs init

   cd ~/work/xyz                 ◄── a raiz onde seus repositórios já estão
   deck setup --packs-root ~/work/xyz-ai-packs/packs --create-packs

1  What is in this workspace?
     3 git repositories found:  api · web · worker

2  Where will the knowledge live?
     Creating a pack collection at ~/work/xyz-ai-packs/packs.

3  Writing the descriptor
     .../packs/_workspaces/xyz/default/workspace.yaml   ◄── versionado, é do time
     ~/.deck/workspaces/xyz/machine.yaml                ◄── só seu, nunca versionado

4  Linking packs to repositories, by name
     linked   api      .../packs/_repos/api
     linked   web      .../packs/_repos/web
     linked   worker   .../packs/_repos/worker
     shared   (every repository)   .../packs/_workspaces/xyz/default

5  What only you can fill in
     1. The `impacts` edges. A manifest declares a checkout, never a propagation.
     2. The `targets` allowlist.

O registro o deck deriva; ele lê repo, .gitmodules ou o campo workspaces de um package.json, e cai em “diretórios que são repositórios git” quando nenhum deles serve.

Passo 2 — as arestas. É a única coisa que ninguém deriva por você.

   # no descriptor: packs/_workspaces/<nome>/default/workspace.yaml
   repos:
     api:    { path: api,    impacts: [web] }   ◄── mudar api obriga a revisitar web
     web:    { path: web,    impacts: [] }
     worker: { path: worker, impacts: [] }

   deck impact api        ◄── confira que a cadeia é a que você tem na cabeça

Um manifesto declara um checkout, nunca uma propagação. Se você não tem certeza, deck propose impacts --repos api web rascunha — mas custa dinheiro e produz proposta, não edição.

Passo 3 — um gate que você já tem. Um, não seis.

   # em ~/work/xyz-ai-packs/packs/_workspaces/all/default/config/gates.yaml
   gates:
     - id: lint
       title: o lint que você já roda
       from_level: static
       per_repo: "npm run lint"        ◄── o comando que você já digita hoje

   deck gate run --task PRIMEIRA --level static

Isto é o primeiro valor real, e chega antes de qualquer regra existir: o comando que você já rodava agora deixa evidência em disco, por repositório, com o degrau alcançado dito em voz alta.

Passo 4 — versione a coleção, e só então convide alguém.

   cd ~/work/xyz-ai-packs && git add -A && git commit && git push

   # cada colega, uma vez:
   git clone <xyz-ai-packs>
   deck init            ◄── semeia o .deck/ da máquina dele
   deck doctor          ◄── e diz o que ainda falta na máquina dele

   dia 1     registro + arestas + 1 gate            ← o mínimo que dá valor
   dia 3     a IA errou algo duas vezes → 1ª regra
   semana 2  uma decisão que volta sempre → 1º toggle
   mês 2     um pack por repositório, com o que aquele repositório ensinou

   o pack cresce pelo uso, não pelo planejamento

1 · Corrigir um documento

O caso mais comum, e aquele em que a escada inteira é desperdício.

   deck mount --task DOC-3 --repos api --no-expand
        │      └─ --no-expand: um README não propaga; não arraste os vizinhos
        ▼
   (a sessão trabalha)
        ▼
   deck gate run --task DOC-3 --level static
        │      └─ lint e nada mais. O relatório DIZ que parou no static,
        │         então a decisão fica no registro
        ▼
   deck unmount --task DOC-3

Sem save: nada de conhecimento novo apareceu. Sem bundle: não há cadeia para um revisor reconstruir.

2 · Mudar um schema que três repositórios consomem

O caso para o qual o deck existe. A pergunta não é como mudar, é o que mais tem que mudar junto.

   deck impact api-schema        ◄── PRIMEIRO. Antes de tocar em qualquer coisa
   ┌────────────────────────────────────────────────────┐
   │ 1. api-schema   2. api-server   3. web-client       │
   │ 4. e2e-suite    (downstream — acompanha, não gera)  │
   └────────────────────────────────────────────────────┘
        ▼
   deck toggle ask-plan --stage plan
        │      └─ o que ainda precisa ser decidido, como perguntas prontas.
        │         Num contrato publicado, `api_compat` é uma delas
        ▼
   deck mount --task API-7 --repos api-schema --brief "campo `cursor` em /items"
        │      └─ SEM --no-expand: os quatro são montados, não um
        ▼
   (a sessão trabalha, na ordem que o impact deu)
        ▼
   deck gate run --task API-7 --level behavior
        │      └─ contrato publicado é o único caso em que "funciona"
        │         precisa ser medido contra o sistema rodando
        ▼
   deck save --task API-7   ·   deck bundle --task API-7   ·   deck unmount --task API-7

3 · Um hotfix, com a escada baixada de propósito

Produção caiu. Você vai cortar caminho — a questão é que o corte fique escrito.

   deck mount --task FIX-9 --repos api-server --brief "NPE em /items quando cursor é nulo"
        ▼
   deck gate run --task FIX-9 --level build
        │      └─ deliberadamente abaixo do padrão (deploy). O relatório
        │         registra o degrau alcançado; ninguém depois vai achar
        │         que estava verificado até o fim
        ▼
   deck bundle --task FIX-9
        │      └─ e o bundle DIZ o que não foi checado. É isso que
        │         transforma o atalho em decisão, e não em omissão
        ▼
   deck save --task FIX-9   ·   deck unmount --task FIX-9

4 · Entrar num time que já usa deck

Você clonou hoje. Não escreva nada — pergunte.

   git clone <os repos>   ·   git clone <o xyz-ai-packs>
        ▼
   deck init                     cria o .deck/ desta máquina, semeado do
        │                        template que a coleção traz
        ▼
   (preencher só três campos: packs_root · paths · targets)
        ▼
   deck doctor                   o que falta, e o comando que resolve cada coisa
   deck info                     o registry, os papéis, quem é downstream
   deck packs                    qual conhecimento se aplica, e em que ordem
   deck toggle list              o que já foi decidido, e de onde veio cada valor
   deck impact <qualquer repo>   o que uma mudança ali alcança

5 · A IA descobriu algo que o time deveria saber

O caso que faz a segunda tarefa custar menos que a primeira.

   (durante a sessão, a IA corrige uma regra errada, ou escreve uma nova)
        ▼
   deck doctor
   ┌──────────────────────────────────────────────────────────────┐
   │ !! API-7  unsaved: 1 edited, 1 written here —                │
   │           nothing in the collection holds them yet           │
   └──────────────────────────────────────────────────────────────┘
        ▼
   deck save --task API-7 --dry-run    ◄── SEMPRE isto antes, nas primeiras vezes:
        │                                  o save escreve no repositório do time
        ▼
   deck save --task API-7
   ┌──────────────────────────────────────────────────────────────┐
   │ saved  changed  <coll>/_workspaces/all/default/rules/estilo.md│
   │ saved  new      <coll>/_repos/api/rules/paginacao.md          │
   └──────────────────────────────────────────────────────────────┘
        ▼
   cd <xyz-ai-packs> && git diff        ◄── você revisa. É aqui que vira do time
   git commit

6 · Duas pessoas, ou dois agentes, ao mesmo tempo

O que impede duas pessoas de produzirem um merge que ninguém consegue revisar.

   deck board list               o que existe, e o que já tem dono
        ▼
   deck board claim T-14         ◄── a reivindicação vai para o RASTREADOR,
        │                            e é lida de volta. Já reivindicada
        │                            por outra pessoa, é recusada
        ▼
   deck board plan               o que pode rodar ao mesmo tempo sem colidir
   ┌──────────────────────────────────────────────────────────────┐
   │ grupo 1: T-14, T-19    (não se tocam)                        │
   │ grupo 2: T-16          (edita o mesmo repo que T-14)         │
   └──────────────────────────────────────────────────────────────┘
        ▼
   deck mount --task T-14 ...    cada tarefa tem o seu mount e o seu manifesto
        ▼
   deck board done T-14

23.Índice de comandos#

Os 33 comandos de primeiro nível. Sete deles têm subcomandos, somando 63 comandos executáveis ao todo. Cada um está explicado, com todas as suas opções, na seção que a última coluna aponta.

24.Os números desta página, e onde foram medidos#

A regra do projeto — nunca declare um número que você não mediu — vale para esta página também. Todo número aqui foi lido de uma execução ou contado do código, no commit em que ela foi escrita.

Todos os exemplos de saída marcados como “saída real” foram produzidos executando o comando: no tour (./docs/tour.sh --fast) ou num workspace sintético de três repositórios construído num diretório temporário para esta finalidade. Nomes de repositório, de tarefa e de host nos exemplos são inventados; qualquer coisa parecida com um endereço usa example.com.