@lenardangeloolajay/len-toolkit 1.1.0

package/templates/skills/code-complete/code-complete.md

@@ -0,0 +1,354 @@
+# OBEY Code Complete by Steve McConnell
+
+## Purpose
+
+This repository follows **Code Complete** in the sense of Steve McConnell:
+apply disciplined software construction practices that reduce defects, improve readability, and produce robust code under real-world constraints.
+
+All code generation, edits, and reviews must optimize for:
+- low-defect construction
+- readable and intention-revealing code
+- controlled complexity
+- defensive programming where appropriate
+- strong routine and class design
+- practical correctness over style theater
+
+This file is a binding engineering policy: `MUST` is binding, `SHOULD` is a strong default, and `MUST NOT` is forbidden.
+
+---
+
+## Primary Directive
+
+Construction quality is not accidental.
+
+When uncertain, choose the option that:
+1. lowers defect probability
+2. makes the code easier to inspect and reason about
+3. reduces control-flow complexity
+4. uses data and routines clearly
+5. protects the program against invalid states and misuse
+
+Do not optimize for cleverness, minimal keystrokes, or fashionable idioms at the cost of clarity.
+
+---
+
+## Foundational Construction Rules
+
+1. Write code primarily for human readers.
+2. Favor clarity, locality, and explicitness over trickiness.
+3. Keep control flow simple and visible.
+4. Make correctness easier to achieve than incorrectness.
+5. Use conventions consistently.
+
+---
+
+## Construction Prerequisites and Decisions
+
+1. Do not treat construction as isolated typing; verify that requirements, architecture, major risks, and coding conventions are clear enough for the change.
+2. Resolve major construction decisions before large implementation work: language constraints, error policy, data representation, reuse strategy, integration approach, and testing approach.
+3. Use upstream uncertainty as a reason to build a small validated slice, not as an excuse for speculative code.
+4. Keep the software metaphor or design model only if it helps make concrete construction decisions.
+5. Measure twice before cutting when an early decision will be expensive to reverse.
+
+---
+
+## Pseudocode Programming Process
+
+1. For complex routines, sketch the routine in precise pseudocode or comments before filling in details.
+2. Refine pseudocode until it names the real steps at a consistent abstraction level.
+3. Convert clear pseudocode into code and keep only comments that still add intent, constraints, or rationale.
+4. Do not use pseudocode as a substitute for understanding the algorithm.
+
+---
+
+## Routine Design Rules
+
+1. Routines should have one clear purpose.
+2. The routine name should describe the result or action precisely.
+3. Keep the interface as small as practical.
+4. Avoid long parameter lists and flag arguments.
+5. Separate setup, validation, computation, and side effects when they are conceptually different.
+6. Return values should be meaningful and hard to misuse.
+7. Prefer guard clauses and straightforward structure over deeply nested logic.
+
+Anti-patterns (MUST NOT):
+- routines that do several unrelated things
+- routines whose names describe implementation detail instead of purpose
+- many hidden side effects
+- boolean parameters that switch routine mode
+
+---
+
+## Variable and Data Rules
+
+1. Use names that reveal purpose and meaning.
+2. Keep variable scope as small as practical.
+3. Initialize variables deliberately.
+4. Prefer named constants or stable values where a variable is not meant to change.
+5. Avoid magic numbers and unexplained sentinel values.
+6. Use stronger data types when primitives hide meaning.
+
+Anti-patterns (MUST NOT):
+- reused loop/index/temp variables beyond their purpose
+- long-lived mutable locals carrying many meanings
+- values whose units or semantics are unclear
+
+---
+
+## Data Type Rules
+
+1. Choose data types that make invalid or ambiguous values harder to represent.
+2. Name constants for magic values, units, bounds, and sentinel meanings.
+3. Use booleans only for true binary meanings; replace flag fields with clearer states when needed.
+4. Use enumerations or named alternatives when a value belongs to a closed set.
+5. Use arrays, records, maps, and tables only where their shape communicates the data meaning.
+6. Encapsulate unusual data structures behind routines or types that reveal purpose.
+7. Keep units, ranges, precision, encoding, and ownership visible near the data they affect.
+
+---
+
+## Control Flow Rules
+
+1. Prefer the simplest control flow that expresses the logic.
+2. Keep nesting shallow when possible.
+3. Replace complicated boolean logic with named predicates or clearer structure.
+4. Use case/switch constructs only when they improve clarity.
+5. Eliminate impossible paths and dead branches.
+6. Avoid surprising exits unless they clarify the routine.
+
+Anti-patterns (MUST NOT):
+- deeply nested conditionals
+- complicated loop exits with hidden state changes
+- control flow dependent on side effects in expressions
+- clever one-liners that obscure the logic
+
+---
+
+## Statement, Conditional, and Loop Rules
+
+1. Organize straight-line code so dependencies appear before use and related statements stay together.
+2. Keep conditionals positive and direct when possible.
+3. Put the normal path where readers can find it quickly.
+4. Use loops with clear initialization, termination, and update rules.
+5. Keep loop bodies focused; extract work when a loop hides several responsibilities.
+6. Avoid unusual control structures unless they are clearer than ordinary alternatives.
+7. Use table-driven methods when repeated branching is stable and the table can be validated.
+
+---
+
+## Defensive Programming Rules
+
+1. Validate inputs at trust boundaries.
+2. Use assertions or invariant checks where programmer assumptions matter.
+3. Distinguish between recoverable conditions and programming errors.
+4. Fail in a way that preserves diagnosability.
+5. Do not silently continue from corrupted or impossible state.
+
+Anti-patterns (MUST NOT):
+- assuming all callers are correct
+- burying invalid state until it causes distant failures
+- swallowing exceptions without context
+
+---
+
+## Error Handling Rules
+
+1. Handle errors at the right level of abstraction.
+2. Preserve useful context.
+3. Do not let error handling dominate the normal path.
+4. Standardize similar failure handling.
+5. Prefer explicit, well-understood failure semantics over ad hoc conventions.
+
+---
+
+## Table-Driven and Data-Driven Rules
+
+1. Prefer data-driven logic over long repeated condition chains when the mapping is stable and explicit.
+2. Use tables or maps for configuration-like decisions.
+3. Keep the structure obvious and validated.
+4. Do not hide complex logic in inscrutable data encodings.
+
+---
+
+## Class and Module Design Rules
+
+1. Each class or module should own a focused responsibility.
+2. Separate interface from implementation.
+3. Hide representation and incidental detail.
+4. Keep classes cohesive.
+5. Reduce coupling through clear contracts and limited knowledge of internals.
+
+Anti-patterns (MUST NOT):
+- god classes
+- modules with mixed persistence, formatting, business logic, and integration concerns
+- public surfaces that expose internal bookkeeping
+
+---
+
+## Complexity Management Rules
+
+1. Treat rising complexity as a defect risk.
+2. Prefer simple code over clever code.
+3. Break apart large or tangled routines and modules.
+4. Remove duplication that multiplies maintenance effort.
+5. Choose designs that reduce the amount a maintainer must keep in working memory.
+
+---
+
+## Construction with Preconditions and Postconditions
+
+1. Be explicit about routine assumptions.
+2. Encode important invariants close to the code they protect.
+3. Keep contracts simple and testable.
+4. Use assertions for programmer mistakes, validation for external input, and domain errors for expected business failures.
+
+---
+
+## Comment Rules
+
+1. Comments should explain intent, rationale, contracts, and non-obvious facts.
+2. Do not comment obvious code instead of improving it.
+3. Keep comments accurate or delete them.
+4. Prefer self-documenting structure first, comments second.
+
+---
+
+## Coding Standards Rules
+
+1. Be consistent within the codebase.
+2. Use formatting, naming, and file structure to support readability.
+3. Standardize common idioms so readers do not need to relearn style per module.
+4. Prefer a shared convention over local personal taste.
+
+---
+
+## Incremental Construction Rules
+
+1. Build in small, verifiable increments.
+2. Integrate frequently enough to surface conflicts and misunderstanding early.
+3. Keep partial work from rotting in long-lived isolation.
+4. Review and improve code as part of construction, not only after it.
+
+---
+
+## Quality, Collaboration, Debugging, and Refactoring
+
+1. Use reviews, inspections, pair work, tests, and static checks according to the risk of the code.
+2. Treat debugging as diagnosis: reproduce, isolate, explain, fix, and verify rather than guessing.
+3. Fix the root cause when practical, not only the symptom.
+4. Add tests around defects so the same failure is easier to detect next time.
+5. Refactor when structure hides intent, duplicates knowledge, or raises defect probability.
+6. Keep refactoring separate from behavior changes when that improves reviewability.
+
+---
+
+## Performance, Integration, Tools, and Craftsmanship
+
+1. Do not tune performance until the requirement and evidence justify it.
+2. When tuning is justified, measure before and after, and keep clarity unless the tradeoff is explicit.
+3. Integrate frequently enough to expose construction conflicts early.
+4. Use programming tools, scripts, debuggers, profilers, editors, and build automation to reduce error-prone manual work.
+5. Keep layout and style consistent enough that readers can focus on meaning.
+6. Prefer self-documenting code, but add documentation where the code cannot express intent, constraints, or usage.
+7. Treat personal discipline, curiosity, and ability to withstand careful review as part of construction quality.
+
+---
+
+## Review Rules
+
+When reviewing code, actively look for:
+- unclear names
+- weak routine boundaries
+- long parameter lists
+- unnecessary nesting
+- hidden side effects
+- poor defensive checks at trust boundaries
+- duplicated logic
+- confusing control flow
+- god classes or mixed responsibilities
+- comments compensating for poor structure
+
+---
+
+## Forbidden Patterns
+
+### Cleverness over Clarity
+- dense tricks that are hard to inspect
+- compressed expressions that save lines but increase interpretation cost
+
+### Routine Bloat
+- one routine doing several phases and concerns
+- long signatures with many unrelated parameters
+
+### Defensive Vacuum
+- no validation at trust boundaries
+- no checks around critical assumptions
+- silent fallback from impossible state
+
+### Comment-as-Crutch
+- obvious comments over bad code
+- stale comments that mislead
+
+### Consistency Neglect
+- arbitrary naming and formatting changes
+- module-specific mini dialects inside one codebase
+
+---
+
+## Code Generation Rules
+
+When generating code, default to:
+1. clear names
+2. focused routines
+3. explicit data meaning
+4. simple control flow
+5. defensive checks at boundaries
+6. cohesive classes/modules
+7. consistent style
+
+Avoid by default:
+- dense clever code
+- broad god objects
+- fragile hidden assumptions
+- unnecessary complexity in loops and conditionals
+- comments where better names or decomposition would do
+
+---
+
+## Testing Rules
+
+1. Test routine behavior around normal, boundary, and invalid inputs.
+2. Test defensive checks where boundary validation matters.
+3. Keep tests aligned with routine contracts.
+4. Test complex data-driven logic with representative tables and edge cases.
+
+---
+
+## Review Checklist
+
+Before finalizing any change, verify:
+- Are names clear and intention-revealing?
+- Are routines focused and reasonably small?
+- Is control flow straightforward?
+- Are trust boundaries defended?
+- Are contracts and invariants explicit enough?
+- Did we reduce or at least not increase complexity?
+- Are classes/modules cohesive?
+- Did we avoid cleverness that harms inspection?
+- Are comments used only where they add value?
+- Is the style consistent with the rest of the codebase?
+
+If any answer is no, revise before shipping.
+
+---
+
+## Final Instruction
+
+When uncertain, choose the option that:
+1. lowers defect risk
+2. improves readability
+3. simplifies control flow
+4. strengthens defensive correctness
+5. keeps the code easier to inspect and maintain
+
+Write code that would stand up to careful review.

