Treinamento

Studio Legado, do primeiro clique à proposta comercial

Aponte um sistema legado e um time de agentes de IA o percorre inteiro: extrai as regras de negócio que só existiam no código, desenha a arquitetura, levanta o modelo de dados, estima tamanho e preço, propõe o plano de migração e inventaria a dívida técnica — com cada afirmação marcada como confirmada, inferida ou lacuna.

→ Ver todas as telas do sistema na Galeria

Quem faz o quê

Como navegar

• Troque o idioma no topo (PT / EN) — o conteúdo é o mesmo nas duas línguas, então dá para treinar times do Brasil e dos EUA com o mesmo material. O link ?lang=en abre direto em inglês.
• Cada módulo tem Anterior / Próximo no pé da página. Clique em qualquer print para ampliar.
• Os checklists lembram o que você marcou, neste navegador.

Training

Studio Legado, from the first click to the sales proposal

Point it at a legacy system and a team of AI agents walks through all of it: it extracts the business rules that only lived in the code, draws the architecture, maps the data model, estimates size and price, proposes the migration plan and inventories the technical debt — with every claim marked as confirmed, inferred, or a gap.

→ See every system screen in the Gallery

Who does what

How to navigate

• Switch language at the top (PT / EN). The content is the same in both, so the same material trains teams in Brazil and the US. The link ?lang=en opens it in English.
• Every module has Previous / Next at the bottom. Click any screenshot to enlarge it.
• Checklists remember what you ticked, in this browser.

Trilha 1 · Operação · 1.1

O que é o Studio Legado e o que ele resolve

O Studio Legado lê um sistema existente e registra, a partir do código, o que ele faz: regras de negócio, arquitetura, dados, integrações e débito técnico. Cada afirmação traz a evidência de onde foi extraída e o grau de confiança.

O débito técnico que o diagnóstico lê

O que o Studio faz

É uma aplicação local (interface web + API) que orquestra dezenas de agentes especialistas de IA sobre um repositório. Você escolhe os sistemas, escolhe até onde a análise desce, e acompanha o processo num grafo. Quando o processo precisa de uma decisão que o código não responde, ele para e pergunta. Tudo fica gravado em SQLite: fechar o navegador não perde a execução.

As seis faixas do diagnóstico completo, na ordem em que rodam

Dentro da extração: cinco fases

1. Reconhecimento Inventário do projeto, dependências e versões, superfície geral — sem abrir gavetas.
2. Escavação Módulo a módulo: funções, algoritmos, estruturas de dados, fluxos de controle. Descreve, não julga.
3. Interpretação Regras de negócio implícitas, máquinas de estado, matriz de permissões, decisões arquiteturais reconstruídas; C4, ERD, integrações.
4. Geração Especificações por unidade, casos de uso, backlog de requisitos e os testes que provam cada card.
5. Revisão Auditoria adversarial das próprias specs: contradições, inferência disfarçada de fato, lacunas — que viram perguntas para você.

Track 1 · Operation · 1.1

What Studio Legado is and what it solves

Studio Legado reads an existing system and records, from the code, what it does: business rules, architecture, data, integrations and technical debt. Each statement carries the evidence it was extracted from and its confidence level.

The technical debt the diagnosis reads

What the Studio does

It's a local application (web UI + API) that orchestrates dozens of specialist AI agents over a repository. You pick the systems, pick how deep the analysis goes, and follow the process on a graph. When the process needs a decision the code can't answer, it stops and asks. Everything is recorded in SQLite: closing the browser doesn't lose the run.

The six stages of the complete diagnosis, in the order they run

Inside extraction: five phases

1. Recognition Project inventory, dependencies and versions, overall surface — without opening drawers.
2. Excavation Module by module: functions, algorithms, data structures, control flow. It describes; it doesn't judge.
3. Interpretation Implicit business rules, state machines, permission matrix, reconstructed architecture decisions; C4, ERD, integrations.
4. Generation Specifications per unit, use cases, a requirements backlog and the tests that prove each card.
5. Review An adversarial audit of its own specifications: contradictions, inference dressed up as fact, gaps — which become questions for you.

Trilha 1 · Operação · 1.2

Instalar e subir

Clonou, roda. Um comando sobe a API e a interface; nenhuma chave de API é necessária.

Requisitos

Primeira execução

git clone https://github.com/lubysoftware/luby-studio-legado.git
cd luby-studio-legado
./run.sh

Na primeira vez ele instala as dependências (alguns minutos). Depois sobe em segundos:

• interface → http://localhost:5273
• API → http://localhost:8788

Ctrl-C derruba os dois. Rodar de novo encerra a execução anterior deste projeto; se a porta estiver com outro processo, o script diz de quem é e para, em vez de matá-lo.

Variações úteis

Onde ficam os dados

studio/data/
  studio.db          histórico: sessões, execuções, eventos, artefatos, decisões
  workspaces/<run>/  o clone do sistema analisado e o que os agentes escreveram

Idioma e tema

O seletor de idioma fica no rodapé da gaveta lateral, ao lado do de tema. O padrão acompanha o navegador. Os artefatos nascem no idioma da tela: abrir uma análise em inglês grava domínio, diagramas e backlog em inglês — escolha o idioma antes de rodar para um cliente dos EUA.

Track 1 · Operation · 1.2

Install and start

Clone it, run it. One command starts the API and the UI; no API key required.

Requirements

First run

git clone https://github.com/lubysoftware/luby-studio-legado.git
cd luby-studio-legado
./run.sh

The first time, it installs dependencies (a few minutes). After that it starts in seconds:

• UI → http://localhost:5273
• API → http://localhost:8788

Ctrl-C stops both. Running it again stops the previous run of this project; if another process holds the port, the script tells you whose it is and stops, instead of killing it.

Useful variations

Where the data lives

studio/data/
  studio.db          history: sessions, runs, events, artifacts, decisions
  workspaces/<run>/  the clone of the analyzed system and what the agents wrote

Language and theme

The language picker sits at the bottom of the side drawer, next to the theme picker. The default follows the browser. Artifacts are written in the screen's language: opening an analysis in English writes the domain, diagrams and backlog in English — pick the language before running for a US client.

Trilha 1 · Operação · 1.3

Escolher os sistemas

Primeira tela: Quais sistemas você quer analisar? Cada origem vira uma execução independente, com o próprio fluxo e os próprios artefatos.

Duas portas de entrada

Boas práticas

• Um repositório por sistema. Se o cliente tem backend, frontend e um batch em repositórios separados, selecione os três: cada um roda em paralelo e, quando terminam, a análise cruzada descobre onde eles se tocam.
• Confira a branch. Analise a que está em produção, não a de desenvolvimento, a menos que o objetivo seja outro.
• Pasta local sem git funciona, mas os agentes perdem o histórico — e é do histórico que o Detetive reconstrói parte das decisões arquiteturais.
• O PRD do produto, se existir, pode ser colado depois na aba PRD/Researcher. Ele tem precedência sobre o que foi deduzido do código.

Track 1 · Operation · 1.3

Pick the systems

First screen: Which systems do you want to analyze? Each source becomes an independent run, with its own flow and its own artifacts.

Two ways in

Good practices

• One repository per system. If the client has backend, frontend and a batch job in separate repositories, select all three: each runs in parallel and, once they finish, the cross-analysis finds where they touch.
• Check the branch. Analyze the one running in production, not a development branch, unless the goal is different.
• A local folder without git works, but the agents lose the history — and the Detective reconstructs part of the architecture decisions from that history.
• The product PRD, if one exists, can be pasted later in the PRD/Researcher tab. It takes precedence over what was deduced from the code.

Trilha 1 · Operação · 1.4

Até onde descer: a escada de quatro degraus

Nem todo repositório merece o pacote inteiro. Descobrir em que linguagem um serviço está escrito não devia custar o diagnóstico completo. Cada degrau contém o de baixo inteiro.

O degrau mexe em duas coisas ao mesmo tempo: quais faixas rodam e com que profundidade cada etapa escreve (nível de documentação, granularidade das specs e quais especialistas opcionais ficam ligados). Os números de faixas, especialistas e paradas não são escritos à mão: saem do grafo real, e o resumo abaixo da escada mostra, a cada clique, o que entra e o que fica de fora.

Qual degrau escolher

Especialistas opcionais

Alguns agentes só fazem sentido quando o repositório tem o material deles:

• Data Master — requer DDL, migrations ou ORM. Ligado em Completa, Profunda e Essencial.
• Design System — requer CSS ou tema. Ligado em Completa e Profunda.
• Visor — requer screenshots, que quase nenhum legado guarda no repositório. Só na Completa.

No grafo, esses aparecem marcados OPC.

Track 1 · Operation · 1.4

How deep to go: the four-rung ladder

Not every repository deserves the whole package. Finding out what language a service is written in shouldn't cost the complete diagnosis. Each rung contains the whole rung below it.

The rung changes two things at once: which stages run and how deeply each step writes (documentation level, spec granularity and which optional specialists are on). Stage, specialist and stop counts aren't hand-written: they come from the real graph, and the summary under the ladder shows, on every click, what's in and what's left out.

Which rung to pick

Optional specialists

Some agents only make sense when the repository has their material:

• Data Master — needs DDL, migrations or an ORM. On in Complete, Deep and Essential.
• Design System — needs CSS or a theme. On in Complete and Deep.
• Visor — needs screenshots, which almost no legacy repository keeps. Complete only.

On the graph they're tagged OPT.

Trilha 1 · Operação · 1.5

Motor, custo e perfil de cobrança

O Studio não tem chave de LLM própria: ele delega ao CLI de IA instalado e logado na máquina — Claude Code ou Cursor. O modelo é uma escolha dentro do motor.

Motores

O painel mostra só o que existe no PATH, em qual conta você está logado e o plano. Motor não instalado aparece com a instrução de instalação. Confira a conta antes de rodar para cliente: a cota consumida é a dela. No --mock qualquer motor "roda", porque nada é executado de verdade.

Custo equivalente

Perfil de cobrança

A faixa Preço e tamanho precisa de dados que nenhuma leitura de código revela. O perfil é preenchido uma vez, nesta máquina, e toda sessão nova leva uma cópia dele:

• País, moeda local e senioridade (Júnior → Principal)
• Taxa hora — direta, ou calculada pela renda mensal desejada e horas faturáveis (tipicamente 80 a 160/mês)
• Markup de projeto (sobre o custo direto; não é margem contábil)
• Regime tributário, modelos de cobrança (escopo fechado, time and materials, sprint, retainer, valor fixo por entrega) e perfil de cliente
• Moeda de cobrança e câmbio, quando o cliente paga em outra moeda

A estimativa entrega três cenários lado a lado — Esforço, Valor e Faixa de mercado — e nunca um número único como resposta final.

Track 1 · Operation · 1.5

Engine, cost and billing profile

The Studio has no LLM key of its own: it delegates to the AI CLI installed and logged in on the machine — Claude Code or Cursor. The model is a choice inside the engine.

Engines

The panel only shows what's on the PATH, which account you're logged into and the plan. An engine that isn't installed shows the install instruction. Check the account before running for a client: its quota is the one being used. In --mock any engine "runs", because nothing actually executes.

Equivalent cost

Billing profile

The Pricing and size stage needs data no code reading reveals. The profile is filled in once, on this machine, and every new session takes a copy:

• Country, local currency and seniority (Junior → Principal)
• Hourly rate — direct, or derived from desired monthly income and billable hours (typically 80 to 160/month)
• Project markup (on direct cost; not accounting margin)
• Tax regime, pricing models (fixed scope, time and materials, per sprint, retainer, fixed price per delivery) and client profile
• Billing currency and exchange rate, when the client pays in another currency

The estimate delivers three scenarios side by side — Effort, Value and Market range — and never a single number as the final answer.

Trilha 1 · Operação · 1.6

Acompanhar a execução

Clique em Rodar processo. Cada sistema abre numa aba; o grafo mostra o processo acontecendo, e descer a tela é percorrer o tempo.

Lendo o grafo

