ima-claude 2.20.0 → 2.25.0

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

@@ -5,224 +5,115 @@ description: "Decomposition and planning sub-skill. Breaks work into Epic > Stor
 
 # Task Planner - Structured Work Breakdown
 
-**"Slow is smooth, smooth is fast."**
+Plan before implementing. Every hour of planning prevents rework.
 
-Complex work fails when we dive in without structure. This skill provides a systematic approach to breaking down work and choosing the right storage.
+## Work Hierarchy
 
-## 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
+Epic (large goal, multi-session)
+├── Story (deliverable outcome with value)
+│   ├── Task (single actionable step, <2 hours)
 │   └── 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")
+If a task exceeds 2 hours or requires context switches, break it down further.
 
-**Rule:** If a task takes more than 2 hours or requires context switches, break it down further.
-
-## Storage Strategy Decision Tree
+## Storage Decision Tree
 
 ```
-Is Serena MCP available?
-├── Yes → Does this need to persist across sessions?
+Serena MCP available?
+├── Yes → Needs cross-session persistence?
 │         ├── 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  → Needs cross-session persistence?
+          ├── Yes → Markdown file (docs/PLANNING.md)
           └── 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 |
+| Storage | Survives | Use Case |
+|---------|----------|----------|
+| **Serena Memory** | Sessions | Milestones, decisions, project state |
+| **Claude Task List** | Compacts | In-session tracking, current work items |
+| **Markdown File** | Forever | No Serena, need persistence or team visibility |
 
-### Serena Memory Pattern
-
-For cross-session persistence of project state:
+## Storage Patterns
 
+**Serena Memory:**
 ```
-# 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
-
+    - [x] Phase 1: 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):
-
+**Claude Task List:**
 ```
-# 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 fallback** (use `docs-organize` skill for file placement):
 ```markdown
-<!-- docs/PLANNING.md -->
-# Project Planning
-
 ## Epic: User Authentication System
 
-### Story: Email/Password Login
-**Status:** In Progress
-
+### Story: Email/Password Login — 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
-```
+## Breakdown Process
 
-### Step 4: Estimate and Sequence
+1. **Define Epic** — one sentence end state
+2. **Identify Stories** — deliverable outcomes composing the epic
+3. **Decompose Tasks** — specific steps per story, each <2 hours
+4. **Sequence** — mark dependencies, estimate effort
+5. **Store** — use decision tree above, then execute
 
-Mark dependencies and rough effort:
+**Example sequencing:**
 ```
 1. [15m] Create users table ─┐
-2. [30m] Password hashing   ─┼─→ 3. [45m] Login endpoint ─→ 5. [30m] Connect form
-4. [30m] Login form component ─────────────────────────────┘
+2. [30m] Password hashing   ─┼─→ 3. [45m] Login endpoint → 5. [30m] Connect form
+4. [30m] Login form ─────────┘
 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
+## Red Flags — Stop and Restructure
 
-**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
+- "Task" has 3+ subtasks → it's a Story
+- Agents nesting 3+ levels → flatten
+- Subagent needs "full context" → task too broad
+- Task estimate >2 hours → break down further
+- Dependencies form cycles → rethink approach
 
-### Anti-Patterns (Planning)
+## Anti-Patterns
 
-| 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 |
+| Anti-Pattern | Solution |
+|--------------|----------|
+| "I'll figure it out as I go" | Plan first, even 5 minutes |
+| "This task is simple enough" | Still write it down |
+| "I'll remember the plan" | Use TaskList or Serena |
 
-**REQUIRED SUB-SKILL:** After decomposition is complete, use `task-runner` to delegate tasks to agents.
+**REQUIRED:** After decomposition, use `task-runner` to delegate to agents.

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

@@ -5,188 +5,106 @@ description: "Agent delegation and execution sub-skill. Selects models (opus/son
 
 # Task Runner - Agent Delegation & Execution
 
-**You are the Orchestrator. You coordinate. Agents implement.**
+You are the Orchestrator. Agents implement. Max nesting: 2 levels deep.
 
-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.
+## Named Agents (Prefer over generic)
 
 ```
 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:tester", ...)          # Test writing/running (sonnet + test skills)
 Agent(agent_type="ima-claude:wp-developer", ...)    # WordPress specialist (sonnet + WP skills)
+Agent(agent_type="ima-claude:memory", ...)          # Memory ops (Vestige/Qdrant/Serena)
 ```
 
