@lenardangeloolajay/len-toolkit 1.1.0

package/templates/examples/flutter-handoff/docs/plans/FEAT-001-implementation.md

@@ -0,0 +1,43 @@
+# Implementation Plan: Local note creation
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Awaiting approval
+Feature spec: [FEAT-001 revision 1](../features/FEAT-001-local-note.md)
+Baseline and architecture: Revision 1 drafts, not approved
+Len's chat approval: Not recorded
+Target branch: Unverified; no Flutter repository exists in this example
+
+## Scope
+
+Implement FEAT-001/REQ-001 through REQ-004 only after the baseline assumptions and verification environment are resolved and Len approves the documents.
+This sample plan is not executable as-is.
+
+## Phase 1: Capture and reopen a note offline
+
+State: Awaiting approval
+
+### Tasks
+
+- [ ] Connect editor validation and pending-save state to the verified existing storage API.
+- [ ] Preserve failed drafts and display accessible error/retry feedback.
+- [ ] Load saved notes newest first and show a useful empty state.
+- [ ] Add focused checks covering invalid input, duplicate taps, failed writes, and persistence.
+
+### Verification
+
+- [ ] Confirm and run the real project's test and analysis commands; proposed `flutter test` and `flutter analyze` are unverified here.
+- [ ] On the selected Android emulator, disable connectivity, save a valid note, restart the app, and confirm it remains first.
+- [ ] Exercise empty/oversized input, repeated Save taps, and a controlled storage failure with expected results from REQ-001 through REQ-003.
+- [ ] Record actual outcomes and a meaningful UI screenshot in the [evidence](../evidence/FEAT-001-verification.md).
+
+### Review and checkpoint
+
+- [ ] Review the diff against the approved architecture and scope.
+- [ ] Update the plan, evidence, and handoff.
+- [ ] Stage reviewed phase paths only and inspect the staged diff.
+- [ ] Commit and confirm success with `feat(notes): add verified offline note capture`.
+
+No checkpoint exists in this fictional example.
+If verification fails, use the shared three-attempt policy and retain unfinished work uncommitted.

package/templates/examples/flutter-handoff/docs/product/ARCHITECTURE.md

@@ -0,0 +1,24 @@
+# Pocket Notes architecture
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Draft example
+
+## Proposed design
+
+Use one Flutter screen with a local notes list and an editor.
+Route storage through the host project's existing local-storage API, retaining entered text until a write succeeds.
+Reload saved notes through that same API when opening the app.
+No new dependency, server, or state-management framework is proposed.
+
+## Assumptions and failure modes
+
+An existing storage API and Flutter project are assumed for illustration; neither is present in this example.
+Before approval, inspect the real storage API, its durability guarantees, and failure behavior.
+If it cannot meet the data model, return the architecture decision to GPT and Len instead of inventing a replacement during implementation.
+Storage errors must preserve the editor contents and must not display a false success message.
+
+## Authority
+
+This proposal is not approved or validated.

package/templates/examples/flutter-handoff/docs/product/CONSTRAINTS.md

@@ -0,0 +1,13 @@
+# Pocket Notes constraints
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Draft example
+
+All note creation and listing behavior must work with connectivity disabled.
+The editor and Save action require accessible labels and an announced validation or storage error.
+Do not log note text or require unrelated permissions.
+Android version support is unresolved and must be decided before approval.
+Emulator scenarios can verify the stated behavior in the selected emulator configuration.
+Physical-device validation remains for Len, and no hardware or field-effectiveness claim is applicable to this example.

package/templates/examples/flutter-handoff/docs/product/DATA_MODEL.md

@@ -0,0 +1,20 @@
+# Pocket Notes data model
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Draft example
+
+## Note
+
+| Field | Definition |
+| --- | --- |
+| id | Unique identifier supplied by the existing local storage API |
+| text | Trimmed, nonempty text; maximum 200 Unicode scalar values |
+| createdAt | UTC creation timestamp |
+
+The device's local store owns the saved record.
+An unsaved draft belongs to the editor until successful persistence.
+The storage operation returns the saved record or an error; no result is inferred from merely starting a write.
+No data is sent off-device.
+The actual storage API must be inspected before this draft can be approved.

