The problem
A coding agent with no operating rules does whatever the last prompt implied. It starts building before it understands the goal, claims work is done without proof, and burns the most expensive model on reading logs. Fixing that by re-explaining yourself every session does not scale. I wanted the rules to live in files, apply to every project, and be checked by a machine.
Role and constraint
I designed and wrote the whole configuration: the global rules file, the skills, the agents, the status line, the hooks and the verification script. The constraint I set myself was that the router file every session reads must stay under 150 lines. If it cannot fit, the rule belongs somewhere narrower.
The decision: route work to the cheapest capable model
The expensive way to research a codebase is to let the main agent read it. Every file it opens stays in its context for the rest of the session, and it is the largest, costliest model in the system.
So the configuration defines two subagents pinned to specific models, and the rules file says when each must be used. A bulk-researcher runs on the cheapest model and exists to read a great deal and return a little: documentation trawls, log analysis, multi-file sweeps. A visual-qa agent runs on a mid-tier model and drives a browser, so screenshots accumulate in its context rather than the main thread’s. The main model keeps its context for judgment.
The alternative I rejected was leaving model choice to the agent per task. It sounds flexible, and in practice the agent picks the model it is already running on. Pinning the model in the agent definition removes the decision, and the verification script fails if the pin is missing.
Enforcing the structure
Rules that are not checked decay. The configuration ships with a verification script that asserts 74 structural invariants across five sections, and it exits non-zero when any fails.
- Prerequisites: the seven tools the skills depend on are on the path.
- Router: the rules file exists, stays under 150 lines, contains its required sections, and contains none of a list of forbidden strings.
- Skills: each of the seven skills has valid frontmatter, a description that starts with the phrase that makes it auto-trigger, and a body of real length. Six checks per skill.
- Agents: each agent exists, is pinned to its intended model, and has a description long enough to route on. Five checks per agent.
- Hygiene: the settings file parses, the deny list has at least twenty rules, no sensitive file is tracked, and the repository is initialised.
The compounding piece
The skill I consider most important is the smallest. When I correct the agent, or when a gotcha surfaces, a capture-learning skill writes the lesson to the narrowest scope that will surface it next time: a specific skill file, a project’s rules, the global rules, or the environment notes. It explicitly refuses to record one-off preferences. The result is a configuration that gets more specific to how I work with every session, without the rules file growing past its cap.
Evidence
- Seven skills that trigger from their own descriptions, covering requirements interviews, project scaffolding, visual verification, learning capture, branding, campaigns and video editing.
- Two agents pinned to two different models with a stated cost and context rationale for each.
- A Python status line that renders model, directory, branch, context usage and session cost, and never breaks the line on missing input.
- Hooks that play a sound and push the configuration repository when a session ends, and that self-heal a plugin cache on session start.
- A written design document with eight stated principles and six constraints, and the verification script that holds the configuration to them.
Where it stands
The repository is private because it holds my working environment. I am happy to walk through any part of it, and the verification output above is reproducible on request.