agentleFS
ChindanaiNaKubChindanaiNaKub/openthought/.claude/skills/intent-graph/SKILL.md

intent-graph

Skill0 starsChanged 4 months agoMITView on GitHub

Read or write the repo's intent graph under intent/ — the mission, bets, goals, problems, projects and stories that say why this code exists. Use when the user asks what something is for, why a decision was made, or what to work on next; when starting work whose purpose is not obvious from the diff; or when they want to record a decision, plan, problem, or piece of scope. Also use before writing code if no artifact is in focus.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run coherence graph to see it.

    line 13
  2. Very specific:

    Check what is in focus with coherence focus.

    line 21
  3. Very specific:

    A bet that cannot be killed is not a bet: Every bet needs a "what would kill it" section with an observation that would make you stop.

    line 71
  4. Very specific:

    When work teaches you something, edit the parent.

    line 88
  5. Very specific:

    After any edit to intent/, run coherence check.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

The intent graph

intent/ holds small markdown files describing why this repo exists and what is currently being built. Every file has frontmatter and hangs off a parent, forming one chain: mission → bet → goal → project → story. user and problem sit off to the side as the facts about the world that the chain answers to.

Run coherence graph to see it. Run coherence focus <id> to see one artifact's chain up to the mission.

(Commands assume coherence on PATH; a repo may vendor it at bin/coherence instead. Use whichever exists.)

Before writing code

Check what is in focus with coherence focus. If nothing is, find the artifact this work serves and focus it. If no artifact covers the work, that is the real finding, so say so before writing anything. Work with no stated intent is exactly what this repo exists to catch.

The types

typeone persays
missionrepowhy this exists at all
betseveral"I believe X, so I'm doing Y instead of Z", falsifiable
goalper bethow you'd know the bet paid off; carries a measure:
userfewa specific person in a specific situation
problemper userwhat goes wrong, told as a moment rather than a category
architectureper beta structural decision and what it forecloses
projectper goala chunk of work big enough to matter, small enough to finish
storyper projectone observable change, with acceptance criteria
domainrepothe nouns, if the vocabulary is contested

Frontmatter

---
id: story-magic-link        # primary key, matches the filename by convention
type: story
title: Magic-link sign-in
status: draft               # draft | active | done | dropped
parent: project-auth        # the one artifact above this
serves: [problem-signup-friction]   # the problem/user this actually helps
priority: p1                # p0..p3, optional
measure: ...                # goals only, the number that moves
code: [src/auth/**]         # globs this artifact owns
---

Bodies use ## Acceptance with - [ ] checkboxes on stories and projects. Those checkboxes are what the ship gate judges a diff against, so write them as things a reader could verify without asking the author.

Templates for every type live in intent/_templates/ (written by coherence init). Copy one instead of writing frontmatter from memory.

Writing artifacts well

The graph is only worth maintaining if reading it is faster than rederiving the answer. That means:

  • Write the reasoning, not the summary. "Use SQLite" is worthless in three months. "Use SQLite because the write pattern is single-writer and Postgres would add an ops surface I won't maintain" survives.
  • A bet that cannot be killed is not a bet. Every bet needs a "what would kill it" section with an observation that would make you stop.
  • Name what you gave up. Bets and architecture decisions both foreclose something. Recording it is how you recognise the pain later instead of rediscovering it as a mystery.
  • Decompose, don't restate. A child that rephrases its parent adds nothing, and the copy-paste check will flag it. Each level down should contain a decision the level above did not make.
  • Delete freely. An artifact nobody reads makes the ones that matter harder to find. status: dropped keeps the record, and deleting the file is fine too.

Maintaining it

  • Finishing work means ticking criteria and setting status: done. The checks flag done artifacts with open criteria or live children.
  • Abandoning work means status: dropped rather than deleting silently. Anything hanging off it gets flagged as standing on a stale premise, which is the point.
  • When work teaches you something, edit the parent. A plan that never changes while its children churn has stopped tracking reality, and plan-staleness catches it.

After any edit to intent/, run coherence check.

Related: coherence-check for the checks, ship-check for the gate.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.