User manual
A field manual for governed coding agents.
A practical guide for installing, updating, and auditing Tilly Engineer Skills in real projects without blind file copying.
Overview
Tilly Engineer Skills installs a governance mesh for coding agents. Codex, Claude Code, and Cursor route through adapter-specific surfaces while project truth lives in versioned Markdown.
Quick install
Start from the target repository with GitHub npx. The command installs TES locally, prepares selected agent hooks, and records the first-session setup path.
npx --loglevel=error -y --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yesbunx --silent --bun --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yes- Run the command from the target repository with Node.js 18+ or Bun 1.0+, plus Python 3.11+.
- Interactive mode asks for target, agents, install mode, and final confirmation.
- Codex: open Settings > Hooks, then Trust and enable the Session Start hook if it is marked needs review.
- Claude Code: open or reopen Claude Code, wait for the TES completion notice, then run
/tes-setup. - Cursor: reopen the workspace, let first-session setup complete, then run
/tes-setupfor the report. - The first-session hook starts setup, project context, and alignment gates once; repeated complete hooks exit quickly.
- Please, run
/tes-setupfor the report before asking for commit or push.
Useful options: --target <path> installs outside the current directory; --agent codex|claude|cursor|all chooses hooks; --yes skips the wizard; --dry-run prints planned writes; --mode preserve is the default.
#v0.3.105 is the supported fixed release ref. Runtime bundles stage under .tes/setup/<version>/; that directory is local cache, not project knowledge to commit. If neither Node/npm nor Bun is installed, install Node.js LTS or Bun first.
Command triggers
Triggers are intent text for the active agent. They are not shell commands.
| Intent | Use for | Write behavior |
|---|---|---|
/tes-init / /tes-setup | Install, recertify, initialize project context, or show the first-session report. | May write TES runtime files and docs/agents/** after gates pass. |
/tes-update / /tes:update | Update an existing mesh through tes_update.py. | Starts with helper-only Layer Zero, then adapter-config only if gates pass. |
/tes-align | Deepen project context into state, gates, glossary, and decisions. | Writes operating mesh files under docs/agents/**. |
/tes-map / /tes:gps | Show the current Project GPS: position, blockers, proof, and next move. | Updates only the managed TES-MAP block in PROJECT-ROADMAP.md. |
/tes-prospect | Explicitly stress-test a plan or design with predictive project pressure. | No project writes; cognitive brake pauses the pressure. |
/tes-mine | Explicitly mine code, terminology, context, and ADR candidates. | May write CONTEXT.md or ADRs only when resolved and not braked. |
/tes-cortex | Inspect, recall, audit, learn from, or reflect into Cortex. | Memory writes require explicit authorization and evidence. |
/tes-mcp | Activate or verify read-only Cortex MCP. | May write project-scoped MCP config and TES helpers. |
/tes-field-reports | Inspect, drain, disable, or enable sanitized reports. | May update .tes/field-reports/** and the local pre-push hook. |
/tes-prospect and /tes-mine are explicit predictive skills. They stay dormant until named, then may drive project-stress prospecting or code mining proactively. Use the cognitive brake (pause, hold, resuma onde estamos) to stop pressure and receive the current state before resuming.
Full trigger contract: COMMAND-TRIGGERS.md.
Routes
The route decides which runtime surfaces move.
| Route | When to use it |
|---|---|
current | Update the detected runtime and its read-only Cortex MCP config. |
codex | Prepare AGENTS.md, Codex skills, plugin metadata, and .codex/config.toml. |
claude | Prepare CLAUDE.md, .claude/skills/**, plugin skills, and .mcp.json. |
cursor | Prepare .cursor/rules/** and .cursor/mcp.json. |
all | Prepare all supported runtime surfaces. |
audit | Inspect without modifying files. |
Project states
The state decides whether the run installs, updates, audits, or recovers.
| State | Meaning |
|---|---|
new | No relevant agent instructions exist. TES creates the minimum mesh. |
existing | Local rules already exist. TES creates backup, installs clean runtime, and recovers useful semantics. |
meshed | TES already exists. The run becomes update or convergence. |
Existing instructions are backed up and useful semantics are recovered instead of discarded.
Cortex
Cortex is filesystem-first memory. Markdown is the contract; SQLite recall is a derived access path.
Cortex lives under docs/agents/cortex/**. Every durable claim needs evidence. Agents may propose memory, but writes require explicit authorization.
You can read Cortex like any repository document, review it in pull requests, and revert it with Git.
What the agent runs
The user asks in natural language; the agent executes the smallest safe oracle and reports the result.
- Step Zero runs first and records the baseline before any write.
- Unsafe or unavailable commands are reported as
BLOCKEDorNEEDS_REVIEW, not hidden. - The final report is the contract. Read it before approving commit or push.
/tes-update repairs bundle helpers first, then touches adapter-config only after post-Layer Zero checks pass.
MCP
Cortex MCP is read-only and project-scoped. It gives the agent recall without write authority.
| Runtime | Config file |
|---|---|
| Codex | .codex/config.toml |
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
The MCP surface can verify, audit, recall, read cells, plan absorbs, plan curation, and reflect. It cannot write memory.
Field Reports
Field Reports help TES learn from real installations without exporting project content.
Reports capture sanitized operational facts and drain only during git push when GitHub CLI, authentication, and network are available. If any link is missing, nothing leaves the machine and push proceeds normally.
/tes:field-reports:disable/tes:field-reports:enableObsidian
Obsidian is an optional visual workbench over Markdown. It is not a runtime dependency and not proof by itself.
- Open
docs/agents/as the vault for the full mesh. - Open
docs/agents/cortex/alone for focused memory work. - Keep Markdown links readable outside Obsidian and avoid Obsidian-only proof.
Final report
The final report is the user-facing contract. Read it before approving commit or push.
It records status, source snapshot freshness, source_package_commit, source_remote_head, source_freshness, STALE_SOURCE, Current public bundles, the installed helper set, Field Reports state, root context gate, changed files, rollback summary, and whether the run was certified against the recorded snapshot.
Important statuses include RECOVERED, NEEDS_REVIEW, BLOCKED, DEGRADED, PASS, and STALE_SOURCE. A backup under .tes/bk/<timestamp> is rollback evidence, not a new TES surface.
Rollback
Rollback should be boring. TES tells you the baseline and the installer-created files so you can undo the run with Git.
git reset --hard <baseline-head>
git clean -fd -- .tes/setup/<version>Do not reset blindly if unrelated user work exists. Ask the agent to explain the changed-file inventory and the clean backup first.
Manual de usuario
Un manual de campo para agentes de codigo gobernados.
Una guia practica para instalar, actualizar y auditar Tilly Engineer Skills en proyectos reales sin copia ciega de archivos.
Vista general
Tilly Engineer Skills instala un mesh de gobernanza para agentes de codigo. Codex, Claude Code y Cursor pasan por superficies especificas mientras la verdad del proyecto vive en Markdown versionado.
Instalacion rapida
Empieza desde el repositorio objetivo con npx desde GitHub. El comando instala TES localmente, prepara los hooks de agentes seleccionados y registra el camino de setup de primera sesion.
npx --loglevel=error -y --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yesbunx --silent --bun --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yes- Ejecuta el comando desde el repositorio objetivo con Node.js 18+ o Bun 1.0+, mas Python 3.11+.
- El modo interactivo pregunta target, agentes, modo de instalacion y confirmacion final.
- Codex: abre Settings > Hooks, luego usa Trust y activa el hook Session Start si aparece como needs review.
- Claude Code: abre o reabre Claude Code, espera el aviso de finalizacion de TES y ejecuta
/tes-setup. - Cursor: reabre el workspace, deja que el setup de primera sesion termine y ejecuta
/tes-setuppara el reporte. - El hook de primera sesion inicia setup, contexto de proyecto y gates de alineacion una vez; los hooks completos repetidos salen rapido.
- Lee el reporte final antes de pedir commit o push.
Opciones utiles: --target <path> instala fuera del directorio actual; --agent codex|claude|cursor|all elige hooks; --yes salta el wizard; --dry-run muestra escrituras planificadas; --mode preserve es el default.
#v0.3.105 es el release ref fijo soportado. Los bundles runtime se preparan bajo .tes/setup/<version>/; ese directorio es cache local, no conocimiento del proyecto para commitear. Si no hay Node/npm ni Bun instalado, instala Node.js LTS o Bun primero.
Gatillos de comando
Los gatillos son texto de intencion para el agente activo. No son comandos de shell.
| Intencion | Uso | Escritura |
|---|---|---|
/tes-init / /tes-setup | Instalar, recertificar, inicializar contexto o mostrar el reporte de primera sesion. | Puede escribir runtime TES y docs/agents/** despues de gates. |
/tes-update / /tes:update | Actualizar un mesh existente mediante tes_update.py. | Empieza con helper-only Layer Zero y luego adapter-config si pasan gates. |
/tes-align | Profundizar estado, gates, glosario y decisiones. | Escribe el mesh operativo en docs/agents/**. |
/tes-map / /tes:gps | Muestra el Project GPS actual: posicion, bloqueos, prueba y siguiente movimiento. | Actualiza solo el bloque gestionado TES-MAP en PROJECT-ROADMAP.md. |
/tes-prospect | Estresar explicitamente un plan o diseno con presion predictiva de proyecto. | No escribe archivos; el freno cognitivo pausa la presion. |
/tes-mine | Minar explicitamente codigo, terminologia, contexto y candidatos ADR. | Puede escribir CONTEXT.md o ADRs solo cuando esten resueltos y sin freno activo. |
/tes-cortex | Inspeccionar, recordar, auditar, aprender o reflexionar en Cortex. | Escrituras de memoria requieren autorizacion y evidencia. |
/tes-mcp | Activar o verificar Cortex MCP read-only. | Puede escribir config MCP con escopo de proyecto y helpers TES. |
/tes-field-reports | Inspeccionar, drenar, desactivar o activar reportes sanitizados. | Puede actualizar .tes/field-reports/** y el hook pre-push local. |
/tes-prospect y /tes-mine son skills predictivas de invocacion explicita. Permanecen dormidas hasta ser nombradas, luego pueden conducir proactivamente la prospeccion de estres de proyecto o la mineria de codigo. Usa el freno cognitivo (pausa, hold, resuma onde estamos) para detener la presion y recibir el estado actual antes de retomar.
Contrato completo: COMMAND-TRIGGERS.md.
Rutas
La ruta decide que superficies se mueven.
| Ruta | Cuando usarla |
|---|---|
current | Actualizar el runtime detectado y su config Cortex MCP read-only. |
codex | Preparar AGENTS.md, skills Codex, plugin metadata y .codex/config.toml. |
claude | Preparar CLAUDE.md, .claude/skills/**, plugin skills y .mcp.json. |
cursor | Preparar .cursor/rules/** y .cursor/mcp.json. |
all | Preparar todas las superficies soportadas. |
audit | Inspeccionar sin modificar archivos. |
Estados del proyecto
El estado decide si el run instala, actualiza, audita o recupera.
| Estado | Significado |
|---|---|
new | No hay instrucciones relevantes de agente. TES crea el mesh minimo. |
existing | Ya existen reglas locales. TES crea backup, instala runtime limpio y recupera semantica util. |
meshed | TES ya existe. La ejecucion pasa a update o convergence. |
Instrucciones existentes se respaldan y la semantica util se recupera, no se descarta.
Cortex
Cortex es memoria filesystem-first. Markdown es el contrato; recall SQLite es un acceso derivado.
Cortex vive en docs/agents/cortex/**. Todo claim durable necesita evidencia. Los agentes pueden proponer memoria, pero las escrituras requieren autorizacion explicita.
Puedes leer Cortex como cualquier documento del repositorio, revisarlo en pull requests y revertirlo con Git.
Lo que ejecuta el agente
El usuario pide en lenguaje natural; el agente ejecuta el menor oraculo seguro y reporta el resultado.
- Step Zero corre primero y registra el baseline antes de cualquier escritura.
- Comandos inseguros o no disponibles se reportan como
BLOCKEDoNEEDS_REVIEW, no se esconden. - El reporte final es el contrato. Leelo antes de aprobar commit o push.
/tes-update repara primero los helpers del bundle y luego toca adapter-config solo si pasan los checks post-Layer Zero.
MCP
Cortex MCP es read-only y con escopo de proyecto. Da recall al agente sin autoridad de escritura.
| Runtime | Config |
|---|---|
| Codex | .codex/config.toml |
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
La superficie MCP puede verificar, auditar, recordar, leer cells, planear absorbs, planear curadoria y reflect. No puede escribir memoria.
Field Reports
Field Reports ayuda a TES a aprender de instalaciones reales sin exportar contenido del proyecto.
Los reportes capturan hechos operativos sanitizados y drenan solo durante git push cuando GitHub CLI, autenticacion y red estan disponibles. Si falta algo, nada sale de la maquina y el push continua.
/tes:field-reports:disable/tes:field-reports:enableObsidian
Obsidian es un workbench visual opcional sobre Markdown. No es dependencia de runtime ni prueba por si mismo.
- Abre
docs/agents/como vault para el mesh completo. - Abre
docs/agents/cortex/para trabajo de memoria enfocado. - Mantiene links Markdown legibles fuera de Obsidian y evita prueba solo-Obsidian.
Reporte final
El reporte final es el contrato visible para el usuario. Leelo antes de aprobar commit o push.
Registra estado, source snapshot freshness, source_package_commit, source_remote_head, source_freshness, STALE_SOURCE, Current public bundles, installed helper set, Field Reports state, root context gate, archivos cambiados, rollback summary y si el run fue certified against the recorded snapshot.
Estados importantes: RECOVERED, NEEDS_REVIEW, BLOCKED, DEGRADED, PASS y STALE_SOURCE. Un backup en .tes/bk/<timestamp> es evidencia de rollback, no una nueva superficie TES.
Rollback
Rollback debe ser aburrido. TES informa el baseline y los archivos creados por el instalador para que puedas deshacer con Git.
git reset --hard <baseline-head>
git clean -fd -- .tes/setup/<version>No hagas reset a ciegas si existe trabajo no relacionado. Pide al agente el inventario de cambios y el clean backup primero.
Manual do usuario
Um manual de campo para agentes de codigo governados.
Um guia pratico para instalar, atualizar e auditar Tilly Engineer Skills em projetos reais sem copia cega de arquivos.
Visao geral
Tilly Engineer Skills instala uma malha de governanca para agentes de codigo. Codex, Claude Code e Cursor passam por superficies especificas enquanto a verdade do projeto vive em Markdown versionado.
Instalacao rapida
Comece pelo repositorio alvo com npx direto do GitHub. O comando instala TES localmente, prepara os hooks dos agentes escolhidos e registra o caminho de setup da primeira sessao.
npx --loglevel=error -y --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yesbunx --silent --bun --package github:murillodutt/tilly-engineer-skills#v0.3.105 tilly-engineer-skills add --agent all --yes- Rode o comando a partir do repositorio alvo com Node.js 18+ ou Bun 1.0+, mais Python 3.11+.
- O modo interativo pergunta target, agentes, modo de instalacao e confirmacao final.
- Codex: abra Settings > Hooks, depois use Trust e ative o hook Session Start se ele aparecer como needs review.
- Claude Code: abra ou reabra o Claude Code, aguarde o aviso de conclusao do TES e rode
/tes-setup. - Cursor: reabra o workspace, deixe o setup de primeira sessao terminar e rode
/tes-setuppara o relatorio. - O hook de primeira sessao inicia setup, contexto do projeto e gates de alinhamento uma vez; hooks completos repetidos saem rapido.
- Leia o relatorio final antes de pedir commit ou push.
Opcoes uteis: --target <path> instala fora do diretorio atual; --agent codex|claude|cursor|all escolhe hooks; --yes pula o wizard; --dry-run mostra escritas planejadas; --mode preserve e o default.
#v0.3.105 e o release ref fixo suportado. Bundles runtime sao preparados em .tes/setup/<version>/; esse diretorio e cache local, nao conhecimento do projeto para commit. Se nao houver Node/npm nem Bun instalado, instale Node.js LTS ou Bun primeiro.
Gatilhos de comando
Gatilhos sao texto de intencao para o agente ativo. Nao sao comandos de shell.
| Intencao | Uso | Escrita |
|---|---|---|
/tes-init / /tes-setup | Instalar, recertificar, inicializar contexto ou mostrar o relatorio de primeira sessao. | Pode escrever runtime TES e docs/agents/** depois dos gates. |
/tes-update / /tes:update | Atualizar um mesh existente por tes_update.py. | Comeca com helper-only Layer Zero e depois adapter-config se gates passarem. |
/tes-align | Aprofundar estado, gates, glossario e decisoes. | Escreve a malha operacional em docs/agents/**. |
/tes-map / /tes:gps | Mostra o Project GPS atual: posicao, bloqueios, prova e proximo movimento. | Atualiza apenas o bloco gerenciado TES-MAP em PROJECT-ROADMAP.md. |
/tes-prospect | Estressar explicitamente um plano ou design com pressao preditiva de projeto. | Nao escreve arquivos; o freio cognitivo pausa a pressao. |
/tes-mine | Minerar explicitamente codigo, terminologia, contexto e candidatos ADR. | Pode escrever CONTEXT.md ou ADRs apenas quando resolvidos e sem freio ativo. |
/tes-cortex | Inspecionar, lembrar, auditar, aprender ou refletir no Cortex. | Escritas de memoria exigem autorizacao explicita e evidencia. |
/tes-mcp | Ativar ou verificar Cortex MCP somente leitura. | Pode escrever config MCP com escopo de projeto e helpers TES. |
/tes-field-reports | Inspecionar, drenar, desativar ou ativar relatorios sanitizados. | Pode atualizar .tes/field-reports/** e o hook pre-push local. |
/tes-prospect e /tes-mine sao skills preditivas de invocacao explicita. Ficam dormentes ate serem nomeadas, depois podem conduzir proativamente prospeccao de estresse de projeto ou mineracao de codigo. Use o freio cognitivo (pausa, freia, resuma onde estamos) para parar a pressao e receber o estado atual antes de retomar.
Contrato completo: COMMAND-TRIGGERS.md.
Rotas
A rota decide quais superficies se movem.
| Rota | Quando usar |
|---|---|
current | Atualizar o runtime detectado e sua config Cortex MCP somente leitura. |
codex | Preparar AGENTS.md, skills Codex, plugin metadata e .codex/config.toml. |
claude | Preparar CLAUDE.md, .claude/skills/**, plugin skills e .mcp.json. |
cursor | Preparar .cursor/rules/** e .cursor/mcp.json. |
all | Preparar todas as superficies suportadas. |
audit | Inspecionar sem modificar arquivos. |
Estados do projeto
O estado decide se o run instala, atualiza, audita ou recupera.
| Estado | Significado |
|---|---|
new | Sem instrucoes relevantes de agente. TES cria a malha minima. |
existing | Ja existem regras locais. TES cria backup, instala runtime limpo e recupera semântica útil. |
meshed | TES ja existe. A execucao vira update ou convergence. |
Instrucoes existentes sao salvas em backup e a semântica útil e recuperada, nao descartada.
Cortex
Cortex e memoria filesystem-first. Markdown e o contrato; recall SQLite e um acesso derivado.
Cortex vive em docs/agents/cortex/**. Todo claim duravel precisa de evidencia. Agentes podem propor memoria, mas escritas exigem autorizacao explicita.
Voce le o Cortex como qualquer documento do repositorio, revisa em pull requests e reverte com Git.
O que o agente executa
O usuario pede em linguagem natural; o agente executa o menor oraculo seguro e reporta o resultado.
- Step Zero roda primeiro e registra o baseline antes de qualquer escrita.
- Comandos inseguros ou indisponiveis aparecem como
BLOCKEDouNEEDS_REVIEW, nao ficam escondidos. - O relatorio final e o contrato. Leia antes de aprovar commit ou push.
/tes-update repara primeiro os helpers do bundle e depois toca adapter-config apenas se os checks post-Layer Zero passarem. O probe compara versão instalada e versão na nuvem, paridade de contrato dos helpers, runtime_trigger_status, recommended_route, recommended_update_scope, legacy_retirement_required e self_test_mode antes de qualquer GO.
MCP
Cortex MCP e somente leitura e com escopo de projeto. Ele da recall ao agente sem autoridade de escrita.
| Runtime | Config |
|---|---|
| Codex | .codex/config.toml |
| Claude Code | .mcp.json |
| Cursor | .cursor/mcp.json |
A superficie MCP pode verificar, auditar, lembrar, ler cells, planejar absorbs, planejar curadoria e refletir. Nao pode escrever memoria.
Field Reports
Field Reports ajuda TES a aprender com instalacoes reais sem exportar conteudo do projeto.
Os relatorios capturam fatos operacionais sanitizados e drenam apenas durante git push quando GitHub CLI, autenticacao e rede estao disponiveis. Se faltar qualquer elo, nada sai da maquina e o push continua.
/tes:field-reports:disable/tes:field-reports:enableObsidian
Obsidian e uma bancada visual opcional sobre Markdown. Nao e dependencia de runtime nem prova por si so.
- Abra
docs/agents/como vault para a malha completa. - Abra
docs/agents/cortex/para trabalho focado de memoria. - Mantenha links Markdown legiveis fora do Obsidian e evite prova que so existe no Obsidian.
Relatorio final
O relatorio final e o contrato visivel para o usuario. Leia antes de aprovar commit ou push.
Ele registra status, frescor do snapshot fonte, source_package_commit, source_remote_head, source_freshness, STALE_SOURCE, Current public bundles, helper set instalado, estado do Field Reports, gate de contexto raiz, arquivos alterados, resumo de rollback e se o run foi certificado contra o snapshot registrado.
Estados importantes incluem RECOVERED, NEEDS_REVIEW, BLOCKED, DEGRADED, PASS e STALE_SOURCE. Um backup em .tes/bk/<timestamp> e evidencia de rollback, nao uma nova superficie TES.
Rollback
Rollback deve ser entediante. TES informa o baseline e os arquivos criados pelo instalador para voce desfazer com Git.
git reset --hard <baseline-head>
git clean -fd -- .tes/setup/<version>Nao faca reset as cegas se houver trabalho de usuario nao relacionado. Peca ao agente o inventario de arquivos alterados e o clean backup primeiro.