Geniro Claude Plugin

A production-grade Claude Code plugin with AI-driven setup and multi-agent workflows. Provides specialist subagents, skills, and session-restore hooks + statusline + update check out of the box.

Built and maintained by the Geniro team.

Install

claude plugin marketplace add geniro-io/geniro-claude-harness
claude plugin install geniro --scope user

Upgrading from v4.x — reinstall required

v5.0.0 renames the plugin geniro-claude-plugin → geniro, so commands render as /geniro:plan instead of the doubled /geniro-claude-plugin:geniro:plan. claude plugin update resolves ids exactly and cannot migrate across a rename, so an existing install needs replacing once:

claude plugin uninstall geniro-claude-plugin@geniro-claude-harness
claude plugin marketplace update geniro-claude-harness
claude plugin install geniro@geniro-claude-harness --scope user

Restart the session afterward. Project files under .geniro/ — instructions, actions, planning artifacts, learnings — are untouched.

--scope user installs the plugin globally so it's available in every directory (this is the default, but pinning it keeps the install global). Avoid --scope project for the plugin itself — a project-scoped install loads only inside that one project, and on the next update it can shadow the global install record and make the plugin disappear from your other directories. To share the marketplace with teammates instead, use the project-scoped marketplace config below — not a project-scoped plugin install.

For your team (project-scoped)

Add to your repo's .claude/settings.json so teammates get prompted to install:

{
  "extraKnownMarketplaces": {
    "geniro-claude-harness": {
      "source": { "source": "github", "repo": "geniro-io/geniro-claude-harness" }
    }
  }
}

Staying up to date

By default the plugin does not update itself. Claude Code auto-updates only marketplaces on its first-party allowlist, and third-party marketplaces like this one are off unless you opt in. The statusline update check tells you when a new version is out, and /geniro:update pulls it and walks any breaking changes in MIGRATION.md. That is the recommended path.

