Publishing Model

O modelo de publicacao descreve como o looply materializa artefatos Markdown no formato nativo de cada host.

Principio geral

O looply publica o contrato. O host executa.

Os artefatos sao canonico em Markdown com frontmatter. A camada de publicacao traduz para o formato que cada host entende nativamente — skills, comandos, hints e arquivos de superficie.

Fluxo de publicacao

sequenceDiagram
    participant Pack as Packs/Artifacts
    participant CLI as looply CLI
    participant Host as Host Adapter
    
    Pack->>CLI: Le artefatos Markdown
    CLI->>CLI: Valida contratos
    CLI->>CLI: Extrai contexto do codebase
    CLI->>CLI: Resolve context_slots inline
    CLI->>Host: Materializa formato nativo
    Host->>Host: Gera arquivos de superficie

Comandos

install

Instala o pack no projeto ou globalmente.

looply install --host codex,claude,opencode --scope project --pack software-delivery-suite

Fases:

1. Le artefatos do pack fonte (packs/)
2. Copia para managed ( .looply/managed/packs/)
3. Detecta hosts ativos
4. Publica no formato nativo de cada host
5. Extrai contexto do codebase
6. Gera estado operacional

sync

Sincroniza mudancas do pack fonte para managed.

looply sync --host codex,claude,opencode --scope project

• Re-le artefatos fonte
• Atualiza managed packs
• Republica nos hosts
• Preserva customizacoes locais

upgrade

Atualiza para nova versao do pack.

looply upgrade --host codex,claude,opencode --scope project

• Busca nova versao do pack
• Aplica mudancas em managed
• Reconcilia estado de features
• Republica nos hosts

doctor

Diagnostica inconsistencia.

looply doctor --host codex,claude,opencode --scope project

Verifica:

• Manifesto de instalacao consistente
• Entrypoints presentes para cada host
• Managed packs sincronizados com fonte
• Estado de features valido

Ownership de arquivos

O looply classifica arquivos em tres categorias:

Categoria	Diretorio	Comportamento
Managed	.looply/managed/	Gerenciado pelo looply, sobrescrito em sync/upgrade
Mergeable	.agents/skills/, .claude/commands/	Publicado pelo looply, mergeavel com customizacoes
Custom	.looply/custom/	Criado pelo usuario ou workflow, nunca sobrescrito

Formatos por host

Codex

Artefato	Arquivo
Instrucoes de projeto	AGENTS.md
Indice de comandos	LOOPLY_COMMANDS.md
Skills	.agents/skills/<name>/SKILL.md
Help files	.looply/state/commands/codex/looply:<name>.md

Cada skill em .agents/skills/ inclui:

• Frontmatter com context_slots resolvidos inline
• Secao Composed Agent Context com constraints, knowledge e rules
• Corpo do agente com instrucoes operacionais

Claude Code

Artefato	Arquivo
Instrucoes de projeto	CLAUDE.md
Slash commands	.claude/commands/looply:<name>.md

OpenCode

Artefato	Arquivo
Instrucoes de projeto	AGENTS.md
Indice de comandos	OPENCODE_COMMANDS.md
Skills	.agents/skills/<name>/SKILL.md
Slash commands	.opencode/commands/looply:<name>.md

OpenCode compartilha o formato de skills com Codex, mas publica comandos no diretorio nativo .opencode/commands/.

Contexto pre-composto

Durante sync e install, o looply pre-compoe contexto estatico nos skills:

• Inline: constraints, knowledge sources, escalation rules e project rules sao lidos dos artefatos e injetados diretamente no SKILL.md
• Reference: outputs de stages anteriores e feature context sao listados como referencias que o host resolve em runtime

Isso reduz o overhead de leitura do host — em vez de 6+ leituras para descobrir constraints, knowledge e rules, o agente recebe tudo composto no prompt.

Exemplo: skill publicado para Codex

---
name: architect
role: Solution design and technical decision making
hosts: [codex, claude, opencode]
---

## Composed Agent Context

### Constraints
- Do not invent business rules
- Validate assumptions against codebase

### Knowledge
(conteudo de architecture-principles.md)

### Project Rules
- architecture-constraints: Prefer stateless services

### Escalation
- Escalate structural ambiguity to pm-analyst

## Instructions
...

## Runtime References
- stage.inputs: story, prd
- feature: pix-webhook-retry
- workflow.ledger: context-ledger.db