Clew — the thread through brownfield

The problem

A new teammate — or a new agent — cannot walk a payload across orders → payments without grepping six repos. Four tools each hold a slice. Alone, they stay irrelevant.

Code is not the use case

charge() calls authorize(). That does not tell you CARD vs COD.

Specs are not the path

OpenAPI says POST /orders exists. Not which event fires.

Traces die on async

The hop continues in a consumer, keyed by a stitch field in a log line.

Memory stores chat

“Don’t refactor old auth” is not a stitch key, and not a tree.

A hop is one node on the thread

A tree is Input → Branches → Output. A forest dispatches inbound events onto trees — OrderCancelled is not a hop of place-order. This service owns one level; next is another service’s tree. Async OUT without stitch is a P0.

Inventory stubs (IN + else) from evidence. Never invent when for a stranger repo.

A tightly wound brass ball of thread — a clew — clue, from clew: a ball of thread to find the way back.

Four cores we keep. Clew is the join.

Code graph

HTTP / ASYNC / CROSS evidence. We do not rebuild an indexer.

Catalog

Messages, producers, consumers — MIT MCP, no Scale license.

Loadout

One payload path in the prompt. Not chat memory.

Traces

OTLP + stitch keys. A live span is evidence, not the map.

A glowing thread passing through a keyhole between dark corridors — Observed · declared · resolved. Join keys: service, HTTP, message name.

The loop

measure→ one P0→ capture→ measure until reflected

CI: clew score --fail-p0. After executable, --fail-p1 freezes uncaptured stubs. New routes turn the sensor red. You do not finish docs.

$ clew watch --root . --traces /tmp/otlp.jsonl --follow
watch: follow /tmp/otlp.jsonl (poll 200ms)
watch: +1 evidence  P0 0→1  P1 1→1  status executable→incomplete
sensor RED — new P0:
- drift: PATCH /v9/ghost has no IN (orders)

Walk one payload

Loadout is the memory core: one path, not the forest.

Install

go install github.com/jeunessegamesee/clew/cmd/clew@v0.1.1

Go 1.22+. Or clone and go test ./... && go build -o clew ./cmd/clew.

Any brownfield, three commands

clew init --root /path/to/repo
clew stub --root /path/to/repo
clew score --root /path/to/repo --by-service
clew loadout --root /path/to/repo --in /package.Service/Method

Adapt a repo you have never seen

Generic core: OpenAPI / proto / GraphQL + OTLP + clew ingest. Kafka, RMQ, SQS, cron, CDC, webhooks, streams: same door (kind, via, address) plus stitch when the trace dies. We do not add a parser per broker. http: [auto] is an optional HTTP guess.

.clew.yaml is the adapt file. Specs, traces, extra git checkouts — not a domain model of your business.

roots:
  - .
  - ../other-repo
services:
  checkoutservice: src/checkoutservice
traces:
  - traces/*.json

swagger.json and *openapi* are found by default. Watch persists live edges to observed.json.

Overhead maze with a single gold path — The map is git markdown. The scorer is the sensor.

Commands

Command	What it does
`init`	Write `.clew.yaml` and `CLEW.md`
`stub`	IN + else for every gRPC / GraphQL / OpenAPI port
`score`	Coverage 0–100. `--by-service` `--fail-p0` `--fail-p1`
`loop`	Name the next P0. Exit 0 only at reflected
`loadout`	One payload path (memory core)
`watch`	`--traces` / `--follow` / `--listen` OTLP JSON or protobuf
`mcp`	stdio tools: loadout, who_calls, next_p0, drift, score
`ingest`	Merge any language’s doors into `observed.json`
`inventory / observe / flows / export-html`	Ports, evidence, connection index, HTML map

What we refuse

GitNexus

PolyForm Noncommercial. We do not ship it.

EventCatalog Scale

Agent APIs are licensed. Clew’s MCP is MIT.

Chat memory as architecture

Loadout is a path. It is not L0–L3 session recall.

GraphRAG of prose

Evidence is specs, traces, and hops.md — not invented architecture.