To opt into background updates instead, add autoUpdate to the marketplace entry in ~/.claude/settings.json (or your repo's .claude/settings.json to opt a whole team in):

{
  "extraKnownMarketplaces": {
    "geniro-claude-harness": {
      "source": { "source": "github", "repo": "geniro-io/geniro-claude-harness" },
      "autoUpdate": true
    }
  }
}

The marketplace and its installed plugins then refresh on startup. /plugin exposes the same toggle interactively, though a value set in a settings file wins and locks the UI toggle out.

The tradeoff: a background update swaps versions without running the MIGRATION.md walk, so a release with breaking changes can land silently. Prefer auto-update if you track releases closely and read the changelog; prefer the default if you'd rather be prompted and have /geniro:update guide the upgrade. Either way, a rename-level change (like v4.x → v5.0.0 above) still needs a manual reinstall — claude plugin update resolves ids exactly and cannot cross a rename.

Quick Start

1. Install the plugin (see above) and open Claude Code in your project.
2. Run setup — analyzes your stack and generates a tailored thin-map CLAUDE.md:

   /geniro:setup
   

3. Map the codebase (optional, recommended for larger repos) — produces .geniro/planning/_CODEBASE_MAP.md:

   /geniro:onboard
   

4. Plan a feature — spec-first planning, turns a vague idea into an approved spec.md:

   /geniro:plan add user authentication with JWT tokens
   

5. Implement — consumes the spec.md (or inline-task if /plan wasn't run), 3-phase autonomous loop:

   /geniro:implement
   

6. Review your work before shipping:

   /geniro:review
   

From there, pick the right skill for each task: /geniro:debug to investigate bugs (authors a fix proposal + reproduction test, escalates to /geniro:implement to ship), /geniro:refactor for zero-behavior-change restructuring, /geniro:investigate for codebase Q&A.

Architecture

See ARCHITECTURE.md for all design decisions — state tiers, memory layers, per-skill rulings, and operational rules.

How it works

The plugin itself ships globally — agents, skills, and hooks live inside the installed plugin and never pollute your repo. The only thing written into your project is a single .geniro/ directory that acts as the working memory across sessions:

.geniro/
├── planning/               # specs, plans, _CODEBASE_MAP.md, _FEATURES.md, _project.md, _focus-*.md
│   └── <task-dir>/         # task-bound: spec.md, plan.md, state.md, milestone-N.md
├── state/                  # session-bound + handoff
│   ├── <skill>/<slug>/state.md  # /debug, /refactor, /onboard, /investigate, /resolve, /audit-instructions
│   ├── setup/state.md      # /setup singleton
│   └── handoff/            # inter-skill: from-<producer>-<branch>.md
├── knowledge/              # learnings.jsonl (L2 episodic)
├── instructions/           # L4 procedural: global.md, memory.md, code-style.md,
│                           # per-skill.md, review-extra/<slug>.md
├── actions/                # T3 user-authored workflow helpers (Slack/PR/release)
└── workflow/               # optional integrations (issue tracker, PR flow)

.geniro/ is gitignored by default, except workflow/, instructions/, and actions/ which are meant to be committed so the team shares the same rules and integrations.

Subagent models

Subagents that decide something run on your session model. If you're running Claude Code on Opus, your code reviewers, researchers, and planners run on Opus; on Sonnet for cost control, they run on Sonnet. You set it once at session start with /model; the plugin doesn't second-guess a judgment call.

Work that only applies a decision already made, or gathers evidence the orchestrator re-checks (running your tests, fetching past learnings, applying approved fixes) runs on a cheaper "light" class instead: the host's smallest or mid current model (which one each host uses: skills/_shared/model-tiering.md §Runtime resolution). Once you've approved a finding, the model that mattered has already run, so top-tier rates buy nothing there. A read-only spawn that returns nothing steps up one class, and one that returns garbled output re-runs on your session model; a spawn that edits files is never re-run. A light spawn never costs more than your session model, except on Cursor, where auto leaves the choice to the host and can pick a dearer one.

The split is decide-vs-apply, not writes-files: a reviewer returns findings in a fixed schema, but the severity and confidence inside it are its own judgment call, so it runs on your session model. Full rules: skills/_shared/model-tiering.md.

Want to choose yourself? --subagent-model sonnet|opus|haiku|fable on /geniro:implement or /geniro:review, announced once at the start, pins every deciding spawn to the model you named and caps the light ones at it: asking for Opus buys deeper review, not an Opus test-runner; asking for Haiku takes everything down with it. A custom reviewer's own model: and your host's settings (such as CLAUDE_CODE_SUBAGENT_MODEL in Claude Code) win too.

Typical workflow

  /geniro:plan  →  /geniro:implement  →  /geniro:review
  (spec-first      (3-phase autonomous     (multi-dim code review
   planning)        execute + ship)         before merge)

For investigation and maintenance:

  /geniro:debug          /geniro:refactor       /geniro:investigate
  (scientific-method     (zero-behavior-change   (parallel research
   bug investigation)     restructuring)          agents Q&A)

Each skill reads from and writes to .geniro/ so context survives across compaction, branches, and sessions:

• Plan → implement — /geniro:plan writes an approved spec.md to .geniro/planning/<task-dir>/; /geniro:implement consumes it (or accepts inline-task input as a fallback). For Big tasks, /geniro:plan Phase 5 milestone-mode emits sibling milestone-N.md files.
• Knowledge accumulates + auto-prunes — every pipeline + discovery skill auto-emits L2 entries to knowledge/learnings.jsonl. Types: discovery / pitfall / diagnosis / convention / decision, plus discarded_hypothesis (/debug Phase 1 ELIMINATED hypotheses), retry_failure_sequence (/implement, /debug, /refactor when retry_count >= 2), user_rejected_suggestion (any skill, AUQ rejection signal). Future runs query before investigating; query-learnings --score-min N ranks by recency x trust x access x recurrence. Auto-archive on SessionStart (default ON, opt-out via safety.json memory.auto_archive_stale: false): flips deprecated: true on stale-candidate entries — criteria owned by lib/archive-stale.sh (spec: skills/_shared/archive-stale.md §Criteria) — never deletes (audit trail). Hash-gated to skip unchanged runs; mkdir-locked for multi-tab safety.
• Rules persist — /geniro:instructions manages .geniro/instructions/, and every relevant skill applies the canonical loader at skills/_shared/load-custom-instructions.md on every run (Step 0 + phase-boundary refresh) to read global.md + memory.md + per-skill file + code-style.md, with one echo line per file printed by the loader (so "always use snake_case for DB columns" only has to be said once, and you can SEE which instruction files were found). Instruction files carry typed sections: ## Rules (standing constraints), ## Additional Steps → ### After <phase> (project-specific steps run at a skill phase boundary — e.g. duplicate an approved plan into OpenSpec), ## Constraints (hard gates), ## Data Sources (read-only sources to cross-check facts against), ## Verification Surface (what each project check covers and does not, so a result is worded at the width that check actually earned), and ## Memory Backend. Ask /geniro:instructions in plain English ("run X after ship", "verify status from my DB", "store learnings in my MCP") and it fills the right section.

Custom instructions from an external directory

By default the plugin reads your custom instructions — global.md, code-style.md, and per-skill files like implement.md — from .geniro/instructions/ in your repo. For clean fresh-clone or ephemeral environments where you don't want to commit those files, point the plugin at a directory outside the repo instead. Two ways to set it, highest precedence first:

1. Environment variable (recommended) — the reliable channel: the plugin reads it from the shell environment its Bash steps run in, so it always takes effect. Best for CI / per-environment setup:

export GENIRO_INSTRUCTIONS_DIR=/etc/geniro/instructions

2. Plugin install option (convenience) — when you enable the plugin, Claude Code prompts for an instructions_dir (a directory), which it exports as CLAUDE_PLUGIN_OPTION_INSTRUCTIONS_DIR. Point it at your external folder; the plugin uses it whenever the environment variable above is unset. If it doesn't take effect for instruction loading in your runtime, set GENIRO_INSTRUCTIONS_DIR instead — that channel always works.

The directory holds the instruction files flat — no .geniro/instructions/ subpath:

/etc/geniro/instructions/
├── global.md
├── code-style.md
├── implement.md
└── review.md

When an external directory is active it replaces the in-repo .geniro/instructions/ (the two are not merged), and only the skills read from it — editing the files with /geniro:instructions still updates the in-repo copy, which you manage yourself. If the configured path is missing, the plugin warns and falls back to the in-repo default, so a bad path never blocks a run.

Skills (14 total)

/geniro:setup — AI-driven project setup

Singleton bootstrap loop (Detect → Interview → Generate → Validate). Scans codebase via lockfile/config presence; interviews you for preferences that can't be auto-detected; generates a thin-map CLAUDE.md (tech stack / commands / conventions / domain context). To keep it thin, every inline section has to justify why it belongs in CLAUDE.md rather than in a doc of its own. Phase 4 verification subagent + 3-retry escalation loop. L2 discovery emit on done.

/geniro:setup

/geniro:plan — Spec-first planning

11-phase loop (mode-detect → explore → visual-companion → clarify (uncapped grill, checkpoint-bounded) → 2-3 approaches → section authoring → write → mechanical validate → spec-challenge → user approve → handoff). Every plan ends with the spec-challenge: the claims the spec makes about your code are read back against the code by agents that did not write them, before you are asked to approve it. Produces an approved spec.md in .geniro/planning/<task-dir>/ with goal-state frontmatter (budget / checkpoints / forbidden_actions / approval_required_for) and optional workflow_refs[] tracker linkage. Phase 2 Visual Companion for UI-shaped tasks previews the UI before any code is written — a text description, or, when the plan artifact is on, a rendered HTML mockup published onto the plan page with a short text summary beside it, revised through the same approve/rewrite loop; Phase 5 authors the sections in 3 dependency-ordered clusters (Goal & scope / Approach & steps / Safety & done) without a per-section approval question, so you approve the plan once, at the end: the final approval renders the whole spec to a full chat message in a friendly visual language (a progress tracker showing where you are in the approval journey, a one-sentence summary of what you're deciding, an in/out scope map, the public surface, a steps flow diagram, the test seams, a done-condition checklist, and plain-English per-section explanations with evidence cites), then asks ONE lean AskUserQuestion (Approve / Request changes / Abort — Request changes names the sections to revise); the chat message is the rendering surface (the AUQ preview side-box is too small for digests, code, and diagrams). Phase 3 asks clarifying questions round by round — each round the whole frontier of open decisions whose prerequisites are settled (uncapped, bounded by a checkpoint) — and never walks on to the approaches by itself: when it runs out of questions it says so and asks whether to start building or keep grilling — deeper on the angles a first pass leaves closed, or on an area you name. Phase 4 stress-tests the generated approaches with independent codebase-grounded critic agents (tier-scaled) before recommending one, so the Recommended marker reflects feasibility evidence rather than the author's confidence. An optional --artifact flag builds a live, collapsible visual artifact of the plan and publishes it to a private claude.ai page that updates as the plan develops (native-only). Milestone-mode for Big tasks emits sibling milestone-N.md files. The closing message prints the /geniro:implement command with a tip to run it in a fresh session.

/geniro:plan add user authentication with JWT tokens
/geniro:plan migrate from Sequelize to Prisma

/geniro:implement — Autonomous implementation

3-phase loop: Analyze → Implement → Self-review-and-Ship. Consumes spec.md from /plan (or inline-task fallback when /plan hasn't been run). Phase 1 fires Step 0 workspace AUQ (passive-detect → auto-continue when prior-task signals present), spawns Knowledge-Retrieval + Codebase-Explorer subagents in parallel for research. Phase 2 uses the host's todo list for decomposition (one-in-progress invariant inline), then partitions the todos by file set: groups whose file sets are disjoint are delegated to parallel subagents by default, coupled work stays with the orchestrator, and test-runner-agent runs once at phase end. Phase 3 spawns the reviewer-agent set in parallel — sized to the codebase-explorer's change_scope estimate (fewer dimensions on a trivial/small diff, the full set on a medium/large one, or on any diff whose scanned Risk flags matched) — and authors edge-case tests inline alongside that round (no separate agent; skipped on a trivial diff or --no-adversarial). One of those reviewers, intent, fires at every size and checks the change against its own stated reason — the spec, or the inline plan's Premises: line recorded from Phase 1 — asking whether each fact the change relies on is true in the code, whether it fixes the root cause rather than a symptom, and whether it covers the whole problem; the PR description it opens states the same problem, premises (with file:line), and root cause for a bug fix. Later review rounds re-check only behavior fixes: a dimension re-runs, focused on the latest fix's diff (the change's merge-base diff stays as context and decides whether each finding is new or pre-existing), only when its finding concerned runtime behavior and its fix edited production code, so test, comment, doc, naming, and refactor fixes start no round. Low-priority findings never force fix rounds — after the loop converges, a minor-findings gate asks whether to fix them now or leave them listed in the ship report. When the run wrote or changed tests, Phase 3 then runs an always-on (skip-when-clean) test-quality gate that surfaces the audit of those tests — does each test assert everything it claims, does every spec-required behavior have a covering test, are any tests redundant or weakly asserted — as a visible decision before Ship (advisory; no extra agent). Consumes T2 handoffs from /review and /debug, gating code-edit transitions on unresolved open_questions[]; questions that need your decision render as self-contained visual explanations in chat before a lean question. Ship cleanup preserves durable T1.5 artifacts (spec.md / state.md / milestone-*.md). When a PR is opened, the report ends with a tip that follow-up work on it (review comments, CI failures) runs cheaper in a fresh session via /geniro:resolve. Reviewers, verifiers and the explorer run on your session model; code delegates, the memory sweep and ad-hoc research run light (mid), and the test runner light (smallest).

/geniro:implement                              # consume spec.md from /plan
/geniro:implement add a CHANGELOG entry        # inline-task fallback

/geniro:review — Parallel multi-agent code review

Reporter loop — six numbered phases plus a mechanical pre-pass (triage → mechanical pre-pass → LLM reviewers → filter → stratify → persist → action-gate). Strictly read-only: /review never edits code and never authors a test. MANDATORY spawn list: always-fire (bugs / security / architecture / tests / conventions / regressions / intent — conventions covers style rubrics, repo-modal patterns, and authored-rule citations when the repo has rule files; intent checks the change against its stated reason, drawn from the PR title and body, commit messages, linked ticket, and plan: are the facts it relies on true in the code, does it fix the root cause, does it cover the whole problem), scaled to its own size boundary (>8 files OR >400 LOC — fewer of them under that boundary, all seven at or over it, or on any diff whose computed risk-tier reads high; intent fires at every size) + conditional (optimizations unless the diff is docs/lockfiles only / design when UI files present / pr-metadata when input was a PR ref / spec-compliance whenever PLAN CONTEXT is non-none, PR or not) + N custom from .geniro/instructions/review-extra/. Phase 2 declares spawn_dims_declared[] in state.md before the parallel batch; Phase 4 §4.0 verifies declared-vs-actual to catch silent skips. Phase 1 Step 0 smart workspace setup; /review is read-only — never mutates tracker status. Phase 1.5 mechanical pre-pass (lint / schema / secret scan + custom-reviewer discovery). Every filter survivor is independently re-verified by a fresh reviewer before it reaches you; findings that need your decision render as self-contained visual explanations in chat (what the code does, why it matters, evidence, your options — with a progress tracker across the decision queue) before a lean question; Phase 5.3 auto-emits pitfall L2 entries on cross-reviewer convergence ≥3. Emits a handoff with structured open_questions[] (3-gate chain prevents posting or implementing with unresolved questions). All reviewer-agents inherit orchestrator tier.

/geniro:review                                # review uncommitted changes
/geniro:review src/auth/ src/middleware/      # review specific files/dirs
/geniro:review HEAD~3..HEAD                   # review a commit range
/geniro:review #1234                          # PR review with draft-review posting gate

/geniro:resolve — PR feedback, decided and fixed

3-phase loop (Fetch & Triage → Decide → Fix & Close). Reads an open PR's unresolved review threads (human + bot) AND failing CI checks via _shared/pr-threads.md, syncs the workspace to the PR head, then decides each item through a worth-doing filter: fix (real and behavior-preserving — applied without asking), ask (changes something a caller could depend on — goes to the decision gate), answer-only, or decline with a reason (wrong-claim / over-engineering / out-of-scope / regression-risk / too-large) and an evidence-backed push-back. Every decline, and every fix whose read is contested, is re-checked by a fresh verifier before it counts. Two user gates: one multi-select over everything that changes behavior, one ship gate that authorizes commit + push + replies + thread resolution. Threads resolve only once the fix is in the pushed diff; a declined thread gets its reply and stays open.

/geniro:resolve #1234                         # work through an open PR's feedback
/geniro:resolve                               # infer the PR from the current branch

/geniro:debug — Scientific-method bug investigation

3-phase loop (Investigate → Propose → Ship). Phase 1 observes / hypothesizes / tests / isolates root cause; Phase 2 authors a text fix proposal + F→P reproduction test (no production-source edits); Phase 3 persists T2 handoff at .geniro/state/handoff/from-debug-<branch>.md and escalates to /geniro:implement. Stall gate (5 inconclusive → AUQ); fix-fail gate (2 attempts → AUQ); decision gates render the investigation context (root cause, evidence, fix options) as a self-contained chat explanation before a lean question. Phase 3 auto-emits L2 diagnosis with ext.{symptom, root_cause, fix}. Never ships code.

/geniro:debug login returns 500 after password reset
/geniro:debug memory leak in WebSocket handler after 1000 connections
/geniro:debug tests pass locally but fail in CI on the date formatting step

/geniro:refactor — Safe code restructuring

3-phase loop (Plan → Apply → Verify) with zero-behavior-change guarantee. Phase 1 classifies tier via canonical _shared/effort-scaling.md (Trivial / Small / Medium / Big); runs orchestrator-inline smell detection per _shared/refactor-patterns.md; HIGH-risk steps are approved from a rendered steps-flow + per-step risk summary before Phase 2 runs. Phase 2 runs orchestrator-inline per-step execution with per-step regression check + Blocked Step Protocol (3 retries → revert + continue). Phase 3 runs independent reviewer + custom reviewers; PRODUCT-DECISION → ESCALATE to /implement (3-option AUQ, rendered as a self-contained explanation in chat first). Auto-emits L2 discovery + pitfall. Never ships code — diff IS the deliverable; user commits manually or runs /geniro:implement.

/geniro:refactor extract payment logic from OrderService into PaymentService
/geniro:refactor consolidate duplicate validation across controllers
/geniro:refactor convert callback-based auth module to async/await

/geniro:onboard — Rapid codebase orientation

2-phase loop (Discover → Map). Scans codebase structure and produces <PRIMARY_ROOT>/.geniro/planning/_CODEBASE_MAP.md with the canonical 8-section template (underscore-prefixed L3 registry). Phase 1 applies a <=50-file scan cap (user-confirmable expansion via AUQ). Phase 2 calls update-semantic (bounded auto-incremental L3 write), emits L2 discovery, prints next-step suggestions (/plan / /investigate / /implement / _FEATURES.md). --focus / --depth retained as scope-limiters on the full 8-section template; --cap N raises the 50-file read budget.

/geniro:onboard
/geniro:onboard --focus api

/geniro:investigate — Deep codebase Q&A

3-phase loop (Classify+Scope → Investigate+Verify → Synthesize+Review+Present). Phase 1 classifies $ARGUMENTS into 9-type taxonomy + 5-step JIT retrieval cadence; pure external "docs lookup" questions suggest the native /deep-research workflow instead, while anything needing code or git evidence stays here. Phase 2 spawns 1-3 parallel research agents (Codebase Analyst / Git Historian / Internet Researcher — literal classified set, never over-spawned). Phase 3 synthesizes, spawns a fresh general-purpose verifier agent, presents with Sources + Open questions, and offers a dive-deeper follow-up. L2 discovery emit with trust label (verified if code-grounded; retrieved if WebFetch/WebSearch load-bearing). Never ships code.

/geniro:investigate how does the caching layer invalidate stale entries?
/geniro:investigate what happens when a WebSocket connection drops mid-transaction?
/geniro:investigate why was the ORM switched from Sequelize to Prisma?

/geniro:reflect — Session-history rule mining

On-demand session-history miner, in three input shapes. Empty selects the recent work-bearing sessions and a search string grep-matches the sessions that mention it — both locate past Claude Code transcripts on disk and spawn one read-only analyst per session. --this-session mines the session you are running in instead: nothing is read from disk, and the corrections are extracted inline because the running session lives only in the orchestrator's context. All three then synthesize one reflection-agent pass against the candidate bar + prior declines, so the judgment stays in an isolated agent either way. Approved candidates route per the improvement-routing ladder (CLAUDE.md / .claude/rules/ / .geniro/instructions/ / ADR / learnings); declines are recorded so they stop re-surfacing. Stateless; read-only until you approve a candidate — Phase 4 then writes only to that candidate's routed target. Zero candidates is a valid outcome. Mining past transcripts needs Claude Code's on-disk layout; --this-session reads no transcript and runs anywhere.

/geniro:reflect
/geniro:reflect ci-flakiness            # grep-match sessions touching a topic
/geniro:reflect --this-session          # mine the corrections from this running session

/geniro:instructions — Custom instruction management

Stateless CRUD loop (parse → execute → done) over .geniro/instructions/. 5 operations: list / create / edit / validate / delete. 13-scope set: global, code-style, memory, review-extra/<slug>, and per-skill (implement, plan, review, resolve, debug, refactor, onboard, investigate, reflect). validate mode: structural + reference + per-scope lint with CRITICAL/HIGH/MEDIUM/LOW severities; catches refs to dropped skills and outdated phase names.

/geniro:instructions list
/geniro:instructions create implement
/geniro:instructions create review-extra sql-bindings    # add a custom code-review dimension
/geniro:instructions validate
/geniro:instructions delete debug

/geniro:audit-instructions — AI-instruction audit

6-phase audit-and-fix pipeline over every AI-assistant instruction surface in the repo: CLAUDE.md (root + nested), AGENTS.md, .cursor/rules + legacy .cursorrules, Copilot / Windsurf / Cline / Gemini / Aider / Junie / Zed / Amazon Q files, and .geniro/instructions/. Deterministic pre-pass (surface discovery, cited-path + command existence, .mdc/.instructions.md/skill/agent frontmatter validity, activation reachability, legacy-format detection, secret scan — values never captured — and an unsafe-directive scan), then 5 parallel dimension reviewers (accuracy vs repo reality / cross-tool consistency / bloat & over-constraint / structure & scoping / coverage & safety), orchestrator re-verification of every cited line, tiered report (persisted to .geniro/state/audit-instructions/report-<date>.md, which seeds the next run's do-not-flag list), then an action gate — approved fixes go to fix agents with disjoint file allowlists, 1 fix round, battery re-run, commit offer. The subtraction sweep runs on every audit and reports what it examined even when empty; a proposal to remove a whole instruction file or section gets its own gate with its own evidence, never a blanket approval; secrets are cited by location and shape, never quoted.

/geniro:audit-instructions                # full audit
/geniro:audit-instructions cursor         # one tool's surfaces only
/geniro:audit-instructions --quick        # mechanical pre-pass only

/geniro:actions — Custom workflow-helper management

Stateless CRUD + runner loop (parse → execute → done) over .geniro/actions/. 6 operations: list / create / edit / run / delete / validate. risk_class: low | medium | high mandatory frontmatter field; run mode executes the action directly with no confirmation gate — invoking it is the authorization, and risk_class is metadata for the list view, delete warning, and lint. validate mode shares only its three description: quality-check rows with /instructions validate review-extra — both cite skills/_shared/description-quality.md as their source; the rest of the check set is actions-specific. L2 discovery emit on successful runs with external-send: true.

/geniro:actions list                                       # show all custom actions
/geniro:actions create pr-notify-slack                     # interview-driven scaffold
/geniro:actions edit pr-notify-slack                       # external edit + re-validate
/geniro:actions run pr-notify-slack 1234                   # invoke by exact slug + args
/geniro:actions run "post release notes k slack"          # invoke by free-text (picker)
/geniro:actions pr-notify-slack 1234                       # bare-slug fast path (defaults to run)
/geniro:actions validate                                   # lint all .geniro/actions/*.md
/geniro:actions delete pr-notify-slack

When invoked from a linked git worktree, run falls back to the main worktree's registry (with confirmation); edit/delete operate on the main-repo copy (with the delete confirmation; a lean question appears only when a differing branch-local copy also exists).

/geniro:update — Update plugin

4-phase stateless loop (Pre-check → Update → Post-check → Migration). Pre-update version-confirm AUQ. User-content snapshot at Pre-check + survival diff at Post-check (catches silent corruption). Bounded exponential-backoff retry on network errors. Hash-check sanity mode. Phase 4 MIGRATION.md reader — for each user-affected breaking change, offers "Fix it for me (Recommended)" / "Show me how to fix" / "Skip for now" / "Cancel walk"; "Fix it for me" runs only the maintainer-written Auto-fix: command for that entry, then re-verifies. Restart-session warning always emitted.

/geniro:update
/geniro:update --dry-run                     # preview without invoking update

Flags & presets

Some skills take flags and modifiers that change how a run behaves. Most answer a setup question in advance so the run starts without stopping; a few change what the run does and ask nothing either way. None of them touches the safety gates (adopting a new dependency, blowing past the planned scope, unresolved questions from a prior review, a real merge conflict, pushing to a shared branch) — those always stop for you regardless of any flag.

• /geniro:plan — --artifact (build a live visual plan page). Plan also accepts the implement launch modifiers (worktree / no-worktree / current-branch / new-branch, the ship choices don't push / draft only / ready-for-review / stop after review, and freshness:merge|rebase|skip) and saves them into the spec so /geniro:implement runs hands-free. With none passed, a question right after you approve the plan offers the same choice: use the recommended settings, pick each one, or leave them for /geniro:implement to ask.
• /geniro:implement — workspace (new-branch / current-branch / worktree / no-worktree), --no-adversarial (skip the inline edge-case test-authoring step), --subagent-model (name the tier this run reasons at), and ship choices (don't push / draft only / ready-for-review / stop after review). A spec written by /plan can pre-answer the setup choices among these at once.
• /geniro:review — --plan <path> (check the diff against a spec), --focus <text> (steer this round toward what you name), --subagent-model (name the tier this run reasons at), and the workspace modifiers.

Full catalog for /geniro:plan, /geniro:implement and /geniro:review — every flag, the values it takes, and how it changes where the run stops to ask you something — in skills/_shared/flags-reference.md; that file covers those three skills only. Flags on the other skills are declared in each skill's argument-hint and documented in its body (e.g. /geniro:onboard --focus api).

Skills deleted

The current skill set absorbed or dropped 8 earlier skills:

Deleted	Replacement
/geniro:brainstorm	Merged → /geniro:plan
/geniro:decompose	Merged → /geniro:plan (milestones as output mode)
/geniro:follow-up	Absorbed → /geniro:implement (handles any size via spec input)
/geniro:deep-simplify	Dropped — covered by /geniro:review standard dimensions
/geniro:features	Manual _FEATURES.md
/geniro:learnings	Auto-step in /geniro:implement Phase 3 + every pipeline skill
/geniro:cleanup	Dropped — niche
/geniro:vendor	Dropped — no cloud-runner requirement

Hooks

All hooks run automatically after installation. The plugin ships no broad command-string guards — the git, file-protection, deletion, state-helper, and security-scan guards were removed because they mostly blocked legitimate work (HOOKS.md §Removed guards).

Hook	What it does
.geniro/ force-add guard	Blocks git add -f on .geniro/ paths, which would put ignored files one "Discard All Changes" click from deletion. Bypass: git-add-force-geniro in .geniro/safety.json allow_patterns
Session-start restore	SessionStart hook (matcher: "compact|resume|startup") re-injects active task state.md + L4 instructions set + CLAUDE.md so context survives compaction

Updating

The plugin does not update itself unless you opt in — see Staying up to date above for the autoUpdate marketplace setting and its tradeoff. To update manually:

claude plugin update geniro@geniro-claude-harness

Or run /geniro:update inside Claude Code — preserves user content, walks any breaking changes in MIGRATION.md, and emits a restart-session warning.

The status line shows an arrow when your version is behind, and names the step that actually closes the gap:

• ⬆ 5.6.2 /reload-plugins — the new version is already on disk. A background auto-update landed it after this session started, so there is nothing left to fetch; the session just has to pick it up.
• ⬆ 5.6.2 /geniro:update — the release has not been fetched yet.

Using with Cursor

The repository ships runtime ports for Cursor under cursor/: cursor/skills/ — generated geniro-<slug>-prefixed copies of the 14 skills, prefixed because Cursor has no plugin namespace and some bare names collide with its built-ins or reserved CLI commands; cursor/agents/ — generated Cursor-frontmatter copies of the 7 agents; cursor/hooks.json — the safety and session-restore hooks adapted through cursor/hooks/claude-hook-shim.sh. Install with scripts/install-cursor.sh, which symlinks these into your Cursor user profile (~/.cursor/skills/, ~/.cursor/agents/) — not as a Cursor plugin: cursor-agent's CLI and ACP load no plugin components at all, so a plugin install leaves those surfaces with none of this. Driven over ACP, cursor-agent never reads ~/.cursor/agents/ — only Cursor's built-in agents and the workspace's own reach it — so the profile install's agent piece reaches the IDE and cursor-agent -p only, and an ACP run spawns through the general-purpose fallback. Full install steps, what works, and what stays Claude-Code-only (/reflect's past-session shapes, /update, structured decision gates): cursor/README.md.

Using with Codex

The plugin installs on OpenAI Codex — the CLI and the ChatGPT desktop app — straight from the same marketplace, with no port or build step. The Codex IDE extension does not support plugins.

codex plugin marketplace add geniro-io/geniro-claude-harness
codex plugin add geniro@geniro-claude-harness

/geniro:setup and /geniro:update both offer to install Geniro into Codex when the codex CLI is present and Geniro isn't installed there yet.

You can also browse it from /plugins inside Codex.

• Invoking. Skills run with $, not /: $geniro:implement <task>, or pick one from the /skills list. Codex applies a skill only in the turn that names it, so when a gate asks a question in chat, answer with the skill name plus your choice ($geniro:implement B).
• Hooks. Codex loads the plugin's hooks but runs them only after you trust them in /hooks, and asks again when a hook changes. Until then they do not fire, and the skills apply the same checks themselves.
• Agents. Codex plugins cannot ship agents, so each Geniro agent runs as Codex's default subagent with the agent's instructions passed in (on your session model, or the host's smallest or mid current model for light work, per skills/_shared/model-tiering.md §Runtime resolution); they follow the same contracts, with tool restrictions stated as instructions rather than enforced. Codex runs only a few subagents at once (3 by default), so wide parallel reviews run in waves and take longer.
• Project rules. Codex reads AGENTS.md, not CLAUDE.md or .claude/rules/. To have it load a project's CLAUDE.md where no AGENTS.md exists, add project_doc_fallback_filenames = ["CLAUDE.md"] to ~/.codex/config.toml. The skills that need .claude/rules/ files read them directly.
• Updating. A GitHub install (the commands above) updates with codex plugin marketplace upgrade geniro-claude-harness, which reinstalls the installed plugin from the refreshed marketplace. An install /geniro:setup or /geniro:update made, from Claude Code's local marketplace checkout, refreshes through /geniro:update, or by hand with codex plugin add geniro@geniro-claude-harness.
• Don't use /import. Codex's Claude importer copies only the skill folders into .agents/skills, away from the plugin's shared files, and rewrites "claude" in the text as it goes: .claude-plugin/plugin.json — the marker every skill uses to find the plugin root — becomes .Codex-plugin/plugin.json, and .claude/rules/ becomes .Codex/rules/. Install it as a plugin.
• Claude-Code-only. geniro:update, and geniro:reflect given a search string or no argument — both read Claude Code's own on-disk data. --this-session reflect works.

Plugin Structure

geniro/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest
│   └── marketplace.json         # Marketplace manifest (plugin source entry)
├── agents/                      # 7 specialized agent definitions (reviewer / finding-verifier / knowledge-retrieval / codebase-explorer / codebase-research / reflection / test-runner)
├── skills/                      # 14 reusable workflow definitions
│   ├── setup/                   # AI-driven project setup
│   ├── plan/                    # spec-first planning
│   ├── implement/               # autonomous implementation
│   ├── review/                  # multi-dim code review
│   ├── resolve/                 # PR feedback → decided and fixed
│   ├── debug/                   # scientific-method investigation
│   ├── refactor/                # zero-behavior-change restructuring
│   ├── onboard/                 # codebase mapping
│   ├── investigate/             # codebase Q&A
│   ├── reflect/                 # session-history rule mining
│   ├── instructions/            # L4 rules CRUD
│   ├── audit-instructions/      # AI-instruction audit & fix
│   ├── actions/                 # workflow-helper CRUD + runner
│   ├── update/                  # plugin update
│   └── _shared/                 # canonical helpers (atomic-state-write, spawn-agent,
│                                # load-custom-instructions, query/emit-learnings, etc.)
├── hooks/                       # force-add guard + session restore + statusline + update check (roster: HOOKS.md §Hook scripts)
│   ├── hooks.json               # Hook configuration
│   ├── geniro-check-update.js   # Update detection (SessionStart)
│   ├── geniro-statusline.js     # Status line renderer
│   └── *.sh                     # Guard, session-restore, and backpressure scripts
├── lib/                         # shell helpers the skills and hooks source
│                                # (atomic-state-write, validate-state-file,
│                                # emit/query-learnings, load/update-semantic, ...)
├── .cursor-plugin/plugin.json   # Cursor manifest (points at cursor/)
├── cursor/                      # Cursor runtime port
│   ├── skills/                  # generated geniro-<slug> skills (scripts/build-cursor-skills.sh)
│   ├── agents/                  # generated Cursor-format agents (scripts/build-cursor-agents.sh)
│   ├── hooks.json               # Cursor hook wiring (camelCase events)
│   └── hooks/claude-hook-shim.sh# Cursor→Claude hook I/O adapter
├── ARCHITECTURE.md              # Consolidated design decisions (state/memory/skills)
├── CLAUDE.md                    # Plugin instructions (auto-loaded)
└── MIGRATION.md                 # Per-release breaking-change notes (consumed by /update)

Credits

Patterns synthesized from analysis of: Metaswarm, GSD, Citadel, claude-pipeline, ECC, SuperClaude, Orchestrator Kit, Claude Forge, gstack, OMC, Beads, Ruflo, and the official Claude Code /code-review plugin.

License

Apache License 2.0

---

Made with care by the Geniro team.