package/templates/skills/code-complete/code-complete.mini.md

@@ -0,0 +1,56 @@
+# OBEY Code Complete by Steve McConnell
+
+## When to use
+
+Use when implementing, changing, reviewing, debugging, refactoring, or tuning production code where construction discipline must reduce defects and keep code easy to inspect.
+
+## Primary bias to correct
+
+Construction quality is not accidental. Do not treat typing code, making it work once, or using a clever idiom as complete construction; choose the option that lowers defect risk and makes the code easier to reason about.
+
+## Decision rules
+
+- Before large construction work, verify that requirements, architecture, major risks, coding conventions, language constraints, error policy, data representation, reuse, integration, and testing approach are clear enough.
+- When upstream uncertainty remains, build a small validated slice instead of speculative code, and make expensive-to-reverse decisions deliberately.
+- Optimize first for human readers: clarity, locality, explicitness, visible control flow, consistent conventions, and practical correctness over cleverness, minimal keystrokes, or fashion.
+- For complex routines, sketch precise pseudocode or intent comments at a consistent abstraction level, then convert them into code and keep only comments that still explain intent, constraints, contracts, or rationale.
+- Keep routines cohesive, precisely named, small at the interface, and hard to misuse. Separate setup, validation, computation, and side effects when they are conceptually different.
+- Make variable and data meaning explicit through purpose-revealing names, small scope, deliberate initialization, named constants, stronger types, and visible units or sentinel meanings.
+- Choose data types that make invalid or ambiguous values harder to represent; use booleans only for true binary meanings, enumerations for closed sets, and records/maps/tables only when their shape communicates meaning.
+- Keep control flow simple enough to verify: shallow nesting, named predicates for complex conditions, clear normal path, clear loop initialization/termination/update, and no side-effect-dependent expressions or clever one-liners.
+- Use table-driven or data-driven logic for stable explicit mappings only when the table is clearer, obvious, synchronized with the rules, and validated; do not hide complex behavior in inscrutable encodings.
+- Validate input at trust boundaries. Use assertions, invariant checks, and simple contracts for programmer assumptions; use validation or domain errors for expected external or business failures.
+- Handle errors at the right abstraction, preserve diagnostic context, standardize similar failures, keep the normal path readable, and never silently continue from corrupted or impossible state.
+- Keep classes and modules focused, cohesive, and bounded by clear contracts; hide representation and internal bookkeeping, and avoid mixed persistence, formatting, business, and integration concerns.
+- Treat rising complexity as defect risk: split tangled routines or modules, remove duplication that multiplies maintenance effort, and reduce what a maintainer must keep in working memory.
+- Build in small, verifiable increments; integrate often enough to expose conflicts, keep partial work from rotting, and review and improve code during construction.
+- Match reviews, inspections, pair work, tests, static checks, and regression tests to defect risk. Debug by reproducing, isolating, explaining, fixing, and verifying root causes rather than guessing.
+- Refactor when structure hides intent, duplicates knowledge, or raises defect probability, and keep refactoring separate from behavior change when that improves reviewability.
+- Tune performance only when requirements and evidence justify it; measure before and after, and keep clarity unless an explicit measured tradeoff warrants the cost.
+- Use tools, scripts, debuggers, profilers, editors, and build automation to reduce error-prone manual work, not to replace understanding.
+- Use layout, comments, documentation, and coding standards to lower reader effort. Prefer self-documenting structure first; comments should explain intent, assumptions, constraints, limitations, usage, or non-obvious facts.
+
+## Trigger rules
+
+- When coding starts from a proposed solution, restate the requirement, architecture fit, risks, conventions, and success constraints before implementation.
+- When a routine is hard to name, mixes phases, has flag arguments, long parameters, or hidden side effects, redesign the interface or split the routine.
+- When readers must decode units, ranges, precision, encoding, ownership, status, magic values, or primitive flags, move that meaning into names, constants, types, or structures.
+- When input crosses a user, file, network, external-system, or other trust boundary, decide what is validated, rejected, recovered from, asserted, and kept diagnosable.
+- When branches, loops, recursion, exits, or exception paths become hard to verify, simplify before adding logic.
+- When repeated branching maps stable categories, ranges, conversions, validation, dispatch, or configuration-like rules, consider a validated table.
+- When a class or module exposes representation, grows into a god object, or mixes unrelated responsibilities, restore the abstraction boundary.
+- When tests cover only the happy path, add normal, boundary, invalid-input, defensive-check, routine-contract, and data-driven edge cases.
+- When debugging begins from a guess, first make the failure repeatable, collect evidence, isolate the path, and explain the cause.
+- When refactoring poorly understood or risky code, add tests or analysis first and keep behavior changes separate.
+- When performance work begins, set a target, measure the current behavior, change one thing, remeasure, and document any clarity tradeoff.
+- When comments restate obvious mechanics or go stale, rewrite the code or delete the comment; when code cannot express intent, constraints, or usage, add a close accurate comment.
+- When local style starts to diverge, follow shared formatting, naming, file-structure, and idiom conventions instead of creating a module-specific dialect.
+
+## Final checklist
+
+- Requirements, architecture fit, risks, conventions, and construction approach are clear enough.
+- Names, routines, data, classes, layout, comments, and standards reduce reader effort.
+- Inputs, errors, assertions, contracts, invariants, impossible states, and trust boundaries are deliberate.
+- Control flow, loops, tables, recursion, exits, and exception paths are simple enough to inspect.
+- Tests, reviews, debugging, refactoring, integration, tooling, and tuning are evidence-based.
+- The change is small enough to verify and would stand up to careful review.

