Agent Loom
z3z1ma/agent-loom
Estrutura durável para sessões de codificação com agentes IA
Ver no GitHubProtocolo Markdown-nativo que converte sessões de codificação com IA em artefatos de engenharia duráveis e auditáveis. Estrutura o trabalho dos agentes capturando decisões, especificações, testes, reviews e lições em arquivos organizados dentro do repositório, eliminando o contexto perdido em chats efêmeros.
Instalação
npx convez-ai z3z1ma/agent-loom1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Documentar decisões e contexto de trabalho com agentes de codificação
- Criar trilha auditável de tarefas, specs e reviews de código
- Permitir continuidade entre múltiplas sessões e subagentes
- Reutilizar artefatos de engenharia em projetos futuros
Veredito

Skill sólida que resolve um problema real: a perda de contexto em fluxos de agentes de IA. Implementação pragmática via Markdown puro, sem dependências, integrando-se naturalmente em IDEs modernas. Ideal para equipes que precisam de auditoria e continuidade em trabalho automatizado.
README
A tradução para o português deste README ainda está na fila.
Agent loom
The missing middle between prompt and patch.

Coding agents perform better when the work has an explicit structure.
While agents are great at writing patches, the critical software engineering context often vanishes inside ephemeral chat threads. This includes intent, lingering uncertainty, core scope, empirical evidence, code reviews, handoffs, and long-term lessons.
Agent Loom brings that work directly into your repository. It converts a standard coding session into durable Markdown records across several surfaces: decisions, research, specs, tickets, evidence, reviews, and knowledge.
This introduces a deliberate loop: shape vague ideas with a human before writing code, break complex tasks into parent and child tickets, execute via focused subagents, and only declare victory when supported by concrete evidence and reviews.
The chat session can be discarded, but the resulting engineering artifacts continue to compound.
The idea
Most failures with coding agents stem from broken processes. A model often jumps straight from a prompt to a patch, leaving the foundational engineering work trapped inside the chat interface.
Loom forces the agent to externalize this context as it works, capturing:
- Intended behavior and technical specs
- Unresolved edge cases or structural uncertainty
- Active task scope boundaries
- Attempted solutions and documented dead ends
- Test observations, outputs, and system logs
- Peer review challenges and lingering risks
- Reusable lessons for future sessions
These records live directly inside the .loom/ directory. The agent can read, update, link, and hand them off to subagents, maintaining perfect continuity even after hitting context windows or starting a new session.
The structured forms guide the model, while humans get a clean audit trail.
Try it
Copy PROTOCOL.md into your project's AGENTS.md, CLAUDE.md, or equivalent rules file, then begin interacting with your coding agent. Records will automatically generate in .loom/ as the agent executes tasks.
Alternatively, install the protocol using the skills ecosystem:
npx skills add z3z1ma/agent-loom
Installing
Copy-paste (recommended)
Copy the contents of PROTOCOL.md into the file your agent references for instructions:
| Harness | File |
|---|---|
| OpenCode | AGENTS.md |
| Claude Code | CLAUDE.md |
| Cursor | .cursor/rules/loom.md or project rules |
| Codex | AGENTS.md |
| Gemini CLI | GEMINI.md |
| Others | The custom instruction file read by your agent |
This approach requires zero dependencies or specialized tooling and works across any environment.
Skills ecosystem
npx skills add z3z1ma/agent-loom
This uses the Vercel skills CLI to add Loom to your agent's local skill directory. It supports dozens of environments, including OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, and Roo Code.
# Install globally across all projects
npx skills add z3z1ma/agent-loom -g
# Target specific agents explicitly
npx skills add z3z1ma/agent-loom -a claude-code -a opencode
# Run non-interactively
npx skills add z3z1ma/agent-loom -g -a claude-code -y
First-class harness support
Native plugin manifests are available for direct marketplace installation:
| Harness | Install command |
|---|---|
| Claude Code | claude plugin marketplace add z3z1ma/agent-loom |
| Cursor | Install via Cursor marketplace or clone to ~/.cursor/plugins/local/agent-loom |
| Gemini CLI | gemini extensions install https://github.com/z3z1ma/agent-loom |
| Codex | codex plugin marketplace add z3z1ma/agent-loom |
| OpenCode | Add "@z3z1ma/agent-loom" to your config plugins list |
After installation
The protocol handles the rest. Initiate the workflow with a straightforward prompt:
Let's shape this feature before building it.
The agent will start generating tracking records inside .loom/.
The shape
flowchart TB
Goal["human goal"]
Goal --> Outer["outer loop: shape intent into records"]
Outer --> Tickets["tickets bridge to execution"]
Tickets --> Inner["inner loop: subagent · evidence · review"]
Inner -->|"done"| Knowledge["knowledge compounds"]
Inner -->|"new scope"| Outer
Loom relies on two loops joined by a bridge. The outer loop structures vague intent into clear, written records. The inner loop executes tightly bounded tickets, producing empirical evidence that faces adversarial review. Discoveries feed back into the system, allowing knowledge to compound over time.
Simple, single-line edits do not need this overhead. The record graph shows its value when dealing with architectural ambiguity, technical risk, asynchronous handoffs, rigorous review constraints, or long-term knowledge retention.
What changes
Loom introduces deliberate friction at the exact points where AI agents typically struggle:
- The outer loop prioritizes active shaping over immediate code patching.
- Specs decouple intended behavior from implementation guesswork.
- Tickets keep scope, acceptance criteria, and progress synchronized.
- Evidence isolates objective observations from subjective model assertions.
- Reviews provide an adversarial challenge to code quality and assumptions.
- Knowledge retains verified lessons in a searchable format.
- Subagents stay bounded while tickets supply necessary context.
The record surfaces
| Surface | Job |
|---|---|
| decisions | Durable choices, constraints, and tradeoffs using the Architecture Decision Record (ADR) format |
| research | Technical investigations, consulted sources, documented dead ends, and syntheses |
| specs | Intended system behavior, requirements, functional scenarios, and interface sketches |
| tickets | Bounded units of work containing scope, explicit acceptance criteria, and progress logs |
| evidence | Observed facts, terminal outputs, reproduction steps, screenshots, and system logs |
| reviews | Adversarial critiques highlighting specific findings, verdicts, and residual risks |
| knowledge | Shared project vocabulary, architectural conventions, operational procedures, and troubleshooting |
flowchart TB
A["agent does software work"] --> B{"what should be durable?"}
B -->|choice, constraint, tradeoff| D["decisions"]
B -->|uncertainty, investigation| R["research"]
B -->|intended behavior, scenario| S["specs"]
B -->|bounded work, progress| T["tickets"]
B -->|observed output, test, log| E["evidence"]
B -->|adversarial critique, risk| V["reviews"]
B -->|reusable context, vocabulary| K["knowledge"]
D --> G[".loom/ record graph"]
R --> G
S --> G
T --> G
E --> G
V --> G
K --> G
G --> T
T --> Sub["subagent"]
Sub --> E
Sub --> T
E --> V
V --> T
When it helps
Deploy Loom when project context needs to survive across sessions:
- Complex behavioral shifts where original intent must be preserved
- Bug fixes requiring deep root-cause analysis or reliable reproduction steps
- Multi-step engineering tasks that need to be broken down into parent and child tickets
- Development tasks spanning multiple sessions, different models, or separate AI harnesses
- Work requiring verified proof through tests, logs, or screenshots
- Code review findings or lingering risks that must outlive the immediate chat window
- Engineering lessons that future agents should immediately look up and reuse
For obvious, straightforward modifications, bypass Loom and use standard Git workflows directly.
Loom mill
Loom Mill is a companion application providing a visual interface for your .loom/ record graph, covering shaping sessions, ticket visualization, and live execution observation. The app reads and writes the exact same Markdown records defined by the core protocol.
Refer to loom-mill/ for additional details.
Repository layout
.
├── PROTOCOL.md : Core protocol file to copy into harness instructions
├── skills/loom/SKILL.md : The same protocol packaged as an installable skill
├── .claude-plugin/ : Marketplace manifest for Claude Code
├── .cursor-plugin/ : Marketplace manifest for Cursor
├── .agents/plugins/ : Marketplace manifest for Codex and OpenCode
├── gemini-extension.json : Extension manifest for the Gemini CLI
├── loom-mill/ : Source folder for the companion visual application
└── .loom/ : Local dogfood records tracking this repository
For agents
If you are an AI coding agent reading this README to install or configure Loom, follow these steps:
- Copy the contents of
PROTOCOL.mdfrom this repository directly into the project's instruction file (AGENTS.md,CLAUDE.md, or equivalent). This is the preferred implementation method. - Run
npx skills add z3z1ma/agent-loomto install the protocol directly into your active skills directory as an alternative method. - The protocol is entirely self-contained once loaded. Read the existing
.loom/directory if it is present. If no directory exists, trigger the outer loop whenever a user request carries ambiguity worth documenting.
The short version
The prompt-to-patch pipeline is too fragile for complex software engineering.
Loom equips coding agents with a structured memory layer for the context that typically disappears: intent, scope, empirical evidence, peer reviews, clean handoffs, and reusable knowledge.
Code transitions smoothly between agents and human developers, allowing engineering work to progress reliably.