package/templates/examples/flutter-handoff/docs/product/OVERVIEW.md

@@ -0,0 +1,26 @@
+# Pocket Notes product overview
+
+Created: 2026-09-05T15:29:25+08:00
+Updated: 2026-09-05T15:29:25+08:00
+Revision: 1
+Status: Draft example
+
+## Purpose and users
+
+A fictional personal Flutter Android app for short notes without an account or network connection.
+This example demonstrates specification organization; it is not an implemented application.
+
+## Planned capabilities
+
+FEAT-001 creates and lists local notes, including reopening the app.
+A later feature may delete a selected note after confirmation; its detailed spec is not ready and it is not part of the FEAT-001 plan.
+The main flow is opening the note list, entering text, saving, and seeing the saved item.
+
+## Non-goals
+
+No sync, sharing, search, photos, accounts, or background collection.
+
+## Readiness
+
+Len has not approved this fictional baseline.
+Supported Android versions and the existing project's verification commands must be established before implementation.

package/templates/rules/.cursorrules

@@ -0,0 +1,7 @@
+# Len's Vibe Coding Rules for Cursor / Copilot
+
+- Bias towards standard library and native platform features over third-party packages.
+- Always check if an existing helper or utility in this codebase already solves the problem before writing new code.
+- Keep diffs minimal, atomic, and focused. Do not refactor unrelated code.
+- When planning multi-step features, suggest a phased plan with test checks and git commit milestones.
+- Write code first, followed by concise explanations.

package/templates/rules/AGENTS.md

@@ -0,0 +1,61 @@
+# Len's personal coding workflow
+
+## Start and resume
+
+At each coding session, run `npx len-toolkit start` if setup has not been checked in that session.
+Use the local source command when developing this toolkit before publication.
+Inspect reported instruction differences and preserve custom content; setup success is not permission to implement.
+Read `docs/SPEC_INDEX.md`, the current root `HANDOFF.md`, and its linked approved documents before implementation.
+If no handoff exists, use the spec workflow to create the missing documents and obtain approval first.
+Inspect Git status and reconcile files with the handoff rather than trusting prior conversation memory.
+
+## Specification and authority
+
+GPT explores the entire product with Len, then details features individually.
+GPT proposes architecture; Len approves the product baseline and architecture in chat, then each feature spec and implementation plan.
+Record approval against exact document revisions or a Git commit; never invent an approval record.
+Gemini follows the approved architecture and scope, reports disagreements, and does not silently redesign or add features.
+Changes to behavior, acceptance criteria, or architecture require new approval for affected work.
+Editorial corrections do not expand authorized behavior.
+Search current specs before creating documents, update overlapping specs, and archive superseded documents with replacement links.
+Keep stable filenames, feature and requirement IDs, and Philippine-time ISO 8601 timestamps inside documents.
+Keep behavior in specs, execution tasks in plans, actual results in evidence, and one current handoff pointing to them.
+Choose the Flutter or web stack per project.
+
+## Phase execution and commits
+
+Execute every approved phase without routine approval stops.
+For each phase: implement, run required checks, review correctness and scope, record evidence and progress, and commit only reviewed phase-related paths.
+Inspect the staged diff and preserve unrelated staged or unstaged work; never use blanket staging.
+A phase is complete only when its checks pass and Git confirms a successful commit.
+Use a unique conventional phase commit message as the checkpoint reference; verify its hash from Git after committing.
+Do not make extra commits just to insert a commit's own hash into that same commit.
+Continue to the next approved phase after the checkpoint succeeds.
+A failed check or commit leaves the phase incomplete; interrupted or failing work stays uncommitted.
+Update the current handoff with completed work, unfinished work, actual checks, attempts, and the next action before ending a session.
+Never push, reset, discard edits, or overwrite working features without explicit authorization.
+
+## Failure recovery
+
+Reproduce bugs through the real user flow where possible, then trace shared callers before editing.
+Investigate and fix within the approved design.
+Allow at most three unsuccessful fix-and-check attempts for the same unresolved problem after its initial observed failure.
+Persist counts and attempted fixes in the handoff across sessions; renaming a problem does not reset its count.
+After the third unsuccessful attempt, stop affected work and report evidence, attempted fixes, outstanding edits, and what is needed to proceed.
+Stop affected work immediately for a required user decision, unavailable access or hardware, or necessary scope/architecture changes.
+Continue independent approved work only when it does not rely on the blocked decision.
+Fix failures caused by or blocking the approved work; report other issues separately rather than expanding scope.
+
+## Evidence and engineering
+
+Use existing code, the standard library, and native platform features before adding custom machinery.
+No new dependency without Len's authorization.
+Preserve input validation, error handling, security, accessibility, existing working features, and tests.
+Record actual verification commands or scenarios, results, conditions, timestamps, and limitations.
+Never describe an unrun check as passing or implementation as proof of real-world effectiveness.
+Emulator checks establish emulator behavior; Len handles physical-device validation.
+Keep emulator, physical-device, hardware-bench, and field evidence separate and pending until actual results exist.
+Attach screenshots for meaningful UI checks when capture is available.
+Do not put credentials or secrets in specs, handoffs, examples, or evidence.
+Use plain dashes, not em dashes, and one full sentence per line in long Markdown.
+Do not manually edit CHANGELOG.md or generated files, and do not add an agent co-author to commits.

