Como usar um agente pra estudar repos open-source de forma estruturada — filesystem como contexto, contratos como instrucao, e diffs como combustivel.

~/Learning

Eu acredito que para um agente ser eficiente, a primeira coisa e fazer o onboarding dele. Ensinar sobre o projeto, os padroes, os limites. Sem isso, cada sessao comeca do zero — o agente descobre a estrutura, acha os comandos, entende as convencoes, e na proxima sessao faz tudo de novo.

A primeira tarefa dada ao Hermes foi exatamente essa: aprender. Nao construir, nao integrar, nao automatizar. Aprender.

A estrutura

A ideia e simples: quebrar o conhecimento em subpastas com arquivos .md instrutivos. Cada repo open-source que quero acompanhar fica dentro do seu proprio namespace no filesystem. O AGENTS.md e o hook inicial — o agente le esse arquivo e entende o que fazer, sem precisar de contexto externo.

~/learning/
  README.md                    <- Indice master com tabela de todos os repos
  AGENTS.md                    <- Contrato principal: o que o agente faz diariamente
  update_repos.py              <- Script: git pull em todos + coleta diffs
  *_learning/                  <- Um namespace por repo
    repo/                      <- Git clone do repo original
      AGENTS.md                <- Instrucoes do repo (build, arquitetura, convencoes)
    HOW_TO_USE.md              <- Guia de uso (quando necessario)
    LEARNING.md                <- Notas de estudo acumuladas
~/LEARNING.md                  <- Digest diario consolidado (fora do ~/learning/)

Cada arquivo tem um papel:

AGENTS.md — O contrato. Instrucoes que o agente segue sem perguntar. Na raiz do learning, dita a rotina diaria: pull, diff, resume. Dentro de cada repo, dita build commands, arquitetura, convencoes de codigo. O agente le e age. Alguns repos vao fundo — o Sim tem 548 linhas de AGENTS.md com sub-AGENTS.md por modulo.

README.md — O indice. Tabela com todos os repos acompanhados, links, prioridades, descricao one-line. Referencia rapida pra saber o que esta sendo trackeado.

update_repos.py — O motor. Script Python que faz git pull em cada repo e coleta os dados em JSON: commits novos, arquivos alterados, diffs. O output alimenta todo o resto.

HOW_TO_USE.md — Guia de uso opcional. Quando o repo e complexo o suficiente pra merecer um resumo alem do AGENTS.md. Fica no nivel do namespace, nao dentro do repo.

LEARNING.md — Notas de estudo. Acumulo de descobertas ao longo do tempo sobre aquele repo especifico. Nao e auto-gerado — e anotacao humana ou extracao do agente.

~/LEARNING.md — O digest diario. Fica fora do ~/learning/ propositalmente. E o consolidado de todos os repos com novidades, commits recentes e destaques. Gerado pelo agente apos cada rotina diaria.

A iteracao do agente com o sistema funciona assim:

graph TD
    A[Cron / Comando manual] --> B[update_repos.py]
    B --> C{Diffs coletados}
    C --> D[Agente analisa mudancas]
    D --> E[~/LEARNING.md atualizado]
    D --> F{Pattern reutilizavel?}
    F -->|Sim| G[Extrai skill Hermes]
    F -->|Nao| E
    G --> H[skills-blackhole]
    G --> I[Toolbox do agente]

O agente nao fica estudando so por estudar. O learning tem saida — patterns viram skills, skills viram ferramentas, ferramentas aceleram o proximo projeto.

Contrato e pre-mapping

O que torna o sistema viavel e o contrato. O AGENTS.md na raiz do learning e um instrucao executavel — nao documentacao. O agente le e sabe o que fazer: quais repos atualizar, como interpretar os diffs, quando gerar skills.

Isso cria o pre-mapping: antes de precisar de um assunto, o mapa ja esta pronto. Quando um repo finalmente aparece num projeto real, o agente ja estudou, ja extraiu os patterns, ja sabe os comandos. O custo de entrada vai pra proximo de zero.

O diff diario nao e estudo passivo — e indexacao continua. O agente compara commits, extrai o que importa, atualiza o resumo. Eu nao leio o resumo — mas quando preciso, ele esta la. Mais importante: o agente leu, entendeu, e ja sabe.

Digest diario

Todo dia, apos o pull e analise, o agente gera o ~/LEARNING.md — um consolidado com o que mudou em cada repo. Novos commits, features relevantes, breaking changes, destaques. Se nao teve mudanca, mantem o entry existente com timestamp atualizado.

O digest e o produto visivel da rotina. E onde o humano acompanha o que o agente aprendeu. E o ponto de entrada pra qualquer discussao sobre “o que mudou no Paperclip essa semana” ou “o Sim lancou algo novo?”.

Primeira skill

A rotina de learning funcionava, mas era manual. Toda vez que queria rodar o update, tinha que explicar o que fazer. A solucao: transformar o learning system numa skill Hermes.

Com a skill, um comando ou citacao no meio de uma conversa e suficiente. O agente carrega o contrato, roda o script, analisa os diffs, gera o digest, e extrai skills se encontrar patterns reutilizaveis. Tudo autonomo.

O learning system virou a primeira skill porque era a primeira tarefa repetivel. E tambem porque representava a premissa central: o agente aprende antes de construir.

# Local Learning System

Manages open-source repositories for study/tracking under ~/learning/.

## Structure Convention

~/learning/
  README.md              <- Master index with table of all repos
  update_repos.py        <- Script to git pull + collect info
  <name>_learning/       <- One folder per repo
    <repo_dir>/          <- The cloned repository
    HOW_TO_USE.md        <- Optional summary/guide

~/LEARNING.md            <- Consolidated daily summary (outside ~/learning/)

## Adding a New Repo

