Composição de bundles

Bundles são a resposta arquitetural para “usuários não querem compor 35 skills na mão”. Um bundle é um pacote curado de skills + roles + rules + (opcionalmente) hooks, escopado a um arquétipo de time — starter para a fundação, quality para times que entregam para usuários pagantes, docs para times que investem em documentação, etc. O wizard do Quick mode mapeia algumas respostas sim/não para bundles; usuários nunca precisam memorizar o catálogo de skills.

O que tem em um arquivo de bundle

name: quality
description: Pre-merge audit gates + senior-reviewer discipline
skills:
  - audit-all
  - audit-contracts
  - refactor-deepen
  - audit-config
roles:
  - architect
rules: []

É isso. Bundles são pura composição — eles referenciam primitivos pelo nome, não adicionam conteúdo novo próprio. A composição é o valor.

Expansão para listas planas

Quando octopus setup lê .octopus.yml e vê bundles: [starter, quality], ele expande cada bundle e faz a união dos resultados:

starter:    skills: [implement, debug, ...] roles: [...] rules: [common]
quality:    skills: [audit-all, audit-contracts, ...] roles: [architect]
                            │
                            ▼ union (dedup by name)
effective:  skills: [implement, debug, audit-all, ...] roles: [...] rules: [common]

A expansão produz uma única lista plana por categoria. Referências duplicadas (o mesmo skill em dois bundles) colapsam para uma entrada. O manifest do usuário também pode adicionar skills individuais por cima, que se unem na mesma lista.

Dependências transitivas

Alguns skills declaram dependências de outros skills via frontmatter:

# skills/audit-all/SKILL.md
---
name: audit-all
depends_on:
  - audit-security
  - audit-money
  - audit-tenant
  - audit-contracts
---

Quando audit-all acaba na lista efetiva (via qualquer bundle ou seleção explícita), o resolvedor de dependências adiciona as quatro auditorias também. Isso mantém bundles pequenos: quality.yml lista apenas audit-all porque o frontmatter de audit-all puxa as quatro auditorias automaticamente.

Ciclos são proibidos — o resolvedor falha no momento do setup com um erro claro em vez de entrar em loop silenciosamente.

A regra “sem skills soltos”

Todo skill novo deve pertencer a pelo menos um bundle. A regra existe porque skills que não estão em nenhum bundle são efetivamente inalcançáveis via octopus setup — eles estão no catálogo, mas ninguém os recebe. O comando scaffold-skill aplica a regra no momento da criação, recusando-se a scaffoldar um skill sem escolher um bundle (ou propor um novo).

A regra é uma disciplina contra skills órfãos, não contra especialização. Se um skill não se encaixa em nenhum bundle atual, a resposta certa geralmente é um novo bundle (ou um pequeno como growth); a resposta errada é um skill que ninguém encontra.

Compondo múltiplos bundles

O setup padrão do Octopus usa vários bundles juntos:

bundles:
  - starter          # the foundation
  - quality          # audits for SaaS
  - docs             # documentation lifecycle
  - backend          # backend patterns and dba role
  - stack-csharp     # auto-detected: dotnet skill + C# rules
  - db-mssql         # auto-detected: dba-mssql skill

A composição é associativa — a ordem não importa para a lista efetiva. A ordem importa para rules/, onde entradas posteriores sobrescrevem as anteriores (é assim que language.local.md funciona para overrides de rules por projeto), mas isso é um detalhe de carregamento de rules, não uma questão de composição de bundles.

Dois eixos: intent bundles e perfis

O catálogo de bundles tem dois eixos distintos.

Intent bundles respondem “que tipo de trabalho esse repo faz?” São pacotes curados escopados a um arquétipo de time — starter, backend, fullstack, quality, docs, growth, tech-lead. Você os escolhe explicitamente no setup.

Perfis respondem “que linguagem e banco de dados esse repo usa?” São bundles com categoria específica que o octopus setup auto-detecta a partir do repo e pré-seleciona no seletor interativo. Você também pode defini-los explicitamente com --stack ou --bundle.

Perfis de stack

Perfil	Skill(s)	Sinal de detecção
`stack-csharp`	`dotnet` + rules de C#	`.csproj` ou `.sln`
`stack-typescript`	rules de TypeScript	`package.json` + `tsconfig` ou `*.ts(x)`
`stack-python`	rules de Python	`pyproject.toml` ou `requirements.txt`

Perfis de banco de dados

Cada perfil de banco de dados carrega exatamente uma skill dba-* específica de engine. A role dba (do backend ou fullstack) despacha os perfis instalados.

Perfil	Skill	Sinal de detecção
`db-mssql`	`dba-mssql`	`Microsoft.Data.SqlClient` nos manifests
`db-postgres`	`dba-postgres`	`Npgsql`, `psycopg` ou `"pg"` nos manifests
`db-mongodb`	`dba-mongodb`	`MongoDB.Driver`, `mongoose` ou `pymongo`
`db-redis`	`dba-redis`	`StackExchange.Redis`, `ioredis` ou `redis-py`

Um repo C# + SQL Server recebe stack-csharp e db-mssql auto-selecionados — nunca os outros três perfis de banco de dados.

Outros bundles

Bundle	Propósito
`workflow-extras`	Skills de workflow opt-in (`map-system`, `delegate`) removidas do `starter`
`knowledge`	Knowledge loop: `knowledge-hygiene`, `knowledge-synthesize`, `knowledge-briefing`

Quick mode vs Full mode

octopus setup usa o Quick mode por padrão: 4–6 perguntas sim/não mapeiam para bundles (“Você está em um SaaS com billing?” → sim adiciona quality, “Esse é um projeto com muita documentação?” → sim adiciona docs). O wizard esconde o catálogo de bundles inteiramente. Perfis de stack e banco de dados são pré-selecionados automaticamente — você confirma ou desmarca antes de qualquer escrita.

O Full mode é para usuários que querem controle por componente — escolher skills específicos, excluir membros de bundle, conjuntos de rules customizados. O Full mode raramente é necessário; bundles cobrem as formas comuns.

Fonte: bundles/