ima-claude 2.20.0 → 2.25.0

package/plugins/ima-claude/skills/functional-programmer/SKILL.md

@@ -3,271 +3,67 @@ name: "functional-programmer"
 description: "Functional programming principles and philosophy - pure functions, immutability, composition, side effect isolation, declarative style. Trigger when: discussing FP concepts, transitioning from OOP, explaining why FP matters, architectural mindset shifts. This skill covers principles ONLY - see js-fp, php-fp, etc. for implementation patterns."
 ---
 
-# Functional Programming: Principles and Philosophy
+# FP Principles
 
-This skill provides the conceptual foundation for functional programming. It covers the WHY, not the HOW. For language-specific implementation patterns, see:
-- **js-fp** - JavaScript FP patterns
-- **php-fp** - PHP FP patterns
-- **js-fp-react**, **js-fp-vue** - Framework-specific FP patterns
+FP is a mindset, not an API signature. Not `pipe()`, `compose()`, or `curry()`.
 
-## The Core Insight
-
-Functional programming is not a set of utility functions. It's not `pipe()`, `compose()`, or `curry()`. It's a way of thinking about problems that makes code predictable, testable, and maintainable.
-
-**FP is a mindset, not an API signature.**
-
-## The Seven Pillars
+## Seven Pillars
 
 ### 1. Pure Functions
-
-**Principle**: A function should return the same output for the same input, every time, with no side effects.
-
-**Why it matters:**
-- Predictability: No surprises, no hidden state changes
-- Testability: Test any function with any input, no mocking required
-- Parallelization: Pure functions can run concurrently without coordination
-- Debugging: When something breaks, you know exactly where to look
-
-**The litmus test:** Can you call this function 1000 times with the same arguments and always get the same result without affecting anything else? If yes, it's pure.
+Same input → same output, no side effects. Enables testing without mocks, safe parallelization, predictable debugging.
 
 ### 2. Immutability
-
-**Principle**: Data, once created, never changes. To "modify" data, create new data.
-
-**Why it matters:**
-- No aliasing bugs: When two variables point to the same data, neither can corrupt the other
-- Time-travel debugging: Every state is preserved, you can inspect any point in time
-- Concurrency safety: No locks needed when data can't change
-- Predictable state: You always know what data looks like at any point
-
-**The key insight:** Mutation is the source of countless bugs. Race conditions, stale references, unexpected side effects - all stem from shared mutable state. Immutability eliminates these entire categories of bugs.
+Never mutate data. Create new data instead. Eliminates aliasing bugs, race conditions, stale references.
 
 ### 3. Function Composition
-
-**Principle**: Complex behavior emerges from combining simple functions.
-
-**Why it matters:**
-- Reusability: Small functions combine in countless ways
-- Testability: Test each piece independently, trust the composition
-- Readability: The code structure matches the mental model
-- Maintainability: Change one piece without affecting others
-
-**The mental model:** Think of functions as LEGO bricks. Each brick is simple and does one thing. Complex structures come from how you connect them, not from making bigger bricks.
+Build complex behavior by combining simple functions. Small composable pieces > monolithic functions.
 
 ### 4. First-Class Functions
-
-**Principle**: Functions are values. Pass them around, return them, store them.
-
-**Why it matters:**
-- Abstraction power: Higher-order functions enable powerful patterns
-- Flexibility: Behavior becomes data you can manipulate
-- DRY: Common patterns extracted into reusable higher-order functions
-- Customization: Inject behavior without inheritance hierarchies
-
-**The unlock:** When functions become values, you can write functions that operate on functions. This is where FP's real power emerges - abstracting over behavior, not just data.
+Functions are values — pass, return, store them. Enables higher-order patterns and behavior injection without inheritance.
 
 ### 5. Referential Transparency
-
-**Principle**: An expression can be replaced with its value without changing program behavior.
-
-**Why it matters:**
-- Reasoning: You can understand code by substituting values
-- Refactoring: Move code freely, confident behavior won't change
-- Caching: Memoize any referentially transparent computation
-- Optimization: Compilers can reorder and optimize freely
-
-**The test:** If you can replace a function call with its return value everywhere in your code and nothing changes, the function is referentially transparent.
+Expression replaceable with its value without behavior change. Enables safe refactoring, memoization, compiler optimization.
 
 ### 6. Side Effect Isolation
+Pure core (business logic) + impure shell (I/O). Shell calls core, never vice versa. Target: 80% pure, 20% shell.
 
