@iceinvein/agent-skills 0.1.7 → 0.1.9

package/README.md

@@ -25,18 +25,30 @@ bunx @iceinvein/agent-skills install design-review
 
 # Install for a specific tool
 bunx @iceinvein/agent-skills install design-review --tool claude
+
+# Install globally (available in all projects)
+bunx @iceinvein/agent-skills install design-review -g
 ```
 
+If no tools are detected in your directory, the CLI will prompt you to choose which tools you use.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `install <skill> [--tool <tool>]` | Install a skill |
-| `remove <skill>` | Remove a skill |
-| `update <skill>` | Update to latest version |
+| `install <skill> [--tool <tool>] [-g]` | Install a skill |
+| `remove <skill> [-g]` | Remove a skill |
+| `update <skill> [-g]` | Update to latest version |
 | `list` | List all available skills |
 | `info <skill>` | Show skill details |
 
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--tool <tool>` | Install for a specific tool (claude, cursor, codex, gemini) |
+| `-g, --global` | Install to home directory instead of current project |
+
 ## Available Skills
 
 ### design-review
@@ -66,6 +78,10 @@ Skills live in this repo under `skills/`. The CLI fetches them from GitHub and i
 - **Codex**: Appended to `AGENTS.md`
 - **Gemini CLI**: `.gemini/skills/` + `.gemini/settings.json`
 
+### Local vs Global
+
+By default, skills install to the **current project directory** (e.g., `./claude/skills/`). Use `-g` to install to your **home directory** (e.g., `~/.claude/skills/`) so the skill is available in every project.
+
 A `.agent-skills.lock` file tracks installations for update and remove.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/complexity-accountant/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: complexity-accountant
