Adding skills

skills/develop/simplify/README.md

@@ -0,0 +1,15 @@
+# Simplify Skill
+
+Behavior-preserving code simplification and readability-focused refactoring.
+
+## Overview
+
+This skill guides agents to reduce unnecessary complexity while preserving behavior. It emphasizes understanding callers and edge cases before editing, following project conventions, making incremental changes, and verifying each refactor.
+
+## Source
+
+Adapted from Addy Osmani's [`code-simplification` skill](https://github.com/addyosmani/agent-skills/blob/main/skills/code-simplification/SKILL.md).
+
+## Installation
+
+This skill is maintained in `skills/develop/simplify` within the `harness-tools` repository. The global installation at `~/.agents/skills/simplify` is a symlink to this directory.

skills/develop/simplify/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: simplify
+description: Simplifies code for clarity without changing behavior. Use for readability, maintainability, and complexity reduction after behavior is understood.
+---
+
+# Code Simplification
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines - it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+## When to Use
+
+- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
+- During code review when readability or complexity issues are flagged
+- When you encounter deeply nested logic, long functions, or unclear names
+- When refactoring code written under time pressure
+- When consolidating related logic scattered across files
+- After merging changes that introduced duplication or inconsistency
+
+**When NOT to use:**
+
+- Code is already clean and readable - don't simplify for the sake of it
+- You don't understand what the code does yet - comprehend before you simplify
+- The code is performance-critical and the "simpler" version would be measurably slower
+- You're about to rewrite the module entirely - simplifying throwaway code wastes effort
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does - only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+Before every change, ask:
+
+- Does this produce the same output for every input?
+- Does this maintain the same error behavior?
+- Does this preserve the same side effects and ordering?
+- Do all existing tests still pass without modification?
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences.
+
+Before simplifying:
+
+1. Read `AGENTS.md` / project conventions
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for imports, naming, function style, error handling, and type annotations
+
+Simplification that breaks project consistency is not simplification - it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+- Replace nested ternaries with readable control flow
+- Replace dense inline transforms with named intermediate steps when they clarify intent
+- Keep helpful names even if they cost a few extra lines
+
+### 4. Maintain Balance
+
+Watch for over-simplification:
+
+- Don't inline away names that carry meaning
+- Don't merge unrelated logic into one larger function
+- Don't remove abstractions that serve testability or extensibility
+- Don't optimize for line count over comprehension
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid unrelated drive-by refactors unless explicitly asked.
+
+## Process
+
+### Step 1: Understand Before Touching
+
+Before changing or removing anything, understand why it exists.
+
+Answer:
+
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define expected behavior?
+- Why might it have been written this way?
+
+If you can't answer these, read more context first.
+
+### Step 2: Look for Simplification Opportunities
+
+Signals:
+
+- Deep nesting
+- Long functions with mixed responsibilities
+- Nested ternaries
+- Boolean flag arguments
+- Repeated conditionals
+- Generic or misleading names
+- Duplicated logic
+- Dead code
+- Wrappers or abstractions that add no value
+
+### Step 3: Apply Changes Incrementally
+
+Make one simplification at a time.
+
+For each simplification:
+
+1. Make the change
+2. Run relevant tests
+3. Keep it only if behavior is preserved
+
+Separate refactoring from feature work whenever possible.
+
+### Step 4: Verify the Result
+
+After simplifying, confirm:
+
+- The code is genuinely easier to understand
+- The diff is clean and reviewable
+- Project conventions still match
+- No behavior, error handling, or side effects changed
+
+## Guidance for This Repository
+
+- Prefer straightforward TypeScript over clever compression
+- Preserve existing runtime behavior, tests, and hooks
+- Favor explicit names and smaller focused helpers when they improve readability
+- Keep refactors tightly scoped to the task or review feedback
+
+## Verification Checklist
+
+- [ ] Existing tests pass without modification
+- [ ] Build/typecheck/lint still pass
+- [ ] No unrelated files were refactored
+- [ ] No error handling was weakened or removed
+- [ ] The result is simpler to review than the original