package/templates/rules/GEMINI.md

@@ -0,0 +1,7 @@
+# Len's Gemini entry point
+
+Read the project-root `AGENTS.md` for the shared workflow policy.
+Then read `docs/SPEC_INDEX.md`, root `HANDOFF.md`, and every approved document it links before implementing.
+Paths above are relative to the project root even when this entry point is under `.agents/rules/`.
+Read relevant skills from `.agents/skills/` explicitly if automatic discovery is unavailable.
+GPT defines architecture with Len; execute only the approved handoff and use the shared phase, recovery, and evidence rules.

package/templates/skills/a-philosophy-of-software-design/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: a-philosophy-of-software-design
+description: Apply John Ousterhout-inspired software design rules when reducing complexity, designing module boundaries, or reviewing APIs and abstractions.
+license: MIT
+---
+
+# A Philosophy of Software Design Skill
+
+Use this skill when a task involves module design, API design, information hiding, abstraction depth, cognitive load, or refactoring shallow interfaces.
+
+Before making design or code decisions, read and apply [a-philosophy-of-software-design.mini.md](a-philosophy-of-software-design.mini.md). Use [a-philosophy-of-software-design.md](a-philosophy-of-software-design.md) only as a deeper reference when the mini rules are not enough for the current design tradeoff.

package/templates/skills/a-philosophy-of-software-design/a-philosophy-of-software-design.md

