ima-claude 2.9.0

package/plugins/ima-claude/skills/task-planner/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: "task-planner"
+description: "Decomposition and planning sub-skill. Breaks work into Epic > Story > Task hierarchy, selects storage strategy (Serena/TaskList/Markdown), and creates structured task lists. Use when work needs to be planned and broken down before execution."
+---
+
+# Task Planner - Structured Work Breakdown
+
+**"Slow is smooth, smooth is fast."**
+
+Complex work fails when we dive in without structure. This skill provides a systematic approach to breaking down work and choosing the right storage.
+
+## Core Philosophy
+
+### The Planning Imperative
+
+**Think before acting. Plan before implementing.**
+
+Every hour of planning saves 10 hours of rework. The urge to "just start coding" is the enemy of clean architecture and maintainable systems.
+
+```
+Unplanned work → Rework → Technical debt → More rework
+Planned work   → Clean implementation → Iteration → Progress
+```
+
+### The Hierarchy of Work
+
+```
+Epic (Big Goal)
+├── Story (Deliverable Outcome)
+│   ├── Task (Actionable Step)
+│   ├── Task
+│   └── Task
+├── Story
+│   ├── Task
+│   └── Task
+└── Story
+    └── Task
+```
+
+**Definitions:**
+- **Epic**: A large goal spanning multiple sessions (e.g., "Implement user authentication system")
+- **Story**: A coherent deliverable that provides value (e.g., "Users can log in with email/password")
+- **Task**: A single actionable step, completable in one session (e.g., "Create login form component")
+
+**Rule:** If a task takes more than 2 hours or requires context switches, break it down further.
+
+## Storage Strategy Decision Tree
+
+```
+Is Serena MCP available?
+├── Yes → Does this need to persist across sessions?
+│         ├── Yes → Serena Memory (write_memory/read_memory)
+│         └── No  → Claude Task List (TaskCreate/TaskUpdate)
+│
+└── No  → Does this need to persist across sessions?
+          ├── Yes → Markdown file (docs/PLANNING.md or similar)
+          └── No  → Claude Task List (survives compacts)
+```
+
+### When to Use Each
+
+| Storage | Use Case | Survives | Example |
+|---------|----------|----------|---------|
+| **Serena Memory** | Big-picture milestones, decisions, project state | Sessions | "Phase 1 complete, moving to Phase 2" |
+| **Claude Task List** | In-session tracking, current work items | Compacts | "[ ] Implement validation [ ] Add tests" |
+| **Markdown File** | No Serena, need persistence, team visibility | Forever | `docs/PLANNING.md` with full breakdown |
+
+### Serena Memory Pattern
+
+For cross-session persistence of project state:
+
+```
+# Save project state
+mcp__serena__write_memory
+  memory_file_name: "planning-{project-name}"
+  content: |
+    # Project: {name}
+    ## Current Phase: 2 - Core Implementation
+
+    ## Completed
+    - [x] Phase 1: Project setup and architecture
+
+    ## In Progress
+    - [ ] Story: User authentication
+      - [x] Task: Database schema
+      - [ ] Task: Login endpoint
+      - [ ] Task: Session management
+
+    ## Upcoming
+    - Phase 3: Testing and polish
+
+# Resume later
+mcp__serena__read_memory
+  memory_file_name: "planning-{project-name}"
+```
+
+### Claude Task List Pattern
+
+For in-session work tracking (survives context compaction):
+
+```
+# Create tasks for current work
+TaskCreate
+  description: "Implement login form validation"
+  status: "in_progress"
+  priority: "high"
+
+TaskCreate
+  description: "Add unit tests for auth service"
+  status: "pending"
+  priority: "medium"
+
+# Update as you work
+TaskUpdate
+  id: {task-id}
+  status: "completed"
+
+# Check status
+TaskList
+```
+
+### Markdown Fallback Pattern
+
+**Note:** When using Markdown, use the `docs-organize` Skill for proper file/folder structure
+
+When Serena isn't available but you need persistence:
+
+```markdown
+<!-- docs/PLANNING.md -->
+# Project Planning
+
+## Epic: User Authentication System
+
+### Story: Email/Password Login
+**Status:** In Progress
+
+- [x] Task: Create users table migration
+- [x] Task: Implement password hashing utility
+- [ ] Task: Create login endpoint
+- [ ] Task: Add session management
+- [ ] Task: Write integration tests
+
+### Story: Password Reset Flow
+**Status:** Not Started
+
+- [ ] Task: Create password reset tokens table
+- [ ] Task: Implement reset email sender
+- [ ] Task: Create reset confirmation endpoint
+```
+
+## The Breakdown Process
+
+### Step 1: Define the Epic
+
+Start with the end state:
+```
+"Users can authenticate via email/password, reset forgotten passwords,
+and stay logged in across browser sessions."
+```
+
+### Step 2: Identify Stories
+
+What deliverable outcomes compose the epic?
+```
+1. Users can log in with email/password
+2. Users can register new accounts
+3. Users can reset forgotten passwords
+4. Sessions persist across browser restarts
+```
+
+### Step 3: Decompose into Tasks
+
+For each story, what specific steps are needed?
+```
+Story: Users can log in with email/password
+├── Create users table with email, password_hash columns
+├── Implement password hashing utility (use bcrypt)
+├── Create POST /api/auth/login endpoint
+├── Add login form component
+├── Connect form to API
+└── Add error handling for invalid credentials
+```
+
+### Step 4: Estimate and Sequence
+
+Mark dependencies and rough effort:
+```
+1. [15m] Create users table ─┐
+2. [30m] Password hashing   ─┼─→ 3. [45m] Login endpoint ─→ 5. [30m] Connect form
+4. [30m] Login form component ─────────────────────────────┘
+6. [30m] Error handling (after 5)
+```
+
+### Step 5: Choose Storage and Execute
+
+Based on the decision tree above, store appropriately and begin work.
+
+## Quick Reference
+
+### Breakdown Checklist
+
+Before starting any significant work:
+
+- [ ] Can I describe the goal in one sentence?
+- [ ] Have I identified all major deliverables (stories)?
+- [ ] Is each task completable in under 2 hours?
+- [ ] Do I know the dependencies between tasks?
+- [ ] Have I chosen appropriate storage (Serena/TaskList/Markdown)?
+- [ ] If delegating, does each subagent have minimal, clear context?
+
+### Red Flags
+
+**Stop and restructure if:**
+- A "task" has more than 3 subtasks → It's actually a story
+- You're nesting agents 3+ levels deep → Flatten the structure
+- Subagent needs "full context" → Task is too broad
+- Task estimate exceeds 2 hours → Break down further
+- Dependencies form cycles → Rethink the approach
+
+### Anti-Patterns (Planning)
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| "I'll figure it out as I go" | Rework, tangents, debt | Plan first, even 5 minutes |
+| "This task is simple enough" | Scope creep | Still write it down |
+| "I'll remember the plan" | Context loss after compact | Use TaskList or Serena |
+
+**REQUIRED SUB-SKILL:** After decomposition is complete, use `task-runner` to delegate tasks to agents.