-**Agent selection tree:**
-
+**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)
+├── Find files, explore code?            → ima-claude:explorer (haiku, read-only, cheap)
+├── Implement, fix, refactor?            → ima-claude:implementer (sonnet, FP-aware)
+├── WordPress (plugin/theme/WP-CLI)?     → ima-claude:wp-developer (sonnet, full WP bundle)
+├── Review code quality/security?        → ima-claude:reviewer (sonnet, read-only)
+├── Write/run tests, TDD?               → ima-claude:tester (sonnet)
+├── Memory search/store/consolidate?     → ima-claude:memory (sonnet)
+├── Custom tool/skill combo?             → generic agent with explicit model
+└── 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)
+| **explorer** | haiku | read-only | File discovery, architecture, code search |
+| **implementer** | sonnet | full | Feature dev, bug fixes, refactoring |
+| **reviewer** | sonnet | read-only | Code review, security, FP compliance |
+| **tester** | sonnet | full | Test creation, TDD, debugging failures |
+| **wp-developer** | sonnet | full | WordPress plugins, themes, WP-CLI |
+| **memory** | sonnet | full | Vestige/Qdrant/Serena memory ops |
 
-For tasks that don't fit a named agent, fall back to generic agents with explicit model selection.
+## Model Selection (Generic Agents)
 
-**Opus orchestrates. Sonnet executes. Haiku handles the trivial.**
+Opus orchestrates. Sonnet executes. Haiku handles 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 |
+| Model | Use For |
+|-------|---------|
+| **haiku** | File searches, quick lookups, simple reads |
+| **sonnet** | Most delegated work: implementation, research, testing |
+| **opus** | Orchestration, complex reasoning, ambiguous trade-offs |
 
-**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
 
-### Minimal Context Principle
-
-**Give subagents only what they need: task in, result out.**
+Give subagents only what they need.
 
 ```
-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."
+Bad:  Full project history + all decisions + "also add a button"
+Good: "Add submit button to /src/components/LoginForm.vue calling onSubmit prop. Return 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
+80% of subagent tasks are fully isolated: specific task + specific file(s) + expected output. No project history, no architectural decisions, no other tasks.
 
-They don't get:
-- Project history
-- Architectural decisions
-- Other tasks
-- Your reasoning process
+## Decomposition Patterns
 
-### Vertical vs Horizontal Decomposition
-
-**Vertical (Sequential):** When steps depend on each other.
+**Vertical (sequential):** Steps depend on each other → execute in order.
 ```
-Step 1: Create database schema
-    ↓
-Step 2: Implement data access layer
-    ↓
-Step 3: Build API endpoints
-    ↓
-Step 4: Create UI components
+Schema → Data layer → API endpoints → UI components
 ```
-*Execute in order. Each step needs the previous step's output.*
 
-**Horizontal (Parallel):** When steps are independent.
+**Horizontal (parallel):** Independent steps → execute concurrently.
 ```
-┌─────────────────────────────────────────┐
-│ Main Claude (coordinator)                │
-├──────────┬──────────┬──────────┬────────┤
-│ Agent A  │ Agent B  │ Agent C  │ Agent D│
-│ Login UI │ Auth API │ DB Setup │ Tests  │
-└──────────┴──────────┴──────────┴────────┘
+Main Claude → [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.
+## Delegation Checklist
 
-**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.
+Before delegating, verify:
+1. **Bounded?** Task describable in 2-3 sentences with clear success criteria
+2. **No shared state?** Agent won't conflict with other agents' files
+3. **Minimal context?** Agent succeeds with task + 1-2 files max
+4. **Failure safe?** Can retry or fix without cascading
+5. **Escalation-aware?** Expect three return shapes — success, failure, **ESCALATION**. Don't treat escalation as failure.
 
-**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.
+## Handling ESCALATION returns (advisor pattern)
 
-**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.
+Executor agents return `ESCALATION: <trigger>` when they hit out-of-scope forks (scope drift, architectural fork, security-sensitive changes, repeated failure, ambiguous requirements). This is the designed-in advisor channel — parent (Opus) is the advisor.
 
-### Anti-Patterns (Delegation)
+When an agent returns ESCALATION:
 
-| 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 |
+1. Read the structured report — `Did`, `Blocked on`, `Options`, `Recommendation`, `Files touched`
+2. Decide — continue as planned, narrow the task, expand the scope, abandon, or ask the human (AskUserQuestion)
+3. Re-dispatch with explicit guidance — do NOT just retry the same prompt. Add the decision to the new task.
 
-## Integration Points
+Cost shape: Sonnet ran cheap, stopped early, returned a focused question. Opus answers the question. Sonnet resumes with clarity. This is cheaper than letting Sonnet guess wrong and rework.
 
-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
+**Do NOT:**
+- Tell agents to "just figure it out" — that defeats the escalation channel
+- Treat ESCALATION as retryable failure — it's a request for arbitration, not a crash
+- Re-dispatch without adding the resolution — agent will escalate the same thing again
 
-**REQUIRED SUB-SKILL:** If work hasn't been decomposed yet, use `task-planner` first.
+## Anti-Patterns
 
-## The Final Word
+| Anti-Pattern | Solution |
+|--------------|----------|
+| "Agent needs everything" | Minimal context — task + files only |
+| "3+ levels of agents" | Max 2 levels — restructure the work |
+| "Every agent needs Opus" | Sonnet for most; Opus orchestrates only |
 
-*"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."*
+**REQUIRED:** If work isn't decomposed yet, use `task-planner` first.