A câmera segue a etapa em execução; desligue o seguindo para navegar livre.

Os indicadores do topo

• Especialistas — concluídos, trabalhando e na fila.
• Artefatos — arquivos gravados até agora.
• Paradas suas — respondidas, a próxima, ou esperando você.
• Custo equivalente — ver 1.5.

Console e painel de artefatos

O console registra cada passo (▶ início, + arquivo gravado, ✓ concluído com custo e tokens, ✗ falha, ⏸ decisão humana). O painel lateral lista os artefatos por pasta, com filtro e prévia. Os arquivos ficam em _lubylegado_sdd/ dentro do workspace da execução; o botão ao lado do caminho abre a pasta.

Parar, retomar e histórico

• Parar interrompe a execução. Retomar continua de onde parou — etapas já concluídas não rodam de novo.
• Sem sinal há N min: se um agente fica mudo por tempo demais, o executor o encerra, em vez de travar o run.
• Histórico lista todas as execuções. Abrir uma reconstrói a tela inteira a partir dos eventos gravados — nenhum agente roda de novo e nada é cobrado.
• No histórico você pode renomear uma sessão (ex.: "Cliente X — diagnóstico de setembro") e excluir — o que apaga também o workspace; o custo daquela análise não volta.

Track 1 · Operation · 1.6

Follow the run

Click Run the process. Each system opens in a tab; the graph shows the process as it happens, and scrolling down the screen is moving forward in time.

Reading the graph

The camera follows the running step; turn off following to move around freely.

The top indicators

• Specialists — done, working and queued.
• Artifacts — files written so far.
• Your stops — answered, the next one, or waiting for you.
• Equivalent cost — see 1.5.

Console and artifacts panel

The console logs every step (▶ start, + file written, ✓ done with cost and tokens, ✗ failure, ⏸ human decision). The side panel lists artifacts by folder, with a filter and preview. Files live in _lubylegado_sdd/ inside the run's workspace; the button next to the path opens the folder.

Stop, resume and history

• Stop interrupts the run. Resume picks up where it left off — steps already done don't run again.
• No signal for N min: if an agent stays silent too long, the executor ends it instead of hanging the run.
• History lists every run. Opening one rebuilds the whole screen from the recorded events — no agent runs again and nothing is spent.
• In History you can rename a session (e.g. "Client X — September diagnosis") and delete it — which also deletes its workspace; the cost of that analysis doesn't come back.

Trilha 1 · Operação · 1.7

Paradas: as decisões humanas

Algumas etapas param e perguntam — qual paradigma adotar, como resolver uma lacuna que o código não respondia. O processo para de verdade, e a resposta fica gravada no histórico junto com o resto.

As paradas do diagnóstico completo

Migração e reconstrução vêm por último de propósito: juntas, somam cinco decisões. Com elas na frente, documentação e preço ficariam esperando alguém voltar do almoço.

Respondendo

1. Leia a pergunta e o leque de respostas. Antes de a pergunta chegar a você, um agente já pesquisou as respostas possíveis no código.
2. Responda com o porquê. Na Resolução de lacunas, as respostas são gravadas de volta em questions.md e viram insumo das etapas seguintes — a arquitetura-alvo roda depois dela justamente para respeitar o que você decidiu. Nas paradas de migração e reconstrução, a decisão fica registrada no histórico e no dossiê, mas não é relida pelos agentes seguintes: eles seguem sem pedir confirmação e registram as dúvidas nos próprios artefatos.
3. Sem certeza? Use Sugerir resposta. Um agente lê o código e os artefatos e redige uma proposta (consome cota, leva um ou dois minutos, uma por vez). Se o código não decide a questão, ele diz: "Sem sugestão: o código não decide esta."
4. Não sabe e ninguém sabe agora? Deixe em branco ou use Seguir sem responder: a lacuna continua registrada, e as specs seguem com o buraco declarado.

Track 1 · Operation · 1.7

Stops: the human decisions

Some steps stop and ask — which paradigm to adopt, how to resolve a gap the code didn't answer. The process really stops, and the answer is recorded in history with everything else.

The stops in the complete diagnosis

Migration and reconstruction run last on purpose: together they add five decisions. Put them first and documentation and pricing would sit waiting for someone to get back from lunch.

Answering

1. Read the question and the answer options. Before the question reaches you, an agent has already researched the possible answers in the code.
2. Answer with the why. At Gap resolution, answers are written back to questions.md and feed the next steps — the target architecture runs after it precisely so it respects what you decided. At the migration and reconstruction stops, the decision is recorded in history and in the dossier, but the following agents don't read it back: they carry on without asking and record their doubts in their own artifacts.
3. Not sure? Use Suggest an answer. An agent reads the code and artifacts and drafts a proposal (uses quota, takes a minute or two, one at a time). If the code doesn't settle it, it says so: "No suggestion: the code does not settle this one."
4. Nobody knows right now? Leave it blank or use Continue without answering: the gap stays recorded, and the specs carry on with the hole declared.

Trilha 1 · Operação · 1.8

Escala de confiança

O processo não finge saber o que não sabe. Toda afirmação carrega um selo — e é esse selo que torna uma especificação gerada por IA utilizável por gente e por outro agente.

Como a confiança sobe

1. O Revisor coleta as lacunas e as transforma em perguntas específicas.
2. Um agente pesquisa o leque de respostas no código antes de a pergunta chegar a você.
3. Você responde na parada Resolução de lacunas. Resposta com evidência vira 🟢; resposta sem certeza absoluta vira 🟡.
4. O que ficou sem resposta continua 🔴, registrado para tratamento posterior — nunca apagado.

Onde o selo aparece na interface

• Casos de uso — pontos verde/amarelo/vermelho por regra e o bloco de lacunas com a pergunta que falta.
• Qualidade — cada oportunidade: coberto e entendido, cobertura parcial ou sem prova de comportamento.
• Kanban — cards que dependem de lacuna aberta ficam na coluna Bloqueado.
• Consolidado — ponto de contato entre sistemas marcado inferido ou só um lado tem evidência.

Track 1 · Operation · 1.8

Confidence scale

The process doesn't pretend to know what it doesn't. Every claim carries a label — and that label is what makes an AI-generated specification usable by people and by another agent.

How confidence goes up

1. The Reviewer collects the gaps and turns them into specific questions.
2. An agent researches the possible answers in the code before the question reaches you.
3. You answer at the Gap resolution stop. An answer with evidence becomes 🟢; an answer without full certainty becomes 🟡.
4. Whatever stays unanswered remains 🔴, recorded for later — never deleted.

Where the label shows up in the UI

• Use cases — green/yellow/red dots per rule and a gaps block with the missing question.
• Quality — each opportunity: covered and understood, partial coverage or no proof of behavior.
• Kanban — cards that depend on an open gap sit in the Blocked column.
• Consolidated — a contact point between systems marked inferred or only one side has evidence.

Trilha 1 · Operação · 1.9

As leituras, aba por aba

A gaveta lateral LEITURAS abre quando uma execução começa. Escolha uma aba abaixo ou pelo submenu.

Cada aba lê os artefatos que os agentes gravaram e mostra em forma de tela. Esta seção tem uma página por aba, sempre na mesma estrutura: propósito, ficha (quem usa, quando, quem produz, em quais degraus, quanto custa), o que aparece na tela, como usar e como ler bem.

O que vale para todas as abas

• As leituras ficam trancadas até uma execução começar: "disponível depois que uma execução começar".
• Aba sem artefato não fica em branco: diz quem produz e em que estado a etapa está — ainda não chegou a vez, rodando agora, parada esperando uma decisão sua, concluiu mas não gravou, falhou, pulada ou fora do recorte escolhido — um mais fundo produz isto.
• Abas que leem JSON se recarregam sozinhas quando o número de artefatos do run muda.
• Se o JSON existe mas não é válido, a aba aparece vazia; se é válido mas com formato inesperado, aparece "não foi possível montar esta aba". Nos dois casos, rode de novo o agente ou confira o arquivo no workspace.
• Agentes sob demanda (PRD, Researcher, Análise, Spec Kit, Tech Spec, atualizar Sumário, sugerir resposta) rodam um por vez por run; o segundo clique recebe "… ainda está rodando neste run". O custo entra no total do run.

Track 1 · Operation · 1.9

The readings, tab by tab

The READINGS side drawer opens once a run starts. Pick a tab below or from the submenu.

Every tab reads the artifacts the agents wrote and shows them as a screen. This section has one page per tab, always in the same structure: purpose, a fact sheet (who uses it, when, who produces it, which rungs, what it costs), what's on screen, how to use it and how to read it well.

What applies to every tab

• Readings stay locked until a run starts: "available once a run has started".
• A tab with no artifact isn't blank: it says who produces it and what state that step is in — not its turn yet, running now, stopped waiting for your decision, finished but didn't write it, failed, skipped, or outside the chosen scan — a deeper one produces this.
• JSON-based tabs reload on their own when the run's artifact count changes.
• If the JSON exists but is invalid, the tab looks empty; if it's valid but oddly shaped, you get "this tab could not be mounted". Either way, rerun the agent or check the file in the workspace.
• On-demand agents (PRD, Researcher, Analysis, Spec Kit, Tech Spec, Summary refresh, answer suggestion) run one at a time per run; a second click gets "… is still running in this run". Their cost is added to the run.

Trilha 1 · Operação · 1.9.1

Aba Fluxo

Onde a execução está, quem está trabalhando, o que já foi gravado, se ela está esperando você — e quanto custou até aqui.

O que aparece na tela

Barra do topo

• Nome do sistema e a fase: em análise, aguardando você, concluído, concluído com falhas (passe o mouse para ver cada etapa que falhou e o motivo), interrompido, na fila.
• O recorte (Recorte Completa etc.) e o selo SIMULAÇÃO no modo simulado.
• Botões Parar, Retomar (só aparece se o run parou sem terminar), Dossiê e Nova execução.

Quatro indicadores

O grafo

• Faixas numeradas (01 · Extração do legado…), cada uma com dica e contador de concluídos.
• Legenda O que cada agente faz com 8 famílias: Reconhecimento, Escavação, Interface, Síntese, Especificação, Verificação, Decisão, Negócio.
• Cartão de agente: faixa de cor da família, monograma, nome, resumo de 2 linhas, status, selos OPC e BIN, atividade ao vivo, número de arquivos e ≈$ ao terminar.
• Medidor de silêncio ⏱: aparece depois de 90 s sem saída do agente, fica âmbar a 2/3 do limite de 15 min.
• Nó de parada (âmbar, redondo): decisão humana ou definido automaticamente; pulsa enquanto espera e mostra a resposta depois.
• Câmera seguindo (acompanha a parada aberta, depois o agente rodando) ou livre; zoom e minimapa.

Console e painel de artefatos

• Console recolhido mostra uma linha; expandido mostra tudo, ● ao vivo. Formatos: ▶ início, + arquivo (kB), ✓ agente · ≈$ · tokens, ✗ falha, – pulado, ⏸ decisão humana.
• Painel Artefatos: filtro por nome, agrupado por pasta, cada arquivo com família, tamanho, agente autor e prévia. Clicar num nó do grafo filtra o painel pelos arquivos daquele agente.

Como usar

• Parar e Retomar valem para o run inteiro; etapa concluída nunca roda de novo.
• Uma parada bloqueia o laço inteiro, não só o ramo dela — por isso o grafo "congela" até você responder.
• Passe o mouse num cartão cinza-tracejado (pulado) ou vermelho (falhou) para ler o motivo.

Track 1 · Operation · 1.9.1

Flow tab

Where the run is, who is working, what has been written, whether it is waiting on you — and what it has cost so far.

What's on screen

Top bar

• System name and phase: analyzing, waiting on you, done, done with failures (hover to see each failed step and why), stopped, queued.
• The scan (Complete scan etc.) and the SIMULATION badge in mock mode.
• Buttons Stop, Resume (only when the run stopped without finishing), Dossier and New run.

Four indicators

The graph

