Loom is a Markdown-native knowledge management protocol for coding agents.

I built it because I wanted less agent tooling, not more.

My coding-agent workflow had outgrown PLAN.md. One file kept turning into the partial spec, research log, task queue, evidence log, review notes, handoff summary, and feature description.

The usual next step is to add more surfaces: a spec tool, an issue tool, a memory system, a review prompt, a planning plugin, a workflow package.

Loom takes the other path.

It puts the agent-facing work record into one Markdown project graph inside the repo.

It gives agents a vocabulary for placing work where it belongs, then uses that vocabulary in two directions:

1. The outer loop routes work into the right project records.
2. The inner loop compiles those records into bounded packets for clean workers.
3. Retrospective promotes accepted learning back into the graph.

The worker is disposable. The graph compounds.

project state -> compiled packet -> bounded worker -> evidence and critique -> promoted learning -> better project state

Install Loom · Read the protocol · Architecture notes

The claim

The pieces are familiar. Teams already use specs, plans, tickets, research notes, test output, review notes, wiki pages, Git branches, and release summaries. Agent workflows added prompts, memory files, context management, subagents, skills, local task stores, and clean execution loops.

Loom's contribution is the composition.

Every kind of work gets a place in the repo. The skills teach agents when to use each place, how records link, how work moves between records, and when the graph is consistent enough to close.

Once the vocabulary exists, common workflows become routes through the same graph. Debugging, spiking, planning, reviewing, shipping, repair, retrospective, codebase mapping, wiki synthesis, and Ralph-style implementation no longer need separate hidden state.

Loom is the project vocabulary long-running agent work compiles to.

Why this changes the work

A bigger context window lets an agent carry more state.

Loom moves the state out of the window.

A fresh worker should not need the whole conversation. It should receive the relevant project records, a bounded goal, a write scope, stop conditions, and an output contract. After the worker returns, the parent reconciles what happened back into the graph.

The child does one slice.

The parent decides what became true.

The project keeps the record.

Project layers

Loom separates project state into canonical layers.

The rule that keeps the graph coherent:

placement beats recency

The newest message does not win. The longest summary does not win. The right record carries the work.

For software work, the source tree is current implementation reality. Git records file history. Specs describe intended behavior. Tickets track live execution and acceptance. Evidence bridges implementation to claims. Critique judges whether the bridge is strong enough. Wiki holds explanation that has become safe to reuse.

Memory can help an agent recover context. It does not become project state.

How agents use the vocabulary

The agent starts by asking where the work belongs.

A vague bug report becomes reproduction evidence, root-cause research, a tightened spec if behavior is ambiguous, a ticket for the fix, a packet for the implementation pass, green evidence, critique when risk warrants, and wiki promotion if the lesson should survive.

No new workflow was invented. The agent used the vocabulary.

Two loops

Loom separates shaping work from doing work.

Outer loop: route work

The outer loop asks which project layer should change next.

constitution -> initiative -> plan -> ticket

Conditional gates keep the agent honest:

need discovery or tradeoff analysis -> research
need behavior clarity -> spec
need sequencing -> plan
need bounded execution -> ticket
need observations -> evidence
need pressure-testing -> critique
need accepted explanation -> wiki

If a step cannot be completed honestly, route backward to the layer that can fix the gap.

Do not advance on vibes.

Inner loop: run clean workers

The inner loop is Ralph-shaped:

one packet
one fresh worker
one bounded mutation
one parent reconciliation

A parent compiles a packet, delegates one fresh-context execution step, receives a bounded outcome, and reconciles the result back into the graph.

The child handles one iteration. The packet defines the child contract. The ticket tracks live execution. The parent reconciles the result.

Critique and wiki may reuse packet discipline, but their domain skills handle review and synthesis. They are sibling routes, not implementation passes pretending to be Ralph.

Packets compile project state

A packet is a compiled contract.

A parent builds it from the upstream graph: relevant constitution records, initiative context, research, spec, plan, ticket, evidence, critique, source fingerprint, execution context, write scope, verification posture, stop conditions, and output contract.

The worker gets less context by volume, but better context by shape.

A strong packet states:

• the ticket or project record being served
• the bounded goal for this iteration
• what the worker can read
• what the worker can write
• the source fingerprint
• the Git branch or worktree context when files will change
• the verification posture
• stop conditions
• the output contract
• what the parent will do after return

