kirei

A specialized agent team for Claude Code. Automated research → execute workflow with domain-specific specialists.

Agents

Research agents (analyse, prescribe, hand off)

Each research agent writes its findings to its own folder under docs/, so reports stay organised by domain instead of piling up in one place.

Execute & review agents

Skills

/kirei flags

/kirei-prism flags

/kirei-deps flags

/kirei-audit flags

/kirei-showcase flags

How it works

flowchart TD
    skill(["/kirei:kirei task"])

    skill --> detect{auto-detect\ntype}

    detect -->|general| kirei[kirei-research\nsonnet · cyan]
    detect -->|security| sec[kirei-security\nopus · red]
    detect -->|ui| ui[kirei-ui\nsonnet · magenta]
    detect -->|refactor| ref[kirei-refactor\nsonnet · yellow]
    detect -->|perf| perf[kirei-perf\nsonnet · cyan]
    detect -->|arch| arch[kirei-arch\nsonnet · blue]
    detect -->|test| test[kirei-test\nsonnet · green]
    detect -->|migrate| mig[kirei-migrate\nsonnet · yellow]
    detect -->|review| rev[kirei-review\nsonnet · cyan]
    detect -->|debug| dbg[kirei-debug\nopus · red]
    detect -->|data| data[kirei-data\nsonnet · blue]
    detect -->|observability| obs[kirei-observability\nsonnet · cyan]
    detect -->|bundle| bun[kirei-bundle\nsonnet · yellow]
    detect -->|license| lic[kirei-license\nsonnet · yellow]
    detect -->|error| err[kirei-resilience\nsonnet · red]
    detect -->|eval| ev[kirei-eval\nsonnet · green]

    kirei-research --> findings
    sec --> findings
    ui --> findings
    ref --> findings
    perf --> findings
    arch -->|advisory only| findings
    test --> findings
    mig --> findings
    rev --> findings
    dbg --> findings
    data --> findings
    obs --> findings
    bun --> findings
    lic --> findings
    err --> findings
    ev --> findings

    findings([docs/<category>/\nYYYY-MM-DD-slug.md])

    findings -->|simple scope| stitch[kirei-stitch\nsonnet · green]
    findings -->|complex scope| loom[kirei-loom\nopus · yellow]
    arch -->|no code changes| done
    findings -->|--research-only| done

    stitch --> done([changes implemented\n+ verified])
    loom --> done

1. /kirei auto-detects task type and complexity (stitch/loom)
2. Spawns the appropriate kirei-* research agent
3. Research agent investigates, validates findings with the user via AskUserQuestion, writes docs/<category>/YYYY-MM-DD-<slug>.md in the target repo (one folder per agent — see table above), and produces a structured handoff
4. Spawns kirei-stitch (sonnet) or kirei-loom (opus) with the handoff (skipped if --research-only)
5. Execute agent implements and verifies

Multi-lens (/kirei-prism)

flowchart TD
    chain(["/kirei-prism task"])
    chain --> lenses{detect\nlenses}
    lenses -->|in parallel| a[kirei-security]
    lenses -->|in parallel| b[kirei-perf]
    lenses -->|in parallel| c[kirei-arch]
    a --> merge[merge findings]
    b --> merge
    c --> merge
    merge --> combined([docs/chain/\nYYYY-MM-DD-slug.md])
    combined -->|user decides next move| user([user runs /kirei or /kirei type])

Use when one question needs more than one perspective. Capped at 4 parallel agents. Research-only by design — the merged report points the user (or a follow-up /kirei) to the highest-leverage fixes.

Code-quality audit (/kirei-audit)

flowchart TD
    audit(["/kirei-audit"])
    audit --> depth{ask depth\nquick/standard/deep}
    depth --> scout[scout pass\nsize repo → agent count]
    scout -->|1 agent| q[full-spectrum pass]
    scout -->|≤3 by category| s[dead-code+dup · god-files · consistency]
    scout -->|≤6 by region| d[one agent per module]
    q --> merge[merge → ordered plan]
    s --> merge
    d --> merge
    merge --> plan([docs/audit/\nYYYY-MM-DD-slug.md])
    plan --> fix{fix in order?}
    fix -->|yes, sequential| exec[kirei-stitch / kirei-loom\nphase by phase, verify between]
    fix -->|--research-only| done([plan only])
    exec --> done2([cleanup applied\n+ verified])