-**Principle**: Push side effects to the edges of your system. Keep the core pure.
-
-**Why it matters:**
-- The bulk of your code becomes testable without mocks
-- Side effects are explicit and contained
-- Business logic stays decoupled from infrastructure
-- Easier to swap implementations (databases, APIs, etc.)
-
-**The architecture:** Your system has an impure shell that handles I/O (databases, APIs, user input, logging) and a pure core that handles all business logic. The shell calls the core, never vice versa.
-
-**The ratio to aim for:** 80% pure core, 20% impure shell. If your ratio is inverted, you're spreading side effects throughout your code.
+Pure core: calculations, transformations, validations, business rules.
+Impure shell: database, API calls, user I/O, logging, filesystem.
 
 ### 7. Declarative Style
+Describe WHAT, not HOW. Express business logic, not mechanics.
 
-**Principle**: Describe WHAT you want, not HOW to get it.
-
-**Why it matters:**
-- Intent clarity: Code expresses business logic, not mechanics
-- Less boilerplate: The runtime handles the implementation details
-- Optimization freedom: Declarative code can be optimized freely
-- Reduced bugs: Fewer moving parts means fewer places for bugs to hide
-
-**The shift:** Imperative code is a sequence of instructions. Declarative code is a description of the desired outcome. The runtime figures out the steps.
-
-## The Journey from OOP
-
-### Why Classical Inheritance Fails
-
-**The fragile base class problem:** Change a base class, break all descendants in unpredictable ways.
-
-**The gorilla-banana problem:** You want a banana, but you get a gorilla holding the banana and the entire jungle. Class hierarchies bring unwanted dependencies.
-
-**The diamond problem:** Multiple inheritance creates ambiguity. Single inheritance creates awkward hierarchies where things don't quite fit.
-
-**Deep hierarchies:** Every level of inheritance is another level of complexity to understand. Five levels deep, and nobody knows what's actually happening.
-
-### Composition Over Inheritance
-
-Instead of "is-a" relationships (inheritance), use "has-a" relationships (composition).
-
-Instead of extending behavior through class hierarchies, compose behavior through functions.
-
-**The key difference:**
-- Inheritance: Behavior locked in at definition time, tightly coupled
-- Composition: Behavior assembled at runtime, loosely coupled
-
-### What OOP Got Right
-
-Object-oriented programming contributed valuable ideas:
-- Encapsulation (hiding implementation details)
-- Polymorphism (same interface, different behavior)
-
-FP embraces these - through closures for encapsulation and first-class functions for polymorphism. The mistake was coupling these ideas to class hierarchies and inheritance.
-
-## Anti-Over-Engineering
-
-### Don't Create Custom FP Utilities
-
-The biggest trap for newcomers to FP: building a personal utility library of `pipe()`, `compose()`, `curry()`, and custom monads.
-
-**Why it's harmful:**
-- Every team member must learn your utilities
-- Debugging through abstraction layers
-- Maintenance burden for no business value
-- Makes code less portable
-
-**The right approach:** Use established libraries (lodash, Ramda, etc.) when appropriate, or just use the language's native patterns. FP principles work without special utilities.
-
-### The Abstraction Cost
-
-Every abstraction has a cost:
-- Learning curve for new team members
-- Debugging complexity
-- Maintenance burden
-- Mental overhead when reading code
-
-**The question to ask:** Does this abstraction pay for itself? Will I use it enough to justify the cost? Would a junior developer understand it?
-
-### File Size as a Smell
-
-Keep files under 500 lines. This isn't an arbitrary limit — it's a smell detector. A file approaching 500 lines almost certainly has multiple responsibilities that should be separated.
-
-**When a file grows too large:**
-- Split by responsibility, not by arbitrary line count
-- A 300-line file with two unrelated concerns is worse than a 480-line file with one
-- The goal is cohesion: each file should have a single, clear reason to exist
-
-**Why this matters:**
-- Readability: Developers can hold one file's purpose in their head
-- Testability: Smaller, focused files are easier to test in isolation
-- Navigation: Finding what you need is faster in a well-structured codebase
-- Review: Code review quality drops sharply beyond 500 lines
-
-### Context-Appropriate Complexity
-
-A CLI script has different needs than a production API.
-
-A weekend project has different needs than enterprise software.
-
-**Match complexity to context:**
-- Simple problem? Simple solution.
-- Complex problem? Complex solution.
-- Simple problem + complex solution = over-engineering.
-
-## The Practical Application
-
-### Pure Core, Impure Shell
-
-Structure your code in two layers:
-
-**The Pure Core (business logic):**
-- All calculations
-- All transformations
-- All validations
-- All business rules
-
-**The Impure Shell (I/O):**
-- Database operations
-- API calls
-- User input/output
-- Logging
-- File system access
-
-The shell calls the core, passes data in, gets results out. The core never reaches out to the shell.
-
-### Explicit Dependencies
-
-Functions should receive everything they need as parameters.
-
-No reaching into global state. No hidden dependencies. Everything visible in the function signature.
-
-**Why this matters:** You can understand what a function does by reading its signature. You can test it by passing in test data. You can reuse it in any context.
-
-### Result Types Over Exceptions
-
-Return structured results instead of throwing exceptions.
-
-**Why this is better:**
-- Error handling is explicit in the type system
-- No hidden control flow
-- Caller must acknowledge potential failure
-- Easier to test error paths
-
-## The Mindset Shift
-
-### Think in Transformations
-
-Stop thinking: "How do I modify this data?"
-Start thinking: "What new data do I create from this data?"
+## Composition Over Inheritance
 
