Appearance
Frameworks
The harness's internal dev docs, one per recurring job. A framework answers how do I do this job the harness way, so an agent does it right without spelunking the repo first – it's agent-facing procedure and routing, not narrative. A framework delegates rather than duplicates: where an authority already exists elsewhere in the repo, the framework points at it, and a framework that restates another doc is a bug. The content is finn's – he dictates what goes in, an agent drafts it agent-facing, and he greenlights it before it lands, never off the agent's own judgement, not even a reasonable-looking default. That's gate G-fw-1, and it holds for everything below.
In Practice
The rule is you read the framework for the job before you do the job, not after guessing. harness/CLAUDE.md routes an agent straight into frameworks/ by task.
Building or changing a module. An agent reads MODULE.md first, declares any hard dependency on another part as needs (or a soft one as wants) per module/DEPS.md, and only calls the module closed once both of MODULE.md's gates – thoroughly tested and documented – actually pass.
Writing a reply to finn. RESPONSE.md is the doctrine for every reply in every session, not just harness work – the i-have-adhd skill on every reply, few bullets, short and direct, bold the load-bearing words.
An example outcome. An agent that skips straight to editing installer/src/* without reading MODULE.md and INSTALLER.md first risks missing which of the two owns the fact it needs – MODULE.md owns the declaration, INSTALLER.md owns the mechanism – and duplicating or contradicting the other.
The Frameworks
| Framework | What it covers |
|---|---|
GENERAL.md | The rules that hold across every framework rather than inside one – doing deterministic work in code, delegating rather than duplicating, and backing a rule that must actually hold with a hook rather than a paragraph. Read it before the framework for the job. |
CONTEXTS.md | Writing the context files a project hands an agent – the budgets, rules not procedures, no contradictions across files, enforcement, and naming. |
INSTALLER.md | Working on the manager and how installing works – what you're adding, what you have to wire, and the traps that bite silently. Slated for a rework once the ratatui installer lands; the ink-bound parts are marked as such inside it. |
MODULE.md | Building a harness module – the module types, depending on other modules, staying self-contained and portable, and the reversible decisions already settled. |
PLANNING.md | Planning work in the harness – the plan-file scheme, sub-plans, anchors, and the done markers. The planning part now ships that scheme as an actual config, .claude/planning/scheme.nuon, editable with harness config --part planning – the first config any part of this module has had. |
RESPONSE.md | How to shape a reply to finn – he skims, so short, direct, and bullet-led, with i-have-adhd on every reply. |
SCRIPTS.md | Writing a script in general. A seed, not a finished framework – it carries one settled rule (a script in harness/scripts/ should most probably earn an inject: line) and the inject bar, and stops there; where a script lives stays harness/CLAUDE.md's job. |
TELEMETRY.md | Adding a tracker – measure post-hoc off what's already on disk rather than emitting per event, the spine, streams, and watermarks, the env overrides a fixture needs, and the honesty rules a number clears before it's printed. |
Gate G-fw-1
Every framework doc is doctrine, follow it exactly. Anything still being shaped with finn lives in that framework's PENDING.md instead, a supplementary file that binds nothing, so reading a framework never costs you the draft material and a reader always knows what's settled versus what's still in play.
Promoting a line out of a PENDING.md and into its framework is finn's call alone. An agent never authors framework content off its own judgement, not even a reasonable-looking default – it drafts the framework-facing prose, finn dictates what it says. That's gate G-fw-1, tracked in the plan/PLAN.H5.frameworks.md plan, and it holds for every framework here, not just the one being drafted today.
The Folder Convention
A folder inside frameworks/ is one of two things, and the name tells you which.
- Named after a framework (case-insensitive, so
module/belongs toMODULE.md) holds that framework's supplementary files – detail that isn't essential to the framework itself, opened only when the framework points you at one.contexts/,installer/,module/,planning/, andtelemetry/each carry aPENDING.mdthis way, andmodule/also carriesDEPS.md(the settledneeds/wantshow-to, checked byharness validate),CONFIG.md(how to give a module a config – theconfig.jsonbeside the manifest, the"config": trueflag on the part, and the three field kindschoice,number, andtext), and a nestedmod-doc/skill. - Not named after a framework is its own thing, and the folder name says what it is.
research/is background material a framework was written against, findings rather than standard, worth opening for the reasoning behind a rule, never for the rule itself.tokens/is seeded ahead ofTOKENS.md, the token-cost framework that isn't written yet, holdingBUDGETS.md(the research brief) andANSWERED.md(lane one of that research, done).
research/ currently holds five docs, all feeding CONTEXTS.md:
| File | What it covers |
|---|---|
context-files-for-claude.md | Writing CLAUDE.md, rules files, and roles – the claude code loading mechanics, the economics, what goes where. |
efficient-context.md | Outside best practice on always-loaded context – the line and token budgets, the adherence numbers, context rot. |
instruction-adherence.md | Why a written instruction gets missed and what makes one stick. |
skill-descriptions.md | Whether an instruction file is ever reached at all – the skill description as trigger router. |
rules-directory.md | How the .claude/rules/ system actually works, read off the vendored claude code source, feeding CONTEXTS.md's rules-system doctrine specifically. |
Key Files
README.md
The index – reads first, lists every framework in the table above with its one-line job, explains the doctrine-versus-PENDING.md split, and states the folder convention.
BACKLOG.md
The pile that isn't doctrine – harness jobs that relate to the frameworks but aren't binding, finn's ideas kept for later, deferred work, and visions that need writing up before they can become a plan. It sits in frameworks/ because every entry is about the frameworks or came out of a frameworks session, not because it is one; the wiki generator skips it. An entry leaves the file when it becomes a plan – allocate it a number, write the plan, delete the entry – and one that turns out to be a bad idea is deleted too, this is not a graveyard. The order is rough priority, top is next, nothing in it is scheduled. It currently carries entries like the TELEMETRY refactor (parked pending another session's lookup-script work landing), the one-shot plan idea (a plan complete enough that an agent builds it cold, forks settled in the plan rather than guessed), and a vocabulary module idea (auto-detecting jargon the way /lesson auto-detects a correction).
DICTIONARY.md
The harness's vocabulary – every word this repo uses in a way an outsider wouldn't guess, one entry per ### header, in one place rather than scattered across whichever doc happened to need it first. It's deliberately not meant to be read whole: read-section.nu slices out one term, a --grep for a concept, or the full list, and a miss lists the terms that do exist so "is this word jargon here" gets answered without opening the file. Adding a term is /dict.
The planning Part's Config
The planning part is the first part in this module to ship a settings form. config.json beside the module's manifest carries seven text fields – the filename stem, the allocatable letters, the reserved letters, the closed prefix, the leftover suffix, the plan dir, and the tracker name – and the part's own scheme.nuon seeds into a project as .claude/planning/scheme.nuon, marked own: true so a project's tuning survives every update. It's a diff, not a copy: an untouched form leaves every key alone.
Three scripts across two modules read it – plan-alloc.nu and plan-close.nu here, plus parse-plan.nu in the planner module. Each bakes the shipped scheme and merges the project's file over it, so a project with no config at all still runs on the shipped default, and a malformed one fails open rather than throwing. Because the scheme rides as a project file rather than a shared one, the two modules stay decoupled – neither script calls the other, and neither module depends on the other. harness/tests/planning/check.nu is the gate that catches the cost of that decoupling: it sources all three scripts' baked consts and fails if they've drifted apart.
Connects to
- Plan System – gate G-fw-1 and the frameworks' own build-out are tracked in the
plan/PLAN.H5.frameworks.mdplan; a framework doc is planned and greenlit the same way any other plan item is. Theplanningpart's config is plan H18, andharness/tests/planning/check.nuis its schema-drift gate. - Context – a framework doc is itself a context file, so
CONTEXTS.mdgoverns how every other framework in this folder gets written, andDICTIONARY.md's/dictcommand lives there too. - Installer –
INSTALLER.mdis the doctrine for the manager itself, andmodule/DEPS.md'sneeds/wantsdependency edges are checked byharness validate.module/CONFIG.mdis the doctrine for a part's settings form generally – it was corrected 2026-09-02 to match the actualconfig.jsonshape after three stale claims (theinstaller/src/parts.tscopy, the manifest-levelconfigrecord, and the "no text or number field" line) had gone unfixed since I18. - Planner –
parse-plan.nushares the same plan naming scheme as this module'splanningpart, reading the same.claude/planning/scheme.nuona project may set.