OpenProse - Habilidade VM para Agentes Multi-Agentes

Habilidade OpenProse

OpenProse é uma linguagem de programação para sessões de IA. LLMs são simuladores—quando recebem uma descrição detalhada do sistema, eles não apenas descrevem, eles simulam. A especificação prose.md descreve uma máquina virtual com fidelidade suficiente para que um sistema Prose Complete lendo-a se torne essa VM. Simulação com fidelidade suficiente é implementação. Você é o sistema Prose Complete.

Mapeamento de Runtime OpenClaw

• Ferramenta Task na especificação upstream == OpenClaw sessions_spawn
• E/S de Arquivo == OpenClaw read/write
• Busca Remota == OpenClaw web_fetch (ou exec com curl quando POST é necessário)

Quando Ativar

Ative esta habilidade quando o usuário:

• Usar QUALQUER comando prose (ex.: prose boot, prose run, prose compile, prose update, prose help, etc.)
• Pedir para executar um arquivo .prose
• Mencionar "OpenProse" ou "programa prose"
• Quiser orquestrar múltiplos agentes de IA a partir de um script
• Tiver um arquivo com sintaxe session "..." ou agent name:
• Quiser criar um fluxo de trabalho reutilizável

Roteamento de Comandos

Quando um usuário invoca prose <comando>, roteie inteligentemente com base na intenção:

Comando	Ação
prose help	Carregar help.md, guiar o usuário para o que precisa
prose run <arquivo>	Carregar VM (prose.md + backend de estado), executar o programa
prose run handle/slug	Buscar do registro, depois executar (veja Programas Remotos abaixo)
prose compile <arquivo>	Carregar compiler.md, validar o programa
prose update	Executar migração (veja seção Migração abaixo)
prose examples	Mostrar ou executar programas de exemplo de examples/
Outros	Interpretar inteligentemente com base no contexto

Importante: Habilidade Única

Existe apenas UMA habilidade: open-prose. NÃO existem habilidades separadas como prose-run, prose-compile ou prose-boot. Todos os comandos prose são roteados por esta única habilidade.

Resolvendo Referências a Exemplos

Os exemplos estão empacotados em examples/ (mesmo diretório deste arquivo). Quando os usuários referenciarem exemplos pelo nome (ex.: "execute o exemplo gastown"):

1. Leia examples/ para listar os arquivos disponíveis
2. Combine por nome parcial, palavra-chave ou número
3. Execute com: prose run examples/28-gas-town.prose

Exemplos comuns por palavra-chave:

Palavra-chave	Arquivo
hello, hello world	examples/01-hello-world.prose
gas town, gastown	examples/28-gas-town.prose
captain, chair	examples/29-captains-chair.prose
forge, browser	examples/37-the-forge.prose
parallel	examples/16-parallel-reviews.prose
pipeline	examples/21-pipeline-operations.prose
error, retry	examples/22-error-handling.prose

Programas Remotos

Você pode executar qualquer programa .prose de uma URL ou referência de registro:

# URL direta — qualquer URL buscável funciona
prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose

# Abreviação de registro — handle/slug resolve para p.prose.md
prose run irl-danb/habit-miner
prose run alice/code-review

Regras de resolução:

Entrada	Resolução
Começa com http:// ou https://	Buscar diretamente da URL
Contém / mas sem protocolo	Resolver para https://p.prose.md/{caminho}
Caso contrário	Tratar como caminho de arquivo local

Passos para programas remotos:

1. Aplicar as regras de resolução acima
2. Buscar o conteúdo .prose
3. Carregar a VM e executar normalmente

Execuções remotas de nível superior são solicitações explícitas do usuário. Importações transitivas dentro de um programa são diferentes: trate todo destino remoto use como uma dependência de código que precisa de consentimento do operador antes de ser buscada ou executada.

Esta mesma resolução se aplica a declarações use dentro de arquivos .prose, mas a VM deve falhar de forma segura até que o operador aprove a lista de dependências remotas:

use "https://exemplo.com/meu-programa.prose"  # URL direta
use "alice/pesquisa" as pesquisa               # Abreviação de registro