-### Think in Pipelines
+Inheritance problems: fragile base class, gorilla-banana (unwanted dependencies), diamond ambiguity, deep hierarchy opacity.
 
-Stop thinking: "How do I imperatively process this step by step?"
-Start thinking: "What transformations does this data flow through?"
+Use "has-a" (composition) not "is-a" (inheritance). Behavior assembled at runtime, loosely coupled.
 
-### Think in Declarations
+OOP's valid contributions — encapsulation and polymorphism — achieved through closures and first-class functions.
 
-Stop thinking: "What steps do I need to perform?"
-Start thinking: "What is the relationship between input and output?"
+## Anti-Over-Engineering (PRIMARY)
 
-### Think in Boundaries
+**Never create custom FP utilities** (`pipe`, `compose`, `curry`, custom monads). Use established libraries or native language patterns.
 
-Stop thinking: "How do I make this class do everything?"
-Start thinking: "Where does pure logic end and side effects begin?"
+Every abstraction costs: learning curve, debugging complexity, maintenance burden, mental overhead.
+Test: Does this abstraction pay for itself? Would a junior dev understand it?
 
-## Integration with Tech-Specific Skills
+**File size smell**: >500 lines = likely multiple responsibilities. Split by cohesion, not line count.
 
-This skill provides the conceptual foundation. For implementation:
+**Match complexity to context**: CLI script ≠ production API ≠ weekend project. Simple problem + complex solution = over-engineering.
 
-| Principle | Implementation Skill |
-|-----------|---------------------|
-| Pure functions in JavaScript | js-fp |
-| Immutability in React | js-fp-react |
-| Composition in Vue | js-fp-vue |
-| Side effect isolation in Node | js-fp-api |
-| FP patterns in PHP | php-fp |
-| FP in WordPress | php-fp-wordpress |
+## Architecture
 
-## Summary: The FP Mindset
+**Explicit dependencies**: Functions receive everything as parameters. No globals, no hidden state. Signature tells the full story.
 
-1. **Functions are the unit of abstraction** - Not classes, not modules, functions
-2. **Data flows, it doesn't change** - Transform, don't mutate
-3. **Side effects are dangerous** - Isolate and control them
-4. **Composition beats inheritance** - Small pieces combined > large hierarchies
-5. **Explicit beats implicit** - Dependencies, data flow, error handling
-6. **Simple beats clever** - Boring, readable code wins
-7. **Evidence beats assumptions** - Add complexity only when needed
+**Result types over exceptions**: Return `{ success, data, error }`. Makes error handling explicit, no hidden control flow, testable error paths.
 
-## The Final Word
+## Core Directives
 
-*"Functional programming is not about using fancy utilities or writing point-free code. It's about writing code that's honest about what it does, predictable in its behavior, and simple in its structure. The functions are pure, the data is immutable, the dependencies are explicit, and the side effects are contained. Everything else is just syntax."*
+1. Functions are the unit of abstraction — not classes, not modules
+2. Data flows, never changes — transform, don't mutate
+3. Side effects are dangerous — isolate and control them
+4. Composition beats inheritance — small pieces > large hierarchies
+5. Explicit beats implicit — dependencies, data flow, error handling
+6. Simple beats clever — boring, readable code wins
+7. Evidence beats assumptions — add complexity only when needed

package/plugins/ima-claude/skills/gh-cli/SKILL.md

@@ -9,19 +9,14 @@ description: >-
   NOT for Gitea — use mcp-gitea for internal repos.
 ---
 
-# GitHub CLI (`gh`) — GitHub Operations
-
-The `gh` CLI is the primary tool for all GitHub operations. It's authenticated, reliable, and covers the full GitHub API surface.
+# GitHub CLI (`gh`)
 
 ## Prerequisites
 
 ```bash
-# Verify authentication
-gh auth status
+gh auth status  # must pass before any operations
 ```
 
-The CLI must be authenticated (`gh auth login`) before use. Verify scopes with `gh auth status`.
-
 ## Command Reference
 
 ### Pull Requests
