AI-Dotfiles

Repositorio-sugestao para estudar, adaptar e montar um harness portatil para agentes de coding com Claude, OpenCode e PI.

Ele foi pensado como ponto de partida para programadores em inicio de jornada: voce pode usar o que fizer sentido, ignorar o que for complexo demais por enquanto e evoluir o setup aos poucos.

Para quem este repo serve

• quem esta comecando e quer um exemplo concreto de como organizar rules, skills, hooks, templates e adapters
• quem quer aprender como instalar e versionar um setup compartilhado sem misturar segredos e estado local no repositório
• quem prefere partir de uma base opinativa, mas editavel, em vez de um framework fechado

Quero instalar

Prerequisito: go no PATH para o install.sh delegar ao CLI em tools/installer/.

1. comece por QUICKSTART.md
2. rode ./install.sh all --tool all --project /caminho/do/projeto
3. explore docs/install/ para entender e adaptar cada target no seu ritmo

Quero contribuir

1. leia CONTRIBUTING.md
2. use docs/README.md como índice de navegação
3. rode go test ./... e bash tests/smoke/all.sh

O que este repositorio busca organizar

• oferecer um exemplo legivel de como versionar policy, rules, hooks, skills, templates e adapters
• explicitar guides, sensors, profiles e query loop sem depender de conhecimento escondido fora do repo
• separar material publicavel de estado operacional, caches, historicos e segredos
• instalar por symlink por padrao, com fallback para copy, para facilitar estudo e adaptacao local
• fazer merge idempotente de configuracoes por ferramenta sem exigir uma stack pesada de dependencias

Fluxo

flowchart LR
  Repo[Repo AI-Dotfiles] --> Installer[install.sh]
  Installer --> GoCLI[tools/installer]
  GoCLI --> Home[Home do usuário]
  GoCLI --> Project[Projeto bootstrapado]
  Home --> Claude[Claude carrega harness]
  Home --> OpenCode[OpenCode carrega harness]
  Home --> PI[PI carrega harness]

Loading

Estrutura

.
├── cmd/
│   └── ai-dotfiles/
├── docs/
├── examples/
├── features/
├── shared/
│   └── core/
├── targets/
│   ├── claude/
│   ├── opencode/
│   └── pi/
├── tests/
│   └── smoke/
├── go.mod
├── install.sh
└── QUICKSTART.md

Installer

• o núcleo do installer agora vive em tools/installer/
• install.sh continua sendo o entrypoint estável para uso local e docs
• install.sh agora exige go disponível no ambiente
• contribuidores podem validar o binário com go build ./tools/installer

Se voce estiver aprendendo, vale olhar primeiro para install.sh e depois para tools/installer/: o shell ficou como uma casca fina, enquanto a logica principal passou a viver em Go de forma mais facil de testar.

Fluxo de instalação

./install.sh install-shared --tool all
./install.sh merge-target --tool all
./install.sh bootstrap-project --project /caminho/do/projeto

Ou em uma passada:

./install.sh all --tool all --project /caminho/do/projeto

Use --sync strict quando quiser sincronização mais rígida no modo copy.

Exemplos visíveis

• QUICKSTART.md mostra output real do ./install.sh all e o diff antes/depois do bootstrap
• examples/ contém exemplos sanitizados de configs locais
• targets/*/README.md resume o merge e os assets reais de cada adapter

Validação

• go test ./... valida build e contratos básicos do installer Go
• bash tests/smoke/all.sh valida hooks, banner do PI, statusline e o installer fim a fim
• GitHub Actions roda smoke tests em ubuntu-latest e macos-latest
• GitHub Actions roda shellcheck e yamllint
• integrações reais com binaries externos de Claude, OpenCode e PI continuam fora do gate automático

Checklist manual para integrações reais:

1. instalar o target real em diretório temporário com ./install.sh all --tool <tool> --project <dir>
2. abrir o harness real correspondente e confirmar que a configuração gerada carrega sem erro
3. exercitar a superfície principal do adapter alterado no corte atual
4. registrar o resultado manual na feature ou no PR quando a mudança tocar contratos reais do adapter

Garantias

• a suíte smoke valida install-shared, merge-target, bootstrap-project e all
• o gate automático cobre statusline, hooks, banner do PI, merge idempotente e bootstrap de projeto
• o gate automático cobre o contrato público de --mode copy --sync strict e um rerun idempotente do fluxo all

Não-garantias

• o gate automático não cobre windows-latest
• o gate automático não valida integrações reais com os harnesses/binários externos de Claude, OpenCode e PI
• o gate automático não substitui a validação manual quando a mudança toca contratos reais do adapter ou comportamento carregado pelo software externo

Targets v1

Target	Escopo	Status
Claude	hooks, skills, statusline, fragments de settings	oficial
OpenCode	instructions, commands, plugins, merge de config	oficial
PI	settings, skills, prompts, extensões mínimas	oficial

Referência rápida

• QUICKSTART.md e a melhor primeira leitura pratica
• docs/README.md organiza a documentacao por assunto
• docs/harness/ explica o control plane do repo e a relacao entre core e adapters
• docs/reference/ resume o modelo de merge e extensao de cada harness
• docs/publishing/sanitization.md mostra o que pode ou nao ir ao repo
• shared/core/templates/project/ mostra o esqueleto de projeto que o bootstrap gera