openthought

A strategic intent layer for one person building with agents.

Agents made building cheap and made drift invisible. You can generate a week of plausible work in an afternoon, and none of it has to connect to anything you actually decided. The code is usually fine. What goes wrong is that you ship a well-made thing that no longer serves the reason you started.

openthought is a graph of small markdown files in your repo saying what you are trying to do and why, plus a checker that notices when today's diff stopped agreeing with it.

$ coherence focus story-magic-link
focus: Magic-link sign-in
  story-magic-link <- project-auth <- goal-activation <- bet-no-passwords <- mission

$ coherence ship
ship check
  6 changed file(s), 0 intent edit(s)
  claiming: Magic-link sign-in

! untraced-change  story-magic-link
  2 changed file(s) are outside story-magic-link's `code:` globs: src/db/pool.py, src/db/migrate.py
  -> Widen `code:` if this is in scope, otherwise it is scope creep and belongs in its own story.

acceptance criteria to judge against the diff:
  [ ] link expires after 15 minutes
  [ ] single use
  [ ] failures log without leaking the token

Install

coherence is one file. Python 3.9+, stdlib only, no dependencies to resolve. Put it anywhere on your PATH:

mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/ChindanaiNaKub/openthought/main/bin/coherence \
  -o ~/.local/bin/coherence
chmod +x ~/.local/bin/coherence

If you work with Claude Code, copy the skills into your repo too, so the agent picks them up on its own:

git clone --depth 1 https://github.com/ChindanaiNaKub/openthought /tmp/openthought
mkdir -p yourrepo/.claude
cp -r /tmp/openthought/.claude/skills yourrepo/.claude/

This repo also carries its own copy at bin/coherence, gradlew-style, so a bare clone works with nothing installed.

Quick start

cd yourrepo
coherence init          # writes intent/ with a mission stub and all templates
$EDITOR intent/orient/mission.md
coherence check

Templates for every artifact type land in intent/_templates/. Copy one, fill it in, run coherence check again. That is the whole authoring workflow.

Then, whenever you sit down to work:

coherence graph            # what's live
coherence next             # what to work on, decided by the graph
coherence focus <id>       # what you're on, and why
# ...build...
coherence ship             # does the diff match what you claimed?

And when you come back to work someone else (or an agent) did:

coherence brief            # the five-minute catch-up

Git is optional, used for accurate "last touched" dates and for the ship gate's diff.

The shape

One chain, four levels:

mission            why this exists at all
  └─ bet           "I believe X, so I'm doing Y instead of Z", falsifiable
      └─ goal      how you'd know the bet paid off; carries a measure
          └─ project   a chunk big enough to matter, small enough to finish
              └─ story  one observable change, with acceptance criteria

Off to the side sit the facts the chain answers to: user (a specific person in a specific situation), problem (what goes wrong, told as a moment), architecture (a structural decision and what it forecloses).

Execution work links sideways with serves: to the problem it addresses. That link turns "am I building something nobody needs" into a question with an answer.

Templates for every type are in intent/_templates/. This repo's own intent/ is a worked example describing openthought itself.

The checks

Fifteen deterministic rules run instantly on every invocation. Three fire while the frontmatter is being parsed:

bad-type · bad-status · duplicate-id

The other twelve run over the assembled graph:

dead-link · orphan · illegal-parent · duplicate-singleton · stale-premise · lifecycle-contradiction · decomposition-gap · coverage-gap · unrealized-commitment · priority-inversion · zombie · plan-staleness

The ship gate adds two of its own — untraced-change and no-criteria — and re-runs stale-premise and coverage-gap against whatever is in focus.

Five more need a reader instead of a rule. Those get emitted as tasks, answered by an agent, and cached by content hash so an unchanged pair is never judged twice:

contradiction · copy-paste · redundant-overlap · orphaned-metric · presupposed-capability

coherence queue --json | # hand to an agent
coherence verdict        # pipe answers back

Editing an artifact changes its hash and retires its verdicts automatically.

Skills

Four skills under .claude/skills/ put this in front of the agent instead of behind it:

skill	when it fires
intent-graph	reading or writing artifacts; before starting work with no stated purpose
coherence-check	after editing intent/; "what's stale?", "does the plan still hold?"
ship-check	before any commit or PR; "is this ready?", "does this match what I asked?"
autopilot	"keep going", "work through the backlog", or any unattended stretch

The gate is deliberately split. The checker does the mechanical part: which files changed, which artifact owns them, which criteria apply. The agent does the judgment: whether the criteria are actually met, and whether the diff quietly did more than it claimed. Run either half on its own and you get very little.

Leaving it running

The graph doubles as a delegation contract. You write intent down to the level you care about; the agent operates everything below it and never touches the levels above. Three commands make that a loop:

coherence next    # the agent picks work: active before draft, priority
                  # inherited from ancestors, blocked and dead-premise
                  # stories skipped
coherence ask "Criterion 'fast' is not checkable. I read it as <2s, \
which the diff meets. Left it unticked." --about story-export
                  # questions queue in intent/_inbox.md instead of
                  # stalling the session
coherence brief   # what shipped, what's blocked, what needs you, in
                  # that order

The autopilot skill binds these into a session: read the human's inbox answers, pick, focus, build, gate, commit, repeat, and end with a brief. Its policy table draws the line explicitly: stories and projects are the agent's to create, complete, and close; bets, goals, the mission, users, and problems are yours, and an agent that wants to change one writes to the inbox and keeps working elsewhere.

You answer the inbox by ticking the checkbox and writing the decision under it. The next session applies your answers before picking any work.

Wiring the gate into git

printf '#!/bin/sh\nexec coherence ship --staged\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

--staged limits the gate to what is actually being committed. Without it the hook also counts unstaged edits and untracked files, so a local .env.local or a scratch note fails every commit over paths the commit does not contain — and a gate that is wrong every time is one you learn to skip. Run bare coherence ship by hand when you want the whole working tree judged.

It reports and exits non-zero on blocking findings, and git commit --no-verify overrides. Keep that escape hatch. A gate you cannot override is a gate you will delete.

What I left out

This started from Helen's Foundry, which runs 32 coherence checks for engineering orgs. Eleven of those only mean something when several people share a backlog: owner over-allocation, resource misallocation, unowned work in flight, missing accountable owner, coordination collision, review cadence breach, portfolio distribution anomalies. With one person the owner is always you, and the answer is always "yes, over-allocated". They are cut.

Also cut: the two vector checks, root-alignment outlier and horizontal incoherence. They need embeddings, which means a model call, an API key, and an index to maintain. On a graph of thirty artifacts they tell you what reading the graph tells you. If your graph ever outgrows one screen, they are worth revisiting.

Kept and reshaped: the four-level chain, the trace-to-intent idea, the split between rules and judgment, and the gate at the moment of shipping.

Known holes

• A cached judgment verdict is hashed over its own subjects. If a sibling changes in a way that creates a contradiction, the stale verdict does not notice. See intent/structural/arch-two-tier-checks.md.
• code: globs are maintained by hand and will rot. unrealized-commitment catches globs that point at nothing. Nothing catches globs that point at too much.
• Recency assumes commit dates track real attention. Rebasing lies to it.

License

MIT. See LICENSE.