• Numbered stages (01 · Legacy extraction…), each with a hint and a done counter.
• Legend What each agent does with 8 families: Recognition, Excavation, Interface, Synthesis, Specification, Verification, Decision, Business.
• Agent card: family color strip, monogram, name, 2-line summary, status, OPT and BIN badges, live activity, file count and ≈$ when done.
• Silence meter ⏱: shows after 90 s with no output, turns amber at 2/3 of the 15-min limit.
• Stop node (amber, round): human decision or set automatically; pulses while waiting and shows the answer afterwards.
• Camera following (tracks the open stop, then the running agent) or free; zoom and minimap.

Console and artifacts panel

• The collapsed console shows one line; expanded shows everything, ● live. Formats: ▶ start, + file (kB), ✓ agent · ≈$ · tokens, ✗ failure, – skipped, ⏸ human decision.
• Artifacts panel: filter by name, grouped by folder, each file with family, size, author agent and preview. Clicking a graph node filters the panel to that agent's files.

How to use it

• Stop and Resume act on the whole run; a finished step never runs again.
• A stop blocks the whole loop, not just its branch — that's why the graph "freezes" until you answer.
• Hover a dashed grey (skipped) or red (failed) card to read why.

Trilha 1 · Operação · 1.9.2

Aba Sumário

O que é este repositório, para que serve e para quem — a primeira leitura de qualquer pessoa.

O que aparece na tela

• Título do documento e o bloco de abertura: quem gerou, quando e a partir de quê.
• Até três cartões lado a lado: Propósito, Objetivo e Pessoas.
• O restante do documento: entidades centrais (5 a 10, com relações), decisões fundadoras (3 a 7, com evidência e implicação), lacunas. Os marcadores 🟢🟡🔴 viram as palavras confirmado, inferido e lacuna.
• Botão Atualizar sumário: roda de novo apenas o agente desta página, com a versão atual da skill.

Para que serve

• Abrir a conversa com o cliente: em três colunas, o sistema em linguagem de negócio.
• Servir de fronteira: etapas seguintes sinalizam mudanças que contrariam a "alma" do sistema.
• É pré-requisito da aba Análise e do PRD.

Track 1 · Operation · 1.9.2

Summary tab

What this repository is, what it's for and for whom — everyone's first read.

What's on screen

• The document title and its opening block: who generated it, when, and from what.
• Up to three cards side by side: Purpose, Goal and People.
• The rest of the document: core entities (5 to 10, with relations), founding decisions (3 to 7, with evidence and implication), gaps. The 🟢🟡🔴 markers become the words confirmed, inferred and gap.
• Refresh summary button: reruns only this page's agent, with the current skill version.

What it's for

• Opening the client conversation: the system in business language, in three columns.
• Acting as a boundary: later steps flag changes that contradict the system's "soul".
• It's a prerequisite for the Analysis tab and the PRD.

Trilha 1 · Operação · 1.9.3

Aba PRD

Remonta o documento de requisitos que ninguém escreveu, a partir do que a análise extraiu — com a origem de cada requisito.

O que aparece na tela

Antes de gerar

• O aviso: é um PRD reconstruído do código, não a especificação original — o documento diz isso na primeira linha.
• A caixa O que ele vai ler deste run, com 8 insumos marcados ✓ ou riscados: Síntese do sistema, Casos de uso, Regras de domínio, Atores e permissões, Integrações, Arquitetura, Dados, Backlog.
• Sem síntese ou sem casos de uso: "Falta material essencial" e o botão Gerar PRD fica desligado.

Depois de gerar

Para que serve

• Dar ao time de produto um documento no formato que ele conhece, sem ninguém precisar ler código.
• Alimentar o Researcher: o PRD gerado aparece como primeiro candidato no campo de PRD de lá.
• A seção 11 é a pauta pronta da reunião com o negócio.

Track 1 · Operation · 1.9.3

PRD tab

Reassembles the requirements document nobody wrote, from what the analysis extracted — with the source of every requirement.

What's on screen

Before generating

• The caveat: it's a PRD reconstructed from the code, not the original specification — the document says so in its first line.
• The What it will read from this run box, with 8 inputs ticked ✓ or struck through: System synthesis, Use cases, Domain rules, Actors and permissions, Integrations, Architecture, Data, Backlog.
• Without synthesis or use cases: "Essential material is missing", and Generate PRD is disabled.

After generating

What it's for

• Giving the product team a document in the format they know, without anyone reading code.
• Feeding the Researcher: the generated PRD shows up as the first candidate in its PRD field.
• Section 11 is a ready agenda for the business meeting.

Trilha 1 · Operação · 1.9.4

Aba Researcher

O que falta neste produto frente ao mercado — e o que ele tem que ninguém mais tem.

As três etapas

O que aparece na tela

• Campo PRD do produto, preenchido nesta ordem: o PRD da última pesquisa → um documento do repositório que se declara PRD → só sugestões. Chips achei no repositório e também achei.
• Botão Realizar pesquisa e os chips das três etapas com o estado de cada uma.
• O produto: nome, o que faz, para quem, Dor que resolve, capacidades entregues e incompletas, e em âmbar "O PRD e o código discordam em N pontos".
• Features candidatas em três grupos: Paridade (o mercado já tem), Diferencial, Aposta (evidência indireta). Cada uma com problema, esforço, persona, já em (concorrentes) e completa (capacidade).
• O que ninguém mais tem (cartões verdes) e Produtos parecidos (disputa alto/médio/baixo, forças, fraquezas, preço).
• O que ficou em aberto: as lacunas das três etapas.
• Botões Refazer a leitura (só o radar, sem internet) e Pesquisar de novo (as três).

Track 1 · Operation · 1.9.4

Researcher tab

What this product is missing against the market — and what it has that nobody else does.

The three steps

What's on screen

• Product PRD field, filled in this order: the last search's PRD → a repository document that declares itself a PRD → suggestions only. Chips found in the repository and also found.
• Run the search button and the three step chips with their state.
• The product: name, what it does, for whom, Pain it solves, delivered and incomplete capabilities, and in amber "The PRD and the code disagree on N points".
• Candidate features in three groups: Parity (the market has it), Differentiator, Bet (indirect evidence). Each with problem, effort, persona, already in (competitors) and completes (capability).
• What nobody else has (green cards) and Similar products (overlap high/medium/low, strengths, weaknesses, price).
• What is still open: gaps from all three steps.
• Buttons Redo the reading (radar only, no internet) and Search again (all three).

Trilha 1 · Operação · 1.9.5

Aba Integrações

Tudo o que cruza a fronteira do sistema: quem chama quem, com que payload, com que credencial e o que acontece quando falha.

O que aparece na tela

• Barra: N saída · N entrada (as bidirecionais não entram em nenhum dos dois) e contagem de lacunas.
• Cartões com ícone de direção: o sistema chama, chamam o sistema, nos dois sentidos; tipo (rest, graphql, soap, grpc, queue, webhook, database, file, other); criticidade alta/média/baixa; chave quando há segredo; número de endpoints e se tem retry.
• Detalhe ao clicar: autenticação, nome do segredo e onde ele vai, timeout, retry, limite de taxa; caixa âmbar com o comportamento em falha; por endpoint, método, caminho, propósito, chamado de (arquivos clicáveis), exemplo de requisição e resposta, erros; link documentação do fornecedor.

Para que serve

• Saber o que quebra fora quando algo muda dentro — e o que precisa de contrato na migração.
• Montar o inventário de terceiros exigido por auditoria e compliance.
• Achar credenciais versionadas: aparecem como lacuna de segurança.

Track 1 · Operation · 1.9.5

Integrations tab

Everything that crosses the system boundary: who calls whom, with what payload, what credential, and what happens when it fails.

What's on screen

• Bar: N outbound · N inbound (bidirectional ones count in neither) and the gap count.
• Cards with a direction icon: the system calls, they call the system, both ways; kind (rest, graphql, soap, grpc, queue, webhook, database, file, other); criticality high/medium/low; a key when there's a secret; endpoint count and whether it retries.
• Detail on click: auth, the secret's name and where it goes, timeout, retry, rate limit; an amber box with failure behavior; per endpoint, method, path, purpose, called from (clickable files), request and response examples, errors; a vendor documentation link.

What it's for

• Knowing what breaks outside when something changes inside — and what needs a contract during migration.
• Building the third-party inventory audits and compliance ask for.
• Finding committed credentials: they show up as a security gap.

Trilha 1 · Operação · 1.9.6

Aba Arquitetura

O que depende de quê — e o que quebra se eu mudar isto.

O que aparece na tela

• Barra: N componentes · N dependências, contador de ciclos e o seletor de nível Containers | + Módulos | Tudo (padrão: módulos).
• "espessura da seta = referências": pares repetidos são somados; a espessura cresce em escala logarítmica; arestas inferidas são tracejadas.
• Nó: nome, externo (tracejado), tipo, responsabilidade, detalhes, impacto, arquivos e linhas, tecnologia. Nó que participa de ciclo ganha anel âmbar.
• Detalhe ao clicar: dependências, impacto de mudar (âmbar), caminho, arquivos, linhas.
• Painel ciclos de dependência: o caminho a → b → a, se é de import ou de execução, e a explicação.

Para que serve

• Estimar com base em estrutura: o impacto de mudar um nó está escrito nele.
• Achar as costuras naturais para modularizar ou extrair serviço.
• Mostrar ao cliente por que "mexeu aqui, quebrou ali": os ciclos.

Track 1 · Operation · 1.9.6

Architecture tab

What depends on what — and what breaks if I change this.

What's on screen

• Bar: N components · N dependencies, a cycles counter and the level picker Containers | + Modules | Everything (default: modules).
• "arrow thickness = references": repeated pairs are summed; thickness grows logarithmically; inferred edges are dashed.
• Node: name, external (dashed), kind, responsibility, details, impact, files and lines, technology. A node that sits in a cycle gets an amber ring.
• Detail on click: dependencies, impact of changing it (amber), path, files, lines.
• Dependency cycles panel: the path a → b → a, whether it's import or runtime, and the explanation.

What it's for

• Estimating from structure: the impact of changing a node is written on it.
• Finding the natural seams to modularize or extract a service.
• Showing the client why "touch it here, it breaks over there": the cycles.

Trilha 1 · Operação · 1.9.7

Aba Diagramas

Todos os desenhos que os agentes deixaram dentro dos documentos, reunidos numa biblioteca navegável.

As famílias

O que aparece na tela

• Barra: N desenhos em N artefatos, contagem das principais famílias e o filtro filtrar diagramas (por arquivo, título ou tipo).
• Índice à esquerda agrupado por família; cada item com título (o cabeçalho mais próximo acima do bloco), arquivo e tipo.
• À direita, o desenho renderizado sobre fundo claro, link para o arquivo e ampliar em tela cheia. O primeiro abre sozinho.

Track 1 · Operation · 1.9.7

Diagrams tab

Every drawing the agents left inside the documents, gathered into one browsable library.

The families

What's on screen

• Bar: N drawings across N artifacts, counts for the main families and the filter diagrams box (by file, title or kind).
• Index on the left grouped by family; each entry with a title (the nearest heading above the block), file and kind.
• On the right, the rendered drawing on a light background, a file link and expand to full screen. The first one opens by itself.

Trilha 1 · Operação · 1.9.8

Aba Casos de uso

Quem usa o sistema, para conseguir o quê, por quais caminhos — e onde isso mora no código.

O que aparece na tela

• Barra: N casos · N atores, confirmados (verde) e lacunas (âmbar); chips de ator para filtrar — pessoa (humano), robô (sistema), relógio (tempo).
• Cartão: UC-id, nome, selo confirmado / inferido / suposto, ator principal, objetivo, include e extend.
• Aberto, duas visões UML: Sequência (padrão, com zoom e alternância de fluxos alternativos e exceções) e Casos de uso (bonecos, fronteira do sistema, elipses).
• Depois: pré-condições, fluxo principal, cada alternativa, exceções (nome → tratamento), pós-condições, regras de negócio e implementado em (arquivos clicáveis).
• Cartão de lacunas no fim.

Para que serve

