ima-claude 2.25.0 → 2.26.0

package/README.md

@@ -63,6 +63,31 @@ npx ima-claude install --target claude      # Claude Code only (plugin recommend
 npx ima-claude detect                       # Show detected platforms
 ```
 
+**Tip: Install into a single project instead of globally**
+
+The installer resolves its target paths via `$HOME` (`~/.claude/...`). Override `$HOME` at invocation time to write skills, agents, hooks, and `settings.json` into the current repo's `./.claude/` instead:
+
+```bash
+HOME=$(pwd) npx ima-claude install --target claude
+```
+
+Produces:
+
+```
+./.claude/skills/       # project-scoped skills
+./.claude/agents/       # project-scoped agents
+./.claude/hooks/        # Python hook scripts
+./.claude/settings.json # hook configuration (absolute paths)
+```
+
+Claude Code already reads these as project-scoped config, so the skills/hooks load only when you're working inside that repo.
+
+Caveats:
+
+- The plugin marketplace flow (`/plugin install ima-claude`) remains the recommended path for most users. Use this override only when you want per-repo skill customization without touching your home install.
+- `settings.json` records hook paths as absolute strings resolved at install time — if you rename or move the project, the hook entries break.
+- `HOME=$(pwd)` also redirects npm's cache, so the install may drop a `.npm/` folder in the project root. Add it to `.gitignore` or clean up afterward.
+
 **What's different per platform?**
 
 | | Claude Code | Junie CLI | Gemini CLI | GitHub Copilot |
@@ -311,6 +336,7 @@ For in-scope hard reasoning (debugging, trade-offs within plan), agents invoke `
 | `wp-ddev` | WP-CLI commands for DDEV WordPress environments |
 | `wp-local` | WP-CLI commands for Flywheel Local WP |
 | `jira-checkpoint` | Jira awareness checkpoints for team visibility |
+| `ima-git` | IMA trunk-based git workflow (main/release/tag model, hotfix flow, deploy-gate push cadence, commit atomicity) |
 | `phpunit-wp` | PHPUnit testing for WordPress plugins with FP principles |
 | `rg` | Ripgrep usage patterns |
 | `ima-forms-expert` | WordPress form components (IMA Forms) |

package/dist/cli.js

@@ -11,7 +11,7 @@ var HOOKS_DIR = join(CLAUDE_DIR, "hooks");
 var COMMANDS_DIR = join(CLAUDE_DIR, "commands");
 var RULES_DIR = join(CLAUDE_DIR, "rules");
 var SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