@@ -0,0 +1,370 @@
+# OBEY A Philosophy of Software Design by John Ousterhout
+
+## Purpose
+
+This repository follows **A Philosophy of Software Design** in the sense of John Ousterhout:
+fight complexity directly by designing modules with deep value, clean interfaces, strong information hiding, and low cognitive load.
+
+All code generation, edits, and reviews must optimize for:
+- lower complexity
+- deeper modules
+- simpler interfaces
+- stronger information hiding
+- fewer special cases
+- clear separation between interface and implementation
+- strategic design over tactical patching
+
+This file is a binding engineering policy: `MUST` is binding, `SHOULD` is a strong default, and `MUST NOT` is forbidden.
+
+---
+
+## Primary Directive
+
+Complexity is anything that makes software hard to understand or hard to change.
+
+When uncertain, prefer the design that:
+1. reduces the number of things a reader must know at once
+2. hides more details behind a stable interface
+3. eliminates exceptions and awkward cases
+4. creates a deeper module instead of a shallower one
+5. lowers future cognitive load, not just present typing effort
+
+Do not optimize for shorter files, fewer lines, or clever compactness if complexity rises.
+
+---
+
+## Core Complexity Rules
+
+### Symptoms of Complexity
+Treat these as architectural warnings:
+- change amplification
+- cognitive load
+- unknown unknowns
+- hidden dependencies
+- information spread across many places
+- temporal coupling that readers must reconstruct mentally
+
+### Default Response
+When a feature feels awkward, first ask:
+- is the interface too wide?
+- is the behavior scattered?
+- are details leaking that should be hidden?
+- are there too many special cases?
+- are we solving a tactical local problem while increasing global complexity?
+
+---
+
+## Module Depth Rules
+
+### Prefer Deep Modules
+A deep module offers a simple interface but hides substantial complexity behind it.
+
+Rules (MUST unless marked SHOULD or MUST NOT):
+1. Design modules to hide meaningful internal complexity.
+2. Prefer a small interface with strong semantics over a large surface with minor helpers.
+3. Make each module carry its own weight.
+4. A module that only forwards work is usually too shallow.
+
+### Avoid Shallow Modules
+Shallow modules are bad when:
+- the interface exposes almost as much complexity as the implementation
+- layers exist mostly to redirect calls
+- small wrappers multiply concepts without reducing reader burden
+
+Anti-patterns (MUST NOT):
+- pass-through service classes
+- thin wrappers around libraries with no simplification
+- helper modules that only rename obvious operations
+
+---
+
+## Information Hiding Rules
+
+1. Hide design decisions that are likely to change.
+2. Hide internal data representations.
+3. Hide incidental workflow steps and bookkeeping.
+4. Keep callers from depending on implementation detail, performance hacks, or storage shape.
+5. Encapsulate messy edge conditions and normalization logic.
+
+Anti-patterns (MUST NOT):
+- exposing internal representation or state through module interfaces
+- leaking storage, protocol, framework, or file-format details through module interfaces
+- callers coordinating object internals across multiple modules
+
+---
+
+## Interface Design Rules
+
+1. Design interfaces around what clients need to know, not how the implementation works.
+2. Keep interfaces narrow but meaningful.
+3. Avoid APIs that require callers to stage operations in fragile sequences.
+4. Eliminate arguments that only exist to expose internal implementation choices.
+5. Use names and method shapes that reveal the abstraction, not the mechanism.
+
+Good interface signs (SHOULD):
+- few methods
+- strong semantic guarantees
+- limited required context
+- callers do not need to understand internals
+
+Bad interface signs (warning; usually MUST NOT):
+- many configuration flags
+- call-order traps
+- multiple setup methods required before use
+- booleans and mode parameters switching internal behavior
+
+---
+
+## Strategic Programming over Tactical Programming
+
+### Strategic Programming
+1. Spend time reducing future complexity, not only making the current change pass.
+2. Reshape abstractions when recurring friction appears.
+3. Invest in interfaces and decomposition that make future changes local.
+4. Leave behind clearer structure after every substantial edit.
+
+### Tactical Programming
+Avoid:
+- patching local symptoms while increasing global complexity
+- copy/paste to meet a deadline
+- exposing one more internal detail instead of designing a better boundary
+- adding flags and exceptions to avoid a better abstraction
+
+---
+
+## General-Purpose vs Special-Purpose Modules
+
+1. Prefer modules that capture a reusable concept at the right abstraction level.
+2. Do not overfit interfaces to one narrow caller if a slightly more general concept is obvious.
+3. Do not generalize so far that the abstraction becomes vague.
+4. The best module is specific enough to be strong and general enough to be reusable within its domain.
+
+---
+
+## Error Handling and Exception Elimination
+
+1. Define APIs that make misuse hard.
+2. Define away invalid states and awkward cases where possible.
+3. Eliminate exception cases by changing the interface or invariant, not only by adding more checks.
+4. Use special/general decomposition when unusual cases clutter the main abstraction.
+5. Keep the normal path obvious and the exceptional path isolated.
+
+Anti-patterns (MUST NOT):
+- APIs that require every caller to repeat defensive ceremony
+- “special case” branches scattered across many call sites
+- exposing half-valid objects and asking callers to tiptoe around them
+
+---
+
+## Pull Complexity Downward
+
+1. Put complexity in one place rather than many.
+2. Hide intricate logic behind a simpler public contract.
+3. Prefer a slightly more complex implementation if it makes all callers simpler.
+4. Remove repeated reasoning burdens from call sites.
+
+This is the opposite of pushing complexity outward through flags, setup steps, and coupled operations.
+
+---
+
+## Comment Rules
+
+Comments must reduce complexity, not narrate obvious code.
+
+Use comments for:
+- interface contracts
+- non-obvious invariants
+- hidden design decisions
+- the reason an abstraction exists
+- tricky implementation facts callers do not need to know
+
+Do not use comments to compensate for:
+- bad naming
+- poor decomposition
+- confusing control flow
+- missing abstraction
+
+---
+
+## Function and Variable Rules
+
+1. Keep functions deep enough to hide a meaningful amount of work.
+2. Avoid long functions only when they create cognitive load, not as a numeric ritual.
+3. Avoid pass-through variables that do not add meaning.
+4. Use variables to capture meaning, not to mirror syntax.
+5. Keep local details local.
+
+Anti-patterns (MUST NOT):
+- chains of tiny functions where readers must jump constantly to understand one idea
+- variables introduced only to satisfy style rather than clarity
+- exposing intermediate states that should stay internal
+
+---
+
+## Temporal Decomposition Rules
+
+1. Do not structure modules primarily around execution order if the real structure is conceptual.
+2. Prefer decomposition around stable concepts and responsibilities.
+3. Initialization steps, processing phases, and cleanup stages should not force readers to reconstruct the design from time-order alone.
+4. Keep call ordering simple and explicit where it matters.
+
+Anti-patterns (MUST NOT):
+- `prepare/process/finalize` everywhere without domain concepts
+- APIs that require secret temporal knowledge
+- partial objects whose meaning depends on which phase has already run
+
+---
+
+## Special-General Decomposition
+
+Use special-general decomposition when a small number of exceptions are cluttering the main logic.
+
+Rules (MUST unless marked SHOULD or MUST NOT):
+1. Keep the general case simple.
+2. Isolate the unusual or rare behavior.
+3. Do not pollute the main abstraction with every edge case.
+
+This is preferable to accreting conditionals into the core path forever.
+
+---
+
+## Combine or Separate Code
+
+1. Separate code only when the separation reduces complexity, hides a real design decision, or creates a stronger abstraction.
+2. Combine code when split pieces force readers to jump between shallow fragments to understand one idea.
+3. Keep related state, behavior, and invariants together when separating them would create change amplification.
+4. Do not preserve a boundary merely because it already exists if it exposes almost as much complexity as it hides.
+5. Prefer one coherent deeper module over several tiny modules that require callers to coordinate details.
+
+Anti-patterns (MUST NOT):
+- splitting code by execution phase when the stable concept is not temporal
+- separating normal and special cases so far apart that their shared invariant is hidden
+- adding helper layers that distribute one design decision across many files
+
+---
+
+## Design Alternatives and Comments-First Design
+
+1. For non-trivial design choices, compare at least two plausible designs before implementing the first one that works.
+2. Evaluate alternatives by interface simplicity, information hiding, special-case reduction, and future cognitive load.
+3. When an interface or abstraction is unclear, sketch the public contract and explanatory comments before committing to implementation.
+4. Use comments-first design to clarify abstraction boundaries, not to preserve vague or misleading code.
+5. Revise the abstraction when the comment needed to explain it becomes complicated.
+
+Anti-patterns (MUST NOT):
+- accepting the first design because it is locally convenient
+- using comments to justify a confusing interface instead of changing the interface
+- documenting implementation mechanics that callers should not need to know
+
+---
+
+## Naming, Consistency, and Obviousness
+
+1. Names must reveal the abstraction, not the internal mechanism.
+2. Use consistent names, argument order, error behavior, and interface conventions for related operations.
+3. Prefer obvious code where a reader can infer behavior from local structure and names.
+4. Remove non-obvious behavior unless it is hidden behind a clear contract.
+5. When code surprises a reader, treat that as complexity even if the code is short.
+
+---
+
+## Performance, Trends, and Tests
+
+1. Do not sacrifice module depth or information hiding for performance without evidence that the tradeoff matters.
+2. When performance matters, hide optimization details behind stable interfaces so callers do not inherit the complexity.
+3. Prefer measurements and targeted changes over broad speculative tuning.
+4. Do not adopt a trend, paradigm, pattern, or framework unless it reduces complexity in this codebase.
+5. Use tests to preserve behavior while changing structure, but do not let test convenience force shallow or leaky interfaces.
+
+---
+
+## Review Rules
+
+When reviewing code, actively look for:
+- shallow modules
+- pass-through layers
+- interfaces that expose implementation detail
+- excessive flags or mode parameters
+- scattered special cases
+- cognitive load caused by too many interacting modules
+- hidden temporal constraints
+- complexity pushed to callers
+- comments that explain what should be encoded in structure
+- tactical patches that increase future difficulty
+
+---
+
+## Forbidden Patterns
+
+### Shallow Decomposition
+- splitting code into many tiny units that do not reduce understanding cost
+- wrappers and facades that add names but not simplification
+
+### Interface Leakage
+- APIs that expose storage, transport, or caching mechanics to ordinary callers
+- method sequences that require callers to know internal workflow
+
+### Tactical Complexity Debt
+- adding one more flag, callback, or conditional instead of improving the abstraction
+- fixing the local symptom while making the design harder overall
+
+### Complexity Spread
+- repeating the same special handling in many places
+- making all callers responsible for one module's awkwardness
+
+---
+
+## Code Generation Rules
+
+When generating code, default to:
+1. identify the concept that deserves a module boundary
+2. design the narrowest strong interface around that concept
+3. hide volatile or complicated details inside
+4. simplify all callers, even if implementation grows slightly
+5. isolate special cases
+6. reduce the number of facts a reader must juggle at once
+
+Avoid by default:
+- pass-through layers
+- needless tiny abstractions
+- exposing internal data formats
+- temporal APIs with fragile call sequences
+- multiplying concepts without reducing complexity
+
+---
+
+## Testing Rules
+
+1. Test public behavior and interface contracts.
+2. Test hidden complexity through stable public APIs where possible.
+3. Add focused tests around isolated special cases.
+4. Avoid tests that force callers to know implementation detail if the abstraction promises otherwise.
+
+---
+
+## Review Checklist
+
+Before finalizing any change, verify:
+- Did this change reduce or increase cognitive load?
+- Is the module deeper or shallower after the edit?
+- Did we hide more complexity behind a stable interface?
+- Did we reduce special-case handling at call sites?
+- Did we remove an implementation detail from the public surface?
+- Did we avoid a pass-through layer?
+- Does the interface describe the abstraction rather than the mechanism?
+- Did we improve future changeability, not just present convenience?
+
+If any answer is no, revise before shipping.
+
+---
+
+## Final Instruction
+
+When uncertain, prefer the design that:
+1. creates a deeper module
+2. hides more complexity
+3. reduces special cases
+4. lowers cognitive load for callers
+5. improves the abstraction instead of patching around it
+
+Fight complexity directly.

