/ct-lean

name: ct-lean
description: >-
  Lean change discipline for CLEO work: the smallest change that fully solves the task, and
  a reply a busy owner understands in one read. Use on every coding task (writing, fixing,
  refactoring, reviewing, choosing dependencies) and when the owner asks for the simplest
  solution, YAGNI, or complains about over-engineering or bloat; also for a lean code review
  ("review this", "review my PR") or a whole-repo audit ("audit the repo", "what can I
  delete"). Never trades away evidence
  gates, package boundaries, validation, data safety or anything the task asked for.
license: MIT
metadata:
  version: 1.6.0
  tier: core
  install: harness
  covers:
    - packages/core/src/orchestration/lean-change.ts
    - packages/cleo/src/cli/commands/lean.ts
    - packages/core/src/orchestration/lean-debt.ts
    - packages/core/src/orchestration/lean-gain.ts
    - packages/core/src/nexus/brief-map.ts
  lastReviewed: 2026-10-13
  stability: stable
  attribution: Adapted from Ponytail 5.1.0 by DietrichGebert (MIT) — https://github.com/DietrichGebert/ponytail

ct-lean — the smallest complete change

The best code is the code never written. Solve the whole task with the least new code, then end the reply with one or two lines: what you skipped or did not check, and any risk the owner must know.

Levels

| Level | What changes | |---|---| | `lite` | Build what was asked. When a smaller option fully works, name it in one line and let the owner pick. | | `full` | The rules below. Default. | | `ultra` | `full`, and question the request first: push back on any part the need does not justify. | | `off` | No lean rules. |

The level resolves from `CLEO_LEAN_LEVEL`, then the session level, then the `lean.level` config key, then `full`. When the owner asks for a level ("go ultra", "lean off"), set it: `cleo lean level ultra --session` for this session, `cleo lean level lite` for the project, `--global` for every project. `cleo lean level` alone shows the level and its source. `cleo lean gain --card` shows the measured benchmark scoreboard: averages, never a number for this repo. Subagents get the same level: CLEO-spawned ones through the spawn prompt, Claude Code Agent-tool ones through the SubagentStart hook (`cleo hook subagent-start`, installed with the heavy-command hook; scope it with `CLEO_LEAN_SUBAGENT_MATCHER`, a regex over the agent type).

Before you write

Read the task (`cleo show <id> --full`) and the code it touches. List every place the change must reach: callers, tests, fixtures, config, exports, contracts. Run `cleo nexus impact <symbol>` before editing a symbol, and grep for runtime callers static analysis cannot see. Check what the change could break: data it would destroy or expose, callers that stop working, stores it would migrate. That is scope. Extra features are not.

Take the first option that fully works

1. **Does it need to exist?** Skip features, options and flexibility nobody asked for, and name them in one line. A vague request gets the smallest version that does the core job. 2. **Already in this codebase?** A helper, accessor, contract or pattern: use it the way the surrounding code does. Search `packages/core/src` and `packages/contracts/src` first; `cleo map --brief` lists what exists per folder (set `lean.map` to get it in `cleo briefing`). 3. **Standard library or platform feature?** Use it, unless the repo has its own (a house chokepoint such as `openDualScopeDb` or `cleo run` beats a raw primitive). 4. **An installed dependency?** Use it. Never add a dependency for a few lines. 5. **One line a reader gets at a glance?** One line. 6. **Otherwise** the minimum code that works, in the package the boundary table assigns.

Rules

• Lazy about the solution, never about the change: finish every part the task needs,

including the callers, tests, fixtures and docs the change breaks.

• No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code

nobody asked for. Deletion beats addition. Keep the layers, contracts and conventions the repo already has.

• The shortest working diff wins once you know everything it must touch. A one-liner that

needs decoding is not short.

• Comment only the why the code cannot show, in one line. Exported symbols still get TSDoc.
• Bug fix: grep every caller of the function you touch, then fix the root cause once in the

shared code. No workaround at a call site.

• Code you move or merge keeps its error handling and validation.
• Between options of equal size, take the one that is correct on edge cases.
• New non-trivial logic (a branch, a loop, a parser, a store write, security) leaves one

small test. Trivial changes need none. Run single test files through `cleo run --wait`.

• A shortcut with a known limit gets a comment: `shortcut: <the limit>, <when to upgrade>`.

`cleo lean debt` lists every one (and flags those with no upgrade trigger); `cleo lean debt --file-tasks --parent <epic>` files each new one as a `lean-debt` task.

Never cut

• Validation at trust boundaries, error handling that prevents data loss, security,

privacy (one user's data never reaches another, e.g. many recipients go in BCC, not To), accessibility, and anything the task or owner asked for.

• A risk your change creates is part of the change: when the fix is small and in scope,

make it, then name it in the reply. Only report a risk you cannot fix in scope.

• CLEO evidence: every gate gets programmatic evidence (`cleo verify`), never self-attested.
• Type safety: no `any`, no `as unknown as X`; shared types live in `packages/contracts/`.
• The package boundary and the `cleo check arch` gates; a smaller diff in the wrong package

is not smaller.

• Store safety: the DB chokepoint, migrations, backups, and the tracked identity files.

Replies

Answer first: the first line is the result, answer or decision. Then only the evidence the reader needs (bullets or a small