Depth caps the parallel agent budget (1 / 3 / 6); a scout pass sizes the real count to the repo. Audit runs in parallel; fixing runs sequentially, phase by phase in dependency order (dead code → extractions → consolidations → conventions → god-file splits → best-practice fixes), verifying typecheck/tests between each.

PR comment workflow (kirei-review --address-pr-comments)

flowchart LR
    invoke(["/kirei review --address-pr-comments 123"])
    invoke --> fetch[fetch PR comments\nvia gh]
    fetch --> classify{classify each\ncomment}
    classify -->|valid| toFix[hand to kirei-stitch/loom\nto address]
    classify -->|invalid / misread| reply[suggest reply text\nuser posts manually]
    classify -->|out of scope| follow[recommend follow-up issue]
    classify -->|nit| optional[optional, only if user asks]

The agent never pushes commits or posts comments — it produces a triage report; you decide what lands.

Parallel execution (/kirei-wave)

flowchart TD
    wave(["/kirei-wave --findings|--audit|--map|--slices"])
    wave --> slice[normalize slices\nscope · issue · complexity · files]
    slice --> plan[plan waves\ndisjoint files per wave]
    plan --> spawn[spawn 1 worktree builder / slice\nkirei-stitch / kirei-loom]
    spawn --> pr[bootstrap → implement → gate battery\n→ commit no-attribution → open PR Closes #N]
    pr --> gate{CI green?\nattribution clean?\ngate surfaces justified?\nkirei-gate: MERGE?}
    gate -->|all yes| merge[merge in dependency order]
    gate -->|any no| hold[HOLD → back to builder or user]
    merge --> ledger([.kirei/wave-YYYY-MM-DD.md])

Turns a set of PR-sized slices into worktree-isolated builders, one per PR, then gates each PR (CI + attribution grep + gate-surface intersection + an adversarial kirei-gate review) and merges in dependency order. Never runs parallel worktrees on files that overlap; keeps a ledger so the plan survives context compaction. Feeds naturally from /kirei findings, /kirei-audit phases, or a wayfinder map.

Builders stop early instead of churning: 5 fix cycles on one failure, or 6 gate runs with an unchanged failure set, ends the slice with a named blocker. Every builder return carries a failure_class from a fixed list, and the wave report tallies them. templates/lane-spec.md holds the same stop rules, failure classes and gate-surface list as drop-in blocks for hand-written lane briefs.

Reviewer recall (scripts/review-eval/)

How often does kirei-gate catch a real bug? scripts/review-eval/harness.py replays real fixes from a project's history (the commit that introduced each bug, or a revert of its fix), runs the reviewer in an isolated repo that cannot see the fix, and scores grounded findings against the lines the fix changed. It reports recall with a Wilson interval and compares reviewer variants with a z-test and an exact McNemar test. It runs on demand, not in CI. See scripts/review-eval/README.md for the method and the first measurement, and scripts/review-eval/PANEL-DESIGN.md for the designed (not built) non-Claude second reviewer.

Install

As a Claude Code plugin (recommended)

Add the kirei marketplace, then install the plugin:

/plugin marketplace add Shironex/kirei
/plugin install kirei@kirei
/reload-plugins

Once installed, the skill is invoked as:

/kirei:kirei [task description]

Manual install (global, standalone)

Agents and skills go directly into your global ~/.claude/ directories — no marketplace needed. Skills are directories (~/.claude/skills/<name>/SKILL.md), so copy the whole skills/ tree, not a single file. Skills then invoke as /kirei, /kirei-prism, /kirei-wave, etc.

git clone https://github.com/Shironex/kirei.git
cp kirei/agents/*.md ~/.claude/agents/
cp -R kirei/skills/* ~/.claude/skills/
cp -R kirei/scripts ~/.claude/skills/kirei/scripts   # optional: the write-findings helper (set CLAUDE_PLUGIN_ROOT or rely on the per-agent fallback)

Standalone installs have no CLAUDE_PLUGIN_ROOT, so agents fall back to mkdir -p docs/<category> + the Write tool for findings — the plugin install is the smoother path.

Local development / testing

claude --plugin-dir ./kirei

Updating

Plugin install:

/plugin marketplace update kirei
/reload-plugins

Manual install: pull latest and re-run the copy commands.

Design decisions

• Ref MCP for docs — agents use mcp__Ref__ref_* for library documentation; falls back to WebSearch if unavailable. context7 is not used.
• AskUserQuestion after investigation — findings are validated with the user once analysis is complete, not before. Prevents scope conversations from slowing down clear tasks.
• Findings persistence, organised by domain — every investigation writes to docs/<category>/YYYY-MM-DD-<slug>.md in the target repo (one folder per agent: docs/security/, docs/perf/, docs/refactor/, docs/test/, docs/migrate/, docs/review/, docs/debug/, docs/data/, docs/arch/, docs/ui/, docs/observability/, docs/bundle/, docs/license/, docs/error/, docs/eval/, docs/chain/, docs/audit/, docs/discuss/, docs/showcase/, plus docs/research/ for the general agent). Findings survive across sessions and stay sorted instead of piling up in one folder.
• Two execute tiers — kirei-stitch (sonnet) for focused changes, kirei-loom (opus) for complex multi-file work. Research agent recommends which; orchestrator skill decides.
• Skill = front door, agent = engine — /kirei-deps, /kirei-sentry and /kirei-showcase are skills that gather decisions and orchestrate; the same-named kirei-deps / kirei-sentry / kirei-showcase agents are the research engines they spawn. New additions should follow this split deliberately.
• Findings folders are stable labels — a couple of agents keep their original findings-folder name after a rename so historical reports stay put: kirei-resilience writes to docs/error/, and the /kirei-prism skill merges into docs/chain/.

{
  "name": "kirei",
  "owner": {
    "name": "Shironex",
    "email": "support@shirone.dev"
  },
  "metadata": {
    "description": "Kirei — specialized research + execute agent team for Claude Code"
  },
  "plugins": [
    {
      "name": "kirei",
      "source": {
        "source": "github",
        "repo": "Shironex/kirei"
      },
      "description": "Specialized research + execute agent team. /kirei auto-detects task type (security, UI, refactor, performance, architecture, test, migrate, review, debug, data, deps, observability, bundle, license, resilience, eval, or general via kirei-research) and complexity, spawns the right specialist to investigate, then an execute agent — kirei-stitch (focused) or kirei-loom (multi-file) — to implement. Also: /kirei-prism (parallel multi-lens research), /kirei-audit (depth-tunable code-quality audits with ordered fixes), /kirei-deps (Dependabot-aware dependency-safety audits), /kirei-sentry (production Sentry setup), /kirei-showcase (a showcase README with reproducible screenshots via @noctcore/showcase-kit), /kirei-templatize (repo to starter template), /kirei-discuss (pre-code idea audit), and /kirei-wave (worktree-parallel multi-slice execute: fan-out builders, run the gate battery, open PRs, gate each with the read-only adversarial kirei-gate reviewer, then merge in dependency order). kirei-resilience audits error handling.",
      "version": "2.1.0",
      "author": {
        "name": "Shironex",
        "email": "support@shirone.dev"
      },
      "homepage": "https://github.com/Shironex/kirei",
      "repository": "https://github.com/Shironex/kirei",
      "license": "MIT",
      "keywords": [
        "agents",
        "research",
        "security",
        "refactoring",
        "performance",
        "ui-ux",
        "architecture",
        "testing",
        "migration",
        "code-review",
        "debugging",
        "database",
        "dependencies",
        "dependabot",
        "audit",
        "cve",
        "template",
        "scaffold",
        "observability",
        "bundle-size",
        "license-compliance",
        "error-handling",
        "evals",
        "ideation",
        "code-quality",
        "code-smells",
        "dry",
        "god-files",
        "dead-code",
        "technical-debt",
        "sentry",
        "error-tracking",
        "crash-reporting",
        "monitoring",
        "source-maps",
        "worktree",
        "parallel-execution",
        "merge-gate",
        "adversarial-review",
        "pull-requests",
        "readme",
        "screenshots",
        "showcase"
      ],
      "category": "development-workflows"
    }
  ]
}