loop-northstar
Skill904 starsChanged 4 days agoMITView on GitHub
Hold an interactive session to create or revise an ideal-state doc, or to slice it into approved repository milestones.
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- ios/CLAUDE.mdCLAUDE.md
- rome_apps/CLAUDE.mdCLAUDE.md
- add-oauth-integrationSkill
- babysit-prSkill
- color-auditSkill
- dddSkill
- file-issueSkill
- imports-ofSkill
- loop-reconcileSkill
- move-codeSkill
- release-rome-imageSkill
- respond-to-reviewSkill
- secondary-text-auditSkill
- todos-to-github-projectSkill
- ux-semantics-auditSkill
- validate-oauth-integrationSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 47
Check consistency. Walk the full Statements list — new and existing statements together — and surface any two that cannot both hold.
≈ “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.
Files
Loop: north star
Goal end-state: the ideal state of the target area is written down and agreed — as a doc PR, and when the session slices it, as approved repository milestones.
This is the interactive half of the reconciliation loop. The autonomous half (loop-reconcile) computes the gap between these artifacts and the codebase and files work issues. This session files no work issues.
The ideal-state doc
The doc lives in docs/northstars/, one file per area, named for the area it describes. It describes the ideal present — what should be true. Never how to get there, and never what used to be. Prose follows WRITING.md.
The body takes whatever form fits the subject — contract tables, flow descriptions, diagrams, examples — with one required section: Statements, a bullet list of checkable claims. Only the Statements section has authority. loop-reconcile computes the gap against it, and everything else is illustration.
Admission rules for every statement:
- Declarative present tense. No "currently", no "we will", no "migrate from", no milestone names.
- Checkable: an agent can verify compliance by reading the code.
- Open: more than one implementation can satisfy it. The test: the statement stands without naming a file, function, or type. A statement only one implementation satisfies is code transcribed into prose.
- A statement asserting that something is answered one way, or once, names the question it answers. Compliance turns on which reads count as the same question, so a uniqueness claim without its question cannot be checked.
Content that never enters the doc:
- Milestones. They go to the repository's milestone list and die there.
- Rationale. It goes to an ADR.
- Migration policy. It lives in
loop-reconcile.
Milestones
A milestone is an intermediate ideal state. Its description is a Statements list — typically a subset or a weakened version of the north star's statements — plus optional notes. The same admission rules apply: what, never how.
- Slice the end state into pillars or layers. Pillars are independent and build in any order. Layers stack and build bottom up.
- A milestone must describe a state worth pausing at indefinitely. If pausing there leaves the codebase incoherent, the slice is wrong.
- Milestones are born approved. Consensus happens in this session, and the record lands as repository milestones. No proposed state exists.
- A milestone that falls behind a revised doc gets fixed here too:
loop-reconcilereports the drift and stops, and the next session revises the milestone. - A session that revises a doc also walks the open milestones and updates any statement the revision changed or removed, while the human is present to confirm.
Flow
- Orient. Read the existing doc if there is one, the repository's open milestones and
loop-reconcileissues, and the code the doc covers. - Discuss to consensus. Draft in chat and iterate with the user. Push back on any statement that fails an admission rule.
- Name each statement's decider. For every statement the session lands, new and existing, name the code a reader opens to decide compliance. A statement whose decider you cannot name is not checkable, and it does not land. This is the step that catches a statement describing a question the code does not ask.
- Check consistency. Walk the full Statements list — new and existing statements together — and surface any two that cannot both hold. A revision session checks against the whole doc, not only the edited part.
- Land the artifacts, only after the user's go-ahead in chat:
- The doc: open a branch and a PR. The user merges.
- The milestones: create each on GitHub with
gh api repos/{owner}/{repo}/milestones -f title=... -f description=...— the title names the slice, the description holds its Statements list. Create layers in build order.
Nothing lands before the go-ahead.
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
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.

