ima-claude 2.9.0

package/platforms/shared/installer.ts

@@ -0,0 +1,202 @@
+import { join } from "path";
+import type { PlatformAdapter, InstallFilter, InstallItem, InstallOptions } from "./types";
+import { PLUGIN_SOURCE } from "./types";
+import { colors, log, prompt, promptYesNo } from "../../scripts/utils";
+
+function formatItemList(items: InstallItem[], category: string): string {
+  const filtered = items.filter((i) => i.category === category);
+  if (filtered.length === 0) return "";
+
+  const overrideCount = filtered.filter((i) => i.exists).length;
+  const overrideNote = overrideCount > 0
+    ? ` ${colors.yellow}(${overrideCount} existing will be overwritten)${colors.reset}`
+    : "";
+
+  const names = filtered.map((i) => {
+    const marker = i.exists ? `${colors.yellow}*${colors.reset}` : " ";
+    return `${marker} ${i.name}`;
+  });
+
+  const label = category.charAt(0).toUpperCase() + category.slice(1) + "s";
+  return `  ${colors.bright}${label} (${filtered.length})${colors.reset}${overrideNote}\n${names.map((n) => `    ${n}`).join("\n")}`;
+}
+
+function showPreview(adapter: PlatformAdapter, items: InstallItem[]): void {
+  console.log(
+    `\n${colors.bright}Install preview for ${adapter.displayName}${colors.reset}`
+  );
+  console.log(`  Target: ${adapter.configDir}\n`);
+
+  const categories = ["skill", "agent", "hook", "guideline"] as const;
+  for (const cat of categories) {
+    const section = formatItemList(items, cat);
+    if (section) console.log(section + "\n");
+  }
+
+  const existingCount = items.filter((i) => i.exists).length;
+  if (existingCount > 0) {
+    console.log(
+      `  ${colors.yellow}*${colors.reset} = exists and will be overwritten (${existingCount} files)\n`
+    );
+  }
+}
+
+async function promptExclusions(items: InstallItem[]): Promise<InstallFilter> {
+  const filter: InstallFilter = {};
+
+  console.log(`${colors.cyan}Options:${colors.reset}`);
+  console.log(`  [Enter]  Install all`);
+  console.log(`  [e]      Exclude specific items`);
+  console.log(`  [c]      Cancel\n`);
+
+  const choice = await prompt("Selection: ");
+
+  if (choice.toLowerCase() === "c") {
+    return { excludeSkills: items.filter((i) => i.category === "skill").map((i) => i.name) };
+  }
+
+  if (choice.toLowerCase() !== "e") {
+    return filter;
+  }
+
+  // Interactive exclusion
+  const skills = items.filter((i) => i.category === "skill");
+  const agents = items.filter((i) => i.category === "agent");
+  const hooks = items.filter((i) => i.category === "hook");
+  const guidelines = items.filter((i) => i.category === "guideline");
+
+  if (skills.length > 0) {
+    console.log(
+      `\n${colors.bright}Skills${colors.reset} (${skills.length} total)`
+    );
+    console.log(
+      `  Enter names to EXCLUDE (comma-separated), or press Enter to keep all:`
+    );
+    console.log(
+      `  ${colors.cyan}Available:${colors.reset} ${skills.map((s) => s.name).join(", ")}\n`
+    );
+    const excluded = await prompt("  Exclude: ");
+    if (excluded) {
+      filter.excludeSkills = excluded.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  }
+
+  if (agents.length > 0) {
+    console.log(
+      `\n${colors.bright}Agents${colors.reset} (${agents.length} total)`
+    );
+    console.log(
+      `  Enter names to EXCLUDE (comma-separated), or press Enter to keep all:`
+    );
+    console.log(
+      `  ${colors.cyan}Available:${colors.reset} ${agents.map((a) => a.name).join(", ")}\n`
+    );
+    const excluded = await prompt("  Exclude: ");
+    if (excluded) {
+      filter.excludeAgents = excluded.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  }
+
+  if (hooks.length > 0) {
+    console.log(
+      `\n${colors.bright}Hooks${colors.reset} (${hooks.length} total)`
+    );
+    console.log(
+      `  Enter names to EXCLUDE (comma-separated), or press Enter to keep all:`
+    );
+    console.log(
+      `  ${colors.cyan}Available:${colors.reset} ${hooks.map((h) => h.name).join(", ")}\n`
+    );
+    const excluded = await prompt("  Exclude: ");
+    if (excluded) {
+      filter.excludeHooks = excluded.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  }
+
+  if (guidelines.length > 0) {
+    const skip = !(await promptYesNo("\n  Install guidelines?", true));
+    filter.skipGuidelines = skip;
+  }
+
+  return filter;
+}
+
+export async function installForPlatform(
+  adapter: PlatformAdapter,
+  options: InstallOptions = {}
+): Promise<void> {
+  const skillsSource = join(PLUGIN_SOURCE, "skills");
+  const agentsSource = join(PLUGIN_SOURCE, "agents");
+  const hooksSource = join(PLUGIN_SOURCE, "hooks");
+
+  // Preview
+  const preview = adapter.preview(PLUGIN_SOURCE);
+  showPreview(adapter, preview.items);
+
+  // Exclusion selection
+  const filter = await promptExclusions(preview.items);
+
+  // Check if everything was cancelled
+  const allSkills = preview.items.filter((i) => i.category === "skill");
+  if (
+    filter.excludeSkills &&
+    filter.excludeSkills.length >= allSkills.length
+  ) {
+    console.log("\nInstallation cancelled.\n");
+    return;
+  }
+
+  // Confirm
+  const excludedCount =
+    (filter.excludeSkills?.length ?? 0) +
+    (filter.excludeAgents?.length ?? 0) +
+    (filter.excludeHooks?.length ?? 0) +
+    (filter.skipGuidelines ? 1 : 0);
+  const totalItems = preview.items.length - excludedCount;
+
+  const proceed = await promptYesNo(
+    `\nInstall ${totalItems} items to ${adapter.configDir}?`
+  );
+  if (!proceed) {
+    console.log("\nInstallation cancelled.\n");
+    return;
+  }
+
+  console.log(
+    `\n${colors.bright}Installing for ${adapter.displayName}${colors.reset}\n`
+  );
+
+  log.step(`Installing skills...`);
+  adapter.installSkills(skillsSource, filter.excludeSkills);
+  log.success(`Skills installed`);
+
+  log.step(`Installing agents...`);
+  adapter.installAgents(agentsSource, filter.excludeAgents);
+  log.success(`Agents installed`);
+
+  if (!filter.skipGuidelines) {
+    log.step(`Installing guidelines...`);
+    adapter.installGuidelines(PLUGIN_SOURCE);
+    log.success(`Guidelines installed`);
+  }
+
+  if (adapter.installHooks) {
+    log.step(`Installing hooks...`);
+    adapter.installHooks(hooksSource, filter.excludeHooks);
+    log.success(`Hooks installed`);
+  }
+
+  if (adapter.configureMcp && !options.skipMcp) {
+    log.step(`Configuring MCP servers...`);
+    await adapter.configureMcp();
+    log.success(`MCP configured`);
+  }
+
+  if (adapter.postInstall) {
+    adapter.postInstall();
+  }
+
+  console.log(
+    `\n${colors.green}Done!${colors.reset} ${adapter.displayName} installation complete.\n`
+  );
+}

package/platforms/shared/types.ts

@@ -0,0 +1,78 @@
+import { homedir } from "os";
+import { join, resolve, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+
+export interface InstallItem {
+  name: string;
+  category: "skill" | "agent" | "hook" | "guideline";
+  destPath: string;
+  exists: boolean;
+}
+
+export interface InstallPreview {
+  platform: string;
+  targetDir: string;
+  items: InstallItem[];
+}
+
+export interface InstallFilter {
+  excludeSkills?: string[];
+  excludeAgents?: string[];
+  excludeHooks?: string[];
+  skipGuidelines?: boolean;
+}
+
+export interface PlatformAdapter {
+  readonly name: string;
+  readonly displayName: string;
+  readonly configDir: string;
+
+  detect(): boolean;
+  preview(sourceDir: string): InstallPreview;
+  installSkills(sourceDir: string, exclude?: string[]): void;
+  installAgents(sourceDir: string, exclude?: string[]): void;
+  installGuidelines(pluginRoot: string): void;
+  installHooks?(sourceDir: string, exclude?: string[]): void;
+  configureMcp?(): Promise<void>;
+  postInstall?(): void;
+}
+
+export interface DetectedPlatform {
+  adapter: PlatformAdapter;
+  detected: boolean;
+  note?: string;
+}
+
+export interface InstallOptions {
+  targets?: string[];
+  verbose?: boolean;
+  skipMcp?: boolean;
+}
+
+export function findPackageRoot(): string {
+  let dir: string;
+  try {
+    dir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    dir = typeof __dirname !== "undefined" ? __dirname : resolve(".");
+  }
+
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+export const PLUGIN_SOURCE = join(
+  findPackageRoot(),
+  "plugins",
+  "ima-claude"
+);
+
+export function platformConfigDir(platformDir: string): string {
+  return join(homedir(), platformDir);
+}

package/plugins/ima-claude/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "ima-claude",
+  "version": "2.9.0",
+  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 47 skills, 24 hooks, default persona, 3-tier memory system.",
+  "author": {
+    "name": "IMA",
+    "url": "https://github.com/Soabirw/ima-claude"
+  },
+  "homepage": "https://github.com/Soabirw/ima-claude",
+  "repository": "https://github.com/Soabirw/ima-claude",
+  "license": "MIT",
+  "keywords": [
+    "functional-programming",
+    "architecture",
+    "wordpress",
+    "skills",
+    "hooks",
+    "memory",
+    "fp-patterns",
+    "team-standards",
+    "ruby",
+    "rails",
+    "discourse"
+  ]
+}

package/plugins/ima-claude/agents/explorer.md

@@ -0,0 +1,30 @@
+---
+name: explorer
+description: "Fast, read-only codebase exploration. Use proactively for file discovery, architecture understanding, and code search before implementation work."
+model: haiku
+tools: Read, Grep, Glob, LS, Bash
+permissionMode: plan
+---
+
+You are a codebase explorer. Your job is to quickly find files, understand structure, and report back with specific paths and relevant code snippets.
+
+## How to work
+
+1. Start with broad searches (Glob for file patterns, Grep for keywords)
+2. Narrow down to specific files and symbols
+3. Report findings with exact file paths and line numbers
+4. Summarize architecture and patterns you discover
+
+## What to report
+
+- File paths and their purposes
+- Key symbols (classes, functions, exports) with locations
+- Patterns and conventions observed
+- Dependencies and relationships between files
+
+## What NOT to do
+
+- Do not modify any files
+- Do not suggest implementations (that's the implementer's job)
+- Do not over-read — scan structure first, read bodies only when needed
+- Do not speculate — report what you find, flag what's uncertain

package/plugins/ima-claude/agents/implementer.md

@@ -0,0 +1,30 @@
+---
+name: implementer
+description: "Standard implementation worker for coding tasks. Default delegation target for feature development, bug fixes, refactoring, and test writing."
+model: sonnet
+skills:
+  - functional-programmer
+---
+
+You are an implementation specialist. You write clean, functional, production-ready code.
+
+## Principles
+
+- **Simple > Complex** — YAGNI strictly, boring code wins
+- **FP-first** — pure functions, composition, immutability where practical
+- **Native patterns** — use language idioms, not custom FP utilities
+- **Minimal changes** — only modify what's needed for the task
+
+## How to work
+
+1. Read the specific files you need to modify
+2. Understand existing patterns before writing new code
+3. Make the change with minimal blast radius
+4. Verify the change is complete and consistent
+
+## What to avoid
+
+- Over-engineering: no abstractions for one-time operations
+- Feature creep: only implement what was asked
+- Unnecessary comments: code should be self-documenting
+- Breaking existing patterns: match the codebase style

package/plugins/ima-claude/agents/memory.md

@@ -0,0 +1,42 @@
+---
+name: memory
+description: "Memory operations across Vestige, Qdrant, and Serena. Search, store, consolidate, and manage persistent knowledge."
+model: sonnet
+tools: Read, Grep, Glob, LS, Bash
+permissionMode: default
+---
+
+You are a memory specialist. Your job is to search, store, and consolidate knowledge across three memory systems:
+
+- **Vestige**: Cognitive memory with spaced repetition — decisions, preferences, patterns, bugs
+- **Qdrant**: Permanent library — standards, PRDs, architecture docs, code samples
+- **Serena**: Project-scoped session state and task progress
+
+## How to work
+
+1. **Search before storing** — always check for existing memories to avoid duplicates
+2. **Route to the right store** — ephemeral decisions → Vestige, reference material → Qdrant, session state → Serena
+3. **Use smart_ingest for Vestige** — it handles dedup and categorization
+4. **Be concise** — store the essence, not the full conversation
+
+## Memory routing
+
+| What | Where | Why |
+|------|-------|-----|
+| Decisions, preferences, patterns | Vestige `smart_ingest` | Fades naturally if not referenced |
+| Reference material, docs, standards | Qdrant `qdrant-store` | Permanent, never forgotten |
+| Session state, task progress | Serena `write_memory` | Project-scoped workbench |
+| Future reminders | Vestige `intention` | Surfaces at next session |
+
+## What to report
+
+- What was found or stored, with enough context to be useful
+- Conflicts or duplicates discovered
+- Suggestions for consolidation if memory is fragmented
+
+## What NOT to do
+
+- Do not store session-specific noise (temp vars, in-progress debugging)
+- Do not store secrets or API keys
+- Do not overwrite existing memories without checking them first
+- Do not speculate about what *should* be remembered — store what was explicitly decided or requested

package/plugins/ima-claude/agents/reviewer.md

@@ -0,0 +1,53 @@
+---
+name: reviewer
+description: "Code quality review specialist. Use after implementation to check for bugs, FP violations, security issues, and code quality. Read-only — reports findings without modifying code."
+model: sonnet
+tools: Read, Grep, Glob, LS, Bash
+permissionMode: plan
+skills:
+  - functional-programmer
+---
+
+You are a code reviewer with 25 years of experience and a functional programming mindset.
+
+## Review checklist
+
+### Correctness
+- Logic errors, off-by-one, null/undefined paths
+- Edge cases and error handling
+- Type safety and contract violations
+
+### FP principles
+- Unnecessary mutation where pure alternatives exist
+- Side effects mixed with business logic
+- Missing composition opportunities
+- Custom FP utilities that should use native patterns
+
+### Security
+- Input validation at system boundaries
+- SQL injection, XSS, command injection
+- Exposed secrets or credentials
+- Improper auth/authz checks
+
+### Code quality
+- Naming clarity and consistency
+- Over-engineering and premature abstraction
+- Dead code and unused imports
+- Pattern consistency with surrounding code
+
+## Output format
+
+Organize findings by severity:
+
+**Critical** — Must fix before merge (bugs, security issues)
+**Warning** — Should fix (FP violations, potential issues)
+**Suggestion** — Consider improving (style, minor simplifications)
+
+For each finding: file path, line number, what's wrong, and a specific fix.
+
+## What NOT to do
+
+- Do not modify any files
+- Do not flag style preferences that don't affect correctness
+- Do not suggest adding comments, docstrings, or type annotations to unchanged code
+- Do not report more than 10 findings — prioritize ruthlessly

package/plugins/ima-claude/agents/tester.md

@@ -0,0 +1,33 @@
+---
+name: tester
+description: "Testing specialist for test creation, TDD, running test suites, and debugging test failures. Routes to domain-specific testing patterns via unit-testing skill."
+model: sonnet
+skills:
+  - unit-testing
+  - functional-programmer
+---
+
+You are a testing specialist with deep expertise in test strategy, TDD, and debugging test failures.
+
+## Principles
+
+- **Test pure core, not impure shell** — FP makes testing easy; leverage it
+- **Bottom-heavy pyramid** — pure function unit tests are cheap and fast; write many
+- **Minimal mocking** — prefer extracting pure logic over mocking dependencies
+- **Tests as documentation** — test names describe behavior, not implementation
+
+## How to work
+
+1. Analyze the code under test — identify pure vs impure boundaries
+2. Classify what type of tests are needed (unit/integration/E2E)
+3. Structure test files following project conventions
+4. Write tests that verify behavior, not implementation details
+5. Run the suite and verify all tests pass
+
+## What to avoid
+
+- Testing implementation details (private methods, internal state)
+- Deep mock chains — if you need 3+ mocks, refactor the code instead
+- Over-testing: don't test framework behavior or trivial getters/setters
+- Flaky tests: no timers, no network calls, no filesystem in unit tests
+- Duplicating test patterns already in domain skills (phpunit-wp, playwright, etc.)

package/plugins/ima-claude/agents/wp-developer.md

@@ -0,0 +1,46 @@
+---
+name: wp-developer
+description: "WordPress development specialist. Use for plugin development, theme work, WP-CLI operations, IMA Forms, and Bootstrap integration in WordPress projects."
+model: sonnet
+skills:
+  - php-fp
+  - php-fp-wordpress
+  - wp-local
+  - ima-forms-expert
+  - ima-bootstrap
+  - jquery
+---
+
+You are a WordPress development specialist with deep knowledge of the WordPress ecosystem, PHP FP patterns, and the IMA toolchain.
+
+## Principles
+
+- **Security first** — nonce verification, capability checks, prepared statements, output escaping
+- **FP in WordPress** — pure business logic, WordPress as the integration shell
+- **Native WordPress** — use core APIs and hooks, avoid reinventing what WordPress provides
+- **Bootstrap utility-first** — use Bootstrap classes, not custom CSS
+
+## Capabilities
+
+- Plugin and theme development with WordPress coding standards
+- WP-CLI operations via Local WP environments
+- IMA Forms component library (ima_forms_* functions)
+- Bootstrap 5.3 integration with IMA brand system
+- jQuery patterns for WordPress DOM manipulation
+- Database operations with $wpdb and prepared statements
+
+## How to work
+
+1. Understand the WordPress context (plugin, theme, mu-plugin, etc.)
+2. Follow WordPress hooks architecture (actions and filters)
+3. Separate pure business logic from WordPress integration
+4. Use proper escaping: esc_html(), esc_attr(), wp_kses() for output
+5. Use proper sanitization: sanitize_text_field(), absint() for input
+
+## What to avoid
+
+- Direct database queries when WordPress API exists
+- Skipping nonce verification on form handlers
+- Mixing business logic with rendering
+- Custom CSS when Bootstrap utilities work
+- Raw jQuery when WordPress-native patterns exist

package/plugins/ima-claude/hooks/README.md

@@ -0,0 +1,145 @@
+# Claude Code Hooks
+
+Pre-tool-use hooks that enhance Claude Code's behavior with soft warnings and suggestions.
+
+## Installation
+
+Copy hooks to your Claude Code hooks directory:
+
+```bash
+cp hooks/*.py ~/.claude/hooks/
+cp hooks/*.md ~/.claude/hooks/
+```
+
+For the Prompt Coach hook, also copy and configure the API key:
+
+```bash
+cp hooks/prompt_coach_config.json.template ~/.claude/hooks/prompt_coach_config.json
+# Edit ~/.claude/hooks/prompt_coach_config.json with your API key
+```
+
+Or the installer will do this automatically when you run `bun run scripts/install.ts`.
+
+## Available Hooks
+
+### `enforce_rg_over_grep.py`
+
+**Type**: PreToolUse (Bash)
+
+Warns about suboptimal search tools (allows command to proceed):
+- Warns on `grep` → suggests `rg` (ripgrep) for better performance
+- Warns on `find -name` → suggests `rg --files -g pattern`
+
+The warning is shown to Claude, encouraging use of `rg` for the rest of the session. See the `/rg` skill for usage patterns.
+
+### `websearch_to_tavily.py`
+
+**Type**: PreToolUse (WebSearch)
+
+Suggests using Tavily search instead of WebSearch (allows command to proceed):
+- Provides correct Airis gateway syntax for Tavily search
+- Includes query from original request in the suggestion
+- References `/mcp-tavily` skill for full documentation
+
+Best for: Research tasks, current information, comparisons.
+
+### `webfetch_to_tavily.py`
+
+**Type**: PreToolUse (WebFetch)
+
+Suggests considering Tavily extract for complex pages (allows command to proceed):
+- Notes that Tavily often extracts cleaner content
+- Provides correct Airis gateway syntax
+- References `/mcp-tavily` skill for full documentation
+
+Note: WebFetch is fine for simple pages; Tavily shines on complex/dynamic content.
+
+### `tavily_extract_advanced.py`
+
+**Type**: PreToolUse (mcp__tavily__*)
+
+Informational hook for direct Tavily tool usage:
+- Reminds about the correct Airis gateway pattern if using old `mcp__tavily__*` tool names
+- References `/mcp-tavily` skill
+
+### `prompt_coach.py`
+
+**Type**: UserPromptSubmit
+
+Evaluates user prompts against team standards using Haiku:
+- Provides inline feedback when prompts could be improved
+- Stays silent when prompts are well-formed
+- Skips short prompts and common follow-ups (yes/no/ok)
+- Uses skills digest for context-aware evaluation
+
+**Configuration:**
+1. Copy config template: `cp hooks/prompt_coach_config.json.template ~/.claude/hooks/prompt_coach_config.json`
+2. Add your Anthropic API key to the config file
+3. Set environment variables:
+   - `PROMPT_COACH_ENABLED=true` - Enable evaluation
+   - `PROMPT_COACH_LOG=true` - Optional: Log to `~/.claude/prompt_coach.log`
+
+**Note:** The API key is isolated in the hook's config file and does not affect Claude Code's OAuth authentication.
+
+## Hook Behavior
+
+All hooks use **soft warnings** (exit code 0) that:
+1. Print helpful suggestions to stderr (shown to Claude)
+2. Allow the original command to proceed
+3. Reference relevant skills for detailed usage patterns
+
+This approach teaches the LLM better patterns without breaking workflows.
+
+## Hook Configuration
+
+Hooks are configured in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "python3 ~/.claude/hooks/enforce_rg_over_grep.py" }
+        ]
+      },
+      {
+        "matcher": "mcp__tavily__tavily-extract",
+        "hooks": [
+          { "type": "command", "command": "python3 ~/.claude/hooks/tavily_extract_advanced.py" }
+        ]
+      },
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          { "type": "command", "command": "python3 ~/.claude/hooks/webfetch_to_tavily.py" }
+        ]
+      },
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          { "type": "command", "command": "python3 ~/.claude/hooks/websearch_to_tavily.py" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "python3 ~/.claude/hooks/prompt_coach.py"
+      }
+    ]
+  }
+}
+```
+
+## Requirements
+
+- Python 3.8+
+- Tavily MCP server via Airis gateway (for Tavily-related suggestions)
+- ripgrep (`rg`) installed (for rg enforcement hook)
+
+## Related Skills
+
+- `/rg` - Ripgrep usage patterns and examples
+- `/mcp-tavily` - Tavily search and extract via Airis gateway