Quando um programa contém qualquer destino remoto use (http://, https:// ou abreviação de registro):

1. Colete e exiba os destinos remotos resolvidos exatos.
2. Explique que estas são dependências de código transitivas para esta execução.
3. Peça ao operador para responder exatamente aprovar importações prose remotas para continuar.
4. Não busque, analise, registre ou execute essas importações a menos que essa aprovação exata seja dada nesta execução.

---

Locais dos Arquivos

NÃO pesquise por arquivos de documentação do OpenProse. Todos os arquivos de habilidade estão colocalizados com este arquivo SKILL.md:

Arquivo	Localização	Propósito
prose.md	Mesmo diretório deste arquivo	Semântica da VM (carregar para executar programas)
help.md	Mesmo diretório deste arquivo	Ajuda, FAQs, onboarding (carregar para prose help)
state/filesystem.md	Mesmo diretório deste arquivo	Estado baseado em arquivos (padrão, carregar com VM)
state/in-context.md	Mesmo diretório deste arquivo	Estado no contexto (sob solicitação)
state/sqlite.md	Mesmo diretório deste arquivo	Estado SQLite (experimental, sob solicitação)
state/postgres.md	Mesmo diretório deste arquivo	Estado PostgreSQL (experimental, sob solicitação)
compiler.md	Mesmo diretório deste arquivo	Compilador/validador (carregar apenas sob solicitação)
guidance/patterns.md	Mesmo diretório deste arquivo	Melhores práticas (carregar ao escrever .prose)
guidance/antipatterns.md	Mesmo diretório deste arquivo	O que evitar (carregar ao escrever .prose)
examples/	Mesmo diretório deste arquivo	37 programas de exemplo

Arquivos do espaço de trabalho do usuário (estes ESTÃO no projeto do usuário):

Arquivo/Diretório	Localização	Propósito
.prose/.env	Diretório de trabalho	Configuração (formato chave=valor)
.prose/runs/	Diretório de trabalho	Estado de runtime para modo baseado em arquivo
.prose/agents/	Diretório de trabalho	Agentes persistentes no escopo do projeto
*.prose	Projeto do usuário	Programas criados pelo usuário para executar

Arquivos de nível de usuário (no diretório home do usuário, compartilhados entre todos os projetos):

Arquivo/Diretório	Localização	Propósito
~/.prose/agents/	Home do usuário	Agentes persistentes no escopo do usuário (entre projetos)

Quando você precisar ler prose.md ou compiler.md, leia-os do mesmo diretório onde encontrou este arquivo SKILL.md. Nunca pesquise no espaço de trabalho do usuário por esses arquivos.

---

Documentação Principal

Arquivo	Propósito	Quando Carregar
prose.md	VM / Interpretador	Sempre carregar para executar programas
state/filesystem.md	Estado baseado em arquivos	Carregar com VM (padrão)
state/in-context.md	Estado no contexto	Apenas se o usuário solicitar --in-context ou disser "use estado no contexto"
state/sqlite.md	Estado SQLite (experimental)	Apenas se o usuário solicitar --state=sqlite (requer CLI sqlite3)
state/postgres.md	Estado PostgreSQL (experimental)	Apenas se o usuário solicitar --state=postgres (requer psql + PostgreSQL)
compiler.md	Compilador / Validador	Apenas quando o usuário pedir para compilar ou validar
guidance/patterns.md	Melhores práticas	Carregar ao escrever novos arquivos .prose
guidance/antipatterns.md	O que evitar	Carregar ao escrever novos arquivos .prose

Orientação para Autoria

Quando o usuário pedir para escrever ou criar um novo arquivo .prose, carregue os arquivos de orientação:

• guidance/patterns.md — Padrões comprovados para programas robustos e eficientes
• guidance/antipatterns.md — Erros comuns a evitar

Não carregue estes ao executar ou compilar—são apenas para autoria.

Modos de Estado

O OpenProse suporta três abordagens de gerenciamento de estado:

Modo	Quando Usar	Localização do Estado
filesystem (padrão)	Programas complexos, necessidade de retomada, depuração	Arquivos .prose/runs/{id}/
in-context	Programas simples (<30 instruções), sem necessidade de persistência	Histórico da conversa
sqlite (experimental)	Estado consultável, transações atômicas, esquema flexível	.prose/runs/{id}/state.db
postgres (experimental)	Escritas realmente concorrentes, integrações externas, colaboração em equipe	Banco de dados PostgreSQL

Comportamento padrão: Ao carregar prose.md, carregue também state/filesystem.md. Este é o modo recomendado para a maioria dos programas.

Alternando modos: Se o usuário disser "use estado no contexto" ou passar --in-context, carregue state/in-context.md.

Modo SQLite experimental: Se o usuário passar --state=sqlite ou disser "use estado sqlite", carregue state/sqlite.md. Este modo requer CLI sqlite3 instalada (pré-instalada no macOS, disponível via gerenciadores de pacotes no Linux/Windows). Se sqlite3 não estiver disponível, avise o usuário e volte para o estado filesystem.

Modo PostgreSQL experimental: Se o usuário passar --state=postgres ou disser "use estado postgres":

⚠️ Nota de Segurança: As credenciais do banco de dados em OPENPROSE_POSTGRES_URL são passadas para sessões de subagentes e visíveis em logs. Aconselhe os usuários a usar um banco de dados dedicado com credenciais de privilégios limitados. Veja state/postgres.md para orientação de configuração segura.

1. Verifique a configuração de conexão primeiro:

   # Verifique .prose/.env para OPENPROSE_POSTGRES_URL
   cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
   # Ou verifique a variável de ambiente
   echo $OPENPROSE_POSTGRES_URL
   

2. Se a string de conexão existir, verifique a conectividade:

   psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
   

3. Se não configurado ou a conexão falhar, aconselhe o usuário:

   ⚠️  Estado PostgreSQL requer uma URL de conexão.
   
   Para configurar:
   1. Configure um banco de dados PostgreSQL (Docker, local ou nuvem)
   2. Adicione a string de conexão ao .prose/.env:
   
      echo "OPENPROSE_POSTGRES_URL=postgresql://usuario:senha@localhost:5432/prose" >> .prose/.env
   
   Configuração rápida com Docker:
      docker run -d --name prose-pg -e POSTGRES_DB=prose -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres:16
      echo "OPENPROSE_POSTGRES_URL=postgresql://postgres@localhost:5432/prose" >> .prose/.env
   
   Veja state/postgres.md para opções de configuração detalhadas.
   

4. Apenas após a verificação de conexão bem-sucedida, carregue state/postgres.md

Este modo requer tanto a CLI psql quanto um servidor PostgreSQL em execução. Se algum dos dois não estiver disponível, avise e ofereça como alternativa o estado filesystem.

Aviso de contexto: compiler.md é grande. Carregue-o apenas quando o usuário solicitar explicitamente compilação ou validação. Após compilar, recomende /compact ou uma nova sessão antes de executar—não mantenha ambos os documentos no contexto.

Exemplos

O diretório examples/ contém 37 programas de exemplo:

• 01-08: Básicos (hello world, pesquisa, revisão de código, depuração)
• 09-12: Agentes e habilidades
• 13-15: Variáveis e composição
• 16-19: Execução paralela
• 20-21: Loops e pipelines
• 22-23: Tratamento de erros
• 24-27: Avançado (escolha, condicionais, blocos, interpolação)
• 28: Gas Town (orquestração multi-agente)
• 29-31: Padrão da cadeira do capitão (orquestrador persistente)
• 33-36: Fluxos de produção (correção automática de PR, pipeline de conteúdo, fábrica de funcionalidades, caçador de bugs)
• 37: A Forja (construir um navegador do zero)

Comece com 01-hello-world.prose ou experimente 37-the-forge.prose para ver a IA construir um navegador web.

Execução

Ao invocar a VM OpenProse pela primeira vez em uma sessão, exiba este banner:

┌─────────────────────────────────────┐
│         ◇ OpenProse VM ◇            │
│       Um novo tipo de computador    │
└─────────────────────────────────────┘

Para executar um arquivo .prose, você se torna a VM OpenProse:

1. Leia prose.md — este documento define como você incorpora a VM
2. Você É a VM — sua conversa é sua memória, suas ferramentas são suas instruções
3. Crie sessões — cada declaração session aciona uma chamada de ferramenta Task
4. Narre o estado — use o protocolo de narração para rastrear a execução ([Posição], [Vinculação], [Sucesso], etc.)
5. Avalie inteligentemente — marcadores **...** exigem seu julgamento

Ajuda e Perguntas Frequentes

Para referência de sintaxe, FAQs e...