+description: Use when the agent creates a new abstraction, splits code into multiple files, introduces a library or framework, or when code feels over-engineered. Trigger on "this is too complicated", "should I extract this?", "do we need this layer?", or when reviewing structural changes. NOT for initial scaffolding or established team patterns.
+---
+
+# Complexity Accountant
+
+A structured complexity analysis framework based on John Ousterhout's *A Philosophy of Software Design*. Treats complexity as a finite budget — every abstraction, layer, and indirection must justify the complexity it adds by reducing complexity elsewhere. Modules should be deep (simple interface, rich functionality), not shallow (interface as complex as the implementation).
+
+**Core principle:** Complexity is the root cause of most software difficulty. It manifests as change amplification, cognitive load, and unknown unknowns. The goal is not zero complexity — it's justified complexity where every cost buys a specific benefit.
+
+## When to Use
+
+- Creating a new abstraction (class, module, helper function, wrapper)
+- Splitting code into multiple files or layers
+- Introducing a library or framework to replace inline code
+- "This is too complicated" / "Should I extract this?" / "Do we need this layer?"
+- Reviewing structural changes or refactoring proposals
+
+**Not for:** Initial project scaffolding with established frameworks, patterns the team has already committed to, trivial organizational changes (renaming, moving a constant).
+
+## The Process
+
+### 1. Measure Complexity Added
+
+For every structural change, evaluate impact across Ousterhout's three dimensions:
+
+**Change amplification** — How many places must change for a single logical change?
+- Count: if you add a field to a data type, how many files need updating?
+- If the answer is > 2, the structure is amplifying changes. Name the specific coupling that causes this.
+
+**Cognitive load** — How much must a developer hold in their head to work here?
+- Count: modules involved, implicit ordering, non-obvious conventions, state to track
+- A function that requires reading 3 other files to understand has high cognitive load
+- Beware: more lines of code ≠ more cognitive load. A single clear 50-line function often has less cognitive load than five 10-line functions spread across files.
+
+**Unknown unknowns** — Things a developer needs to know that aren't apparent from reading the code.
+- Hidden dependencies ("this only works if X runs first")
+- Implicit initialization order
+- Convention-based behavior ("files named *.handler.ts are auto-registered")
+- Side effects that aren't visible in the function signature
+
+### 2. Depth Test
+
+For every new module, function, or class, evaluate its depth:
+
+**Deep module** = Simple interface, lots of functionality behind it. The caller's life is genuinely easier because the module absorbs complexity.
+- Good example: `fs.readFile(path)` — one call hides file descriptors, buffering, encoding, OS syscalls
+- Good example: `db.query(sql, params)` — one call hides connection pooling, parameterization, result mapping
+
+**Shallow module** = Interface nearly as complex as its implementation. The abstraction doesn't earn its keep.
+- Bad example: `UserValidator` class that wraps three `if` statements
+- Bad example: `ConfigManager` that just reads `process.env` with a method per variable
+- Bad example: `ApiClient` where every method is a one-liner calling `fetch` with different URLs
+
+**The inlining test:** Would removing this abstraction and inlining the code make things simpler or more complex? If simpler — the abstraction is shallow. Kill it.
+
+### 3. Justify or Kill
+
+If a new abstraction doesn't meaningfully reduce at least one complexity dimension, remove it.
+
+**Justifications that DO count:**
+- "This absorbs the complexity of [specific thing] so callers don't need to know about it"
+- "Without this boundary, changing [X] would require modifying [N] files instead of 1"
+- "This eliminates an unknown-unknown: callers no longer need to know about [hidden constraint]"
+
+**Justifications that do NOT count:**
+- "Might be useful later" — YAGNI. Add it when it's needed, not when it's imagined.
+- "Separation of concerns" — without naming the specific concerns being separated and why they need separation.
+- "It's the standard pattern" — patterns serve purposes. Name the purpose in this codebase. If the purpose doesn't apply, the pattern doesn't apply.
+- "Makes it more testable" — only valid if you're actually writing those tests right now. Hypothetical testability is not a benefit.
+- "Clean architecture says so" — architecture serves the system, not the reverse.
+
+### 4. Complexity Budget Report
+
+Produce a brief annotation with every non-trivial structural change:
+
+```
+COMPLEXITY: [what changed]
+  Added: [specific complexity cost]
+  Bought: [specific benefit — what's easier now?]
+  Net:    [worth it / not worth it / marginal — with reasoning]
+```
+
+Example:
+
+```
+COMPLEXITY: Extract PricingEngine from OrderProcessor
+  Added: new module boundary (+1 file to understand), interface between them (PricingInput/PricingResult types)
+  Bought: pricing rules can change without touching order flow, pricing is independently testable with known inputs
+  Net:    worth it — pricing is a likely change axis and the boundary matches a real domain separation
+```
+
+Counter-example:
+
+```
+COMPLEXITY: Extract validateEmail into utils/validation.ts
+  Added: new file, new import, function is now in a different directory from its only caller
+  Bought: nothing — this function has one caller and the validation logic is 4 lines
+  Net:    not worth it — inline it. If a second caller appears, extract then.
+```
+
+## Interaction Model
+
+Decision engine. The agent runs this analysis on its own work before presenting code to the human. The complexity report appears alongside the diff — the human sees what complexity was added, what it bought, and whether it's justified. The human can challenge the assessment or override the verdict.
+
+## Red Flags
+
+| Signal | Diagnosis |
+|--------|-----------|
+| A wrapper that adds no logic, just delegates | Shallow module — remove the middleman |
+| A file with one exported function under 10 lines | Doesn't need its own file — put it near its caller |
+| An interface/type with only one implementation | Premature abstraction — inline it, extract when a second implementation appears |
+| A "utils" or "helpers" directory | Complexity junk drawer — each utility should live near its caller |
+| A class where most methods delegate to another class | Pass-through layer adding indirection without value |
+| Configuration object with 15+ fields | Interface is as complex as the problem — the abstraction isn't simplifying anything |
+| "Manager", "Handler", "Processor" suffix with vague responsibility | Name doesn't describe a clear, bounded responsibility |
+| Three files created for one feature (type, implementation, barrel export) | Ceremony without benefit — does the feature need all three? |
+
+## Guard Rails
+
+**Don't punish good abstractions.** Deep modules that genuinely simplify their callers' lives are worth their cost. The goal isn't minimal code — it's minimal accidental complexity.
+
+**Respect existing architecture.** If the team uses a repository pattern and it's working, don't argue against it in the middle of a feature. The complexity accountant evaluates *new* additions, not relitigates committed decisions.
+
+**Acknowledge uncertainty.** Sometimes it's genuinely unclear whether an abstraction earns its keep. Say so: "This is marginal — it could go either way. Here's what I'd watch for to decide later."
+
+**Scale the analysis.** A 3-line helper doesn't need a complexity report. A new service layer does. Match the rigor to the stakes.
+
+## The Ousterhout Heuristics (Reference)
+
+1. **Classes should be deep, not shallow.** A deep class has a simple interface relative to the functionality it provides.
+2. **Define errors out of existence.** Handle common error cases as part of the normal code path rather than throwing exceptions. An API that can't fail is simpler than one that handles 5 error types.
+3. **Pull complexity downward.** It's better for a module to be internally complex with a simple interface than to push complexity onto its callers.
+4. **General-purpose modules are deeper.** Making a module slightly more general often makes it significantly deeper — the same interface handles more cases.
+5. **Different layer, different abstraction.** If two adjacent layers use the same abstraction, one layer is probably not adding value. Each layer should transform or enrich the abstraction.
+6. **Complexity is incremental.** No single change makes a system complex — it's the accumulation of many "small" additions that each seemed harmless. This is why you account for every one.

package/skills/complexity-accountant/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "complexity-accountant",
+  "version": "1.0.0",
+  "description": "Ousterhout-inspired complexity analysis — deep vs shallow modules, complexity budget, justified abstractions",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/complexity-accountant/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/complexity-accountant.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/complexity-accountant.md"
+    }
+  }
+}