package/templates/skills/a-philosophy-of-software-design/a-philosophy-of-software-design.mini.md

@@ -0,0 +1,46 @@
+# OBEY A Philosophy of Software Design by John Ousterhout
+
+## When to use
+
+Use for module design, API changes, decomposition, refactoring, naming, comments, tests, performance work, and changes that feel awkward or spread complexity across files.
+
+## Primary bias to correct
+
+Working code, small pieces, familiar patterns, flags, wrappers, and extra documentation do not make a design simple when they increase cognitive load or leak knowledge.
+
+## Decision rules
+
+- Use reduced complexity as the primary success metric. Prefer the design that lowers cognitive load, change amplification, hidden dependencies, temporal coupling, and the number of facts a reader must hold at once.
+- Treat design as continuous work. A first working patch is not done if it worsens future changeability; compare plausible alternatives for non-trivial interface, decomposition, or abstraction choices.
+- Prefer deep modules: small, semantic interfaces that hide meaningful internal complexity. Reject pass-through services, thin library wrappers, helper modules, and tiny split-outs that add names without reducing reader burden.
+- Design interfaces around what callers need to know, not how the implementation works. Avoid fragile staging, setup sequences, mode flags, configuration knobs, and arguments that expose internal choices.
+- Hide volatile decisions, internal representations, storage shape, protocols, file formats, performance hacks, bookkeeping, normalization, and messy edge handling inside the module that owns the knowledge.
+- Pull complexity downward when the lower module owns the detail. Prefer a slightly more complex implementation if it gives callers a simpler public contract and removes repeated reasoning from call sites.
+- Choose generality at the right level. Avoid one-caller overfitting, vague speculative abstractions, and core paths polluted by rare edge cases; isolate special behavior with special-general decomposition.
+- Combine or split by total complexity, not by size, runtime order, habit, or aesthetics. Keep related state, behavior, invariants, and design decisions together unless the new boundary is deeper and independently understandable.
+- Reduce exception surface by changing interfaces or invariants where possible. Define away invalid states and awkward cases instead of making every caller repeat defensive ceremony.
+- Use comments to reduce complexity: document interface contracts, invariants, hidden design decisions, rationale, and tricky implementation facts callers should not need to know. Do not narrate code or compensate for bad names, poor decomposition, or confusing flow.
+- Treat names, consistency, and obviousness as design information. Names should reveal abstractions rather than mechanisms; related operations should share conventions; surprising code is complexity even when short.
+- Use tests to protect behavior through public contracts and stable APIs, especially around hidden complexity and isolated special cases. Do not let test convenience force shallow or leaky interfaces.
+- Add performance optimizations, trends, paradigms, patterns, or frameworks only when they reduce complexity in this codebase or evidence shows the tradeoff matters; hide optimization details behind stable interfaces.
+
+## Trigger rules
+
+- When a feature feels awkward, one change spreads across files, or reviewers must reconstruct hidden dependencies, look for missing information hiding, shallow modules, temporal coupling, or complexity pushed to callers.
+- When adding a module, layer, service, helper, wrapper, facade, pattern, option, callback, or argument, prove that it hides more complexity than it adds.
+- When touching an API, check whether ordinary callers must know sequencing, representation, storage, transport, caching, protocol, file format, internal workflow, or too many setup steps.
+- When adding a special case, flag, exception path, conditional, or exposed container, first ask whether the owning module can eliminate the invalid state, isolate the unusual behavior, or provide a stronger operation.
+- When splitting, extracting, or introducing variables, check whether the new boundary or name captures meaning or only adds jumps, pass-through state, and visible intermediate steps.
+- When code is organized as `prepare/process/finalize`, staged objects, or other execution-order phases, verify that temporal structure is the real concept; otherwise reorganize around stable responsibilities.
+- When naming is vague, mechanism-focused, inconsistent, or surprising, reconsider the abstraction boundary instead of accepting a near miss.
+- When comments get long, duplicate code, justify a confusing interface, or explain usage by exposing internals, redesign the abstraction or move the missing contract to the interface.
+- When optimizing performance, measure first and hide the optimization; do not sacrifice module depth or information hiding without evidence that the tradeoff matters.
+- When testing or reviewing, focus on public behavior, interface contracts, hidden complexity through stable APIs, and special cases isolated behind the abstraction.
+
+## Final checklist
+
+- Did the change reduce the effort required to understand, modify, verify, and extend the system?
+- Does every interface element, wrapper, layer, helper, option, and name hide enough complexity to justify its existence?
+- Are important decisions localized, dependencies visible, caller-needed constraints documented, and mutable internals protected?
+- Did common cases become automatic while rare controls, special cases, performance tricks, and exception details stayed out of the common path?
+- Are names precise and consistent, comments current and non-duplicative, and conventions followed unless new information justified changing them?