working-model
Skill0 starsChanged 2 days agoMITView on GitHub
Right-size the working model — the doc surface, oversight cadence, scope unit, and decision-capture style — to a project's current size, phase and stakes, and re-tune it as the project scales. Use when planning a new project or feature; before creating any new .md file; at a stage or milestone boundary to run the audit; and whenever the user says "restructure the docs", "too many files", "this is over-documented", "the codebase grew too fast", "this milestone feels big", "split this", "merge these docs", or asks how much to review versus let the agent execute. Guards against .md sprawl, sudden codebase growth, untracked decisions, and mis-sized scope.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- commitSkill
- delegateSkill
- design-reviewSkill
- endSkill
- retroSkill
- review-gatesSkill
- reviewSkill
- startSkill
- web-kitSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 64
Simplify the approach before documenting it: If a design needs a paragraph to justify, first try to make the design smaller.
- Very specific: line 85
Run at each stage / milestone boundary, after the state file is updated.
- Distinctive: line 114
When the Audit flags anything beyond a trivial one-line fix, write a short
≈ “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
Working model
The working model is four dials, not one:
- Doc surface — how many files, each file's single job, append vs. rewrite.
- Oversight cadence — review per commit / per stage / per PR; inline vs. subagent.
- Scope unit — how large a chunk the agent takes before checking in.
- Decision capture — what gets recorded, where, how heavy.
The failure this skill prevents: the working model is set once at the start and never re-tuned, so a small project accretes the doc apparatus of a large one, the codebase grows past its milestone, and decisions scatter. Re-tune the dials to the project's size and phase — re-check at every milestone boundary.
Vocabulary here is generic. "The state file" = whatever the project uses to track
where it is. "The decisions log" = the architecture-decision record, if the
project keeps one. "The commit-count estimate" = any running [n of x] or
similar gauge of how big the current chunk is.
When to run
- Session startup — classify the archetype (below); state it in one line.
- Before creating any new
.mdfile — check the doc budget first; a new file must clear the bar in "Doc budget". - At a stage / milestone boundary — run the Audit, after the state file is updated.
- On request — "restructure the docs", "too many files", "over-documented", "this feels big", "split this", "merge these", "how much should I review".
Archetype
Pick the row that matches the project today. Re-classify at each milestone. Crossing a boundary is itself a trigger (see the trigger list).
| Dial | Small / short-cycle | Growing codebase | Large-scoped |
| Docs | One running plan file; a README if someone else runs it. No standalone architecture or decisions docs — architecture is a few bullets in the plan file. | "One job per file" set (state / architecture / decisions / readme), each capped ~150–300 lines, and no more. | Hierarchical: a top-level index → per-area docs → one file per decision record. |
| Oversight | Steer direction; review at the end or 1–2 checkpoints. Tests are the safety net. | Subagent review per meaningful change (staged diff only) + a heavier review at milestone boundaries. Not per-commit inline. | Agent executes inside a pre-fenced area; humans review at PR boundaries. |
| Scope unit | The whole task fits one context window. If it doesn't, it's not small — use the next column. | A named milestone, roughly 6 commits. Estimate drift is the alarm. | A bounded task, decomposed by a human before the agent starts. |
| Decisions | Inline comments + one-liners under a "Decisions" heading in the plan file. | Recorded only if the choice moves a boundary, semantics, persistence, concurrency, security, or extensibility. Everything else is not recorded. | Numbered decision-record process, each owned. |
Most projects are "growing". The common mistake is applying the growing (or large) row's doc instincts to a small / short-cycle project.
Stakes
Separate from size: how much rigour the plan gets. If unsure, ask once.
- Quick — a script, a prototype, one feature on a known codebase: plan in a short conversation.
- Standard — a new app, a nontrivial feature, anything shared with others: a full plan with blind spots checked.
- High-stakes — money, auth, PII, health data, customer-facing, or "the real thing": extra rigour
on security, the data model and risks; name open risks in
CLAUDE.mdrather than picking silent defaults.
Concision & simplicity — the default posture
Applies to every edit this skill makes or reviews:
- Simplify the approach before documenting it. If a design needs a paragraph to justify, first try to make the design smaller.
- Every doc edit should remove at least as much as it adds where the content allows. A net-additive edit needs a reason.
- Redundancy across files is a defect, not thoroughness. The same fact in two docs is one fact to keep and one to delete-and-link.
- Prefer deleting to adding, a section to a file, a link to a copy.
- No new abstraction — code or doc — without a nameable current requirement. "We'll need it later" is not one.
Doc budget
The project's CLAUDE.md (or equivalent) states the number of root docs and each
one's one-line job. Before adding doc N+1: propose retiring or splitting an
existing one instead, and get agreement.
Ledgers append (the decisions log, a retro log). Everything else is rewritten in place — never append a "update" section to a doc whose body is now stale.
Audit
Run at each stage / milestone boundary, after the state file is updated. One line
of output per check — either OK or the fixed response to apply.
- Archetype — still the right row? If it changed, adopt the new row's doc surface and oversight cadence.
- Doc size — any file past its cap, or holding content outside its one-line job?
- Resume cost — would a cold read of the docs exceed ~5k tokens? Any two docs stating the same thing?
- Triggers — did any row in the trigger list fire this milestone?
- Abstractions — anything added (code or doc) with no current consumer?
Anything beyond a one-line in-place fix opens a restructure proposal (below) — the Audit does not itself edit.
Triggers → fixed response
| Trigger | Fixed response |
| A doc's content has drifted from its one-line job | De-overlap the doc set (restructure proposal) |
| Cold resume reads > ~5k tokens of docs, or docs repeat each other | Prune / merge (restructure proposal) |
| The commit-count estimate drifts upward mid-milestone | Split into named sub-milestones; a fresh session for each; the state file carries the baton |
| You're reviewing every commit and it's slowing the work | Move oversight to milestone boundaries; per-change review becomes a subagent on the staged diff |
| A review was skipped and a real bug shipped | Oversight back up one level, or fix task sizing if the tasks were too big to review |
| More than one agent / instance is working the same tree | Each in its own worktree + branch; shared-doc edits deferred to scratchpad notes; one integrator applies them |
| An abstraction exists with no nameable current requirement | Revert it |
| The project crossed an archetype boundary | Adopt the next archetype's doc surface and oversight cadence |
Restructuring .md files — proposal first, always
- When the Audit flags anything beyond a trivial one-line fix, write a short restructure proposal: what merges into what (or is split, or deleted), why, which references get repointed, and the resulting doc budget. Touch no files yet.
- Present it and get an explicit green light. If the user wants changes, revise the proposal — still no edits.
- On approval, execute with minimal edits: move sections verbatim, don't rewrite prose that's already aligned; delete emptied files; repoint every reference in one pass; update the doc budget. One restructure = one docs-only commit.
- Restructure at milestone boundaries only, never mid-stage.
Do not
- Restructure docs autonomously — always propose first.
- Turn this skill into tooling: a doc-count linter, an archetype detector. It is a checklist a person runs.
- Rewrite aligned content to "improve" it.
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.