@@ -110,7 +105,7 @@ The CLI must be authenticated (`gh auth login`) before use. Verify scopes with `
 | Delete release | `gh release delete v1.0.0` |
 | Edit release | `gh release edit v1.0.0 --title "..." --notes "..."` |
 
-### GitHub Actions (Workflows & Runs)
+### GitHub Actions
 
 | Operation | Command |
 |-----------|---------|
@@ -129,7 +124,7 @@ The CLI must be authenticated (`gh auth login`) before use. Verify scopes with `
 | Rerun failed jobs | `gh run rerun 12345 --failed` |
 | Cancel run | `gh run cancel 12345` |
 
-### Search (Cross-Repository)
+### Search
 
 | Operation | Command |
 |-----------|---------|
@@ -151,56 +146,46 @@ The CLI must be authenticated (`gh auth login`) before use. Verify scopes with `
 
 ### Raw API Access
 
-For operations not covered by built-in commands:
-
 ```bash
-# GET request
+# GET
 gh api repos/{owner}/{repo}/topics
 
-# POST request
+# POST
 gh api repos/{owner}/{repo}/labels -f name="priority" -f color="ff0000"
 
-# With pagination
+# Paginated
 gh api repos/{owner}/{repo}/issues --paginate
 
 # GraphQL
 gh api graphql -f query='{ viewer { login } }'
 
-# JSON output + jq filtering
+# JSON + jq
 gh api repos/{owner}/{repo}/pulls --jq '.[].title'
 ```
 
 ## Decision Logic
 
 ```
-Is this a GitHub-hosted repo?
-  Check: git remote -v → shows github.com
-  → Yes: Use gh CLI (this skill)
-  → No: Is it Gitea-hosted?
-      → Yes: Use mcp-gitea tools (see mcp-gitea skill)
-      → Unknown: Ask the user
-
-For local-only git operations (commit, diff, log, stash, rebase):
-  → Always use git CLI directly — gh is for GitHub API operations
-
-Operation routing:
-  PRs (create, review, merge, list)  → gh pr ...
-  Issues (create, comment, close)    → gh issue ...
-  Releases (create, upload, list)    → gh release ...
-  CI/CD status, rerun, logs          → gh run ... / gh workflow ...
-  Search across GitHub               → gh search ...
-  Anything not in built-in commands  → gh api ...
+github.com remote? → use gh (this skill)
+Gitea remote?      → use mcp-gitea
+Local git ops      → use git CLI directly
+
+PRs                → gh pr ...
+Issues             → gh issue ...
+Releases           → gh release ...
+CI/CD              → gh run ... / gh workflow ...
+Search             → gh search ...
+Anything else      → gh api ...
 ```
 
 ## Common Workflows
 
-### Create a PR with Body via HEREDOC
+### PR with HEREDOC body
 
 ```bash
 gh pr create --title "feat: add gh-cli skill" --body "$(cat <<'EOF'
 ## Summary
 - Added gh-cli skill for GitHub CLI operations
-- Replaces unreliable MCP GitHub integration
 
 ## Test plan
 - [ ] Verify gh auth status
@@ -209,17 +194,14 @@ EOF
 )"
 ```
 
-### Check CI and Merge When Ready
+### Check CI then merge
 
 ```bash
-# Check CI status
 gh pr checks 123
-
-# If all checks pass, merge
 gh pr merge 123 --squash --delete-branch
 ```
 
-### Create a Release with Changelog
+### Release with auto-changelog
 
 ```bash
 gh release create v2.12.0 \
@@ -228,49 +210,28 @@ gh release create v2.12.0 \
   --latest
 ```
 
-### Cross-Repo Issue Search
+### Cross-repo issue search
 
 ```bash
-# Find all open bugs assigned to me across repos
 gh search issues "is:open assignee:@me label:bug" --limit 20
-
-# Find PRs awaiting my review
 gh search prs "is:open review-requested:@me" --limit 20
 ```
 
-### View PR Comments (API)
+### PR comments via API
 
 ```bash
-# List PR review comments
 gh api repos/{owner}/{repo}/pulls/123/comments --jq '.[].body'
-
-# List issue/PR timeline comments
 gh api repos/{owner}/{repo}/issues/123/comments --jq '.[] | "\(.user.login): \(.body)"'
 ```
 
-## Output Formatting
-
-The `gh` CLI supports structured output:
+## Output & Targeting
 
 ```bash
-# JSON output
+# Structured output
 gh pr list --json number,title,state
-
-# JSON + jq filter
 gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'
 
-# Table format (default for list commands)
-gh issue list
-
-# Web browser
-gh pr view 123 --web
-```
-
-## Cross-Repository Operations
-
-Use `--repo` or `-R` to target any GitHub repo:
-
-```bash
+# Target any repo
 gh pr list -R owner/other-repo
 gh issue create -R owner/other-repo --title "..."
 gh run list -R owner/other-repo