package/plugins/ima-claude/skills/task-runner/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: "task-runner"
+description: "Agent delegation and execution sub-skill. Selects models (opus/sonnet/haiku), assigns skills, and delegates tasks to subagents via the Task tool. Use after work has been decomposed by task-planner."
+---
+
+# Task Runner - Agent Delegation & Execution
+
+**You are the Orchestrator. You coordinate. Agents implement.**
+
+This skill handles the execution phase: delegating decomposed tasks to subagents with the right model, minimal context, and relevant skills.
+
+## Agent Delegation Patterns
+
+### The Two-Level Rule
+
+**Maximum nesting: 2 levels deep.**
+
+```
+Main Claude
+├── Subagent A (specific task)
+└── Subagent B (specific task)
+```
+
+Deeper hierarchies create:
+- Debugging nightmares
+- Context loss
+- Coordination overhead
+- Exponential complexity
+
+**If you think you need 3+ levels, restructure the work instead.**
+
+### Named Agents (Preferred)
+
+**Delegate to named agents when one fits. Fall back to generic agents for edge cases.**
+
+The plugin provides purpose-built agents with enforced constraints (model, tools, permissions, skills). Use them instead of manually configuring generic agents.
+
+```
+Agent(agent_type="ima-claude:explorer", ...)       # Read-only codebase exploration (haiku)
+Agent(agent_type="ima-claude:implementer", ...)     # Standard implementation (sonnet + FP skills)
+Agent(agent_type="ima-claude:reviewer", ...)        # Code quality review (sonnet, read-only)
+Agent(agent_type="ima-claude:wp-developer", ...)    # WordPress specialist (sonnet + WP skills)
+```
+
+**Agent selection tree:**
+
+```
+What does the subtask need?
+├── Find files, understand structure, explore code?
+│   → ima-claude:explorer (haiku, read-only, cheap/fast)
+├── Implement a feature, fix a bug, write code?
+│   → ima-claude:implementer (sonnet, FP-aware)
+├── WordPress-specific work (plugin, theme, WP-CLI, forms)?
+│   → ima-claude:wp-developer (sonnet, full WP skill bundle)
+├── Review code quality, check for bugs/security?
+│   → ima-claude:reviewer (sonnet, read-only)
+├── Write tests, run test suites, TDD, debug test failures?
+│   → ima-claude:tester (sonnet, test orchestration + FP)
+├── Memory operations (search, store, consolidate)?
+│   → ima-claude:memory (sonnet, Vestige/Qdrant/Serena)
+├── Needs a custom tool/skill combination?
+│   → general-purpose with explicit model parameter
+└── Uncertain?
+    → ima-claude:implementer (safe default)
+```
+
+| Agent | Model | Mode | Use For |
+|-------|-------|------|---------|
+| **explorer** | haiku | read-only | File discovery, architecture understanding, code search |
+| **implementer** | sonnet | full access | Feature dev, bug fixes, refactoring, tests |
+| **reviewer** | sonnet | read-only | Code review, security audit, FP compliance |
+| **tester** | sonnet | full access | Test creation, test running, TDD, debugging failures |
+| **wp-developer** | sonnet | full access | WordPress plugins, themes, WP-CLI, forms, Bootstrap |
+| **memory** | sonnet | full access | Memory search, storage, consolidation (Vestige/Qdrant/Serena) |
+
+### Model Selection (Generic Agents)
+
+For tasks that don't fit a named agent, fall back to generic agents with explicit model selection.
+
+**Opus orchestrates. Sonnet executes. Haiku handles the trivial.**
+
+| Model | Cost | Use For |
+|-------|------|---------|
+| **haiku** | Lowest | File searches, quick lookups, simple reads |
+| **sonnet** | Medium | Most delegated work: implementation, research, testing, formatting |
+| **opus** | Highest | Orchestration (main agent), complex reasoning, architecture decisions |
+
+**Rule of thumb:** If you can describe the task in 2-3 sentences with clear success criteria,
+Sonnet can handle it. If the agent needs to make judgment calls about ambiguous trade-offs,
+consider Opus.
+
+### Minimal Context Principle
+
+**Give subagents only what they need: task in, result out.**
+
+```
+Bad:  "Here's the full project context, all decisions we've made,
+       the entire codebase history, and now please also add a button."
+
+Good: "Add a submit button to /src/components/LoginForm.vue that
+       calls the onSubmit prop. Return the updated file."
+```
+
+**The 80% Rule:** 80% of subagent tasks should be completely isolated. They get:
+- The specific task
+- The specific file(s) to modify
+- The expected output format
+
+They don't get:
+- Project history
+- Architectural decisions
+- Other tasks
+- Your reasoning process
+
+### Vertical vs Horizontal Decomposition
+
+**Vertical (Sequential):** When steps depend on each other.
+```
+Step 1: Create database schema
+    ↓
+Step 2: Implement data access layer
+    ↓
+Step 3: Build API endpoints
+    ↓
+Step 4: Create UI components
+```
+*Execute in order. Each step needs the previous step's output.*
+
+**Horizontal (Parallel):** When steps are independent.
+```
+┌─────────────────────────────────────────┐
+│ Main Claude (coordinator)                │
+├──────────┬──────────┬──────────┬────────┤
+│ Agent A  │ Agent B  │ Agent C  │ Agent D│
+│ Login UI │ Auth API │ DB Setup │ Tests  │
+└──────────┴──────────┴──────────┴────────┘
+```
+*Execute in parallel when tasks don't share state or dependencies.*
+
+### Delegation Decision Framework
+
+Before delegating to a subagent, ask:
+
+**1. Is the task clearly bounded?**
+- Can you describe the input and expected output in 2-3 sentences?
+- Are the success criteria unambiguous?
+- No? → Break it down further before delegating.
+
+**2. Does it require shared state?**
+- Does the agent need to modify files another agent is touching?
+- Does it need context from other ongoing work?
+- Yes? → Don't parallelize. Do sequentially or yourself.
+
+**3. Is the context minimal?**
+- Can the agent succeed with just the task description?
+- Do they need more than 1-2 files for context?
+- No? → Simplify the task or provide only essential context.
+
+**4. What's the failure mode?**
+- If the subagent fails, can you retry or fix easily?
+- Does failure cascade to other work?
+- High risk? → Do it yourself or add verification.
+
+**5. What model does this need?**
+- Is the task well-scoped with clear criteria? → `model: "sonnet"`
+- Is it a quick file search or lookup? → `model: "haiku"`
+- Does it require complex reasoning or ambiguous trade-offs? → `model: "opus"`
+- Default to Sonnet. Opus orchestrates, Sonnet executes.
+
+### Anti-Patterns (Delegation)
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| "The agent needs everything" | Context overload, errors | Minimal context principle |
+| "Just one more level of agents" | Debugging nightmare | Max 2 levels, restructure |
+| "Every agent needs Opus" | Wastes expensive tokens | Sonnet for most tasks, Opus for orchestration |
+
+## Integration Points
+
+This skill works with:
+- **Named agents** - `ima-claude:explorer`, `ima-claude:implementer`, `ima-claude:reviewer`, `ima-claude:tester`, `ima-claude:wp-developer` — preferred delegation targets
+- **task-planner** - For decomposition before delegation
+- **mcp-serena** - For persistent memory across sessions
+- **mcp-vestige** - For cross-project decisions, patterns, and intentions
+- **architect** - For evaluating architectural choices during planning
+- **save-session / resume-session** - For session state management
+
+**REQUIRED SUB-SKILL:** If work hasn't been decomposed yet, use `task-planner` first.
+
+## The Final Word
+
+*"The goal isn't to create perfect plans. It's to think through the work before doing it. A 10-minute planning session that gets revised three times is infinitely better than diving in blind. Master small chunks, then combine. The whole becomes greater than the sum of its parts."*