package/templates/skills/code-complete/code-complete.nano.md

@@ -0,0 +1,41 @@
+# OBEY Code Complete by Steve McConnell
+
+## When to use
+
+Use as a compact always-on construction discipline for implementation, review, debugging, refactoring, and tuning.
+
+## Primary bias to correct
+
+Working code is not enough. Construction must lower defect risk, control complexity, and make human inspection cheap.
+
+## Decision rules
+
+- Clarify requirements, architecture fit, risks, conventions, and major construction decisions before coding from a solution idea.
+- Choose clarity, locality, explicitness, simple control flow, and consistent style over clever compactness or fashionable idioms.
+- Keep routines, classes, and modules cohesive, precisely named, small at the interface, encapsulated, and hard to misuse.
+- Make data meaning visible with names, constants, stronger types, closed states, deliberate initialization, units, and ownership.
+- Validate trust boundaries; use assertions, invariants, and contracts for programmer assumptions; keep error handling explicit and diagnosable.
+- Keep branches, loops, exits, exceptions, and table-driven logic simple enough to verify.
+- Build, test, review, debug, refactor, integrate, and tune in small evidence-based loops: root cause before fixes, behavior protection before refactoring, measurement before optimization.
+- Use comments, documentation, tools, and standards to reduce reader or manual effort, never to hide poor structure.
+
+## Trigger rules
+
+- When a solution appears before the problem is clear, restate the requirement, constraints, and construction risks.
+- When readers must decode names, flags, primitives, units, states, or layout, model the meaning explicitly.
+- When a routine mixes phases or has a hard-to-use interface, split concerns or change the data model.
+- When input crosses a trust boundary, decide validation, rejection, recovery, assertion, and diagnostics.
+- When control flow, loops, exceptions, or branching tables are hard to inspect, simplify before adding logic.
+- When tests only prove happy paths, add boundary, invalid-input, defensive-check, contract, and data-driven cases.
+- When debugging, refactoring, or performance work starts from a guess, get evidence first.
+- When comments repeat obvious mechanics, rewrite the code or delete the comment; keep comments for intent and constraints.
+
+## Final checklist
+
+- Clear construction context?
+- Inspectable code shape?
+- Explicit data meaning?
+- Defended boundaries and diagnosable failures?
+- Simple flow?
+- Defect-finding tests and reviews?
+- Evidence before fixes, refactors, and tuning?