package/skills/contract-enforcer/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: contract-enforcer
+description: Use when writing or modifying functions with non-trivial logic — especially functions that handle external input, state transitions, or cross-module boundaries. Trigger on "is this correct?", "what are the edge cases?", "what does this function guarantee?", or when reviewing boundary behavior. NOT for trivial getters, simple mappings, or configuration code.
+---
+
+# Contract Enforcer
+
+A structured correctness framework based on Bertrand Meyer's *Design by Contract*. Before writing or modifying non-trivial functions, the agent articulates preconditions, postconditions, invariants, and failure contracts — then verifies the implementation satisfies them.
+
+**Core principle:** Every function participates in a contract. The caller promises preconditions, the function promises postconditions, and both rely on invariants. Code without an explicit contract has an implicit one — and implicit contracts breed bugs.
+
+## When to Use
+
+- Writing or modifying a function with non-trivial logic
+- Functions that handle external input, state transitions, or cross-module boundaries
+- "Is this function correct?" / "What are the edge cases?"
+- "What does this function guarantee?"
+- Reviewing boundary behavior or error handling
+
+**Not for:** Trivial getters, simple property access, configuration code, pure mappings with obvious behavior.
+
+## The Process
+
+Before presenting code for any non-trivial function, articulate the contract. This is not optional overhead — it's how you discover bugs before writing them.
+
+### 1. Preconditions
+
+What must be true about inputs for this function to behave correctly?
+
+Go beyond types. Types catch shape errors; preconditions catch semantic errors:
+- "Array must be sorted" (not just "array of numbers")
+- "userId must correspond to an existing user in the database" (not just "string")
+- "Amount must be positive and in a supported currency" (not just "number")
+
+For each precondition, answer: **If this is violated, does the function fail loudly or silently corrupt state?** Silent corruption is the worst outcome — it means the contract exists but isn't enforced.
+
+### 2. Postconditions
+
+What does this function guarantee about its output?
+
+- What relationship holds between input and output?
+- What state changes are guaranteed to have happened?
+- What side effects are promised? What side effects are promised NOT to occur?
+- Is the guarantee conditional (e.g., "returns sorted array IF input was non-empty")?
+
+A postcondition should be specific enough to write a test from. "Returns the correct result" is not a postcondition — it's a wish.
+
+### 3. Invariants
+
+What must remain true throughout execution?
+
+- **Class/module invariants** this function must preserve (e.g., "the balance is never negative")
+- **Data structure invariants** (e.g., "the heap property is maintained")
+- **Resource invariants** (e.g., "the database connection is returned to the pool, even on error")
+- **Concurrency invariants** (e.g., "the lock is held during the critical section")
+
+If the function temporarily violates an invariant (e.g., rebalancing a tree), note where it's restored.
+
+### 4. Failure Contract
+
+When preconditions are violated, what happens? The answer must be explicit:
+
+- **Throw** a specific, named error type — not a generic `Error("something went wrong")`
+- **Return** an error union or result type — with the error case documented
+- **Never** return a magic value (null, -1, empty string) without documenting what it means
+
+"Undefined behavior" is not a contract. If you can't state what happens on bad input, you don't understand the function yet.
+
+### 5. Verify Implementation
+
+After articulating the contract, evaluate the actual code:
+- Are preconditions **enforced** at the function boundary, or merely **assumed**?
+- Does the implementation actually satisfy the postconditions for all valid inputs?
+- Are invariants maintained across all code paths, including error paths?
+- Does the failure behavior match the failure contract?
+
+If the implementation doesn't match the contract, either fix the implementation or revise the contract — but never leave them misaligned.
+
+## Output Format
+
+Present contracts as a structured block alongside the code:
+
+```
+CONTRACT: functionName(param1, param2)
+  Requires: [preconditions — semantic, not just types]
+  Ensures:  [postconditions — what the caller can rely on]
+  Invariant: [what is preserved across the call]
+  On violation: [specific failure behavior]
+```
+
+Example:
+
+```
+CONTRACT: calculateShippingCost(order, destination)
+  Requires: order.items.length > 0, all items have weight > 0, destination is valid ISO 3166-1 alpha-2
+  Ensures:  returns { cost: number > 0, currency: order.currency }, does not modify order
+  Invariant: shipping rules table is not mutated
+  On violation: throws InvalidOrderError (bad order) or UnsupportedDestinationError (bad destination)
+```
+
+## Interaction Model
+
+Produce contracts independently for anything derivable from code. But **ask the human** for semantic preconditions you can't determine alone:
+
+- "Should this accept negative quantities, or is that a precondition violation?"
+- "When the user isn't found, should this throw or return null? That's a contract decision — it affects every caller."
+- "Is an empty array a valid input here, or should it be rejected?"
+
+These are design decisions, not implementation details. The human owns them.
+
+## Anti-Patterns
+
+| Pattern | Problem |
+|---------|---------|
+| `if (!x) return null` without documentation | Silent failure — caller doesn't know null means "contract violated" vs "legitimate absence" |
+| Defensive checks buried deep inside the function | Preconditions should be checked at the boundary, not scattered through logic |
+| Return type is `any` or overly broad union | Postcondition is too vague to be useful — what does the caller actually get? |
+| Function modifies its inputs without declaring it | Hidden side effect — violates caller's assumption of immutability |
+| "Works for all inputs" | Almost certainly false — name the actual domain |
+| Catching all exceptions and returning a default | Converts loud failure into silent corruption — the worst trade |
+| Error messages that don't identify which precondition failed | "Invalid input" tells the caller nothing — name the violated condition |
+
+## Guard Rails
+
+**Scale to the function.** A 3-line pure function doesn't need a formal contract block. Use judgment — the overhead should be proportional to the function's complexity and the consequences of getting it wrong.
+
+**Contracts are for humans, not compilers.** Write contracts that a developer reading the code can understand and verify. Don't write contracts in formal logic unless the team reads formal logic.
+
+**Don't gold-plate.** If the function has one obvious precondition and one obvious postcondition, state them briefly. The format is a tool, not a ritual.
+
+**Contracts evolve.** When requirements change, update the contract first, then the implementation. A stale contract is worse than no contract — it's actively misleading.
+
+## The Meyer Principles (Reference)
+
+1. **Separate commands from queries.** Functions that return values should not have side effects. Functions with side effects should not return values. When you must violate this, document it in the contract.
+2. **Demand no more, promise no less.** Preconditions should be as weak as possible (accept the widest reasonable input). Postconditions should be as strong as possible (guarantee the most specific output).
+3. **The client is responsible for preconditions.** The function does not need to "handle" invalid input gracefully — it needs to fail clearly and immediately when preconditions are violated.
+4. **Inheritance respects contracts.** Subtypes may weaken preconditions (accept more) and strengthen postconditions (guarantee more), but never the reverse.
+5. **Contracts are documentation that compiles.** The best contracts are checked at runtime (assertions, type narrowing, validation) — not just written in comments.

