Documentar sistemas em nivel agentico — blueprints de arquitetura, com roteamento de tarefas, assim o agente acha e opera no codigo de forma eficiente.

Agentic Workflow Blueprint

Todo projeto tem uma arquitetura por tras. Sistema de auth, camada de banco, rotinas de cron, background jobs, pipelines de deploy. Quando o agente precisa operar nesse projeto, ele precisa entender como tudo se conecta — e normalmente descobre isso lendo arquivos aleatorios, perguntando ao usuario ou tentando adivinhar.

O Agentic Workflow Blueprint é uma meta-skill que documenta o sistema como um todo em nivel agentico: como ele funciona, como os modulos se conectam, como operar em cada camada. O resultado é um conjunto de skills que o agente carrega por demanda — e quando carrega, ele ja sabe exatamente onde estar, o que tocar e como proceder.

RTFM

Blueprint do sistema

A ideia: documentar o comportamento do sistema como blueprint, nao como texto descritivo. Blueprint de auth. Blueprint da camada de banco. Blueprint de background jobs. Cada modulo vira um contrato que o agente segue pra trabalhar naquela area.

O agente identifica o pattern — “toda vez que eu termino uma implementacao, preciso documentar, revisar e gerar changelog” — e transforma isso em um contrato executavel:

Goal        -> Gerar docs a partir de evidencia de implementacao
Scope       -> Documentacao pos-implementacao
Triggers    -> "Document this change", diff pronto
Inputs      -> baseBranch, diffScope, docTarget
Procedure   -> Inspeciona diff, rascunha docs, valida claims
Outputs     -> Documentacao atualizada
Review gate -> Toda claim é groundada em evidencia

Esse contrato é um SKILL.md. O agente carrega ele quando precisa. Executa o procedimento. Passa pelo gate. Segue pro proximo passo. Nao precisa de instrucoes genericas do AGENTS.md — precisa do contrato especifico da tarefa.

O formato tem 9 secoes fixas: Goal, Scope, Triggers, Inputs, Invariants, Procedure, Outputs, Review gate, References. Cada workflow no projeto vira um desses contratos.

Subskills: composição de comportamentos

Workflows raramente vivem isolados. O workflow de documentacao precisa do workflow de revisao. O workflow de criacao de issues no Linear precisa de um passo de preflight antes de executar mutacoes.

O blueprint suporta subskills — workflows que compoe outros workflows como dependentes:

linear/
  SKILL.md               <- Workflow principal: criar issues no Linear
mcp-linear-planner/
  SKILL.md               <- Subskill: validar prereqs e gerar plano
mcp-linear-sync/
  SKILL.md               <- Subskill: executar o plano validado

O planner valida que o MCP server esta acessivel, inspeciona os schemas das ferramentas, resolve o contexto de team/project, e gera um plano de acoes deterministico. O sync recebe esse plano e executa as chamadas em ordem — sem adivinhar payloads, sem pular validacao.

Cada subskill é um contrato isolado com seus proprios inputs, invariants e review gates. O agente carrega so a subskill que precisa no momento. O workflow principal orquestra a sequencia.

Isso escala: um workflow complexo decomposto em subskills menores é mais legível, mais testavel, mais debugavel. Se o sync falha, o retry foca no sync — nao reprocessa o planner.

Plan-to-blueprint: de plano a sistema executavel

Quando vc escreve um plano de implementacao — com tarefas, dependencias e criterios de aceite — vc ja tem a materia-prima de um blueprint. A transformacao é direta:

Plano: "Task 1 -> Task 2 -> Task 3"
Blueprint: workflow/task-1/SKILL.md -> workflow/task-2/SKILL.md -> workflow/task-3/SKILL.md

Cada tarefa do plano vira um contrato. Os criterios de aceite viram review gates. As dependencias entre tarefas viram referencias entre workflows. O plano nao fica parado no markdown — vira um sistema executavel que o agente segue tarefa a tarefa.

O writing-plans gera o plano. O blueprint transforma em contratos. O subagent-driven-development executa via subagentes com review em cada etapa. O ciclo fecha: planejar -> blueprint -> executar -> revisar.

A estrutura

Quando o blueprint é disparado com o slug do projeto, ele scaffolds:

skills/<projectSlug>/
  SKILL.md                          <- Orchestrator (roteamento)
  reference/
    routing-matrix.md               <- Task category -> workflow
    role-contracts.md               <- Roles, boundaries, handoffs
    hook-blueprint.md               <- Automation hooks (opt-in)
  workflows/
    <workflowName>/SKILL.md         <- Contrato por workflow
docs/runbooks/
  agent-role-system.md              <- Playbooks operacionais

O orchestrator classifica a tarefa e aponta pro workflow correto. O routing matrix mapeia categorias de tarefa. Cada workflow é autocontido. O agente carrega o slice relevante — nunca a estrutura inteira.

Memoria que vive no projeto

A memória do agente sobre o projeto nao fica em um banco externo nem em prompt system — fica dentro do proprio projeto, nos blueprints. O estado atual do sistema sempre reside nas skills do projeto.

Primeira sessao: o agente executa o blueprint, scaffolds a estrutura, e o resultado fica no repo — em SKILL.md, routing matrix, referencias
Sessoes seguintes: o agente abre o projeto, lê os blueprints, e ja sabe como o sistema funciona hoje
O projeto evolui: quando algo muda no sistema, o blueprint atualiza junto — a memória esta no codigo, nao em um lugar separado

Isso significa que o blueprint é ao mesmo tempo documentacao agentica e memória persistente do projeto. Nao precisa de sync, nao precisa de MCP server, nao precisa de embedding vector. O repo é a memória. O agente le o repo.

Runbooks: agente vs operador

O blueprint separa dois niveis de documentacao:

SKILL.md (agent-facing): o contrato que o agente segue. Procedimento, gates, inputs, outputs.
Runbook (operator-facing): o playbook que o humano consulta. Attempt limits, failure handling, remediation steps.

O agente nao precisa saber de attempt limits — ele segue o contrato. O humano consulta o runbook quando precisa intervir. Cada nivel tem sua linguagem e sua profundidade.

Workflow chaining

O pipeline de documentacao demonstra chaining na pratica:

document -> review -> changelog

O document gera docs a partir de evidencia (git diff). O review valida com pass/fail determinista. Se falha, findings voltam pro document — retry bounded a 3 tentativas. Se passa, o changelog gera a entrada final.

attempt = 1
while attempt <= 3:
    doc = run(document)
    review = run(review, input=doc)
    if review.pass:
        run(changelog, input=doc)
        break
    attempt += 1

O handoff entre workflows é estruturado — inputs e outputs definidos, não é dump de contexto. O retry foca no gate que falhou.

Stack-agnostic

O blueprint nao impoe stack. Regras especificas ficam no project skill e sao linkadas pelos workflows. Go, TypeScript, Python — a estrutura se adapta. O contrato é o formato. O conteúdo é do projeto.

Mas a premissa vai alem: nao importa muito o agent. Qualquer agente é apenas um runtime capaz de interpretar passos em linguagem natural e executa-los no sistema operacional. Claude, GPT, Gemini, Codex, Hermes — o runtime muda, o contrato nao. O blueprint define o que precisa ser feito; o agente define como executar. Enquanto o agent consegue ler um SKILL.md e seguir um procedimento deterministico, o blueprint funciona.

A abstracao dupla — stack-agnostico e agent-agnostico — é o que torna o formato portavel. O mesmo blueprint roda em projetos diferentes, com agentes diferentes, sem adaptacao.

No lab

O blueprint ja gerou skills em uso:

Learning system — o cron diario extrai skills dos repos estudados usando o formato de contrato. Ja gerou: plugin-lifecycle-pattern, validate-before-execute, distributed-token-refresh, bedrock-converse-tool-schemas.
Subagent-driven development — execucao de planos via subagentes com 2-stage review. Usa gates e handoffs do blueprint.
Writing-plans — planos que viram blueprints executaveis. Cada tarefa é um contrato potencial.

O ciclo:

graph LR
    A[Comportamento identificado] -->|contrato| B[Skill extraida]
    B -->|execucao| C[Usada no projeto]
    C -->|feedback| B
    B -->|nova skill| D[Blueprint cresce]

Comportamento observado, extraido como contrato, executado pelo agente, refinado pelo feedback. O blueprint cresce organicamente com o projeto.