-var VERSION = "2.25.0";
+var VERSION = "2.26.0";
 var colors = {
   reset: "\x1B[0m",
   bright: "\x1B[1m",
@@ -111,6 +111,7 @@ var SKILLS_TO_INSTALL = [
   "design-to-code",
   "livecanvas",
   "jira-checkpoint",
+  "ima-git",
   // Testing skills
   "unit-testing",
   "phpunit-wp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima-claude",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "IMA's AI coding agent skills - FP patterns, architecture guidance, and team standards. Supports Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot.",
   "type": "module",
   "scripts": {

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

@@ -1,7 +1,7 @@
 {
   "name": "ima-claude",
-  "version": "2.25.0",
-  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 62 skills, 24 hooks, default persona, 3-tier memory system.",
+  "version": "2.26.0",
+  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 63 skills, 24 hooks, default persona, 3-tier memory system.",
   "author": {
     "name": "IMA",
     "url": "https://github.com/Soabirw/ima-claude"

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

@@ -23,6 +23,33 @@ Use Serena as FIRST approach for ALL code investigation. Saves 40-70% tokens vs
 
 Use Read only for specific symbol bodies under review. Fall back to Read/Grep for non-code files.
 
+## Configured validators (REQUIRED — run first)
+
+A review is incomplete without running the project's configured gate. Validator output is primary evidence; code-reading is supplementary.
+
+Discover validators in this order:
+
+| Ecosystem | Where to look |
+|---|---|
+| PHP | `composer.json` scripts — `check`, `test`, `test:unit`, `phpcs`, `phpcs:report`, `lint` |
+| JS/TS | `package.json` scripts — `test`, `lint`, `typecheck`, `check`, `ci` |
+| Make-based | `Makefile` targets — `check`, `test`, `lint`, `ci` |
+| Python | `pyproject.toml` / `tox.ini` / `noxfile.py` |
+| Ruby | `Rakefile` — `ci`, `test`, `rubocop` |
+
+Run the project's aggregated gate if one exists (`composer check`, `npm run check`, `make check`, `rake ci`, etc.). Otherwise run lint + tests separately. If the project has none, that's a finding — not a silent pass.
+
+**Every review output MUST include a "Validators run" block:**
+
+```
+## Validators run
+- composer test:unit → exit 0 (308 tests, 0 failures)
+- composer phpcs:report → exit 1 (0 errors, 82 warnings)
+- (no JS lint configured)
+```
+
+A review with zero validator invocations is structurally incomplete. If you couldn't run a discovered validator (missing deps, auth required, etc.), say so explicitly and flag as a blocker for the review.
+
 ## PR review mode
 
 When given a Gitea/GitHub PR URL or diff:
@@ -39,7 +66,7 @@ Diff-only analysis is the failure mode. Always read surrounding context.
 
 **FP** — unnecessary mutation, side effects mixed with business logic, missing composition, custom FP utilities over native patterns
 
-**Security** — input validation at boundaries, SQL injection, XSS, exposed secrets, auth/authz
+**Security** — start with security-sniff output (WPCS security, eslint-plugin-security, bandit, etc.) if available; then input validation at boundaries, SQL injection, XSS, exposed secrets, auth/authz
 
 **Quality** — naming clarity, over-engineering, dead code, pattern consistency
 
@@ -73,3 +100,4 @@ Parent (Opus) decides whether to expand scope, re-dispatch a focused follow-up r
 - Flag style preferences that don't affect correctness
 - Suggest adding comments/docstrings/types to unchanged code
 - Report more than 10 findings — prioritize ruthlessly
+- Assert on code standards, security, or test coverage without having run the corresponding validator. "Looks clean" is not a finding; "phpcs reports 0 errors" is.

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

@@ -0,0 +1,81 @@
+---
+name: "ima-git"
+description: "IMA git workflow. Trunk-based development with release branches: main = dev trunk, release/* = release candidate branches, v* tags = production releases. Covers branch promotion, hotfix flow, push cadence for deploy-gate verification, commit atomicity. Use when: creating branches, opening PRs, cutting releases or tags, writing hotfixes, or asked about git workflow, branching strategy, trunk-based development, release process, or when a deploy gate fails because commits weren't pushed."
+---
+
+# IMA Git Workflow
+
+**Strategy:** Trunk-based development with release branches.
+
+## Branch model
+
+| Branch / tag | Role | Source | Deploys to |
+|---|---|---|---|
+| `main` | Dev trunk — latest integrated work | All new work lands here first | Dev environment |
+| `release/<name>` | Release candidate | Fast-forwarded from `main` when ready | Staging environment |
+| `v<version>` (tags) | Production release | Tag cut from a release branch at promotion | Production environment |
+| `hotfix/<name>` | Emergency production fix | Branched off the production tag | Merged back to `main` + new tag cut |
+
+## Core rules
+
+1. **Commits originate on `main`.** Not on release branches. Feature work, bug fixes, refactors — all start on the trunk.
+2. **Release branches only fast-forward from `main`.** Never merge sideways; never commit directly to a release branch.
+3. **Hotfixes branch off the production tag**, not main. After the fix lands, cut a new tag and merge the hotfix back into `main`.
+4. **Tags are immutable.** Rolling back to a prior production state means deploying the prior tag — not force-pushing or retagging.
+
+## Deploy-gate verification cadence
+
+Deploy tools (e.g., `trn-deploy` at `/home/eric/IMA/dev/sites/trn/deploy/`) **clone fresh from the remote** — they do not read the local filesystem. Unpushed commits are invisible to the gate.
+
+**To verify a change:** push to `main` first, then invoke the dry-run.
+
+Between commits in a multi-commit sequence:
+
+1. Commit locally
+2. `git push origin main`
+3. Run `./deploy dev --dry-run`
+4. Confirm exit 0 in `log.jsonl` before the next commit
+
+## Commit atomicity
+
+- **Security fixes: separate commits** from test-only changes and mechanical sweeps. A security change should land in a reviewable, revertable commit of its own.
+- One commit per logical change class. Don't batch "fix XSS + rename variable + reformat whitespace" into one diff.
+- Pure tests-only changes never mix with production code changes in the same commit.
+
+## Commit messages
+
+- Use a HEREDOC to pass multi-line messages: `git commit -m "$(cat <<'EOF' ... EOF)"`.
+- Single-quoted `EOF` marker (`<<'EOF'`) prevents shell expansion — required to keep `$_POST`, `$_GET`, `$variable` etc. unescaped.
+- A message with literal `\$_POST` in the body is a shell-escape artifact — amend before pushing, or treat it as a signal the HEREDOC was wrong.
+
+## Deploy tool exit codes
+
+Shared convention across IMA deploy tools:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Validation / config error |
+| 3 | Pre-flight failure (tests, lint, clean-state check) |
+| 4 | Remote push failure (WPEngine or similar) |
+
+The authoritative record is the tool's `log.jsonl`: `tail -1 log.jsonl` shows the last run's sha, exitCode, duration. The shell's `$?` may be masked by a pipe (`| tail`), so trust the log over stdout exit.
+
+## Gitea / GitHub
+
+- IMA internal repos live on Gitea: `ssh://git@gitea.theflccc.org:2222/IMA/<repo>.git`
+- Some are mirrored to GitHub for FOSS / public presence.
+- Use `mcp-gitea` for internal repo operations, `mcp-github` or `gh-cli` for public.
+
+## When the deploy gate fails
+
+1. Check `log.jsonl` for the exit code. Don't guess from terminal output.
+2. Exit 3 = pre-flight. Look at the pipeline stage that failed — tests, lint, clean-state, composer check.
+3. Reproduce locally with the project's configured validators (`composer check`, `npm run check`, `make check`, etc.) before touching code.
+4. If a pre-flight failure is tests, invoke the source-quality triage pattern: categorize each failure as test rot, code bug, or design question **before** changing anything.
+
+## Reference
+
+- Qdrant `ima-knowledge` → article "IMA Git Workflow & Pre-flight Deploy Gate" for full detail on the gate architecture and the source-quality triage playbook.
+- Project-specific deploy specifics live in the project's Serena memory (typically named `project-workflow` or similar).

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

@@ -26,9 +26,25 @@ Arguments are domain skills to evaluate against. If none provided, auto-detect f
 3. Identify project's primary language(s) and framework(s)
 4. Locate README (or note its absence)
 
-### Step 2: Parallel Review
+### Step 2: Run project validators (REQUIRED)
 
-Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grade (A-F) + 2-3 justifying bullets. Be honest — inflated scores help nobody.
+Before any grading, discover and run the project's configured gate. Same discovery order as the `reviewer` agent:
+
+| Ecosystem | Where to look |
+|---|---|
+| PHP | `composer.json` scripts — `check`, `test`, `phpcs`, `phpcs:report` |
+| JS/TS | `package.json` scripts — `test`, `lint`, `typecheck`, `check` |
+| Make-based | `Makefile` targets — `check`, `test`, `lint`, `ci` |
+| Python | `pyproject.toml` / `tox.ini` / `noxfile.py` |
+| Ruby | `Rakefile` — `ci`, `test`, `rubocop` |
+
+Capture exit codes, error/warning counts, and test coverage % (run the coverage variant — `composer test:coverage`, `npm test -- --coverage` — when available). These are primary evidence for Code Standards, Security, and Test Coverage grades.
+
+Grades without validator backing are vibes grades. Don't ship them. No validators configured is itself a signal — floor Code Standards at C until they exist.
+
+### Step 3: Parallel Review
+
+Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grade (A-F) + 2-3 justifying bullets rooted in validator output. Be honest — inflated scores help nobody.
 
 | Category | What to Evaluate | Key Signals |
 |----------|-----------------|-------------|
@@ -38,7 +54,7 @@ Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grad
 | **Documentation** | README quality, inline docs, API docs | Setup instructions, usage examples, architecture notes |
 | **Maintainability** | Complexity, coupling, file organization | Small functions, clear boundaries, no circular deps |
 
-### Step 3: Compile Scores
+### Step 4: Compile Scores
 
 ```markdown
 ## Scorecard
@@ -69,7 +85,7 @@ Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grad
 | D | 🔴 D | Poor — significant issues |
 | F | 🔴 F | Failing — critical problems |
 
-### Step 4: Insert into README
+### Step 5: Insert into README
 
 - Replace existing `## Scorecard` section, or insert after first heading if absent
 - Present full scorecard to user before writing