• É o coração da demonstração: uma regra 🟢 com o arquivo de origem e uma lacuna 🔴 com a pergunta.
• Base dos critérios de aceite do backlog e dos testes de ponta a ponta.
• Conversa com o negócio sem jargão técnico.

Track 1 · Operation · 1.9.8

Use cases tab

Who uses the system, to get what, along which paths — and where that lives in the code.

What's on screen

• Bar: N cases · N actors, confirmed (green) and gaps (amber); actor chips to filter — person (human), bot (system), clock (time).
• Card: UC-id, name, confirmed / inferred / assumed badge, primary actor, goal, include and extend.
• Expanded, two UML views: Sequence (default, with zoom and toggles for alternative flows and exceptions) and Use cases (stick figures, system boundary, ellipses).
• Then: preconditions, main flow, each alternative, exceptions (name → handling), postconditions, business rules and implemented in (clickable files).
• A gaps card at the end.

What it's for

• It's the heart of the demo: a 🟢 rule with its source file and a 🔴 gap with its question.
• The basis for backlog acceptance criteria and end-to-end tests.
• A conversation with the business without technical jargon.

Trilha 1 · Operação · 1.9.9

Aba Tecnologias

O que cada tecnologia sustenta, quão espalhada ela está e qual o risco de sustentação — a conversa do orçamento.

O que aparece na tela

• Barra: total, estruturais (acoplamento estrutural), sem suporte (vermelho: abandonada ou fim de vida), não usadas (âmbar); chips por categoria (linguagem, runtime, framework, biblioteca, banco, infraestrutura, ferramenta).
• Cartão: logo, nome, versão (a dica mostra de que arquivo veio), categoria, propósito, risco (ok, desatualizada, abandonada, fim de vida, risco desconhecido), acoplamento (isolado, espalhado, estrutural), nota de risco e substituição.
• Onde é usada · N: os três primeiros arquivos com o uso, depois mais N lugares.
• Declarada e sem uso: "candidata a remoção".
• Caixa vermelha sem manutenção: "trocar estas é trabalho que entra no orçamento da reescrita, não melhoria opcional".

Para que serve

• Separar o que é melhoria opcional do que é trabalho obrigatório no orçamento.
• Responder auditoria sobre componentes sem suporte.
• Priorizar: acoplamento estrutural pesa mais no custo de reescrita do que o risco sozinho.

Track 1 · Operation · 1.9.9

Technologies tab

What each technology holds up, how widespread it is and what its support risk is — the budget conversation.

What's on screen

• Bar: total, structural (structural coupling), unsupported (red: abandoned or end of life), unused (amber); category chips (language, runtime, framework, library, database, infrastructure, tool).
• Card: logo, name, version (the tooltip shows which file it came from), category, purpose, risk (ok, outdated, abandoned, end of life, unknown risk), coupling (isolated, spread, structural), a risk note and replacement.
• Where it is used · N: the first three files with how each uses it, then N more places.
• Declared and unused: "removal candidate".
• Red unmaintained box: "replacing these is work that belongs in the rewrite budget, not an optional improvement".

What it's for

• Separating optional improvement from mandatory budget work.
• Answering audits about unsupported components.
• Prioritizing: structural coupling weighs more on rewrite cost than risk alone.

Trilha 1 · Operação · 1.9.10

Aba Arquitetura-alvo

Para onde este sistema pode ir — 2 a 4 arquiteturas viáveis, com a evidência — e com o que construir a escolhida.

1 · Para onde migrar

• Propostas ordenadas por aderência, escolhidas de um catálogo fixo: manter-e-endurecer (sempre presente), monolito-modular, hexagonal, microsserviços, event-driven, cqrs-event-sourcing, serverless, soa-bff, pipeline-batch.
• Cada uma: esforço (baixo a muito alto), formato de time, por quê, barra de aderência 0–100 (verde ≥ 65, âmbar ≥ 40, vermelho abaixo).
• detalhes: como a aderência foi calculada, quando esta é a escolha errada (âmbar), por onde começar (passos), riscos, o que precisa existir antes.
• Linha de descartadas, com o motivo (aderência abaixo de 30).

2 · Com o que construir

• Antes de escolher: "O Tech Spec pesquisa a stack para aquele cenário — não para todos ao mesmo tempo."
• Depois: um cartão por necessidade (linguagem, framework HTTP, persistência, mensageria…), com 2–3 candidatos, um sugerido, maturidade, atrito de migração, custo, lock-in e a lista âmbar confira antes de fechar.

Como usar

• escolher → grava refactor/decision.json (decidido por humano) e dispara o Tech Spec na hora.
• Escolher outra sobrescreve a decisão e roda a stack de novo. Se a decisão mudou e a stack não, a tela avisa: "Esta stack foi pesquisada para X, não para a escolha atual. Refaça a stack."
• A escolha alimenta o Spec Kit: sem ela, os planos dizem o que precisa ser decidido antes de codificar.

Track 1 · Operation · 1.9.10

Target architecture tab

Where this system can go — 2 to 4 viable architectures, with the evidence — and what to build the chosen one with.

1 · Where to migrate

• Proposals sorted by fit, picked from a fixed catalog: keep-and-harden (always present), modular monolith, hexagonal, microservices, event-driven, cqrs-event-sourcing, serverless, soa-bff, pipeline-batch.
• Each: effort (low to very high), team shape, why, a 0–100 fit bar (green ≥ 65, amber ≥ 40, red below).
• details: how the fit was calculated, when this is the wrong choice (amber), where to start (steps), risks, what must exist first.
• A discarded line, with the reason (fit below 30).

2 · What to build it with

• Before choosing: "Tech Spec researches the stack for that scenario — not for all of them at once."
• After: one card per need (language, HTTP framework, persistence, messaging…), with 2–3 candidates, one suggested, maturity, migration friction, cost, lock-in and the amber check before closing list.

How to use it

• choose → writes refactor/decision.json (decided by a human) and starts Tech Spec right away.
• Choosing another overwrites the decision and reruns the stack. If the decision changed and the stack didn't, the screen warns: "This stack was researched for X, not for the current choice. Redo the stack."
• The choice feeds Spec Kit: without it, the plans list what must be decided before coding.

Trilha 1 · Operação · 1.9.11

Aba Qualidade

O inventário da dívida técnica, por área, na ordem do que é mais seguro e barato corrigir primeiro — com o especialista que faria cada mudança.

O que aparece na tela

• Barra: N oportunidades em N áreas, e sem prova em vermelho.
• Faixa âmbar fixa: "Nada foi aplicado. Este é o inventário priorizado: cada transformação é feita pelo especialista do verbo correspondente, sob aprovação de diff, no projeto — não neste clone."
• Grupos por contexto. Cartão: número, título, verbo (reestruturar, modularizar, desacoplar, otimizar, simplificar, padronizar, podar — a dica explica cada um), estado quando decidido (aprovada, aplicada, revertida, recusada), retorno estimado, confiança e custo.
• Aberto: o que se observa, por que vale, alvo com arquivos, não pode mudar (as regras da "alma" que o item toca), specs relacionadas.

Como a lista é ordenada

1. Abertas primeiro. Decididas ficam esmaecidas.
2. Por confiança: 🟢 coberto e entendido → 🟡 cobertura parcial → 🔴 sem prova de comportamento.
3. Por custo: baixo → alto.
4. Pelo número. O número é ordem de registro, não prioridade.

Track 1 · Operation · 1.9.11

Quality tab

The technical debt inventory, by area, in order of what's safest and cheapest to fix first — with the specialist who would make each change.

What's on screen

• Bar: N opportunities across N areas, and no proof in red.
• A fixed amber strip: "Nothing was applied. This is the prioritized inventory: each transformation is done by the matching verb's specialist, with diff approval, in the project — not in this clone."
• Groups by context. Card: number, title, verb (restructure, modularize, decouple, optimize, simplify, standardize, prune — the tooltip explains each), state once decided (approved, applied, reverted, refused), estimated return, confidence and cost.
• Expanded: what is observed, why it's worth it, target with files, must not change (the "soul" rules it touches), related specs.

How the list is ordered

1. Open ones first. Decided ones are dimmed.
2. By confidence: 🟢 covered and understood → 🟡 partial coverage → 🔴 no proof of behavior.
3. By cost: low → high.
4. By number. The number is registration order, not priority.

Trilha 1 · Operação · 1.9.12

Aba Análise

Um relatório para o sistema que vai continuar no ar: o que atrapalha mantê-lo, para quem decide e não programa.

As quatro partes

Como usar

• Backlog futuro · opcional: anexe a lista do cliente (md, txt, csv, json) de até 512 kB. Arquivo vazio é recusado.
• analisar roda o agente; exportar markdown baixa <sistema>-analise.md com tabela-resumo e as quatro partes na ordem.
• As categorias de dívida explicam o tipo de dor: entendimento, mudança, verificação, operação, entrega, dependência, conhecimento.

Track 1 · Operation · 1.9.12

Analysis tab

A report for the system that will stay live: what gets in the way of maintaining it, for people who decide and don't code.

The four parts

How to use it

• Future backlog · optional: attach the client's list (md, txt, csv, json) up to 512 kB. Empty files are refused.
• analyze runs the agent; export markdown downloads <system>-analise.md with a summary table and the four parts in order.
• Debt categories name the kind of pain: understanding, change, verification, operation, delivery, dependency, knowledge.

Trilha 1 · Operação · 1.9.13

Aba Kanban

Transforma a análise no backlog de requisitos da reescrita — e deixa as pessoas decidirem o que está pronto.

As colunas

O que aparece na tela