When user says /learning <repo_url> or asks to add a repo:

1. Extract repo name from URL (e.g. usestrix/strix -> strix)
2. Create folder: ~/learning/<name>_learning/
3. Clone repo: use terminal to clone the provided URL into ~/learning/<name>_learning/<repo_name>
4. Update ~/learning/README.md table with new entry (Pasta, Repo link, Descricao)
5. Update ~/LEARNING.md with initial entry for the new repo using the update script output
6. Run python3 ~/learning/update_repos.py to verify the new repo is tracked

## Updating All Repos (Daily Routine)

Run: python3 ~/learning/update_repos.py

This outputs JSON with git status for all repos. Use the output to update ~/LEARNING.md:
- Highlight significant changes (new features, breaking changes, major refactors)
- Keep summaries concise (~50 lines max per repo)
- Write everything in Portuguese
- Include last update timestamp

## README.md Table Format

Each repo gets a row: Pasta name, Repo link, Prioridade, One-line description.

Priority meaning:
- 3 stars = Maximum priority (user explicitly requested highest focus)
- 2 stars = High interest
- 1 star = Normal tracking

When user says "prioridade maxima" or "prioridade maxima", mark with 3 stars and place at top of the table.

## Skill Extraction Phase (Agentic Workflow Blueprint)

After the daily update routine, run the skill extraction phase using the Agentic Workflow Blueprint as meta-skill.

### When to Extract

- After updating all repos (daily routine complete)
- When a repo has significant changes (new features, useful patterns, architectures)
- When user explicitly asks

### Extraction Process

1. Classify the learning: What kind of reusable knowledge was discovered?
   - Pattern/architecture (e.g. "temporal workflow pattern")
   - Tool/API (e.g. "typesense grouping API")
   - Operational workflow (e.g. "deploy pipeline")
   - Debugging/troubleshooting (e.g. "docker stale image fix")

2. Extract as Hermes skill: Follow the executable contract format from the blueprint:
   - Goal: 1 sentence
   - Scope: applies to / does not cover
   - Triggers: when to load this skill
   - Inputs: what it needs
   - Procedure: deterministic steps
   - Outputs: what it produces
   - Review gate: success criteria

3. Save as Hermes skill: Use skill_manage(action='create') to persist in ~/.hermes/skills/
   - Categorize properly (devops, software-development, data-science, etc.)
   - Clear, descriptive name

### Decision Criteria

Extract when: recurring pattern, undocumented API/config, automatable workflow, reusable error/solution.
Skip when: trivial change, existing skill covers it, too repo-specific to generalize.

### Extraction Flow per Repo

For each repo with had_changes=true:
  1. Analyze diff of new commits
  2. Identify reusable patterns/knowledge
  3. If skill-worthy:
     a. Draft contract (Goal..Review gate)
     b. Check if similar skill exists (skills_list)
     c. If new: skill_manage(action='create')
     d. If exists but incomplete: skill_manage(action='patch')
  4. Log extracted skills in ~/LEARNING.md under the repo section

## Publishing Phase — skills-blackhole

After extracting Hermes skills, publish them to ~/projects/skills-blackhole/ using the blueprint contract format.

### When to Publish

- User says "coloca no skills-blackhole" or "publica as skills"
- After a study session produced 3+ Hermes skills on a single topic
- When skills are mature enough to be reusable contracts

### Blueprint Contract Format

Every skills-blackhole skill MUST have these sections:

1. Frontmatter: name, description, version: 1.0.0, author: skills-blackhole, license: MIT, metadata.hermes.tags
2. Goal: 1 sentence
3. Scope: applies to / does not cover
4. Triggers: file patterns + intent keywords
5. Inputs: what the workflow needs
6. Invariants: hard rules
7. Procedure: deterministic steps (evidence-driven)
8. Outputs: what must be produced
9. Review gate: pass/fail checklist
10. References: links to parent skill and sibling workflows

### Directory Structure

skills/<tech>/
  SKILL.md                          <- orchestrator entry (task -> workflow routing)
  reference/                        <- progressive disclosure (architecture, maps)
  workflows/
    <topic>/
      SKILL.md                      <- blueprint contract
      reference/                    <- topic-specific detail

### Conversion Workflow (Hermes -> Blueprint)

1. Create orchestrator SKILL.md at skills/<tech>/SKILL.md:
   - Orchestrator section: task classification -> workflow routing table
   - Project constraints section
   - Links to all workflow sub-skills

2. Convert each Hermes skill to workflows/<topic>/SKILL.md:
   - Read Hermes SKILL.md source content
   - Read existing blueprint skills for format consistency
   - Rewrite: Hermes freeform -> blueprint contract sections (Goal..Review gate)
   - Add reference/ files for detail that would bloat the main SKILL.md

3. Update README.md at repo root with new entry in Available Skills list

4. Git commit with descriptive message listing all workflows

### Pitfalls

- Don't duplicate the Hermes skill content verbatim -- restructure into Goal/Scope/Triggers/Procedure contract sections
- Reference files are for progressive disclosure -- move large tables and catalogs out of SKILL.md into reference/
- Check existing sibling workflows for format consistency before writing new ones
- The orchestrator SKILL.md must route to ALL workflows -- verify routing table completeness before commit

## Rules

- Folder names MUST end with _learning suffix
- All summaries in Portuguese
- Keep LEARNING.md concise and practical
- Focus on what changed that affects usage/contribution
- Skip trivial changes (lint, CI typos) - mention briefly
- Always include last update timestamp in LEARNING.md
- Run skill extraction after daily update when significant patterns are found
- Use the Agentic Workflow Blueprint contract format for all extracted skills
- Publish extracted skills to skills-blackhole when user requests or after study sessions produce 3+ skills on a single topic