Skip to content

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 ​

FrameworkWhat it covers
GENERAL.mdThe 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.mdWriting the context files a project hands an agent – the budgets, rules not procedures, no contradictions across files, enforcement, and naming.
INSTALLER.mdWorking 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.mdBuilding a harness module – the module types, depending on other modules, staying self-contained and portable, and the reversible decisions already settled.
PLANNING.mdPlanning 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.mdHow to shape a reply to finn – he skims, so short, direct, and bullet-led, with i-have-adhd on every reply.
SCRIPTS.mdWriting 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.mdAdding 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 to MODULE.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/, and telemetry/ each carry a PENDING.md this way, and module/ also carries DEPS.md (the settled needs/wants how-to, checked by harness validate), CONFIG.md (how to give a module a config – the config.json beside the manifest, the "config": true flag on the part, and the three field kinds choice, number, and text), and a nested mod-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 of TOKENS.md, the token-cost framework that isn't written yet, holding BUDGETS.md (the research brief) and ANSWERED.md (lane one of that research, done).

research/ currently holds five docs, all feeding CONTEXTS.md:

FileWhat it covers
context-files-for-claude.mdWriting CLAUDE.md, rules files, and roles – the claude code loading mechanics, the economics, what goes where.
efficient-context.mdOutside best practice on always-loaded context – the line and token budgets, the adherence numbers, context rot.
instruction-adherence.mdWhy a written instruction gets missed and what makes one stick.
skill-descriptions.mdWhether an instruction file is ever reached at all – the skill description as trigger router.
rules-directory.mdHow 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.md plan; a framework doc is planned and greenlit the same way any other plan item is. The planning part's config is plan H18, and harness/tests/planning/check.nu is its schema-drift gate.
  • Context – a framework doc is itself a context file, so CONTEXTS.md governs how every other framework in this folder gets written, and DICTIONARY.md's /dict command lives there too.
  • Installer – INSTALLER.md is the doctrine for the manager itself, and module/DEPS.md's needs/wants dependency edges are checked by harness validate. module/CONFIG.md is the doctrine for a part's settings form generally – it was corrected 2026-09-02 to match the actual config.json shape after three stale claims (the installer/src/parts.ts copy, the manifest-level config record, and the "no text or number field" line) had gone unfixed since I18.
  • Planner – parse-plan.nu shares the same plan naming scheme as this module's planning part, reading the same .claude/planning/scheme.nuon a project may set.