Packets prevent context drift, hidden assumptions, uncontrolled changes, and scope creep.

A packet is a contract. It is not the project record.

After the child returns, the parent reconciles the result into tickets, evidence, critique, research, specs, plans, wiki, constitution, initiatives, or memory as needed.

The transaction spine

Non-trivial Loom work follows one spine:

route -> shape -> ready -> execute -> reconcile -> verify -> accept -> promote -> close

A transaction does not need every layer. It does need to preserve placement.

Example bug fix:

1. Capture reproduction evidence.
2. Research the root cause if it is unknown.
3. Update or create a spec if the intended behavior is fuzzy.
4. Create or tighten the ticket.
5. Compile a packet for one implementation pass.
6. Run a fresh worker.
7. Record red and green evidence.
8. Route critique when risk warrants.
9. Accept only when the ticket reflects reality.
10. Promote durable learning into research, wiki, spec, plan, initiative, constitution, evidence, or memory.
11. Close when the graph is consistent.

That is Loom.

Done is a property of the graph

Work is not done when the code compiles. It is done when the project is consistent.

For software work, closure usually requires:

• the relevant spec is satisfied, or ticket-local acceptance criteria are explicit
• evidence supports the claim being made
• critique is resolved, accepted, or recorded as residual risk
• the ticket reflects the actual final state
• durable learning has been promoted when it should survive the task

A child worker saying done is not enough. A commit is not enough. A green test is not enough if the ticket still lies.

Done is a property of the graph.

Research is first-class

A lot of software work is knowledge work before it is code.

Agents explore libraries, inspect implementation paths, test approaches, compare options, discover constraints, and learn that something does not work. If that work stays in scratch files or short-lived context, the next session repeats it.

Research gives that work a durable place: questions, options, experiments, rejected approaches, null results, supporting evidence, open questions, and evidence-grounded recommendations.

A failed path can be valuable. A null result can be the most important thing the project learned that day.

This is where Loom crosses from coding workflow into knowledge-work protocol.

Workflows emerge from the vocabulary

Workflow skills coordinate routes through project layers. They do not create new ledgers unless a new kind of work needs a durable place.

brainstorm:
workspace problem shaping -> research/spec as needed -> plan -> ticket

test-first implementation:
ticket -> packet with verification_posture:test-first -> red evidence -> green evidence -> ticket acceptance

debug:
evidence -> root-cause research -> spec if needed -> ticket -> packet -> evidence -> critique -> retrospective

spike:
research -> throwaway scope if needed -> evidence -> conclusions/null results -> downstream spec, plan, ticket, or wiki

sketch:
design question -> 2-3 variants -> evidence -> critique -> accepted spec or wiki updates

code map:
scan evidence -> research where structure is uncertain -> wiki atlas when accepted

review:
critique -> evidence -> ticket reconciliation -> acceptance or repair

review response:
critique finding -> verify against source/evidence -> resolve, accept risk, supersede, or create follow-up -> ticket disposition

parallel execution:
plan execution waves -> non-overlapping tickets/packets/worktrees -> child results -> parent integration evidence -> ticket reconciliation

git isolation:
ticket/packet scope -> explicit baseline -> branch/worktree -> diff provenance -> handoff evidence

implementation:
ticket -> packet -> worker -> evidence -> reconcile

plan execution:
plan -> bounded tickets -> Ralph/local edits -> evidence -> critique as needed -> acceptance

branch finish:
ticket/evidence/critique truth -> ship package -> merge, PR, keep, or abandon handoff -> ticket acceptance gate

ship:
ticket/evidence/critique/wiki disposition -> PR summary, release note, risk summary, follow-up list

accept:
ticket acceptance dossier -> evidence/critique/wiki disposition -> close or loop back

repair:
evidence -> critique -> ticket -> packet -> evidence -> accept

retrospective:
ticket or initiative lessons -> wiki, research, spec, plan, initiative, constitution, evidence, or memory

wiki write/audit:
accepted explanation -> wiki page or audit -> links, freshness, and maintenance disposition

You do not invent a workflow every time. You route through the project graph.

Influences

Loom is influenced by Superpowers, GSD, Spec Kit, Beads, Ralph, ECC, and the broader field of agent-skills projects.

Superpowers showed how much better coding agents get when they have explicit development skills. GSD showed how context engineering changes long-running work. Spec Kit showed that well-defined specs can drive implementation. Beads showed that local agent-facing tickets externalize context and make long-horizon work easier to manage. Ralph showed the value of clean context windows, bounded tasks, disk-backed state, commits, and restart loops. ECC put real effort into continuous learning and compound engineering.