package/skills/contract-enforcer/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "contract-enforcer",
+  "version": "1.0.0",
+  "description": "Meyer-inspired Design by Contract — preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/contract-enforcer/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/contract-enforcer.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/contract-enforcer.md"
+    }
+  }
+}

package/skills/index.json

@@ -16,5 +16,35 @@
     "description": "Semantic code search, call hierarchy, dependency graphs, and impact analysis via MCP",
     "type": "code",
     "version": "1.0.0"
+  },
+  {
+    "name": "contract-enforcer",
+    "description": "Meyer-inspired Design by Contract — preconditions, postconditions, invariants, and failure contracts for non-trivial functions",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "complexity-accountant",
+    "description": "Ousterhout-inspired complexity analysis — deep vs shallow modules, complexity budget, justified abstractions",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "module-secret-auditor",
+    "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "seam-finder",
+    "description": "Feathers-inspired legacy code modification — find seams, make minimal incisions, preserve existing behavior",
+    "type": "prompt",
+    "version": "1.0.0"
+  },
+  {
+    "name": "simplicity-razor",
+    "description": "Hickey-inspired simplicity analysis — simple vs easy, complecting detection, strand decomposition",
+    "type": "prompt",
+    "version": "1.0.0"
   }
 ]

package/skills/module-secret-auditor/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: module-secret-auditor
+description: Use when creating new files, directories, or modules, when reviewing project structure, when a change ripples across 3+ directories, or when the user asks "where should this code live?" or "how should I structure this?". Trigger on structural decisions and reorganizations.
+---
+
+# Module Secret Auditor
+
+A structural analysis framework based on David Parnas' information hiding principle. Every module should hide exactly one design decision that is likely to change. Module boundaries exist to isolate the impact of change — not to group related nouns or match technical layers.
+
+**Core principle:** The question isn't "what is this module?" but "what secret does this module hide?" If you can't name the secret, the boundary is wrong.
+
+## When to Use
+
+- Creating new files, directories, or modules
+- Reviewing or questioning existing project structure
+- A change to one feature requires modifying files in 3+ directories
+- "Where should this code live?" / "How should I structure this?"
+- Proposing a refactoring that reorganizes code
+- Post-mortem on a change that rippled further than expected
+
+**Not for:** Naming conventions, code style, adding code to existing well-bounded modules, or trivial file organization (moving a constant).
+
+## The Process
+
+### 1. Identify the Secrets
+
+For each module (file, directory, package), answer: **"What design decision does this module hide from the rest of the system?"**
+
+**Good secrets** (specific, likely to change):
+- "How authentication tokens are validated and refreshed"
+- "The algorithm for calculating shipping costs"
+- "How we communicate with the payment provider's API"
+- "The format and schema of the analytics event payload"
+
+**Bad secrets** (vague, organized by noun or layer):
+- "All the models" — grouped by technical role, not by change-reason
+- "Utility functions" — no shared secret, just a junk drawer
+- "Things related to users" — too broad. Which *decision* about users?
+- "The controller layer" — a technical layer isn't a secret
+
+If you can't name the secret in one specific sentence, the module is hiding nothing — or hiding too many things.
+
+### 2. One Change, One Module Test
+
+For each likely change the system will face, trace the blast radius:
+
+1. Name the change: "We switch from Stripe to a different payment provider"
+2. List every module that must be modified
+3. If > 1 module must change for a single business decision, the secret is leaked
+
+Run this test for 3-5 realistic changes. The changes that matter most are the ones the human identifies as likely — ask them:
+
+> "What are the things most likely to change in this system over the next 6 months?"
+
+This is domain knowledge the code doesn't reveal. Without it, you're guessing at change-likelihood based on patterns.
+
+### 3. Leak Detection
+
+Scan for information hiding violations — places where a module's internal decisions are visible to the outside:
+
+- **Exported internals:** A module exports data structures that encode its implementation choices (e.g., a database module exports raw row types instead of domain types)
+- **Caller knowledge:** A caller must understand the internal state machine or initialization order of another module to use it correctly
+- **Configuration leaks:** File formats, protocol details, or algorithm parameters visible across module boundaries
+- **Connector types:** Types that exist solely to shuttle data between modules that should be independent — these are often symptoms of a missing or misdrawn boundary
+
+### 4. Recommend by Secret
+
+When proposing structure, organize around change-reasons, not around nouns or technical layers.
+
+Instead of:
+```
+models/user.ts
+services/userService.ts
+controllers/userController.ts
+repositories/userRepository.ts
+```
+
+Propose:
+```
+auth/               — secret: how identity is verified and sessions are managed
+pricing/            — secret: how costs are calculated and discounts applied
+notifications/      — secret: how and when users are notified, via which channels
+```
+
+Each directory answers: **"If this decision changes, only this directory is affected."**
+
+This doesn't mean you can't have shared infrastructure (database client, HTTP framework, logging). Infrastructure modules hide *infrastructure secrets* — "how we talk to Postgres" or "how we structure HTTP responses." The test still applies: when the infrastructure decision changes, only the infrastructure module changes.
+
+## Interaction Model
+
+The agent analyzes code structure independently but must ask the human one critical question:
+
+> "What are the things most likely to change in this system over the next 6 months?"
+
+This determines what the secrets should be. The agent can assess *structural* quality on its own (leak detection, coupling analysis), but *change-likelihood* is a domain judgment.
+
+If the human isn't sure, offer concrete prompts:
+- "Will you likely switch any external services (payment, email, auth provider)?"
+- "Are there business rules that are still being figured out?"
+- "Is there a part of the system that gets changed every sprint?"
+
+## Output Format
+
+```
+MODULE AUDIT: [module or directory name]
+  Secret:     [the design decision this module hides — one sentence]
+  Leak check: [leaked? where does the secret escape?]
+  Change test: [for the most likely change — how many modules would be affected?]
+  Verdict:    [well-bounded / leaking / misdrawn / no clear secret]
+```
+
+## The Parnas Litmus Tests (Reference)
+
+| Question | Good answer | Bad answer |
+|----------|-------------|------------|
+| What secret does this module hide? | A specific design decision | "User-related things" |
+| If the secret changes, what else breaks? | Nothing outside this module | Multiple other modules |
+| Can you describe the module's interface without revealing the secret? | Yes — the interface is abstract | No — callers need to know internals |
+| Why are these two things in the same module? | They share a secret | They share a noun |
+| Why are these two things in different modules? | They hide different secrets | They're in different technical layers |
+
+## Guard Rails
+
+**Don't reorganize for its own sake.** If the current structure works and changes don't ripple, the boundaries are fine — even if they don't match textbook information hiding. Parnas' principle is a tool for evaluating structure, not a mandate to restructure everything.
+
+**Respect team conventions.** If the team uses MVC and it's working, don't unilaterally propose feature-based organization. Present the analysis and let the team decide.
+
+**Infrastructure is a valid secret.** "How we talk to the database" is a real secret that deserves its own module. Not everything needs to be a business domain boundary.
+
+**Small projects get simple boundaries.** A 10-file project doesn't need 10 modules with formal interfaces. The secret principle scales — apply it at whatever granularity fits the codebase.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Organizing by technical layer (models/, services/, controllers/) | Organize by change-reason. Ask: "what secret does each layer hide?" |
+| Creating a module per entity (UserModule, OrderModule, ProductModule) | Entities aren't secrets. Ask: "which *decisions* about users change independently?" |
+| "Utils" or "shared" directories | Each utility should live near its caller. If two callers need it, that's a signal of a shared secret — name it. |
+| Assuming current structure is wrong | Always evaluate before prescribing. Working code with imperfect boundaries beats reorganized code that breaks. |
+| Ignoring the human's change-likelihood input | Domain knowledge trumps structural analysis. If the human says "pricing never changes," don't optimize for pricing changes. |

