ima-claude 2.9.0

package/plugins/ima-claude/skills/ruby-fp/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: "ruby-fp"
+description: "Functional Ruby patterns - Enumerable as FP toolkit, lambdas, freeze, functional core/imperative shell"
+---
+
+# Ruby FP
+
+Ruby is OOP-first, but its FP toolkit is excellent. The goal is **functional core, imperative shell** — pure methods for logic, OOP shell only where the framework demands it.
+
+## When to Use This Skill
+
+- Writing standalone Ruby scripts
+- Building Ruby utilities or service objects
+- Refactoring procedural Ruby toward composable units
+- Any Ruby code where framework conventions don't dictate the pattern
+
+## Core Philosophy
+
+> Ruby's Enumerable is a functional toolkit hiding inside an OOP language.
+
+The architect's lens applied to Ruby:
+- **Pure methods** for logic (no instance variable mutation in calculation methods)
+- **Enumerable over explicit loops** — `map/select/reduce` not `each` + accumulator
+- **Lambdas** for first-class functions (strict arity, `lambda?` is true, `return` is scoped)
+- **freeze** for value objects and constants
+- **Functional core** isolated from I/O, database, external state
+
+Ruby will never be Haskell. Don't fight the language — compose with it.
+
+## Enumerable: The FP Toolkit
+
+These are your primary tools. Prefer them over `each` + mutation.
+
+```ruby
+users = [
+  { name: 'Alice', age: 30, active: true },
+  { name: 'Bob',   age: 17, active: false },
+  { name: 'Carol', age: 25, active: true }
+]
+
+# select — filter
+adults = users.select { |u| u[:age] >= 18 }
+
+# map — transform
+names = users.map { |u| u[:name] }
+
+# reduce — accumulate
+total_age = users.reduce(0) { |sum, u| sum + u[:age] }
+
+# filter_map — select + transform in one pass (Ruby 2.7+, preferred)
+active_names = users.filter_map { |u| u[:name] if u[:active] }
+
+# flat_map — map + flatten
+tags = posts.flat_map { |p| p[:tags] }
+
+# each_with_object — build a hash/array without external mutation
+index = users.each_with_object({}) { |u, h| h[u[:name]] = u[:age] }
+
+# group_by — partition
+by_status = users.group_by { |u| u[:active] ? :active : :inactive }
+
+# Chaining — functional pipeline
+result = users
+  .select { |u| u[:active] }
+  .map { |u| u.merge(display_name: u[:name].upcase) }
+  .sort_by { |u| u[:age] }
+```
+
+**Rule**: If you find yourself writing `results = []; collection.each { |x| results << x if ... }`, reach for `filter_map` instead.
+
+## Lambdas vs Procs
+
+Use `lambda` (or `->`) for reusable, composable functions. Avoid bare `proc` for logic units.
+
+```ruby
+# Lambda — strict arity, scoped return, first-class function
+validate_age = ->(age) { age.is_a?(Integer) && age >= 0 && age <= 150 }
+normalize_email = ->(email) { email.to_s.strip.downcase }
+
+# Compose with >> (Ruby 2.6+)
+process_user = normalize_email >> method(:save_user)
+
+# Use as argument (higher-order functions)
+def transform_all(items, transformer)
+  items.map(&transformer)
+end
+
+transform_all(emails, normalize_email)
+
+# Method references — convert instance/class methods to callables
+validator = method(:validate_age)
+emails.map(&method(:normalize_email))
+```
+
+**Lambda vs Proc differences that matter:**
+| | Lambda | Proc |
+|-|--------|------|
+| Arity | Strict (raises ArgumentError) | Loose (fills nil) |
+| `return` | Exits lambda only | Exits enclosing method |
+| Use for | Reusable functions, composition | Blocks, iterators |
+
+## Immutability with freeze
+
+```ruby
+# Freeze constants
+VALID_STATUSES = %w[active inactive pending].freeze
+DEFAULT_CONFIG = { timeout: 30, retries: 3 }.freeze
+
+# Value object pattern — frozen struct
+UserRecord = Data.define(:name, :email, :age)  # Ruby 3.2+
+user = UserRecord.new(name: 'Alice', email: 'alice@example.com', age: 30)
+# user is immutable — no setters
+
+# For older Ruby, use Struct with freeze
+Config = Struct.new(:host, :port, :timeout).new('localhost', 5432, 30).freeze
+```
+
+**Rule**: Any hash/array used as a constant gets `.freeze`. Value objects use `Data.define` (Ruby 3.2+) or frozen `Struct`.
+
+## Functional Core / Imperative Shell
+
+The central pattern. Separate pure logic from I/O and external state.
+
+```ruby
+# PURE CORE — no I/O, no DB, fully testable, no side effects
+module UserLogic
+  def self.validate(attrs)
+    errors = []
+    errors << "Name required" if attrs[:name].to_s.strip.empty?
+    errors << "Invalid email" unless attrs[:email].to_s.include?('@')
+    errors << "Age must be 18+" if attrs[:age].to_i < 18
+    errors
+  end
+
+  def self.normalize(attrs)
+    attrs.merge(
+      name: attrs[:name].to_s.strip,
+      email: attrs[:email].to_s.strip.downcase
+    )
+  end
+
+  def self.prepare_for_save(raw_attrs)
+    normalized = normalize(raw_attrs)
+    errors = validate(normalized)
+    errors.empty? ? { ok: true, attrs: normalized } : { ok: false, errors: errors }
+  end
+end
+
+# IMPERATIVE SHELL — orchestrates I/O, calls pure core
+def create_user(raw_params)
+  result = UserLogic.prepare_for_save(raw_params)
+  return { success: false, errors: result[:errors] } unless result[:ok]
+
+  user = User.create!(result[:attrs])  # database side effect here only
+  { success: true, user: user }
+end
+```
+
+## Pure Method Guidelines
+
+A method is pure when:
+1. Same inputs always return same output
+2. No mutation of instance variables during computation
+3. No I/O (logging, DB, network) inside the calculation
+
+```ruby
+# BAD — mutates state during calculation
+def calculate_totals
+  @subtotal = @items.sum { |i| i[:price] * i[:qty] }
+  @tax = @subtotal * 0.08
+  @total = @subtotal + @tax
+end
+
+# GOOD — returns new values, no mutation
+def self.calculate_totals(items, tax_rate: 0.08)
+  subtotal = items.sum { |i| i[:price] * i[:qty] }
+  tax = subtotal * tax_rate
+  { subtotal: subtotal, tax: tax, total: subtotal + tax }
+end
+```
+
+## Composition Patterns
+
+```ruby
+# Method chaining on custom objects — return self or new instance
+class Pipeline
+  def initialize(steps = [])
+    @steps = steps.freeze
+  end
+
+  def add(step)
+    Pipeline.new(@steps + [step])  # returns new instance, immutable
+  end
+
+  def call(input)
+    @steps.reduce(input) { |data, step| step.call(data) }
+  end
+end
+
+# Lambda composition with >>
+sanitize  = ->(s) { s.strip.downcase }
+validate  = ->(s) { raise "empty" if s.empty?; s }
+normalize = sanitize >> validate
+
+# Callable objects (duck-typed lambdas)
+class Validator
+  def call(value)
+    value.is_a?(String) && !value.empty?
+  end
+end
+
+validators = [Validator.new, ->(v) { v.length < 255 }]
+valid = validators.all? { |v| v.call(input) }
+```
+
+## Anti-Patterns to Avoid
+
+```ruby
+# BAD — accumulator mutation inside each
+result = []
+items.each { |item| result << transform(item) if item[:active] }
+# GOOD
+result = items.filter_map { |item| transform(item) if item[:active] }
+
+# BAD — output parameter mutation
+def process(items, output)
+  items.each { |i| output << i * 2 }
+end
+# GOOD — return new value
+def process(items)
+  items.map { |i| i * 2 }
+end
+
+# BAD — complex logic inside a class with side effects mixed in
+def calculate_and_save
+  total = @items.sum(&:price)
+  @total = total          # side effect
+  DB.save(total)          # side effect
+  total
+end
+# GOOD — separate concerns
+total = calculate_total(@items)  # pure
+update_total(total)              # side effect isolated
+
+# BAD — bare proc for reusable function
+adder = proc { |a, b| a + b }  # loose arity, weird return behavior
+# GOOD
+adder = ->(a, b) { a + b }
+```
+
+## When to Use Classes
+
+OOP is fine for: stateful objects that model real entities (User, Order, Connection), framework integration (ActiveRecord models, controllers), objects that encapsulate a lifecycle.
+
+Use modules with class methods (or plain lambdas/methods) for: pure logic, utilities, transformations, validators.
+
+```ruby
+# Module for pure logic — no instances needed
+module PriceCalculator
+  def self.discount(price, tier)
+    rates = { bronze: 0.05, silver: 0.10, gold: 0.20 }.freeze
+    price * (1 - rates.fetch(tier, 0))
+  end
+end
+
+# Class for stateful lifecycle
+class ImportJob
+  def initialize(source_db, config)
+    @source_db = source_db
+    @config = config
+  end
+
+  def run
+    records = fetch_records        # I/O
+    processed = process(records)   # pure
+    persist(processed)             # I/O
+  end
+
+  private
+
+  def process(records)
+    records
+      .select { |r| valid?(r) }
+      .map { |r| transform(r) }
+  end
+end
+```
+
+## Security Notes for Standalone Scripts
+
+- **Never interpolate external input into shell commands** — use `Open3.capture3` with array args, not `system("cmd #{input}")`
+- **Never interpolate input into SQL** — use parameterized queries or the driver's escape method
+- **ENV for credentials** — never hardcode; raise if missing: `ENV.fetch('DB_PASSWORD')`
+
+```ruby
+# BAD — shell injection
+system("convert #{filename} output.png")
+
+# GOOD — array form, no shell expansion
+require 'open3'
+stdout, stderr, status = Open3.capture3('convert', filename, 'output.png')
+
+# BAD — hardcoded credential
+client = Mysql2::Client.new(password: 'secret123')
+
+# GOOD — fail loudly if not set
+client = Mysql2::Client.new(password: ENV.fetch('MYSQL_PASSWORD'))
+```
+
+## Quick Reference: When to Reach for What
+
+| Need | Use |
+|------|-----|
+| Transform a collection | `map` |
+| Filter a collection | `select` / `reject` |
+| Transform + filter in one pass | `filter_map` |
+| Accumulate to a single value | `reduce` / `inject` |
+| Build a hash from a collection | `each_with_object` / `to_h` |
+| Group by a property | `group_by` |
+| Reusable function | `lambda` / `->` |
+| Compose functions | `>>` operator |
+| Immutable constant | `.freeze` |
+| Immutable value object | `Data.define` (Ruby 3.2+) or frozen `Struct` |
+| Pure logic module | `module Foo; def self.method...` |
+
+## When to Load Reference Files
+
+### FP Patterns Deep Dive
+**File**: [`references/patterns.md`](references/patterns.md)
+**Load when**: Need advanced composition, lazy enumerables, currying, memoization
+**Contains**: Lazy evaluation, `Comparable`/`Enumerable` mixin, memoization patterns, full pipeline example
+
+### Security Examples
+**File**: [`references/security.md`](references/security.md)
+**Load when**: Working with external input, SQL, shell commands, file operations
+**Contains**: SQL parameterization, shell safety, input validation, ENV credential management