package/templates/skills/council/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: council
+description: >
+  Stress-test consequential architecture decisions, dependencies, schemas,
+  security boundaries, or difficult debugging with distinct perspectives.
+  Use for Council requests and design trade-offs before specification approval.
+license: MIT
+---
+
+# Council
+
+Inspired by hex/claude-council: https://github.com/hex/claude-council
+Read project `AGENTS.md` for shared workflow policy.
+The Council proposes decisions; Len's approval determines the authoritative architecture.
+
+## Ground the decision
+
+State observed facts separately from assumptions and untested targets.
+Inspect relevant code, constraints, and existing specifications before proposing a replacement.
+
+## Challenge it from four perspectives
+
+- Devil's advocate: identify failure modes, missing requirements, and assumptions that could invalidate the design.
+- Simplicity: look for existing or native solutions and unnecessary scope.
+- Security and reliability: inspect trust boundaries, data loss, input validation, and partial failure.
+- Architecture: evaluate clarity, robustness, and long-term maintainability.
+
+Use a concise synthesis by default.
+For an explicit debate, present initial positions, rebuttals, and synthesis.
+Use independent subagents only when delegation is explicitly requested and available.
+
+## Decision record
+
+Report observed facts, unverified assumptions, key critiques, agreement, unresolved trade-offs, the proposed decision, and conditions that would justify revisiting it.
+Feed the decision into the product architecture or feature spec through the spec workflow.
+Obtain Len's approval before using a proposed architecture for implementation planning or execution.
+The Council does not implement production code or silently amend approved architecture.

package/templates/skills/designing-data-intensive-applications/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: designing-data-intensive-applications
+description: Apply Martin Kleppmann-inspired data-system rules when designing reliability, scalability, consistency, replication, transactions, streams, or schema evolution.
+license: MIT
+---
+
+# Designing Data-Intensive Applications Skill
+
+Use this skill when a task involves data ownership, consistency semantics, event flows, replication, partitioning, transactions, streams, batch processing, fault tolerance, or schema evolution.
+
+Before making design or code decisions, read and apply [designing-data-intensive-applications.mini.md](designing-data-intensive-applications.mini.md). Use [designing-data-intensive-applications.md](designing-data-intensive-applications.md) only as a deeper reference when the mini rules are not enough for the current data-system tradeoff.