package/skills/module-secret-auditor/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "module-secret-auditor",
+  "version": "1.0.0",
+  "description": "Parnas-inspired information hiding analysis — module boundaries drawn by change-reason, not by noun or technical layer",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/module-secret-auditor/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/module-secret-auditor.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/module-secret-auditor.md"
+    }
+  }
+}

package/skills/seam-finder/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: seam-finder
+description: Use when modifying existing code the agent didn't write, when the agent's instinct is to rewrite or heavily refactor, when adding tests to untested code, or when working in a codebase with minimal coverage. Trigger on "change this behavior", "add a feature to this", or any modification of legacy or unfamiliar code. NOT for greenfield code or code the agent just wrote in this session.
+---
+
+# Seam Finder
+
+A structured approach to modifying existing code based on Michael Feathers' *Working Effectively with Legacy Code*. Before changing existing code, find the seams — places where behavior can be altered without editing the code at that point. Seams enable safe modification: you can sense what code does, separate dependencies, and change behavior through the narrowest possible incision.
+
+**Core principle:** Existing code is not an obstacle to be rewritten. It's a system with embedded knowledge — implicit behavior, battle-tested edge case handling, and hard-won correctness. The default is *preserve*, not *replace*. Find the seam, make the minimal incision.
+
+## When to Use
+
+- Modifying existing code you didn't write (or wrote long ago)
+- "Change this behavior" / "Add a feature to this existing code"
+- When your first instinct is to rewrite or heavily refactor
+- Adding tests to untested code
+- Working in a codebase with minimal test coverage
+- When a modification feels risky and you want a safe approach
+
+**Not for:** Greenfield code, code you just wrote in this session, throwaway prototypes, or code the team has explicitly decided to rewrite.
+
+## The Process
+
+### 1. Identify the Seam Types
+
+Before modifying existing code, survey the available seams:
+
+**Object seam** — Can behavior be changed by passing a different object or dependency?
+- Look for: constructor parameters, function arguments that accept interfaces, injected services, callback parameters, strategy patterns already in place
+- This is the most common seam in object-oriented code. If a dependency is passed in, you can substitute it.
+
+**Preprocessing seam** — Can the inputs be transformed before they reach this code?
+- Look for: middleware chains, interceptors, data transformation layers, event handlers, input normalization steps
+- The code doesn't change — its inputs do. This is safe because the original code path is untouched.
+
+**Link seam** — Can a different implementation be substituted at the module or import level?
+- Look for: imports that could be aliased, environment-based module resolution, plugin architectures, dependency injection containers, test mocks at the module level
+- In dynamic languages, this is powerful. In static languages, it requires more planning.
+
+If no seams exist, you may need to create one — but creating a seam is a smaller change than rewriting the code. Introduce one parameter, extract one function, add one interface.
+
+### 2. Classify the Goal
+
+What are you trying to do? The answer determines which seam to use.
+
+**Sensing** — You need to observe what the code does.
+- Goal: understand behavior, add tests, verify assumptions before changing anything
+- Strategy: find a seam that lets you intercept outputs or side effects
+- Example: pass a test double that records calls instead of making real network requests
+
+**Separation** — You need to break a dependency so one side can change independently.
+- Goal: modify one part without affecting another
+- Strategy: find a seam that decouples the parts
+- Example: extract a function parameter so the algorithm can be tested without its data source
+
+### 3. Minimal Incision
+
+Identify the **smallest change** that achieves the goal:
+
+- NOT "refactor the function" — "extract this 4-line block behind a function parameter so we can vary its behavior"
+- NOT "rewrite with better patterns" — "add one parameter that lets us substitute this dependency in tests"
+- NOT "clean up while we're here" — "change only what we were asked to change"
+
+**The one-sentence test:** Can you describe the change in one sentence? If it takes a paragraph, the incision is too large. Break it down.
+
+### 4. Preserve the Unknown
+
+Existing code has behavior you don't fully understand. Treat it with respect:
+
+- **Assume load-bearing until proven otherwise.** That weird null check? Probably caught a production bug. That redundant-looking condition? Probably handles a case you haven't seen.
+- **Side effects are features.** Logging, metrics, cache warming, audit trails — if you don't understand why a side effect exists, don't remove it.
+- **Timing and ordering matter.** Reordering operations can break subtle invariants. If the original code does A before B, keep that order unless you can prove it doesn't matter.
+- **Error swallowing may be intentional.** A catch-all that silently ignores errors looks wrong, but it might be preventing a cascade failure that took days to debug.
+
+When in doubt: preserve, annotate with a question, and ask the human.
+
+### 5. Present the Surgical Plan
+
+Before making any changes, present the plan:
+
+```
+SEAM ANALYSIS: [what needs to change]
+  Seam type:  [object / preprocessing / link / new seam needed]
+  Location:   [file:line where behavior can be altered]
+  Incision:   [the minimal change — one sentence]
+  Preserved:  [what existing behavior is explicitly kept]
+  Risk:       [what could break — be specific]
+```
+
+Example:
+
+```
+SEAM ANALYSIS: Add retry logic to payment processing
+  Seam type:  object — PaymentProcessor accepts a gateway parameter
+  Location:   src/payments/processor.ts:42 (constructor accepts PaymentGateway)
+  Incision:   Wrap the existing gateway in a RetryingGateway decorator that retries on transient errors
+  Preserved:  all existing payment logic, error handling, and logging untouched
+  Risk:       retry could cause duplicate charges if the gateway doesn't support idempotency keys — verify before implementing
+```
+
+## Interaction Model
+
+Decision engine. When the agent encounters existing code it needs to modify, it produces the seam analysis before making any changes. The human sees the surgical plan — seam type, incision point, what's preserved, what's at risk — and approves before cuts are made.
+
+## Red Flags
+
+| Agent impulse | Better approach |
+|---------------|----------------|
+| "Let me rewrite this function" | Find a seam. Make a minimal change. |
+| "I'll refactor this to be cleaner" | Were you asked to refactor? If not — preserve and extend. |
+| "This code is messy, let me fix it" | Messy code that works has value. Messy code that you break has negative value. |
+| "I'll wrap this in a new abstraction" | Does the abstraction help the change, or does it just hide code you don't understand? |
+| "Let me add types to make this safer" | Adding types to code you don't fully understand can introduce false confidence — the types might be wrong. |
+| "I'll extract a class for this" | Is extraction the minimal incision, or are you redesigning while the patient is on the table? |
+| "Let me clean up these comments/formatting" | Unrelated formatting changes make the diff noisy and hide the real change. Don't. |
+| "This would be simpler if I just started over" | Simpler to write, maybe. Simpler to be correct? Almost never. |
+
+## The Feathers Techniques (Reference)
+
+1. **Sprout Method** — Need new behavior? Write a new function and call it from the existing code. Don't modify the existing logic — add alongside it.
+
+2. **Wrap Method** — Need behavior before or after existing code? Rename the original, create a new function with the old name that calls the original plus the new behavior.
+
+3. **Sprout Class** — Same as Sprout Method but at the class level. Create a new class for the new behavior and instantiate it from the existing code.
+
+4. **Scratch Refactoring** — Need to understand code? Refactor it aggressively in a throwaway branch. Delete the branch. Now make your real, minimal change with the understanding you gained.
+
+5. **Characterization Tests** — Before changing code, write tests that document its current behavior (even if that behavior seems wrong). These tests protect against accidental changes.
+
+6. **The Legacy Code Dilemma** — To change code safely, you need tests. To add tests, you often need to change code. Seams break this cycle by creating safe points of intervention.
+
+## Guard Rails
+
+**Don't moralize about code quality.** The skill is about making safe, effective changes — not about judging the code you're working with.
+
+**Small seams first.** If you need to create a seam, start with the smallest possible one. You can always widen it later.
+
+**Characterize before changing.** If the code has no tests and you're about to modify it, write at least one characterization test first. Even a rough test that asserts current output is better than changing code with no safety net.
+
+**Ask about the unknown.** When you encounter behavior you don't understand, ask the human before removing or modifying it. "I see this null check on line 47 — do you know if there's a case where this value is actually null in production?"