Loom makes the shared vocabulary explicit.

Brainstorming becomes research, spec, plan, and ticket shaping. Test-driven development becomes packet verification posture plus evidence and ticket acceptance. Review becomes critique. Finishing becomes ticket acceptance, ship packaging, and retrospective promotion. Ralph becomes packet, child worker, bounded mutation, and parent reconciliation.

You can run other tools beside Loom. For many projects, you may not need to. Loom's skills already teach the agent how to route the same underlying work through the repo.

Markdown, on purpose

Loom is Markdown-native.

No service. No daemon. No hidden runtime database.

The graph is files. Agents already know how to search with rg, traverse with find, inspect with cat, compare with git diff, edit records, move files, and compose shell tools with awk, sed, xargs, and pipes.

That is enough.

Optional utilities may validate, project, or summarize state. They do not define Loom semantics.

Harness adapters may preload bootstrap references where a harness supports it cleanly. That is an adapter optimization over the same skill package, not a second doctrine source.

The protocol is the corpus.

What ships

This repository ships the Loom skill package.

It is not a runtime, service, daemon, MCP server, product CLI, workflow engine, hidden database, or prompt dump.

Included:

• skills/, the canonical Loom surface
• loom-bootstrap, the mandatory entry skill
• project-layer skills for constitution, initiatives, research, specs, plans, tickets, evidence, critique, wiki, and memory
• workflow skills for workspace entry, records, Ralph, Git, debugging, spike, codemap, ship, retrospective, and skill authoring
• templates and references for Markdown-native operation
• harness manifests and adapters where useful
• PROTOCOL.md, the stable protocol summary
• ARCHITECTURE.md, the implementation and package architecture notes
• examples and fixtures for protocol behavior

The product surface is the skill package. The skills are the protocol in operational form.

Skill map

Repository layout

.
├── README.md
├── INSTALL.md
├── PROTOCOL.md
├── ARCHITECTURE.md
├── AGENTS.md
├── examples/             # golden protocol fixtures and traces, not project records
├── optional-utilities/   # helpers that do not define semantics
└── skills/               # canonical Loom skill package

Inside a Loom-enabled project, the runtime tree looks roughly like this:

.loom/
├── constitution/
├── initiatives/
├── research/
├── specs/
├── plans/
├── tickets/
├── evidence/
├── critique/
├── wiki/
├── packets/
│   ├── ralph/
│   ├── critique/
│   └── wiki/
└── memory/        # optional

Use loom-workspace, loom-constitution, and loom-tickets for the first records.

Install

Loom installs as a skills package. The fastest path is to expose skills/ to your harness and use loom-bootstrap first.

git clone https://github.com/z3z1ma/agent-loom.git

First-class harness paths are in INSTALL.md:

• Claude Code
• OpenCode
• Codex
• Cursor
• Gemini CLI
• generic skills-directory install

After install, start with:

Use the loom-bootstrap skill. Then route the work through the Loom skill that handles the next kind of work.

What Loom can replace

Loom can coexist with external issue trackers, planning tools, review systems, workflow packages, and agent command surfaces.

It can also make many of them unnecessary for the agent-facing work record.

The skills already prescribe project layers, routing rules, execution, acceptance, evidence, review, knowledge promotion, and handoff packaging. Once those terms exist inside the repo, the agent can compose the workflows directly.

External systems can mirror Loom state. They should not be the only place the agent learns what is true.

Costs

Loom asks for discipline.

Broken links matter. Stale records matter. Evidence that overclaims matters. A ticket that says the work is accepted when critique is unresolved is worse than no ticket at all.

Loom also has a threshold. If the work is small, local, and obvious, use the source tree and Git. Do not create a graph-shaped shrine around a one-line edit.

The graph pays for itself when work crosses sessions, changes behavior, needs review, involves research, carries risk, or leaves behind knowledge the next worker would otherwise rediscover.

The point

Loom keeps AI work from scattering across chat, plan files, tool state, and stale scratchpads.

It gives agents a vocabulary for placing work where it belongs.

It gives projects a memory that survives context windows, compaction, worker handoff, and time.

The pieces already existed. Loom puts them in one place and gives each one a job.

the work stops drifting
the agent stops carrying everything
the project starts remembering