convez.ai
SkillAutomaçãoIntermediário
z3z1ma

Agent Loom

z3z1ma/agent-loom

Estrutura durável para sessões de codificação com agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

Protocolo 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-loom

1 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

Estrelas
23
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 4 meses
Versão
v1.1.0
Issues abertas
1
Contribuidores
1

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.

Loom banner

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.

Protocol

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:

HarnessFile
OpenCodeAGENTS.md
Claude CodeCLAUDE.md
Cursor.cursor/rules/loom.md or project rules
CodexAGENTS.md
Gemini CLIGEMINI.md
OthersThe 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:

HarnessInstall command
Claude Codeclaude plugin marketplace add z3z1ma/agent-loom
CursorInstall via Cursor marketplace or clone to ~/.cursor/plugins/local/agent-loom
Gemini CLIgemini extensions install https://github.com/z3z1ma/agent-loom
Codexcodex plugin marketplace add z3z1ma/agent-loom
OpenCodeAdd "@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

SurfaceJob
decisionsDurable choices, constraints, and tradeoffs using the Architecture Decision Record (ADR) format
researchTechnical investigations, consulted sources, documented dead ends, and syntheses
specsIntended system behavior, requirements, functional scenarios, and interface sketches
ticketsBounded units of work containing scope, explicit acceptance criteria, and progress logs
evidenceObserved facts, terminal outputs, reproduction steps, screenshots, and system logs
reviewsAdversarial critiques highlighting specific findings, verdicts, and residual risks
knowledgeShared 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:

  1. Copy the contents of PROTOCOL.md from this repository directly into the project's instruction file (AGENTS.md, CLAUDE.md, or equivalent). This is the preferred implementation method.
  2. Run npx skills add z3z1ma/agent-loom to install the protocol directly into your active skills directory as an alternative method.
  3. 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.

Ver o original no GitHub

Bom para

Relacionados