Graph Climbing

A small, runtime-neutral protocol for long-running agentic engineering.

Graph Climbing keeps an agent tied to durable claims and evidence instead of chat history. The smallest useful setup is deliberately ordinary:

one durable spec + tests and Git + one capable coding agent

No private system, task tracker, skill loader, hook, dashboard, or particular model vendor is required.

Run one climb in five minutes

1. Copy starter/SPEC.md to your repository as SPEC.md.
2. Replace the placeholders with the real request, boundaries, and atomic done criteria. Give every criterion one falsifying probe.
3. Give starter/START.md, starter/CLAIM-CHECKLIST.md, and your repository to any capable coding agent.
4. Ask the agent to derive the open claim frontier, select one bounded vertical, run its first falsifier, build, verify, reconcile the spec, and derive again.

That is Graph Climbing. The reference checker is optional. If you have Bun:

cd /path/to/graph-climbing
bun run graph-check /path/to/your-repository/SPEC.md

Without Bun, use the manual checklist: a claim is ready only when it is open, every declared dependency is verified, it has one binary falsifying probe, and no blocker or unresolved assumption changes its meaning.

See examples/notes-cli for a complete small serial example.

The loop

derive the claim frontier
→ select one bounded vertical
→ build and falsify
→ reconcile durable truth
→ derive again

The durable spec owns product meaning and official progress. Git, tests, runtime observations, and release artifacts provide snapshot-bound evidence. Add one operational ledger only when ownership or gates must survive sessions or coordinate multiple writers; the ledger never becomes a second product specification.

The standalone protocol is GRAPH-CLIMBING.md.

For one-file reading, the Graph Climbing Gist mirrors GRAPH-CLIMBING.md at tagged releases. This repository is authoritative.

What ships in v0.3

• GRAPH-CLIMBING.md: canonical protocol.
• starter: three-file, vendor-neutral adoption kit.
• examples/notes-cli: checked serial example.
• docs/spec-and-ledger.md: generic authority and evidence contract.
• EVIDENCE.md: what the current public evidence does and does not establish.
• advanced: optional multi-worker and durable-runtime mechanics.
• adapters: optional harness and checker integrations.
• conformance: deterministic behavior contract and fixtures.
• visuals: generic explanatory diagrams.

The default path ends before advanced/ and adapters/. They are optional extensions, not hidden prerequisites.

Check this repository

bun test
bun run graph-check starter/SPEC.md
bun run graph-check examples/notes-cli/SPEC.md

graph-check validates the strict reference SPEC.md format: IDs, dependencies, probes, evidence requirements, optional vertical mappings, frontier derivation, scope isolation, and companion-join invariants. It cannot certify product correctness. The probes named by the product spec remain authoritative.

Boundaries

Graph Climbing is not:

• an agent runtime or scheduler;
• a required specification brand or task tracker;
• an automatic completion authority;
• proof that more agents improve productivity;
• a replacement for product tests, release gates, or human authority.

Status

v0.3 release candidate. This version makes portability and the standalone serial path explicit. The evidence base remains deterministic fixtures plus experience from the origin project cluster; there is no independent replication or general productivity claim yet.

License

MIT