package/plugins/ima-claude/skills/unit-testing/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: "unit-testing"
+description: "Test workflow orchestration — decision tree routing to domain skills (phpunit-wp, playwright, js-fp, php-fp). TDD, test strategy, mock decisions, quality checklists. Triggers on: unit test, write tests, TDD, test coverage, mock, test strategy."
+---
+
+# Unit Testing - Orchestration Skill
+
+**"Test pure core, not impure shell. FP makes testing easy."**
+
+This skill orchestrates test workflows by routing to the right domain skills. It does NOT duplicate domain-specific testing patterns — it coordinates them.
+
+## Core Philosophy
+
+Pure functions are trivially testable. If something is hard to test, the problem is the code design, not the test setup.
+
+1. **Extract pure logic** — separate decisions from effects
+2. **Test behavior, not implementation** — what it does, not how
+3. **Bottom-heavy pyramid** — many unit tests, few integration, fewer E2E
+4. **Minimal mocking** — mock boundaries (DB, network, filesystem), not your own code
+
+## Decision Tree: Which Skills to Use
+
+```
+What are you testing?
+├── WordPress PHP plugin/theme?
+│   → phpunit-wp (primary) + php-fp + php-fp-wordpress
+│   → References: php-fp/references/testing-patterns.md
+│                  php-fp-wordpress/references/testing-strategy.md
+│
+├── General PHP (non-WordPress)?
+│   → php-fp (primary)
+│   → References: php-fp/references/testing-patterns.md
+│
+├── JavaScript/TypeScript?
+│   ├── React components?
+│   │   → js-fp-react + js-fp
+│   ├── Vue components?
+│   │   → js-fp-vue + js-fp
+│   │   → References: js-fp-vue/references/testing.md
+│   └── General JS/TS?
+│       → js-fp (primary)
+│       → References: js-fp/references/testing-patterns.md
+│
+├── End-to-end / browser tests?
+│   → playwright (primary)
+│
+└── Unknown / mixed?
+    → Start with functional-programmer principles
+    → Route to domain skill once context is clear
+```
+
+**Always apply:** `functional-programmer` principles (pure functions, composition, immutability).
+
+## Workflow: Adding Tests to Existing Code
+
+### Step 1: Analyze
+
+- Read the code under test
+- Identify pure functions vs impure boundaries
+- Map dependencies: what does this code touch? (DB, filesystem, network, global state)
+
+### Step 2: Classify
+
+| Code Type | Test Type | Speed | Mocking |
+|-----------|-----------|-------|---------|
+| Pure function (no side effects) | Unit test | Fast (<10ms) | None |
+| Function with injected deps | Unit test | Fast | Stub the deps |
+| WordPress hook/filter callback | Unit or integration | Medium | Mock WP functions |
+| API endpoint handler | Integration test | Medium | Mock external services |
+| Full user workflow | E2E test | Slow | None (real browser) |
+
+### Step 3: Structure
+
+Follow project conventions for test file location:
+- PHP: `tests/Unit/`, `tests/Integration/` (mirror `src/` structure)
+- JS/TS: colocated `*.test.ts` or `__tests__/` directory
+- E2E: `tests/e2e/` or `e2e/`
+
+### Step 4: Write
+
+Apply the domain skill's patterns. General principles:
+
+```
+Arrange → Act → Assert (one behavior per test)
+```
+
+- **Test name = behavior description**: `it('returns empty array when no items match filter')`
+- **One assertion per concept** (multiple `expect` calls are fine if they verify one behavior)
+- **No logic in tests**: no conditionals, no loops, no try/catch
+- **Test data is minimal**: only include fields relevant to the behavior under test
+
+### Step 5: Verify
+
+- Run the test suite: `composer test`, `npm test`, `npx vitest`, etc.
+- All tests pass (green)
+- No skipped or pending tests without a documented reason
+- Coverage meets project floor (if configured)
+
+## Workflow: TDD (Test-Driven Development)
+
+### Red-Green-Refactor
+
+```
+1. RED    — Write a failing test for the next behavior
+2. GREEN  — Write the minimum code to make it pass
+3. REFACTOR — Clean up while keeping tests green
+```
+
+### TDD with Pure Functions (Ideal Case)
+
+Pure functions + TDD = fast feedback loops. No setup, no teardown, no mocking.
+
+```
+Test: add(2, 3) === 5
+Code: const add = (a, b) => a + b
+Done.
+```
+
+### TDD for Impure Boundaries
+
+When TDD hits an impure boundary (DB, network, filesystem):
+
+1. **Define the interface** — what does the boundary need to provide?
+2. **Stub the boundary** — test against the interface, not the implementation
+3. **Wire up later** — connect the real implementation after the pure logic is tested
+
+### When TDD Slows You Down
+
+TDD is a tool, not a religion. Skip it when:
+- Exploring/prototyping (you'll throw the code away)
+- The implementation is trivial and obvious
+- You're writing glue code with no logic
+
+See `references/tdd-workflow.md` for detailed mechanics.
+
+## Mock Decision Tree
+
+```
+Is the dependency hard to test?
+├── No (pure function, simple data) → Don't mock. Test directly.
+├── Yes, but I own the code
+│   ├── Can I extract pure logic? → Extract it. Test the pure part.
+│   └── Can I inject the dependency? → Inject it. Pass a stub.
+└── Yes, external service (DB, API, filesystem, time)
+    → Mock it. Use the simplest mock type that works.
+```
+
+### Mock Types (Simplest First)
+
+| Type | What it does | When to use |
+|------|-------------|-------------|
+| **Stub** | Returns canned data | Most cases. Default choice. |
+| **Spy** | Records calls for verification | When you need to verify a call was made |
+| **Fake** | Working simplified implementation | Complex interfaces (in-memory DB) |
+| **Full mock** | Strict expectations on calls | Almost never. Couples tests to implementation. |
+
+See `references/mock-patterns.md` for language-specific examples and anti-patterns.
+
+## Test Quality Checklist
+
+Before considering tests "done":
+
+- [ ] Tests verify behavior, not implementation
+- [ ] Each test has a descriptive name explaining the scenario
+- [ ] No test depends on another test's state (isolation)
+- [ ] No flaky signals: no timers, no real network, no filesystem in unit tests
+- [ ] Pure functions tested without mocking
+- [ ] Mocks used only at impure boundaries
+- [ ] Edge cases covered: empty input, null/undefined, boundary values
+- [ ] Error paths tested (not just happy path)
+- [ ] Test runs fast (unit suite < 10s for most projects)
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Testing implementation details | Breaks on refactor | Test behavior/output instead |
+| Mocking everything | Tests prove nothing | Extract pure logic, mock only boundaries |
+| Giant test setup | Hard to understand | Simplify code under test or use factories |
+| Copy-paste test bodies | Maintenance nightmare | Use parameterized/table-driven tests |
+| Testing framework behavior | Wastes time | Trust the framework |
+| 100% coverage target | Diminishing returns | Set a floor, not a ceiling |
+| `sleep()` in tests | Flaky, slow | Use deterministic waits or fix the design |
+
+## Integration: Domain Skill Reference
+
+| Context | Primary Skill | Reference Files |
+|---------|--------------|-----------------|
+| WordPress PHP | `phpunit-wp` | `php-fp/references/testing-patterns.md`, `php-fp-wordpress/references/testing-strategy.md` |
+| General PHP | `php-fp` | `php-fp/references/testing-patterns.md` |
+| JavaScript/TypeScript | `js-fp` | `js-fp/references/testing-patterns.md` |
+| Vue.js | `js-fp-vue` | `js-fp-vue/references/testing.md` |
+| React | `js-fp-react` | `js-fp/references/testing-patterns.md` |
+| E2E / Browser | `playwright` | (self-contained skill) |
+
+## The Final Word
+
+*"If it's hard to test, it's hard to use. Testability is a design signal, not a chore. Extract the pure, inject the impure, and the tests write themselves."*