package/plugins/ima-claude/skills/save-session/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: "save-session"
+description: "Save session state to Serena MCP memory (no file path confusion)"
+---
+
+# save-session
+
+Save current session state to Serena MCP memory for cross-session persistence.
+
+## Trigger Phrases
+
+- "save session"
+- "save the session"
+- "save current session"
+- "create session save"
+- "checkpoint session"
+
+## Instructions
+
+Use `mcp__serena__write_memory` to save session state.
+
+**Memory name**: `session-state`
+
+**Content format**:
+
+```markdown
+# Session State
+Saved: {current_date_time}
+
+## Current Task
+{1-2 sentences describing the active task or goal}
+
+## Modified Files
+- {path/to/file1}
+- {path/to/file2}
+
+## Decisions Made
+- {Key decision 1}
+- {Key decision 2}
+
+## Technical Context
+- **Relevant code**: {endpoints, functions, components involved}
+- **Patterns**: {FP patterns, type constraints, architectural decisions}
+- **Dependencies**: {external libraries, services, APIs}
+
+## Outstanding Items
+- [ ] {Incomplete item or next step}
+- [ ] {Blocker or open question}
+
+## Resume Hint
+{One sentence: what to do first when resuming}
+```
+
+## Rules
+
+**Include:**
+- Active task state (what's in progress)
+- Files touched this session
+- Decisions that affect future work
+- Blockers or open questions
+- Enough context to resume without re-reading entire codebase
+
+**Exclude:**
+- Conversation history or dialogue
+- Code snippets (the actual files have the code)
+- Completed work that doesn't affect next steps
+- Research paths that led nowhere
+- Obvious context (project name, basic structure)
+
+## After Writing
+
+Confirm with: "Session saved to Serena memory 'session-state'"
+
+**Note:** For persistent knowledge (decisions, patterns, preferences) that should survive beyond this session, use Vestige via `smart_ingest` — not Serena memory. Serena is for ephemeral session state only.
+
+## Technical Notes
+
+- Uses Serena MCP `write_memory` tool (no file path confusion)
+- Memory persists across Claude sessions in project context
+- Overwrites previous session-state (single checkpoint model)
+- Project-specific storage (appropriate for session state)

package/plugins/ima-claude/skills/scorecard/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: scorecard
+description: "Generate a quick visual scorecard for any project's README. Scores codebase on Code Standards, Security, Test Coverage, Documentation, and Maintainability using a Markdown table with letter grades and color indicators. Use when: user wants a project review with scores, project quality assessment, README badge/scorecard generation, or code health check. Usage: /scorecard [skill1] [skill2] ... where skills are the domain-relevant FP/framework skills to evaluate against (e.g., js-fp js-fp-api, or php-fp php-fp-wordpress)."
+---
+
+# Scorecard — Project Quality Assessment
+
+Generate a compact visual scorecard and insert it into the project README.
+
+## Invocation
+
+```
+/scorecard js-fp js-fp-api
+/scorecard php-fp php-fp-wordpress
+/scorecard js-fp js-fp-vue quasar-fp
+```
+
+Arguments are domain skills to evaluate against. If none provided, auto-detect from project files.
+
+## Process
+
+Use `task-master` to organize all work. Delegate review categories to parallel agents.
+
+### Step 1: Setup
+
+1. Invoke `task-master` skill for orchestration
+2. Invoke each domain skill passed as arguments (these define the code standards to score against)
+3. Identify the project's primary language(s) and framework(s)
+4. Locate the README (or note its absence)
+
+### Step 2: Parallel Review (delegate via task-master)
+
+Spawn parallel agents for each scoring category:
+
+| Category | What to Evaluate | Key Signals |
+|----------|-----------------|-------------|
+| **Code Standards** | FP adherence, naming, patterns, consistency | Pure functions, immutability, composition, no anti-patterns from loaded skills |
+| **Security** | Input validation, injection risks, auth patterns, secrets | OWASP top 10, hardcoded credentials, SQL/XSS/command injection, dependency vulnerabilities |
+| **Test Coverage** | Test existence, quality, edge cases | Test files present, assertions meaningful, critical paths covered |
+| **Documentation** | README quality, inline docs where needed, API docs | Setup instructions, usage examples, architecture notes |
+| **Maintainability** | Complexity, coupling, file organization, dead code | Small functions, clear boundaries, no circular deps, sensible structure |
+
+Each agent should:
+- Use `model: "sonnet"` (Opus orchestrates, Sonnet evaluates)
+- Scan relevant files for its category
+- Return a letter grade (A-F) with 2-3 bullet points justifying the score
+- Be honest — inflated scores help nobody
+
+### Step 3: Compile Scores
+
+Collect agent results into the scorecard table format:
+
+```markdown
+## Scorecard
+
+| Category | Grade | Notes |
+|----------|-------|-------|
+| Code Standards | 🟢 A | Brief justification |
+| Security | 🟡 B | Brief justification |
+| Test Coverage | 🔴 D | Brief justification |
+| Documentation | 🟡 C | Brief justification |
+| Maintainability | 🟢 A | Brief justification |
+
+> Last reviewed: YYYY-MM-DD · Skills: js-fp, js-fp-api
+```
+
+### Grading Scale
+
+**Formatting rules (non-negotiable):**
+- Use **exact emoji characters**: `🟢` `🟡` `🔴` — never GitHub shortcodes (`:green_circle:`), never Unicode geometric shapes (`●`, `◐`, `○`). Shortcodes don't render outside GitHub; geometric shapes are grey in terminals.
+- Use **whole letter grades only**: A, B, C, D, F — no `+` or `-` modifiers. Nuance belongs in the Notes column, not the grade.
+- Format as `🟢 A` (emoji + space + letter) — no backticks around the grade in the README output.
+
+| Grade | Indicator | Meaning |
+|-------|-----------|---------|
+| A | 🟢 A | Excellent — meets or exceeds standards |
+| B | 🟢 B | Good — minor improvements possible |
+| C | 🟡 C | Adequate — notable gaps to address |
+| D | 🔴 D | Poor — significant issues |
+| F | 🔴 F | Failing — critical problems |
+
+### Step 4: Insert into README
+
+- Find the existing `## Scorecard` section and replace it, OR
+- Insert after the first heading (title) if no scorecard section exists
+- Keep the table compact — no lengthy explanations in the README
+- Present the full scorecard to the user before writing, in case they want adjustments
+
+## Guidelines
+
+- **Honest scores only.** A scorecard that says everything is an A is useless.
+- **Notes are terse.** Each note is 5-10 words max. The scorecard is a glance, not a report.
+- **Domain skills define "Code Standards."** The loaded FP/framework skills set the bar for what good looks like.
+- **Security is always evaluated** regardless of which domain skills are passed.
+- **Auto-detect when no skills given.** Scan for package.json (JS), composer.json (PHP), etc. and suggest appropriate skills.
+- **Date stamp every scorecard** so readers know how fresh it is.

package/plugins/ima-claude/skills/skill-analyzer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: skill-analyzer
+description: Analyzes Skills against best practices and provides actionable improvement recommendations. Use when reviewing, auditing, or improving existing Skills (.skill files or skill directories), when validating Skills before distribution, or when the user asks for feedback on a skill they're developing.
+---
+
+# Skill Analyzer
+
+Evaluate Skills against documented best practices and provide actionable feedback.
+
+## Quick Start
+
+1. Run automated validation:
+   ```bash
+   python scripts/analyze_skill.py /path/to/skill-directory
+   ```
+
+2. Review the analysis report for issues and recommendations
+
+3. For manual deep-dive, follow the Analysis Workflow below
+
+## Analysis Workflow
+
+### Phase 1: Structural Validation
+
+Check YAML frontmatter requirements:
+- `name`: Present, ≤64 chars, lowercase letters/numbers/hyphens only, no reserved words (anthropic, claude)
+- `description`: Present, non-empty, ≤1024 chars, no XML tags
+
+Check file organization:
+- SKILL.md exists at root
+- Body ≤500 lines (optimal context efficiency)
+- References are one level deep from SKILL.md (no nested chains)
+
+### Phase 2: Description Quality
+
+**Good descriptions include:**
+- What the skill does
+- When/triggers for using it
+- Key terms users might mention
+
+**Red flags:**
+- Vague: "helps with documents", "processes data"
+- First/second person: "I can help you...", "You can use this to..."
+- Missing trigger contexts
+
+**Example transformation:**
+```
+Bad:  "Helps with PDFs"
+Good: "Extracts text and tables from PDF files, fills forms, merges documents. 
+       Use when working with PDF files or when the user mentions PDFs, forms, 
+       or document extraction."
+```
+
+### Phase 3: Content Efficiency
+
+**Check for over-explanation:**
+- Does the skill explain concepts Claude already knows?
+- Are there verbose paragraphs that could be concise code examples?
+- Token cost vs. value delivered?
+
+**Conciseness test:** For each section ask:
+1. "Does Claude really need this?"
+2. "Can I assume Claude knows this?"
+3. "Does this justify its token cost?"
+
+### Phase 4: Progressive Disclosure
+
+**Verify proper layering:**
+1. Metadata (name + description) - triggers skill selection
+2. SKILL.md body - core instructions loaded on trigger
+3. Reference files - loaded only when needed
+
+**Check reference patterns:**
+- Large content (>100 lines) split into separate files
+- Reference files have table of contents if >100 lines
+- Domain-specific content organized by domain
+- Clear pointers in SKILL.md to when each reference should be read
+
+### Phase 5: Workflow Quality
+
+For skills with multi-step processes:
+- Steps are clear and sequential
+- Decision points have conditional guidance
+- Feedback loops exist for quality-critical operations
+- Validation steps precede irreversible actions
+
+### Phase 6: Anti-Pattern Detection
+
+Check for these common issues:
+
+| Anti-Pattern | Detection | Fix |
+|--------------|-----------|-----|
+| Too many options | Multiple equivalent approaches offered | Provide one default + escape hatch |
+| Windows paths | Backslashes in file paths | Use forward slashes everywhere |
+| Time-sensitive info | Dates, "before/after X" conditionals | Use "old patterns" section or remove |
+| Inconsistent terminology | Same concept, multiple terms | Choose one term throughout |
+| Deeply nested refs | File A → File B → File C | Flatten to one level from SKILL.md |
+| Voodoo constants | Unexplained magic numbers in scripts | Document why each value was chosen |
+| Excessive files | README, CHANGELOG, QUICK_REFERENCE | Only SKILL.md + essential resources |
+
+## Output Report Format
+
+After analysis, produce a structured report:
+
+```markdown
+# Skill Analysis: [skill-name]
+
+## Summary
+- Overall assessment: [Pass/Needs Work/Major Issues]
+- Lines: X (target: <500)
+- Description quality: [Good/Needs Work]
+
+## Critical Issues
+[Issues that must be fixed]
+
+## Recommendations
+[Improvements that would help but aren't blocking]
+
+## Strengths
+[What the skill does well]
+```
+
+## Detailed Checklists
+
+For comprehensive evaluation criteria, see:
+- [references/core-checklist.md](references/core-checklist.md) - Essential quality checks
+- [references/advanced-checklist.md](references/advanced-checklist.md) - For skills with scripts/code

package/plugins/ima-claude/skills/skill-analyzer/references/advanced-checklist.md

@@ -0,0 +1,44 @@
+# Advanced Checklist (Skills with Scripts)
+
+Use in addition to core-checklist.md when analyzing Skills that include executable code.
+
+## Script Quality
+
+- [ ] Scripts solve problems rather than punt to Claude
+- [ ] Error handling is explicit and helpful
+- [ ] No "voodoo constants" (all values justified and documented)
+- [ ] Scripts are self-documenting with clear comments
+- [ ] Clear distinction between "execute" vs "read as reference"
+
+## Dependencies
+
+- [ ] Required packages listed in instructions
+- [ ] Packages verified as available in target environment
+- [ ] Version constraints specified where necessary
+- [ ] Installation commands provided
+
+## Verification & Feedback Loops
+
+- [ ] Validation steps for critical operations
+- [ ] Feedback loops for quality-critical tasks
+- [ ] Intermediate outputs are machine-verifiable
+- [ ] Error messages are specific and actionable
+
+## File Path Conventions
+
+- [ ] All paths use forward slashes (Unix-style)
+- [ ] Relative paths used where possible
+- [ ] Path references are correct and exist
+
+## Script Documentation
+
+- [ ] Clear usage examples in SKILL.md
+- [ ] Expected input/output documented
+- [ ] Error conditions documented
+- [ ] Return codes/exit statuses explained where relevant
+
+## MCP Tool References (if applicable)
+
+- [ ] Fully qualified tool names used (ServerName:tool_name)
+- [ ] Server names match available MCP servers
+- [ ] Tool capabilities accurately described