package/skills/seam-finder/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "seam-finder",
+  "version": "1.0.0",
+  "description": "Feathers-inspired legacy code modification — find seams, make minimal incisions, preserve existing behavior",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/seam-finder/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/seam-finder.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/seam-finder.md"
+    }
+  }
+}

package/skills/simplicity-razor/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: simplicity-razor
+description: Use when the agent recommends a library, framework, or pattern, when proposing architecture or technology choices, when the user asks "should I use X?", or when code has many dependencies for its scope. Trigger on technology decisions and dependency introductions. NOT for choices the team has already committed to.
+---
+
+# Simplicity Razor
+
+A decision framework based on Rich Hickey's *Simple Made Easy*. Distinguishes between "simple" (not interleaved — one concern per construct) and "easy" (near at hand — familiar, convenient). These are orthogonal properties. Easy things can be complex. Hard things can be simple. AI agents and developers consistently reach for easy over simple, accumulating *complecting* — the braiding together of independent concerns until the system becomes impossible to reason about.
+
+**Core principle:** Before recommending any tool, library, pattern, or approach, name its strands. If they're braided together such that you can't change one without affecting the others, the solution is complex — regardless of how easy it is to use. Simplicity is a choice, not an accident.
+
+## When to Use
+
+- Recommending a library, framework, or pattern
+- Proposing an architecture or technology choice
+- "Should I use X?" where X is a popular tool or approach
+- Code has many dependencies relative to its scope
+- A solution feels "enterprise-grade" for a small problem
+- Evaluating competing approaches
+
+**Not for:** Choices the team has already committed to (don't relitigate the framework), trivial utility selections (date formatting library), or ecosystem-mandated tools (your CI provider's required CLI).
+
+## The Process
+
+### 1. Name the Strands
+
+For any proposed solution, identify the independent concerns it handles:
+
+- A function that does validation AND transformation AND logging: **3 strands**
+- A library that couples data fetching with caching with state management: **3 strands**
+- A pattern that ties request handling to serialization to error formatting: **3 strands**
+
+Each strand should be nameable in 2-3 words. If you can't name the strands, you don't understand the solution well enough to recommend it.
+
+**Naming exercise:** For a proposed ORM:
+- Strand 1: query construction
+- Strand 2: result mapping
+- Strand 3: schema migration
+- Strand 4: connection management
+- Strand 5: query caching
+- Strand 6: change tracking
+
+That's 6 strands. Are they all braided? Can you use query construction without change tracking? If not, you've bought 6 concerns to solve 1 problem.
+
+### 2. Complecting Test
+
+Are any strands braided together such that you can't change one without affecting the others?
+
+Ask for each pair:
+- Can you change the validation logic without touching the transformation? **If no: complected.**
+- Can you swap the data fetching strategy without reconfiguring the cache? **If no: complected.**
+- Can you modify error formatting without changing request handling? **If no: complected.**
+
+**The substitution test:** Can you replace one strand with a different implementation without modifying the code that handles the other strands? If you can, the strands are composed (good). If you can't, they're complected (investigate).
+
+### 3. Easy vs. Simple Audit
+
+For the proposed solution, evaluate both dimensions independently:
+
+**Easy signals** (not inherently bad, but suspicious when used as justification):
+
+| Signal | Why it's suspicious |
+|--------|-------------------|
+| "Everyone uses it" | Popularity ≠ simplicity. Popular tools are often complex tools with good marketing. |
+| "It has a nice API" | Nice APIs can hide enormous complecting behind convenience methods. |
+| "It's one line to add" | One line to add, but how many concepts to understand? |
+| "It's the standard approach" | Standards emerge from momentum, not from analysis. |
+| "There's a plugin for that" | Plugin ecosystems are dependency graphs you'll inherit. |
+| "It handles everything" | "Everything" means braided concerns. What if you don't need everything? |
+
+**Simple signals** (what to aim for):
+
+| Signal | Why it's good |
+|--------|-------------|
+| "Each piece does one thing" | Single-strand constructs compose freely. |
+| "I can replace this part without touching that part" | Strands are separated, not braided. |
+| "The data flows in one direction" | Unidirectional flow is inherently less complected. |
+| "There's no hidden state" | State that you can see is state you can reason about. |
+| "I can understand this without reading my dependencies' source" | The abstraction boundary holds. |
+| "I chose each piece deliberately" | Composition by choice, not by inheritance. |
+
+### 4. Decomplect or Justify
+
+If the solution complects, the agent must either:
+
+**Decomplect** — Use separate, composable pieces:
+- Replace the all-in-one library with focused tools that each handle one strand
+- Split the multi-concern function into single-purpose functions that compose
+- Use data-oriented designs that separate data from behavior
+
+**Justify** — Explain *specifically* why the complecting is worth it:
+- A measured performance requirement that the composed version can't meet
+- The team has standardized on it and switching would be more disruptive than the complecting
+- The braided concerns genuinely change together — not hypothetically, but *actually*, based on real change history
+
+**Justifications that do NOT count:**
+- "It's industry standard" — standards can be complex
+- "Everyone uses it" — popularity is not simplicity
+- "It's easier" — that is *literally the trap this skill exists to catch*
+- "It's well-maintained" — maintenance quality doesn't affect complecting
+- "It has good docs" — documented complexity is still complexity
+
+### When the Human Requests Something Complex
+
+Don't refuse. Present the analysis and ask:
+
+> "Here's what [X] braids together: [strands]. Is that tradeoff worth it for your situation?"
+
+The human may have context you don't — team familiarity, contractual obligations, performance constraints. Respect their decision. The skill ensures the decision is *informed*, not that it's *yours*.
+
+## Output Format
+
+```
+SIMPLICITY: [proposed solution]
+  Strands:      [list independent concerns involved]
+  Complected:   [which strands are braided — or "none"]
+  Easy score:   [high / medium / low]
+  Simple score: [high / medium / low]
+  Verdict:      [use it / decomplect / justify]
+  Alternative:  [if complected — what's the simpler composition?]
+```
+
+Example:
+
+```
+SIMPLICITY: Using Redux + Redux Toolkit + RTK Query for app state
+  Strands:      UI state, server cache, async data fetching, optimistic updates, devtools
+  Complected:   server cache is braided with UI state (same store, same reducers)
+  Easy score:   high (popular, well-documented, team knows it)
+  Simple score: low (5 braided concerns behind one store abstraction)
+  Verdict:      decomplect
+  Alternative:  React state for UI + TanStack Query for server cache — each strand handled by a focused tool
+```
+
+## The Hickey Vocabulary (Reference)
+
+| Term | Meaning | Example |
+|------|---------|---------|
+| **Simple** | Not interleaved; one braid | A pure function: data in, data out |
+| **Easy** | Near at hand; familiar | An ORM with convention-over-configuration |
+| **Complex** | Interleaved; multiple braids | A function that fetches, caches, transforms, and logs |
+| **Complecting** | The act of braiding together | Adding "just one more concern" to an existing module |
+| **Decomplecting** | The act of separating braids | Splitting a god module into composable parts |
+| **Compose** | Combining simple things | Piping focused functions together |
+| **Artifact** | What you build | Code, modules, services |
+| **Construct** | Tools you use to build | Languages, libraries, patterns |
+
+## Guard Rails
+
+**Simple ≠ minimal.** A well-composed system of 10 focused tools can be simpler than a 3-tool system where each tool braids 5 concerns. Simplicity is about separation, not about having fewer things.
+
+**Don't relitigate committed decisions.** If the team has chosen React, you don't run the simplicity razor on React. You run it on *new* choices being made within the React ecosystem.
+
+**Acknowledge the tradeoff.** Sometimes easy IS the right choice — when time is the binding constraint, when the team's familiarity reduces the effective complexity, when the complecting is genuinely harmless for this project's expected lifetime. Say so when it's true.
+
+**Composition has costs too.** Gluing together 8 tiny libraries has its own complexity — version management, interface adaptation, debugging across boundaries. The simplicity razor checks for braided concerns, not for an absolute count of dependencies.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Treating "popular" as "proven simple" | Popularity signals ease, not simplicity. Evaluate strands. |
+| Decomplecting into too many tiny pieces | Composition has costs. Find the right granularity. |
+| Rejecting all libraries as "complex" | Libraries aren't inherently bad. Libraries that braid unrelated concerns are bad. |
+| Running this analysis on every 3-line decision | Scale to stakes. A date formatting library doesn't need strand analysis. |
+| Refusing the human's choice without explanation | Present the analysis. Respect the decision. You inform, you don't veto. |

package/skills/simplicity-razor/skill.json

@@ -0,0 +1,26 @@
+{
+  "name": "simplicity-razor",
+  "version": "1.0.0",
+  "description": "Hickey-inspired simplicity analysis — simple vs easy, complecting detection, strand decomposition",
+  "author": "iceinvein",
+  "type": "prompt",
+  "tools": ["claude", "cursor", "codex", "gemini"],
+  "files": {
+    "prompt": "SKILL.md"
+  },
+  "install": {
+    "claude": {
+      "prompt": ".claude/skills/simplicity-razor/SKILL.md"
+    },
+    "cursor": {
+      "prompt": ".cursor/rules/simplicity-razor.mdc"
+    },
+    "codex": {
+      "prompt": "AGENTS.md",
+      "append": true
+    },
+    "gemini": {
+      "prompt": ".gemini/skills/simplicity-razor.md"
+    }
+  }
+}