~/Projects

Construir para aprender — usar o que aprendeu no learning e extrair skills da pratica.

sysadmin@srv-hermes
·
learning projects skills agents

Da observacao pra pratica: utilizando as tecnologias do learning system pra construir projetos reais, e por que construir ensina mais do que ler.

~/Projects

O learning system resolve o problema de entrada. O agente estuda o repo, entende a arquitetura, extrai os patterns. Se o agente nunca usa o que aprendeu, o conhecimento fica dormente.

A segunda camada veio dessa constatacao: se o agente aprendeu sobre Typesense no learning, ele deveria construir algo com Typesense. Nao esperar o projeto perfeito chegar. Construir agora, errar agora, extrair a skill agora.

A ideia

Dois diretorios, dois propositos:

~/learning/          <- Onde o agente absorve (repos open-source, diffs, estudo)
~/projects/          <- Onde o agente constroi (projetos proprios, integracoes, experimentos)

O learning e input. O project e output. O ciclo:

graph LR
    A[Learning] -->|tech estudada| B[Project]
    B -->|construcao real| C[Skill extraida]
    C -->|ferramenta reutilizavel| A
    C -->|ferramenta reutilizavel| B

Diferenca fundamental: o learning extrai skills de diffs — o que mudou no repo, o que os commits dizem. O project extrai skills de construcao — o que funcionou, o que quebrou, o que o tutorial nao conta. Sao tipos diferentes de conhecimento. O diff e teoria. O build e pratica.

Construcao como aprendizado

Quando o agente estuda o repo do Temporal no learning, ele entende workflows, activities, task queues. Sabe os conceitos. Mas so quando constroi um workflow pro DOU Digest que ele descobre que o retry policy precisa de backoff exponencial, que a activity timeout e diferente de workflow timeout, e que o schedule-to-close silencioso e o bug mais dificil de rastrear.

Nenhum diff ensina isso. So a construcao ensina.

O projeto nao precisa ser grande. Um docker-compose com Typesense, um endpoint Go que faz search, um worker que processa JSON. O tamanho nao importa — o que importa e que o agente esta usando a tecnologia de verdade, contra requisitos reais, com erros reais.

Estrutura

Cada projeto segue o mesmo padrao de contrato do learning:

~/projects/<nome>/
  AGENTS.md          <- Contrato: stack, build, deploy, convencoes
  docker-compose.yml <- Infra (quando aplicavel)
  SKILL.md           <- Skill extraida da construcao (quando pronta)

O AGENTS.md e o hook. O agente entra no projeto, le o contrato, e sabe tudo que precisa: qual linguagem, qual framework, como buildar, como deployar, quais decisoes ja foram tomadas. Nao pergunta. Aja.

A SKILL.md e a saida. Quando o projeto esta maduro o suficiente, o agente extrai o que aprendeu numa skill reutilizavel. Essa skill vai pro toolbox do Hermes e pra collection do skills-blackhole. O proximo projeto que usar a mesma tecnologia ja parte com o conhecimento acumulado.

Fluxo de extracao

Nao e automatico. O agente precisa de um gatilho — ou eu peço, ou a rotina diaria identifica que o projeto teve atividade significativa. O processo:

  1. Analisar o que foi construido — commits recentes, mudancas na stack, problemas resolvidos

  2. Classificar o conhecimento — e um pattern de arquitetura? Um workflow de deploy? Um workaround de API?

  3. Extrair a skill — contrato executavel com goal, scope, procedure, review gate

  4. Validar contra o existente — ja tem skill similar? Complementa ou substitui?

  5. Publicar — salva no Hermes e, se maduro o suficiente, no skills-blackhole

O learning system ja tem esse fluxo de extracao. A diferenca e a fonte: no learning, o agente extrai de diffs alheios. No projects, ele extrai de erros proprios. E mais valioso. O project system e essa partida. E onde o agente descobre que a documentacao mente, que o tutorial omite, e que a unica forma de realmente entender uma tecnologia e usa-la.

Referencia

# Companies — AI Company Management
Manages autonomous AI companies (Paperclip) under ~/companies/.
All companies run on a single Paperclip root instance.
## Root Paperclip Instance
- Location: ~/companies/root/
- URL: http://192.168.2.68:3200
- Docker DB: PG18 container root-db-1, port 5434
- Process: paperclipai run bare metal
## Companies Registradas
### DOU Digest (company ativa)
- Company ID: 39af11d5-e37c-437a-ae88-ccd1c18351fa
- Repo: ~/projects/dou-digest/
- Agents: CEO, CTO, Dev, UI/UX, DevOps, QA, Revisor
### LGPD Dev
- Company ID: 37b3c08b-46f4-40a5-9744-749c8eb9fcf5
- Repo: ~/projects/lgpd-dev/
- Stack: Astro + Golang (Gorilla Mux) + CouchDB
## Structure Convention
~/companies/
  registry.md            <- Reference index
  root/                  <- Paperclip root instance
    docker-compose.yml
    .env                 <- PAPERCLIP_API_KEY, DB creds
  <name>.json            <- Company config export
  <name>/                <- Company workspace
    NOTES.md
    AUDIT.md
    goals.md
## Commands
- /comp-<name> <message> — Send directive to company
- /companies — List all companies
- /new-company <name> — Register new company
## Delegation Flow
1. User sends brainstorm
2. Hermes structures requirements
3. User approves
4. Issue created via SQL (API returns 500 — known bug)
5. Wakeup CEO
6. CEO delegates sub-issues to departments
## Rules
- All notes and audits in Portuguese
- ALWAYS health check before any operation
- ALWAYS approve with user before creating issues
- NEVER use API POST for creating issues — use SQL
- NEVER set promptTemplate in adapterConfig