Platform Model

O modelo de plataforma do looply define as entidades centrais, regras de validacao e fluxo de dados entre packs, hosts e CLI.

Entidades centrais

erDiagram
    PACK ||--o{ AGENT : contains
    PACK ||--o{ TASK : contains
    PACK ||--o{ WORKFLOW : contains
    PACK ||--o{ KNOWLEDGE : contains
    PACK ||--o{ TEMPLATE : contains
    PACK ||--o{ CHECKLIST : contains
    PACK ||--o{ RULE : contains
    PACK ||--o{ SQUAD : groups
    AGENT ||--o{ TASK : executes
    WORKFLOW ||--o{ STAGE : orchestrates
    STAGE ||--o{ TASK : invokes
    STAGE ||--o{ AGENT : delegates_to
    WORKFLOW ||--o{ GATE : validates
    WORKFLOW ||--o{ HANDOFF : transfers
    HOST ||--o{ SKILL : materializes
    FEATURE ||--o{ WORKFLOW : tracks

Regras de validacao

Naming

• Artefatos usam kebab-case: pm-analyst, idea-to-prd
• Schemas usam @v<major>: looply/agent@v1
• Packs sao identificados por diretorio e pack.md

Frontmatter obrigatorio

Todo artefato Markdown declara:

schema: looply/<tipo>@v1
name: <kebab-case>
summary: <descricao curta>

Imutabilidade de contrato

• Schemas sao versionados (@v1, @v2)
• Breaking changes exigem novo schema major
• Additions sao backward-compatible no mesmo major

Port and Adapters

┌─────────────────────────────────────────────┐
│                   CLI                        │
│  install  sync  validate  doctor  upgrade   │
└──────────────────┬──────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│ Codex  │  │ Claude   │  │ OpenCode │
│ Adapter│  │ Adapter  │  │ Adapter  │
└────────┘  └──────────┘  └──────────┘
    │              │              │
    ▼              ▼              ▼
 AGENTS.md    CLAUDE.md     AGENTS.md
 .agents/     .claude/      .agents/
 skills/      commands/     skills/
                            .opencode/

Storage Model

.looply/ — Raiz de estado

.looply/
├── managed/packs/          # Copias gerenciadas dos packs
├── custom/
│   ├── features/           # Estado por feature
│   └── integrations/       # Contexto de integracoes
└── state/                  # Estado operacional
    ├── project-context.json
    ├── interaction-policy.json
    ├── locale.json
    ├── code-context.json
    ├── knowledge-graph.json
    └── install-manifest.json

Feature state

.looply/custom/features/<feature>/
├── workflow-control.json   # Estado da maquina de workflow
├── workflow-status.md      # Status legivel por humanos
├── context-ledger.db       # SQLite append-only
└── artifacts/              # Outputs de stages

Sync Model

1. Install: le artefatos do pack fonte, publica nos hosts, extrai contexto
2. Sync: atualiza managed packs com mudancas da fonte, republica
3. Upgrade: atualiza versao do pack, reconcilia estado
4. Doctor: diagnostica inconsistencia entre fonte, managed e host

Cross-cutting

• Context Ledger: append-only por feature, entradas estruturadas por stage
• Knowledge Graph: nos e arestas de codigo, banco e features
• Session Links: vincula sessao, feature e ultimo comando
• Context Slots: pre-composicao de prompt por agente (inline vs reference)