• Barra: N requisitos, contagens must / should / could, testes e filtro por épico.
• Card: título, REQ-id, prioridade (must, should, could, won't riscado), estimativa PP–GG, ícones de testes, integrações e dependências, épico.
• Painel de detalhe: descrição, Por que não reescrever (nos won't), critérios de aceite, regras de negócio, testes de unidade com o veredito do QA (coberto por testes, parcial, sem critério para testar, fora do escopo) e cada teste em dado / quando / então, com o que prova e os dublês.
• Campos: Coluna, épico, estimativa, confiança, componentes, integrações, dependências, casos de uso, arquivos no legado.

Como usar

• Não há arrastar e soltar: mova o card pelo seletor Coluna no painel de detalhe.
• A mudança vale na hora e fica gravada por run e card no banco local; rodar a análise de novo não apaga as movimentações.
• Avisos úteis: "Sem critério de aceite: este card não deveria sair do refinamento" e "O Analista de Testes ainda não passou por este card".

Track 1 · Operation · 1.9.13

Kanban tab

Turns the analysis into the rewrite requirements backlog — and lets people decide what's ready.

The columns

What's on screen

• Bar: N requirements, must / should / could counts, tests and an epic filter.
• Card: title, REQ-id, priority (must, should, could, won't struck through), estimate XS–XL, icons for tests, integrations and dependencies, epic.
• Detail panel: description, Why not rewrite (on won't cards), acceptance criteria, business rules, unit tests with the QA verdict (covered by tests, partial, no criterion to test, out of rewrite scope) and each test as given / when / then, with what it proves and its doubles.
• Fields: Column, epic, estimate, confidence, components, integrations, dependencies, use cases, legacy files.

How to use it

• No drag and drop: move a card with the Column picker in the detail panel.
• The move applies immediately and is saved per run and card in the local database; rerunning the analysis doesn't wipe moves.
• Useful warnings: "No acceptance criteria: this card should not leave refinement" and "The Test Analyst has not reviewed this card yet".

Trilha 1 · Operação · 1.9.14

Aba Spec Kit

Transforma os cards que uma pessoa marcou como prontos num pacote de desenvolvimento orientado a especificação, para um projeto novo.

O que aparece na tela

• Barra: N features especificadas, cards prontos, no backlog, tarefas; botões gerar specs (desligado com zero cards prontos) e exportar arquivos.
• Uma de três situações: sem backlog; nenhum card em Pronto para reescrever (com a contagem por coluna); ou "N de T cards estão prontos e entram no pacote".
• Constituição do projeto: os princípios que nenhuma implementação pode violar — o documento que o agente de codificação relê a cada tarefa.
• Stack do plano, escolhida na Arquitetura-alvo, ou o aviso de que ainda não foi escolhida.
• Features, na ordem de dependência: cada uma com épico, depende de, histórias, critérios, tarefas e links para spec, plan e tasks.
• Fora deste pacote (id, coluna e motivo) e perguntas em aberto — a pauta com quem conhece o negócio.

Exportação

exportar arquivos baixa <sistema>-speckit.zip com speckit/ e um index.md montado na hora: resumo, como usar, ordem de implementação (ciclos quebrados e sinalizados com "começa antes de…"), dependências fora do pacote, perguntas em aberto, cards excluídos e o mapa de pastas.

Track 1 · Operation · 1.9.14

Spec Kit tab

Turns the cards a person marked ready into a spec-driven development package for a new project.

What's on screen

• Bar: N features specified, ready cards, in the backlog, tasks; buttons generate specs (disabled with zero ready cards) and export files.
• One of three situations: no backlog; no card in Ready to rewrite (with a per-column count); or "N of T cards are ready and go into the package".
• Project constitution: the principles no implementation may break — the document the coding agent rereads on every task.
• Plan stack, chosen in Target architecture, or a warning that it hasn't been chosen.
• Features, in dependency order: each with epic, depends on, stories, criteria, tasks and links to spec, plan and tasks.
• Outside this package (id, column and reason) and open questions — the agenda with whoever knows the business.

Export

export files downloads <system>-speckit.zip with speckit/ and an index.md built on the spot: summary, how to use, implementation order (cycles broken and flagged "starts before…"), dependencies outside the package, open questions, excluded cards and the folder map.

Trilha 1 · Operação · 1.9.15

Aba Consolidado

Para sessões com dois ou mais sistemas: onde eles se tocam, o que compartilham e onde divergem.

O que aparece na tela

• Barra: N sistemas nesta sessão, linhas totais, casos de uso, cards e custo.
• Panorama: tabela por sistema — módulos, linhas, ciclos, integrações que entram e saem, tecnologias, casos de uso, cards e custo. "—" é falta de dado.
• Onde os sistemas se tocam: o estado da análise cruzada (rodando, parada esperando decisão na aba do run de Federação, pronta para rodar com o botão rodar análise cruzada, ou o motivo do bloqueio) e os cartões de ponto de contato — de → para, tipo, criticidade, assíncrono, inferido, protocolo, propósito, comportamento em falha, contrato divergente e só um lado tem evidência. Infraestrutura compartilhada em âmbar.
• Stack: tecnologias em comum e exclusivas; mesma tecnologia, versão declarada diferente só quando os dois lados declaram número.
• Backlog somado e as lacunas da análise cruzada.

Quando a federação roda

Sozinha, quando nenhum run da sessão está pendente, rodando ou esperando decisão e ao menos dois terminaram (concluído ou com falhas). Tem uma parada própria: Confirmação dos pontos de contato — integração real, rota morta ou sistema fora desta sessão?

Track 1 · Operation · 1.9.15

Consolidated tab

For sessions with two or more systems: where they touch, what they share and where they diverge.

What's on screen

• Bar: N systems in this session, total lines, use cases, cards and cost.
• Overview: a per-system table — modules, lines, cycles, inbound and outbound integrations, technologies, use cases, cards and cost. "—" means missing data.
• Where the systems touch: the cross-analysis state (running, stopped waiting for a decision in the Federation run tab, ready to run with run cross-analysis, or the blocking reason) and contact-point cards — from → to, kind, criticality, asynchronous, inferred, protocol, purpose, failure behavior, divergent contract and only one side has evidence. Shared infrastructure in amber.
• Stack: shared and exclusive technologies; same technology, different declared version only when both sides declare a number.
• Combined backlog and the cross-analysis gaps.

When federation runs

On its own, when no run in the session is pending, running or waiting for a decision and at least two have finished (done or with failures). It has its own stop: Contact point confirmation — a real integration, a dead route, or a system outside this session?

Trilha 1 · Operação · 1.9.16

Aba Dossiê

Tudo o que a execução produziu, num markdown que dá para mandar por e-mail.

O conteúdo, na ordem

Como usar

• Botão Dossiê na barra do topo, em qualquer aba. Baixa dossie-<sistema>-<data>.md no idioma da tela e guarda uma cópia em studio/data/dossies/.
• Cada bloco é recorte literal com a fonte citada — nada é resumido nem reescrito.

Track 1 · Operation · 1.9.16

Dossier tab

Everything the run produced, in one markdown file you can email.

Contents, in order

How to use it

• The Dossier button in the top bar, on any tab. Downloads dossie-<system>-<date>.md in the screen language and keeps a copy in studio/data/dossies/.
• Every block is a literal excerpt with its source cited — nothing is summarized or rewritten.

Trilha 1 · Operação · 1.10

Exportar: dossiê, relatório e specs

Três saídas prontas para levar para fora do Studio. Todas funcionam a partir do que está em disco — sem rodar agente de novo.

* A higiene de IA avalia como o repositório está preparado para trabalho com agentes (arquivo de contexto CLAUDE.md/AGENTS.md, CI, segredos fora do git, configuração local fora do versionamento etc. — 15 itens). Só aparece quando o sistema foi selecionado como pasta local e o Agentic Squad está rodando na mesma máquina; fora disso o dossiê diz "Não verificado", e não "está tudo certo".

Os artefatos brutos

Tudo o que os agentes escreveram fica em _lubylegado_sdd/ no workspace da execução: inventário, dependências, dicionário de dados, domínio e regras, máquinas de estado, permissões, decisões arquiteturais, C4, ERD, casos de uso, backlog, perguntas e lacunas. A faixa Documentação ainda gera um mini-site HTML navegável do sistema como ele é hoje, útil para onboarding do time do cliente.

Track 1 · Operation · 1.10

Export: dossier, report and specs

Three outputs ready to take outside the Studio. All of them work from what's on disk — no agent runs again.

* AI hygiene checks how the repository is set up for agent work (a CLAUDE.md/AGENTS.md context file, CI, secrets kept out of git, local config kept out of version control, etc. — 15 items). It only shows up when the system was selected as a local folder and Agentic Squad is running on the same machine; otherwise the dossier says "Not verified", not "all good".

The raw artifacts

Everything the agents wrote lives in _lubylegado_sdd/ in the run's workspace: inventory, dependencies, data dictionary, domain and rules, state machines, permissions, architecture decisions, C4, ERD, use cases, backlog, questions and gaps. The Documentation stage also builds a navigable HTML mini-site of the system as it is today, useful for onboarding the client's team.

Trilha 1 · Operação · 1.11

Vários sistemas e federação

Empresas raramente têm um legado só. Selecione vários repositórios na mesma sessão: cada um roda em paralelo, e a análise cruzada descobre o que trafega entre eles.

1. Selecione todas as origens na primeira tela. O botão mostra quantas execuções vão rodar em paralelo.
2. Cada sistema tem sua aba, com fluxo, paradas e artefatos próprios.
3. Quando pelo menos dois sistemas terminam, a Federação começa sozinha. Ela tem uma parada própria: Confirmação dos pontos de contato. Se não tiver disparado, a aba Consolidado oferece rodar análise cruzada.
4. Leia o Consolidado. Ele só aparece com mais de um sistema.

O que o Consolidado mostra

• Panorama — por sistema: módulos, linhas, ciclos, integrações que entram e saem, tecnologias, casos de uso, cards e custo.
• Onde os sistemas se tocam — cada ponto de contato com criticidade, se é assíncrono, e se é inferido ou se só um lado tem evidência.
• Stack — tecnologias em comum e exclusivas; divergência de versão só quando os dois lados declaram número.
• Backlog somado e lacunas da análise cruzada.

Track 1 · Operation · 1.11

Several systems and federation

Companies rarely have just one legacy system. Select several repositories in the same session: each runs in parallel, and the cross-analysis finds out what flows between them.

1. Select every source on the first screen. The button shows how many runs will go in parallel.
2. Each system gets its own tab, with its own flow, stops and artifacts.
3. Once at least two systems finish, Federation starts on its own. It has its own stop: Contact point confirmation. If it didn't fire, the Consolidated tab offers run cross-analysis.
4. Read Consolidated. It only appears with more than one system.

What Consolidated shows

• Overview — per system: modules, lines, cycles, inbound and outbound integrations, technologies, use cases, cards and cost.
• Where the systems touch — each contact point with criticality, whether it's asynchronous, and whether it's inferred or only one side has evidence.
• Stack — shared and exclusive technologies; a version mismatch is flagged only when both sides declare a number.
• Combined backlog and the cross-analysis gaps.

Trilha 1 · Operação · 1.12

Segurança e limites

O que o Studio garante por construção — e o que ele deliberadamente não faz. Saber os dois evita prometer errado.

Garantias de construção

Limites que você precisa saber

• O código é lido por um modelo de IA através do CLI logado (Claude Code ou Cursor). A política de dados é a do provedor e do plano desse CLI. Para código de cliente, use a conta corporativa aprovada e confirme o que o contrato permite antes de rodar.
• O Studio não escreve código — nem de produção, nem de teste. Ele especifica os testes; os testes de caracterização e as transformações são escritos depois, no projeto real.
• O Studio não aplica refatoração. O Ato "Transformar" do processo comercial é conduzido por engenheiros no projeto real, com rede de segurança, diff aprovado e reversibilidade.
• O que não está no código não é descoberto. Regra que só existe na cabeça de alguém, comportamento que depende de dado de produção, configuração de infraestrutura fora do repositório: tudo isso vira lacuna.
• Profundidade depende do ecossistema. O processo é agnóstico de linguagem, mas a riqueza dos artefatos varia com o que o repositório oferece (histórico git, DDL, testes, telas).
• Custo e tempo crescem com o porte e com o degrau escolhido. Use o Reconhecimento para medir antes de comprometer o pacote completo.

Track 1 · Operation · 1.12

Safety and limits

What the Studio guarantees by design — and what it deliberately doesn't do. Knowing both keeps you from promising the wrong thing.

Guarantees by design

Limits you need to know

• The code is read by an AI model through the logged-in CLI (Claude Code or Cursor). The data policy is that provider's and that plan's. For client code, use the approved corporate account and confirm what the contract allows before running.
• The Studio doesn't write code — neither production nor test code. It specifies the tests; characterization tests and transformations are written later, in the real project.
• The Studio doesn't apply refactorings. The "Transform" act of the sales process is run by engineers in the real project, with a safety net, an approved diff and reversibility.
• What isn't in the code isn't discovered. A rule that only lives in someone's head, behavior that depends on production data, infrastructure config outside the repository: all of it becomes a gap.
• Depth depends on the ecosystem. The process is language-agnostic, but how rich the artifacts are depends on what the repository offers (git history, DDL, tests, screens).
• Cost and time grow with size and with the rung you pick. Use Recon to measure before committing to the complete package.

Trilha 1 · Operação · 1.13

Solução de problemas

Os tropeços mais comuns e o que fazer.

"Nenhum motor encontrado nesta máquina"

Nenhum CLI está no PATH. Instale o Claude Code ou o Cursor CLI e clique em procurar de novo. Se usa nvm, abra um terminal novo antes de rodar ./run.sh.

"execução real ainda não suporta o motor …"

Você selecionou Codex ou Gemini CLI. Eles aparecem no painel, mas só Claude Code e Cursor executam agentes. Selecione um dos dois e rode de novo.

"O CLI está instalado, mas nenhuma conta está logada"

Rode o comando de login indicado na tela (claude auth login ou cursor-agent login) e clique em procurar de novo. Sem login, o primeiro agente falha com "Not logged in".

"O CLI está instalado, mas não consegui ler a conta autenticada"

Faça login no CLI pelo terminal (ex.: abra o claude e autentique) e volte à tela. Sem conta autenticada o agente não consegue rodar.

A porta 8788 (ou 5273) está ocupada

O run.sh diz qual processo está na porta e para. Se for outro projeto, suba com PORT=9000 ./run.sh. Se for uma execução antiga deste projeto, rodar de novo já a derruba.

Uma etapa ficou "sem sinal há N min"

O agente não emitiu nada por um tempo. O executor encerra a etapa ao atingir o limite exibido, em vez de travar o run. Depois, use Retomar: as etapas concluídas não rodam de novo.

Uma etapa falhou ou foi pulada

Clique na etapa para ver o motivo. Opcionais sem material (ex.: Visor sem screenshots) são pulados por design. Ferramenta binária ausente também é pulada com aviso, quando a etapa a declara opcional.

A faixa de preço não trouxe preço

O perfil de cobrança não foi preenchido. Sem ele, a faixa só mede tamanho. Preencha o perfil e rode de novo.

"Não foi possível montar esta aba"

O artefato que alimenta a tela saiu fora do formato esperado. Rode de novo o agente daquela aba (quando há botão de atualizar) ou confira o JSON correspondente no workspace.

"O diagrama não compila"

Um bloco Mermaid gerado tem erro de sintaxe. O restante da aba continua válido; o arquivo de origem pode ser aberto e corrigido no workspace.

O disco está enchendo

Cada execução guarda um clone. Exclua sessões antigas pelo Histórico (apaga o workspace junto) ou, para zerar tudo, rm -rf studio/data.

Os artefatos saíram em português para um cliente dos EUA

Os artefatos seguem o idioma da tela no momento da execução. Troque para English no rodapé da gaveta e rode de novo.

Track 1 · Operation · 1.13

Troubleshooting

The most common stumbles and what to do.

"No engine found on this machine"

No CLI is on the PATH. Install Claude Code or the Cursor CLI and click scan again. If you use nvm, open a new terminal before running ./run.sh.

"real execution doesn't support the … engine yet"

You selected Codex or Gemini CLI. They show up in the panel, but only Claude Code and Cursor run agents. Select one of them and run again.

"The CLI is installed, but no account is logged in"

Run the login command shown on screen (claude auth login or cursor-agent login) and click scan again. Without a login, the first agent fails with "Not logged in".

"The CLI is installed, but I couldn't read the authenticated account"

Log in to the CLI from the terminal (e.g. open claude and authenticate) and come back to the screen. Without an authenticated account the agent can't run.

Port 8788 (or 5273) is taken

run.sh tells you which process holds the port and stops. If it's another project, start with PORT=9000 ./run.sh. If it's an old run of this project, running again already stops it.

A step shows "no signal for N min"

The agent hasn't emitted anything for a while. The executor ends the step when it hits the displayed limit, instead of hanging the run. Then use Resume: finished steps don't run again.

A step failed or was skipped

Click the step to see why. Optional steps without material (e.g. Visor without screenshots) are skipped by design. A missing binary tool is also skipped with a warning when the step declares it optional.

The pricing stage produced no price

The billing profile wasn't filled in. Without it, the stage only measures size. Fill in the profile and run again.

"Couldn't build this tab"

The artifact behind the screen came out in an unexpected format. Rerun that tab's agent (when there's a refresh button) or check the matching JSON in the workspace.

"The diagram doesn't compile"

A generated Mermaid block has a syntax error. The rest of the tab is still valid; the source file can be opened and fixed in the workspace.

The disk is filling up

Every run keeps a clone. Delete old sessions from History (it deletes the workspace too) or, to wipe everything, rm -rf studio/data.

The artifacts came out in Portuguese for a US client

Artifacts follow the screen's language at run time. Switch to English at the bottom of the drawer and run again.

Trilha 1 · Operação · 1.14

Laboratório prático

Três exercícios, do sem custo ao real. Faça na ordem. O repositório já traz um sistema pequeno em sample/ para praticar.

Exercício 1 — A interface, sem gastar cota (20 min)

• Subir com ./run.sh --mock e confirmar o selo SIMULAÇÃO.
• Selecionar a pasta sample/ e um repositório remoto qualquer.
• Clicar nos quatro degraus e anotar o que entra e sai em cada um.
• Rodar a Completa, responder uma parada e deixar outra sem resposta.
• Parar no meio e retomar. Conferir que nada rodou duas vezes.
• Abrir o Histórico, renomear a sessão e reabri-la.

Exercício 2 — Reconhecimento real (≈ minutos)

• Subir com ./run.sh, conferir motor, conta e modelo.
• Rodar o degrau Reconhecimento sobre sample/.
• Ler Sumário, Tecnologias e Arquitetura. Anotar o custo equivalente.
• Explicar em 3 frases, para um colega, o que o sistema faz.

Exercício 3 — Diagnóstico com decisões

• Preencher o perfil de cobrança com valores de treino.
• Rodar a Profunda ou a Completa sobre sample/.
• Na Resolução de lacunas, usar Sugerir resposta em uma pergunta e comparar com a sua.
• Encontrar, na aba Casos de uso, uma regra 🟢 e uma lacuna 🔴, e achar o arquivo de origem da regra.
• Mover cards no Kanban, gerar o Spec Kit e exportar os arquivos.
• Exportar o Dossiê e revisá-lo como se fosse enviar a um cliente.

Track 1 · Operation · 1.14

Hands-on lab

Three exercises, from zero cost to real. Do them in order. The repository ships a small system in sample/ for practice.

Exercise 1 — The UI, without spending quota (20 min)

• Start with ./run.sh --mock and confirm the SIMULATION badge.
• Select the sample/ folder and any remote repository.
• Click all four rungs and note what's in and out of each.
• Run Complete, answer one stop and leave another unanswered.
• Stop halfway and resume. Check that nothing ran twice.
• Open History, rename the session and reopen it.

Exercise 2 — A real Recon (≈ minutes)

• Start with ./run.sh, check engine, account and model.
• Run the Recon rung on sample/.
• Read Summary, Technologies and Architecture. Note the equivalent cost.
• Explain in 3 sentences, to a colleague, what the system does.

Exercise 3 — A diagnosis with decisions

• Fill in the billing profile with practice values.
• Run Deep or Complete on sample/.
• At Gap resolution, use Suggest an answer on one question and compare it with yours.
• In Use cases, find a 🟢 rule and a 🔴 gap, and locate the rule's source file.
• Move cards on the Kanban, generate the Spec Kit and export the files.
• Export the Dossier and review it as if you were sending it to a client.

Fluxo · F1

O motor em uma página

Da pasta do cliente até a aba na tela: o caminho que uma análise percorre.

O Studio Legado é uma aplicação local com duas partes: uma API em Node que orquestra o trabalho e uma interface em React que mostra o que acontece. Quem faz a análise não é o Studio: são agentes — instruções escritas executadas, uma a uma, pelo CLI de IA logado na máquina (Claude Code ou Cursor).

As sete ideias que explicam tudo

1. O legado nunca é tocado. Cada execução trabalha num clone em studio/data/workspaces/<run>/. A pasta ou o repositório de origem não muda.
2. Um agente é um arquivo de instruções. Uma SKILL.md diz o que ler, o que produzir e com que regras. O Studio só manda o CLI executá-la. F2
3. Um agente por vez, em ordem de dependência. O executor monta um grafo (DAG) e roda cada etapa quando as dependências terminaram. Vários sistemas rodam em paralelo; dentro de um sistema, é serial. F4
4. Tudo vira arquivo. Cada agente grava seus artefatos; o próximo lê o que o anterior escreveu. As abas leem esses mesmos arquivos. F3
5. Quando o código não responde, o processo para. Paradas (gates) esperam uma decisão humana; a resposta é gravada e, nas lacunas, volta para os arquivos. E3
6. Tudo fica gravado como evento. Cada início, arquivo, falha e decisão é um evento no SQLite. A tela é recalculada a partir deles — por isso reabrir pelo Histórico não roda nada de novo. F5
7. Nada escreve código. Os agentes do diagnóstico produzem conhecimento, planos e especificações. Transformar código é trabalho de engenharia, fora do Studio, com prova.

Onde cada coisa mora

Flow · F1

The engine on one page

From the client's folder to the tab on screen: the path an analysis takes.

Studio Legado is a local application with two parts: a Node API that orchestrates the work and a React UI that shows what's happening. The Studio doesn't do the analysis: agents do — written instructions run, one at a time, by the AI CLI logged in on the machine (Claude Code or Cursor).

The seven ideas that explain everything

1. The legacy system is never touched. Each run works on a clone in studio/data/workspaces/<run>/. The source folder or repository doesn't change.
2. An agent is an instruction file. A SKILL.md says what to read, what to produce and under which rules. The Studio just tells the CLI to run it. F2
3. One agent at a time, in dependency order. The executor builds a graph (DAG) and runs each step once its dependencies finish. Several systems run in parallel; within one system, it's serial. F4
4. Everything becomes a file. Each agent writes its artifacts; the next one reads what the previous wrote. The tabs read those same files. F3
5. When the code can't answer, the process stops. Stops (gates) wait for a human decision; the answer is recorded and, for gaps, written back into the files. E3
6. Everything is recorded as an event. Every start, file, failure and decision is an event in SQLite. The screen is recomputed from them — that's why reopening from History reruns nothing. F5
7. Nothing writes code. Diagnosis agents produce knowledge, plans and specifications. Transforming code is engineering work, outside the Studio, with proof.

Where everything lives

Fluxo · F2

O que é um agente

Um agente é uma pasta com um arquivo SKILL.md. O começo do arquivo (frontmatter) é metadado; o resto são instruções em linguagem natural para o modelo: o que ler, o que produzir, em que formato e com que regras.

---
name: lubylegado-integrations
description: Mapeia tudo que cruza a fronteira do sistema...
metadata:
  team: discovery
  phase: interpretacao
  network: web      # só quem declara isto recebe internet
---
# Mapeador de Integrações
## Antes de começar
## O que produzir
## Regras absolutas
...

Como um agente roda

1. O workspace recebe todas as skills em .claude/skills/.
2. O executor monta um prompt fixo: leia .claude/skills/<id>/SKILL.md inteiro; execute do início ao fim; grave os artefatos nos caminhos que ele manda; leia .lubylegado/state.json para pasta de saída, nível e idioma; não peça confirmação — registre a dúvida e siga; .claude/, .cursor/ e .lubylegado/ não são o sistema analisado.
3. O CLI roda sem interface (claude -p … --output-format stream-json ou cursor-agent -p … --output-format stream-json), com a sessão logada — nunca com chave de API, que é removida do ambiente.
4. O Studio lê a saída linha a linha: texto vira atividade na tela; escrita confirmada vira artefato (tamanho lido do disco); o resultado final traz custo e tokens.

O que um agente pode fazer

No Cursor, a mesma lista é traduzida para .cursor/cli.json no clone (Read(**), Write(**), Shell(git)…, com rm, curl e wget negados).

Famílias

Cada agente pertence a uma família, que dá a cor do cartão no grafo:

De onde vêm

• agents/lubylegado-*: o framework de engenharia reversa de especificações que roda por baixo.
• studio/agents/lubylegado-*: agentes da Luby que produzem os dados estruturados das abas (JSON legível por máquina).
• O catálogo tem 89 agentes; o diagnóstico completo usa 32 deles, mais os sob demanda. Os demais são usados pela CLI, fora do Studio — ver F11.
• Agente novo em agents/ aparece no grafo sem mexer no front: npm run catalog regenera o catálogo a partir do frontmatter.

Flow · F2

What an agent is

An agent is a folder with a SKILL.md file. The start of the file (frontmatter) is metadata; the rest is natural-language instructions for the model: what to read, what to produce, in which format and under which rules.

---
name: lubylegado-integrations
description: Maps everything that crosses the system boundary...
metadata:
  team: discovery
  phase: interpretacao
  network: web      # only skills declaring this get internet
---
# Integration Mapper
## Before you start
## What to produce
## Absolute rules
...

How an agent runs

1. The workspace receives every skill in .claude/skills/.
2. The executor builds a fixed prompt: read .claude/skills/<id>/SKILL.md in full; run it end to end; write artifacts where it says; read .lubylegado/state.json for output folder, level and language; don't ask for confirmation — record the doubt and move on; .claude/, .cursor/ and .lubylegado/ aren't the analyzed system.
3. The CLI runs headless (claude -p … --output-format stream-json or cursor-agent -p … --output-format stream-json), with the logged-in session — never an API key, which is stripped from the environment.
4. The Studio reads the output line by line: text becomes on-screen activity; a confirmed write becomes an artifact (size read from disk); the final result carries cost and tokens.

What an agent may do

With Cursor, the same list is translated into .cursor/cli.json in the clone (Read(**), Write(**), Shell(git)…, with rm, curl and wget denied).

Families

Every agent belongs to a family, which sets its card color on the graph:

Where they come from

• agents/lubylegado-*: the specification reverse-engineering framework underneath.
• studio/agents/lubylegado-*: Luby agents that produce the tabs' structured data (machine-readable JSON).
• The catalog has 89 agents; the complete diagnosis uses 32 of them, plus the on-demand ones. The rest are used through the CLI, outside the Studio — see F11.
• A new agent in agents/ shows up on the graph without touching the front end: npm run catalog regenerates the catalog from the frontmatter.

Fluxo · F3

Como o legado é extraído

Do clone ao contrato: o que acontece com o código do cliente em cada fase.

1 · Preparar o workspace

Depois copia as skills para .claude/skills/, roda rtk init se o rtk estiver instalado (comprime a saída de comandos) e grava a configuração do run:

2 · As cinco fases da extração

3 · Os princípios da extração

• Módulo a módulo, de propósito. Analisar tudo de uma vez consome contexto e degrada a qualidade; o Arqueólogo escava um módulo por vez a partir do inventário.
• Descrever antes de interpretar. A escavação cataloga sem julgar; a interpretação pergunta o porquê e usa o histórico do git.
• Cada afirmação tem selo. 🟢 confirmado com arquivo e linha, 🟡 inferido, 🔴 lacuna. Ver 1.8.
• Um agente lê o que o anterior gravou. O surface.json guia a escavação; o domain.md é o documento mais reaproveitado adiante.
• Contrato, não texto bonito. Critérios verificáveis em dado/quando/então; requisito não funcional só com evidência.
• Auditoria adversarial no fim. O Revisor procura contradição e inferência disfarçada de fato antes de a extração ser considerada pronta.

Flow · F3

How the legacy system is extracted

From clone to contract: what happens to the client's code in each phase.

1 · Prepare the workspace

Then it copies the skills into .claude/skills/, runs rtk init if rtk is installed (it compresses command output) and writes the run configuration:

2 · The five extraction phases

3 · Extraction principles

• Module by module, on purpose. Analyzing everything at once burns context and degrades quality; the Archaeologist digs one module at a time from the inventory.
• Describe before interpreting. Excavation catalogs without judging; interpretation asks why and uses git history.
• Every claim has a label. 🟢 confirmed with file and line, 🟡 inferred, 🔴 gap. See 1.8.
• Each agent reads what the previous one wrote. surface.json guides excavation; domain.md is the most reused document downstream.
• Contract, not pretty prose. Verifiable given/when/then criteria; non-functional requirements only with evidence.
• Adversarial audit at the end. The Reviewer hunts for contradictions and inference dressed as fact before extraction counts as done.

Fluxo · F4

O executor: ordem, paradas, relógios e retomada

Ordem

• As etapas formam um grafo de dependências. O executor faz uma ordenação topológica e lança erro se houver ciclo, em vez de rodar um fluxo incompleto.
• Um agente por vez em cada run. Paralelismo existe entre sistemas: cada repositório da sessão é um run independente, todos ao mesmo tempo.
• As faixas rodam nesta ordem: Extração → Qualidade → Documentação → Preço → Migração → Reconstrução. Migração e reconstrução vêm por último porque somam cinco decisões humanas, e uma parada segura o laço inteiro.
• Etapa opcional fora do degrau é pulada com motivo, e conta como satisfeita para quem depende dela.
• Perfil de cobrança não roda agente: o Studio grava o perfil salvo na tela. Sem perfil, a estimativa fica bloqueada.
• Etapa BIN: o executor também sabe rodar ferramenta determinística (verificador, mutação de testes), sem LLM, uma tentativa. Nenhum fluxo atual usa — é infraestrutura pronta.

Paradas

A parada dispara depois que a etapa dela termina e bloqueia o laço inteiro, não só o ramo. Detalhe de cada uma na trilha do engenheiro.

Relógios

Por que progresso e não duração: um teto fixo de 60 minutos já matou um agente saudável que gravava um arquivo a cada vinte segundos. Lento é normal em legado grande; travado é outra coisa. O encerramento é TERM, depois KILL em 10 s, e abandono em 15 s — um agente perdido custa uma etapa; um executor pendurado custaria o run.

Falhas

• Cada etapa tem 2 tentativas com 20 s de intervalo (STUDIO_AGENT_ATTEMPTS, STUDIO_AGENT_RETRY_MS). Binário ausente não é repetido. O custo das tentativas falhas entra no total.
• Etapa que falhou bloqueia só quem depende dela ("depende de X, que não concluiu"); as independentes continuam.
• O run termina concluído com falhas, não concluído. O stderr da falha vai para .lubylegado/logs/<agente>.log.

Parar e retomar

O workspace é reaproveitado e o custo soma todas as passagens. Se o servidor cai, na volta ele marca como falha toda etapa que ficou "iniciada" sem fim.

Modo simulado

./run.sh --mock: sem workspace, cada agente emite três atividades e até três artefatos falsos, custo fictício; as paradas abrem normalmente. Serve para treinar e desenvolver a interface.

Flow · F4

The executor: order, stops, clocks and resume

Order

• Steps form a dependency graph. The executor sorts it topologically and throws on a cycle, instead of running an incomplete flow.
• One agent at a time per run. Parallelism exists across systems: each repository in the session is an independent run, all at once.
• Stages run in this order: Extraction → Quality → Documentation → Pricing → Migration → Reconstruction. Migration and reconstruction go last because they add five human decisions, and a stop holds the whole loop.
• An optional step outside the rung is skipped with a reason, and counts as satisfied for its dependents.
• The billing profile doesn't run an agent: the Studio writes the profile saved on screen. Without it, the estimate is blocked.
• BIN step: the executor can also run a deterministic tool (checker, mutation testing), no LLM, one attempt. No current flow uses it — the infrastructure is ready.

Stops

A stop fires after its step finishes and blocks the whole loop, not just its branch. Details for each one in the engineer track.

Clocks

Why progress and not duration: a fixed 60-minute cap once killed a healthy agent that was writing a file every twenty seconds. Slow is normal on a large legacy system; stuck is something else. Shutdown is TERM, then KILL after 10 s, then abandon after 15 s — a lost agent costs one step; a hung executor would cost the run.

Failures

• Each step gets 2 attempts 20 s apart (STUDIO_AGENT_ATTEMPTS, STUDIO_AGENT_RETRY_MS). A missing binary isn't retried. Failed attempts' cost is added to the total.
• A failed step blocks only its dependents ("depends on X, which did not finish"); independent steps keep going.
• The run ends done with failures, not done. The failure's stderr goes to .lubylegado/logs/<agent>.log.

Stop and resume

The workspace is reused and cost adds up across passes. If the server crashes, on restart it marks as failed every step left "started" with no end.

Simulation mode

./run.sh --mock: no workspace, each agent emits three activity lines and up to three fake artifacts, fictional cost; stops still open. For training and UI work.

Fluxo · F5

Eventos, histórico, degraus e federação

Tudo é evento

O banco local (studio/data/studio.db) guarda a execução como uma sequência de eventos — a fonte da verdade. O evento é gravado antes de chegar à tela.

Além de events, há sessions, repos, runs, as projeções assets e gates, settings (perfil de cobrança) e card_status (movimentos do Kanban).

Tela ao vivo e Histórico

• A interface assina /api/runs/:id/events (SSE): recebe todos os eventos gravados, um aviso replayed, e depois os novos ao vivo.
• A tela é calculada só a partir da sequência de eventos. Por isso reabrir pelo Histórico remonta tudo sem rodar agente e sem custo.

Degraus são recortes de um único grafo

Os quatro degraus não são listas separadas: são filtros sobre o diagnóstico completo. O recorte mantém as faixas do degrau (e, no Reconhecimento, só os 8 agentes da espinha da extração) e poda as dependências para quem ficou — senão uma etapa esperaria para sempre por quem não vai rodar. Faixa vazia some do grafo.

A diferença entre etapas e especialistas: o perfil de cobrança é fornecido pelo Studio (não é agente) e opcionais desligados não contam.

Vários sistemas e federação

1. Uma sessão, um run por repositório, todos com o mesmo degrau, rodando em paralelo.
2. Quando nenhum run está pendente, rodando ou esperando decisão, e ao menos dois terminaram, o Studio cria e dispara sozinho o run de federação.
3. A federação não clona nada: recebe as skills e federation/systems.json com o workspace de cada sistema, e lê os artefatos deles (integrações, tecnologias, arquitetura, dados, casos de uso).
4. Mapeador de Federação → Pesquisador de Respostas → parada Confirmação dos pontos de contato.
5. Adicionar um repositório à sessão marca a federação como desatualizada.

Flow · F5

Events, history, rungs and federation

Everything is an event

The local database (studio/data/studio.db) stores the run as a sequence of events — the source of truth. An event is written before it reaches the screen.

Besides events, there are sessions, repos, runs, the assets and gates projections, settings (billing profile) and card_status (Kanban moves).

Live screen and History

• The UI subscribes to /api/runs/:id/events (SSE): it gets every stored event, a replayed marker, then new ones live.
• The screen is computed only from the event sequence. That's why reopening from History rebuilds everything with no agent and no cost.

Rungs are cuts of a single graph

The four rungs aren't separate lists: they're filters over the complete diagnosis. The cut keeps the rung's stages (and, for Recon, only the 8 backbone extraction agents) and prunes dependencies to what survived — otherwise a step would wait forever for one that won't run. Empty stages disappear from the graph.

Steps vs specialists: the billing profile is supplied by the Studio (not an agent) and optional steps that are off don't count.

Several systems and federation

1. One session, one run per repository, all on the same rung, running in parallel.
2. When no run is pending, running or waiting for a decision, and at least two have finished, the Studio creates and starts the federation run on its own.
3. Federation clones nothing: it gets the skills and federation/systems.json with each system's workspace, and reads their artifacts (integrations, technologies, architecture, data, use cases).
4. Federation Mapper → Answer Researcher → the Contact point confirmation stop.
5. Adding a repository to the session marks the federation as stale.

Fluxo · F6

Exemplo: o pedido que nunca é pago

Um passeio pelo fluxo sobre o sistema de exemplo do repositório — dois serviços que conversam e uma regra que só aparece quando os dois são lidos juntos.

O sistema

Dois serviços Node.js sem dependências, ~580 linhas no total:

A sessão

Duas origens (Selecionar pasta em cada projeto), degrau Essencial, motor Claude Code ou Cursor. Dois runs em paralelo; quando os dois terminam, a federação começa sozinha.

O que cada agente encontra

1. Scout — inventory.md: Node 18+, ESM, sem dependências, entrada src/server.js, sem testes, sem banco. Sugere organização por módulo.
2. Extrator de Essência — soul.md: propósito "aceitar pedidos e cobrar o cliente"; entidades Pedido e Pagamento; decisão fundadora: cobrança assíncrona com callback.
3. Arqueólogo — code-analysis.md: as regras de validateOrderInput (cliente e itens obrigatórios, valor positivo, valor ≤ maxOrderAmount, valor = soma dos itens com arredondamento em centavos) e o ciclo de vida do pedido.
4. Detetive — domain.md e state-machines.md: CREATED → AWAITING_PAYMENT → PAID | REJECTED | FAILED, com a regra 🟢 "callback repetido para pedido finalizado é ignorado" (orderService.js, applyPaymentResult).
5. Radar de Tecnologias — Node e node:http/fetch nativos: nada fim de vida, nada a trocar.
6. Mapeador de Integrações — no portal, saída POST /payments e entrada do webhook; no pagamento, o inverso. Header x-callback-secret. Lacuna de segurança: o segredo tem valor padrão escrito no código dos dois lados.
7. Casos de uso — UC-01 Criar pedido (ator: cliente), UC-02 Registrar resultado do pagamento (ator: payment-service), com sequência e exceções (400 inválido, 502 falha ao contatar).
8. Backlog e QA — cards como "Rejeitar pedido cuja soma dos itens difere do valor" com critérios dado/quando/então e testes especificados (feliz: soma confere; borda: diferença de 1 centavo; erro: lista vazia).
9. Revisor — questions.md com lacunas que o código não responde (abaixo).
10. Qualidade — oportunidades como padronizar o segredo compartilhado e cobrir validateOrderInput com testes antes de mexer — 🔴 sem prova de comportamento, porque não há teste nenhum.

As lacunas que param o processo

Na parada Resolução de lacunas, o engenheiro responde com quem conhece o negócio — ou deixa em aberto, e a lacuna segue declarada. Ver E4.

O que só aparece com os dois sistemas juntos

// sample/project_1/src/config.js
maxOrderAmount: Number(process.env.MAX_ORDER_AMOUNT ?? 10000),
callbackSecret: process.env.CALLBACK_SECRET ?? 'segredo-compartilhado-sample',

// sample/project_2/src/config.js
autoApproveLimit: Number(process.env.AUTO_APPROVE_LIMIT ?? 5000),

// sample/project_2/src/paymentProcessor.js
if (payment.amount > config.autoApproveLimit) {
  return { status: 'REJECTED',
           reason: `valor acima do limite de aprovacao automatica (${config.autoApproveLimit})` };
}

O Mapeador de Federação confirma os dois pontos de contato (POST /payments e o callback) com evidência dos dois lados 🟢, e cruza as regras:

É exatamente o tipo de achado que vira item crítico do dossiê, pergunta para o negócio ("existe aprovação manual fora do sistema?") e critério de teste de paridade numa reescrita.

Flow · F6

Example: the order that never gets paid

A walk through the flow on the repository's sample system — two services that talk to each other and a rule that only appears when both are read together.

The system

Two Node.js services with no dependencies, ~580 lines in total:

The session

Two sources (Select folder for each project), Essential rung, Claude Code or Cursor engine. Two runs in parallel; when both finish, federation starts on its own.

What each agent finds

1. Scout — inventory.md: Node 18+, ESM, no dependencies, entry src/server.js, no tests, no database. Suggests organizing by module.
2. Essence Extractor — soul.md: purpose "accept orders and charge the customer"; entities Order and Payment; founding decision: asynchronous charging with a callback.
3. Archaeologist — code-analysis.md: the validateOrderInput rules (customer and items required, positive amount, amount ≤ maxOrderAmount, amount = item total rounded to cents) and the order lifecycle.
4. Detective — domain.md and state-machines.md: CREATED → AWAITING_PAYMENT → PAID | REJECTED | FAILED, with the 🟢 rule "a repeated callback for a finished order is ignored" (orderService.js, applyPaymentResult).
5. Technology Radar — Node with native node:http/fetch: nothing end-of-life, nothing to replace.
6. Integration Mapper — in the portal, outbound POST /payments and the inbound webhook; in payments, the reverse. Header x-callback-secret. Security gap: the secret has a default value hard-coded on both sides.
7. Use cases — UC-01 Create order (actor: customer), UC-02 Record payment result (actor: payment-service), with sequence and exceptions (400 invalid, 502 couldn't reach payments).
8. Backlog and QA — cards like "Reject an order whose item total differs from the amount" with given/when/then criteria and specified tests (happy: totals match; edge: one cent off; error: empty list).
9. Reviewer — questions.md with gaps the code can't answer (below).
10. Quality — opportunities such as standardizing the shared secret and covering validateOrderInput with tests before touching it — 🔴 no proof of behavior, because there are no tests at all.

The gaps that stop the process

At the Gap resolution stop, the engineer answers together with whoever knows the business — or leaves it open, and the gap stays declared. See E4.

What only shows up with both systems together

// sample/project_1/src/config.js
maxOrderAmount: Number(process.env.MAX_ORDER_AMOUNT ?? 10000),
callbackSecret: process.env.CALLBACK_SECRET ?? 'segredo-compartilhado-sample',

// sample/project_2/src/config.js
autoApproveLimit: Number(process.env.AUTO_APPROVE_LIMIT ?? 5000),

// sample/project_2/src/paymentProcessor.js
if (payment.amount > config.autoApproveLimit) {
  return { status: 'REJECTED',
           reason: `valor acima do limite de aprovacao automatica (${config.autoApproveLimit})` };
}

The Federation Mapper confirms both contact points (POST /payments and the callback) with evidence on both sides 🟢, and cross-checks the rules:

This is exactly the kind of finding that becomes a critical dossier item, a question for the business ("is there manual approval outside the system?") and a parity test criterion in a rewrite.

Fluxo · F7

Agentes · Extração do legado

Legenda dos degraus: C Completa · P Profunda · E Essencial · R Reconhecimento.

Os 18 agentes da primeira faixa, na ordem em que rodam. É a faixa presente em todos os degraus e a que alimenta todas as outras.

Flow · F7

Agents · Legacy extraction

Rung legend: C Complete · P Deep · E Essential · R Recon.

The 18 agents of the first stage, in running order. It's the stage present in every rung and the one that feeds all the others.

Fluxo · F8

Agentes · Qualidade, Documentação e Preço

Legenda dos degraus: C Completa · P Profunda · E Essencial · R Reconhecimento.

A "ponte da extração" são os agentes da primeira faixa de que ninguém depende (Extrator de Essência, Radar de Tecnologias e Arquiteto de Refatoração): as faixas seguintes começam quando eles terminam.

Flow · F8

Agents · Quality, Documentation and Pricing

Rung legend: C Complete · P Deep · E Essential · R Recon.

The "extraction bridge" is the first-stage agents nobody depends on (Essence Extractor, Technology Radar and Refactoring Architect): the following stages start when they finish.

Fluxo · F9

Agentes · Migração e Reconstrução

Legenda dos degraus: C Completa · P Profunda · E Essencial · R Reconhecimento.

Flow · F9

Agents · Migration and Reconstruction

Rung legend: C Complete · P Deep · E Essential · R Recon.

Fluxo · F10

Agentes · Federação e sob demanda

Estes não fazem parte de nenhum degrau: rodam no run de federação ou quando alguém clica um botão numa aba. Um por vez por run; o custo entra no total.

Flow · F10

Agents · Federation and on demand

These aren't part of any rung: they run in the federation run or when someone clicks a tab button. One at a time per run; their cost is added to the total.

Fluxo · F11

Catálogo além do Studio

A tela do Studio lança só o diagnóstico (quatro degraus), a federação e os agentes sob demanda. O restante do catálogo é usado pela CLI, direto no chat do CLI de IA, dentro do projeto real:

node bin/cli.js install      # instala os agentes no projeto atual
# depois, no chat do CLI: /lubylegado-forward, /lubylegado-refactor, /lubylegado-debugger…

Flow · F11

Catalog beyond the Studio

The Studio screen launches only the diagnosis (four rungs), federation and on-demand agents. The rest of the catalog is used through the CLI, directly in the AI CLI's chat, inside the real project:

node bin/cli.js install      # installs the agents into the current project
# then, in the CLI chat: /lubylegado-forward, /lubylegado-refactor, /lubylegado-debugger…

Trilha 2 · Comercial · 2.1

Abordagem

O serviço é um processo de engenharia com evidência, conduzido pela Luby sobre um sistema legado: primeiro a especificação do que existe, depois as alterações, cada uma verificada contra o comportamento registrado.

O princípio

Alterar um sistema exige conhecer o comportamento atual dele. A especificação vem antes da mudança.

Uma reescrita sem especificação tende a omitir regras que só existiam no código original. Uma refatoração sem testes de caracterização não tem como demonstrar que o comportamento foi preservado. Nos dois casos, a mudança começa antes de o comportamento atual estar registrado. O primeiro passo é extrair a especificação do que existe.

As etapas

1. Estado inicial. O comportamento do sistema não está especificado nem coberto por testes.
2. Especificação. Descobrir — o comportamento é extraído do código, com evidência e nível de confiança.
3. Verificação. Provar — testes de caracterização registram o comportamento antes de qualquer alteração.
4. Evolução. Transformar — cada mudança é aprovada, verificada e reversível.

Os três atos

A frase-invariante

Propor uma transformação e aplicá-la são atos separados. Nada toca o legado sem prova de preservação de comportamento.

Track 2 · Sales · 2.1

Approach

The service is an engineering process with evidence, run by Luby on a legacy system: first the specification of what exists, then the changes, each one verified against the recorded behavior.

The principle

Changing a system requires knowing its current behavior. The specification comes before the change.

A rewrite without a specification tends to omit rules that only existed in the original code. A refactoring without characterization tests cannot demonstrate that behavior was preserved. In both cases the change starts before the current behavior is recorded. The first step is to extract the specification of what exists.

The stages

1. Initial state. The system's behavior is neither specified nor covered by tests.
2. Specification. Discover — behavior is extracted from the code, with evidence and a confidence level.
3. Verification. Prove — characterization tests record behavior before any change.
4. Evolution. Transform — each change is approved, verified and reversible.

The three acts

The invariant

A proposed transformation and an applied transformation are two different steps. Nothing touches the legacy system without proof that behavior was preserved.

Trilha 2 · Comercial · 2.2

Contextos de aplicação

O diagnóstico se aplica a sistemas críticos para a operação cujo comportamento não está inteiramente especificado. O material produzido é técnico; parte dele é lida também por quem decide sem perfil técnico.

Perfil de empresa

• Sistema de negócio crítico com anos de vida (receita, operação, regulatório passam por ele).
• Concentração de conhecimento: a equipe que construiu o sistema não está mais disponível, ou o conhecimento depende de poucas pessoas.
• Setores com legado pesado e regra de negócio densa: financeiro, meios de pagamento, seguros, saúde, varejo, logística, governo.
• Momento de decisão: modernização, aquisição/fusão, troca de fornecedor, fim de vida de tecnologia, auditoria.

Personas

Indicadores de débito técnico

Quando não é para nós

• Quer um botão "modernizar tudo" sem participar das decisões.
• Quer só auditoria de código, lint ou lista de bugs.
• Sistema pequeno, bem testado, com o time original presente — o ganho é baixo.
• Não pode dar acesso ao código em nenhuma modalidade.

Track 2 · Sales · 2.2

Application contexts

The diagnosis applies to business-critical systems whose behavior is not fully specified. The material produced is technical; part of it is also read by decision makers without a technical background.

Company profile

• A business-critical system that's years old (revenue, operations or compliance runs through it).
• Concentrated knowledge: the team that built the system is no longer available, or knowledge depends on a few people.
• Industries with heavy legacy and dense business rules: financial services, payments, insurance, healthcare, retail, logistics, government.
• A decision moment: modernization, acquisition/merger, vendor change, technology end of life, audit.

Personas

Technical debt indicators

When it isn't for us

• They want a "modernize everything" button without taking part in the decisions.
• They only want a code audit, lint or a bug list.
• A small, well-tested system with the original team still there — the gain is low.
• They can't grant access to the code in any form.

Trilha 2 · Comercial · 2.3

Casos de uso

21 situações de aplicação do Studio Legado, cada uma com o indicador que a identifica, o degrau recomendado, as telas que mostram a evidência, o que ele entrega, onde para e o que o mercado diz.

Cada caso cruza três coisas: o sinal que aparece na conversa, o que o Studio entrega de fato (verificado no código) e o que o mercado diz, com fonte e ano. Onde o Studio para e começa a engenharia, está escrito — e os limites também.

Mapa rápido

Modernização e arquitetura

Aplicativos e produto

Testes e qualidade

IA no desenvolvimento

Negócio, risco e compliance

Time, integração e operação