Agents
Agents Reference
The complete agent roster: core pipeline, support, Jira, and Confluence agents, with type, role, phase, and activation conditions.
MeowKit's agents fall into four categories: core pipeline agents, support agents, Jira integration agents, and Confluence Cloud integration agents. Each owns a specific phase or concern, and no two agents modify the same file type. The sections below are the roster; a count here would only go stale against it.
Core Agents
Pipeline agents that execute sequentially through phases 0-6.
| Agent | Phase | Role | Auto-activates |
|---|---|---|---|
| orchestrator | 0 | Task router, complexity classification, model tier assignment | Every task |
| planner | 1 | Scope-adaptive planning, Gate 1, bead decomposition | Standard/complex tasks |
| architect | 1 | ADRs, system design | Complex tasks |
| tester | 2 | Test writing (TDD red/green/refactor) | After planning |
| security | 2, 4 | Security audit, BLOCK verdicts | Auth/payment changes |
| developer | 3 | Implementation, bead processing | After tester |
| evaluator | 3, 4 | Behavioral verification, rubric grading | Harness pipeline, mk:evaluate |
| reviewer | 4 | 5-dimension structural audit, Gate 2 | After developer |
| shipper | 5 | Deploy pipeline, PR creation | After Gate 2 |
| documenter | 6 | Living docs, changelogs | After ship |
| analyst | 0, 6 | Cost tracking, pattern analysis | Session start/end |
| project-manager | on-demand | Cross-workflow delivery tracking, status reports | On request via /mk:status |
Support Agents
Invoked on-demand by core agents or explicitly by the user.
| Agent | Phase | Role | Subagent type |
|---|---|---|---|
| brainstormer | 1 | Trade-off analysis, solution exploration | advisory |
| researcher | 0, 1, 4 | Technology research, library evaluation | advisory |
| ui-ux-designer | 3 | UI design, accessibility, design systems | advisory |
| git-manager | 5, any | Git operations, conventional commits | utility |
| journal-writer | 6 | Failure documentation, root cause analysis | escalation |
Jira Agents
Domain agents for Jira integration via the jira-as CLI wrapper. All share a 4-tier safety model and follow the Rule of Two.
| Agent | Role | Safety highlight |
|---|---|---|
| jira-issue | Single-issue CRUD (create, read, update, delete) | 4-tier graduated confirmation |
| jira-search | JQL queries, filter management, result export | Mandatory JQL sanitization |
| jira-lifecycle | Transitions, assignments, versions, components | Workflow discovery before transitions |
| jira-collaborate | Comments, attachments, watchers, notifications | Internal-vs-public comment gate |
| jira-relationships | Issue links, blockers, dependencies, clones | Semantic link type enforcement |
| jira-time | Work logging, estimates, time reports | Confirm before worklog edits/deletes |
| jira-agile | Sprints, epics, backlog, story points, velocity | Board ID ≠ Project Key validation |
| jira-fields | Custom field discovery and caching | Read-only by default; admin for config |
| jira-bulk | Bulk transition, assign, priority, clone, delete | Mandatory dry-run for all operations |
| jira-jsm | Service desks, requests, SLAs, approvals | JSM license + agent role required |
| jira-admin | Projects, users, groups, schemes, automation | 2-step token confirmation for deletes |
| jira-dev | Branch names, PR descriptions, commit links | Read-only, output generation only |
| jira-ops | Cache management, connectivity, project context | Diagnostic-only, no Jira state changes |
| jira-evaluator | Ticket complexity scoring (8 dimensions) | Read-only analysis |
| jira-estimator | Story point estimation with reasoning | Read-only, never sets points |
| jira-analyst | Full context analysis with media and linked issues | Read-only, processes attachments |
Confluence Agents
Domain agents for Confluence Cloud integration via the confluence-as CLI wrapper. Cloud-only (the wrapper exits 3 on non-*.atlassian.net URLs); follow the Rule of Two.
| Agent | Role | Safety highlight |
|---|---|---|
| confluence-page | Single-page CRUD + hierarchy + version + copy/move | 4-tier graduated confirmation; ADF-round-trip warning on macro-heavy bodies |
| confluence-search | CQL queries, validation, space listing, saved filters, export | Mandatory CQL sanitization for any user-derived term |
| confluence-spec-analyst | Read-only deep spec analysis with macro-aware ADF fetch + persisted Spec Research Report | Read-only at Confluence side; [UNHANDLED_NODE] keys-only metadata blocks injection |
| confluence-bulk | Bulk-label / bulk-move / bulk-delete on 10+ pages | Mandatory 3-step dry-run + typed-token confirmation |
| confluence-collaborate | Comments, attachments, labels, watchers per page | Footer-default for comments; path-traversal guard on uploads |
Agent communication
All subagents report structured status on completion:
**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
**Summary:** [1-2 sentences]
**Concerns/Blockers:** [if applicable]File ownership
No two agents modify the same file type. Conflicts escalate to human.
| File type | Owned by |
|---|---|
src/, lib/, app/ | developer |
tasks/plans/ | planner |
tasks/reviews/ | reviewer |
docs/ | documenter |
.meowkit/memory/ (curated stores), .meowkit/telemetry/ (cost log, trace log) | analyst, documenter |
See also
- How agents and skills work together
- Workflow phases
- Skills reference
- Agent definitions on disk — canonical source
Every agent
Generated from .claude/. Every agent on disk appears here; the sections above group the ones you reach for most.
| Agent | What it does |
|---|---|
advisor | Isolated advisory executor for mk:advise. Interviews one question at a time, confirms a reframing of the user's problem, then delivers a single honest recommendation packet. Invoked ONLY by mk:advise — never routed to directly by the orchestrator, and never as a lifecycle phase owner. Examples: "What should I do about our slow build?", "Advise me on splitting this service.", "Am I approaching this migration right?" |
analyst | Cost and learning analysis agent that tracks token usage, generates cost reports, extracts patterns from sessions, and maintains institutional memory. Invoked on session end only by its owning workflow, or on demand via /mk:budget. Not for implementation, planning, or review decisions. |
architect | System design specialist for architectural tradeoff evaluation and ADR generation. Use when tasks touch database schema, new service boundaries, auth systems, API contracts, or infrastructure. Also use for any task classified as complex by the orchestrator. Not for implementation or routine planning. |
athena | Strategic intelligence and lifecycle supervision. At --advice checkpoints, Athena supervises ONE delivery run across GUIDE, RESCUE, REVIEW and RECHECK. Where a runtime exposes it, direct Athena is a stateless strategy consult for trade-offs, judgement and a recommended operational decision. It returns evidence-backed assessment, recommendation and directive, may return work to its executor for correction, but holds no gate authority, writes nothing, and never interviews the user. Examples: "which architecture trade-off should we choose within this approved scope?", "two fix approaches failed on an evidenced root cause — what next?", "verification passed; does the evidence actually cover the acceptance criteria?" |
brainstormer | Use this agent when you need to brainstorm software solutions, evaluate architectural approaches, or debate technical decisions before implementation. Examples: "Should I use WebSockets or SSE for real-time?", "What's the best approach for file uploads?", "Evaluate REST vs GraphQL for our API." Use proactively during Phase 1 (Plan) when the task involves significant technical decisions or multiple viable approaches. Not for implementation or final decisions. |
confluence-bulk | Execute bulk Confluence operations on 10+ pages via the confluence-as CLI wrapper: bulk-label, bulk-move, bulk-delete. Dry-run is MANDATORY first. Routed by mk:confluence-bulk skill. NOT for single-page ops (confluence-page); NOT for comments/attachments (confluence-collaborate). |
confluence-collaborate | Manage Confluence collaboration surface: comments, attachments, labels, watchers. Routed by mk:confluence-collaborate skill. NOT for page CRUD (confluence-page); NOT for bulk ops (confluence-bulk). |
confluence-page | Execute Confluence page CRUD + hierarchy + version ops via the confluence-as CLI wrapper. Use for: 'create page in SPACE', 'show page 12345', 'update page', 'delete page', 'children/ancestors of page'. Routed by mk:confluence-page skill. NOT for bulk ops (confluence-bulk); NOT for spec analysis (confluence-spec-analyst); NOT for comments/attachments/labels (confluence-collaborate). |
confluence-search | Find Confluence pages by criteria via the confluence-as CLI wrapper. Use for: 'search confluence', 'find pages where X', 'export search results', CQL filter management, space list/get. Routed by mk:confluence-search skill. NOT for single-page CRUD (confluence-page); NOT for bulk write ops (confluence-bulk). |
confluence-spec-analyst | Read full Confluence spec page (+ children + images) and produce structured Spec Research Report with requirements, acceptance criteria, gaps, ambiguities, suggested user stories. Read-only via the confluence-as CLI wrapper. Routed by mk:confluence-spec-analyst skill. NOT for raw page CRUD (confluence-page); NOT for ticket complexity scoring (planning-engine). |
developer | Implementation agent that writes production code following approved plans. TDD is opt-in via --tdd / MEOWKIT_TDD=1: when enabled, never writes code until failing tests exist; when disabled (default), implements directly per the approved plan. Use in Phase 3. Self-heals up to 3 times on test failures. Not for unapproved planning or shipping. |
documenter | Living documentation agent that keeps project docs in sync with the codebase. Generates changelogs, updates API docs, and syncs documentation after every feature completion. Use in Phase 6 (Reflect) after shipping. Not for production source or architecture records. |
evaluator | Behavioral active-verification agent. Phase 3 (active verifier: drives the running build against rubric criteria with browser/curl/CLI evidence) + Phase 4 (contract reviewer: critiques sprint contracts for testability before code is written). Distinct from reviewer (which audits code structure) — evaluator runs the actual built artifact. Skeptic by default — assumes bugs exist and refuses static-only PASS verdicts. Not for structural review verdicts. |
explore | Fast, read-only agent optimized for searching and analyzing codebases. Use when locating code, tracing how a feature or bug path actually works, or building repo orientation before unfamiliar work. Examples: "Where is the session timeout enforced?", "What calls createInvoice?", "How is the webhook wired end to end?" Use proactively before planning or reviewing unfamiliar code. Not for implementation, plans, or review verdicts — it reports findings and never writes files. |
git-manager | Stage, commit, and push code changes with conventional commits. Use when user says "commit", "push", or finishes a feature/fix. Does NOT create PRs or run CI — that's the shipper's job. Not for deployment orchestration. |
jira-admin | Execute JIRA project + user + group + scheme + automation administration via the jira-as CLI wrapper (11 sub-domains, ~65 verbs). Routed by mk:jira-admin skill. Requires Jira admin role. NOT for per-issue ops (jira-issue / jira-lifecycle); NOT for JSM admin (jira-jsm). |
jira-agile | Manage JIRA agile surfaces via the jira-as CLI wrapper: epics, sprints, backlog, ranking, story points, subtasks, velocity. Routed by mk:jira-agile skill. NOT for issue CRUD (jira-issue); NOT for issue links (jira-relationships); NOT for time tracking (jira-time). |
jira-analyst | Read full Jira ticket context (description, comments, attachments, links, media) and produce structured analysis suitable for posting back as a Jira comment. Read-only via the jira-as CLI wrapper. Routed by mk:jira-analyst skill. NOT for complexity scoring (jira-evaluator); NOT for story-point estimation (jira-estimator). |
jira-bulk | Execute bulk JIRA operations on 10+ issues via the jira-as CLI wrapper: bulk transition, assign, set-priority, clone, delete. Dry-run is MANDATORY first. Routed by mk:jira-bulk skill. NOT for single-issue ops (jira-issue / jira-lifecycle); NOT for bulk-update by JQL field changes (jira-search bulk-update — same dry-run discipline). |
jira-collaborate | Manage JIRA collaboration surface: comments, attachments, watchers, notifications. Routed by mk:jira-collaborate skill. NOT for issue CRUD (jira-issue); NOT for issue links (jira-relationships); NOT for transitions (jira-lifecycle). |
jira-dev | Generate developer artifacts from JIRA tickets via the jira-as CLI wrapper: branch names, PR descriptions, parsed commits, commit/PR-to-issue links. Routed by mk:jira-dev skill. NOT for executing git/gh commands (mk:ship); NOT for issue CRUD (jira-issue). |
jira-estimator | Heuristic story-point estimation for a single Jira ticket via the jira-as CLI wrapper. Read-only. Routed by mk:jira-estimator skill. NOT for complexity/inconsistency analysis (jira-evaluator); NOT for full RCA (jira-analyst). |
jira-evaluator | Analyze a single Jira ticket for complexity + inconsistencies via the jira-as CLI wrapper. Read-only. Routed by mk:jira-evaluator skill. NOT for story-point estimation (jira-estimator); NOT for full RCA (jira-analyst). |
jira-fields | Discover and configure JIRA custom fields via the jira-as CLI wrapper: list fields, find field IDs, check per-project field availability, configure agile field mappings. Routed by mk:jira-fields skill. NOT for setting per-issue field values (jira-issue update); NOT for project admin (jira-admin). |
jira-issue | Execute JIRA issue CRUD via the jira-as CLI wrapper. Use for: 'create bug/task/story', 'show me PROJ-123', 'update issue', 'delete PROJ-123'. Routed by mk:jira-issue skill — receives task brief via skill-content injection. NOT for transitions (jira-lifecycle); NOT for comments/attachments (jira-collaborate); NOT for bulk ops on 10+ issues (jira-bulk); NOT for issue links (jira-relationships); NOT for time logging (jira-time); NOT for sprint/epic (jira-agile). |
jira-jsm | Execute JIRA Service Management operations via the jira-as CLI wrapper: service desks, request types, requests, customers, organizations, queues, SLAs, approvals (8 sub-domains, ~45 verbs total). Routed by mk:jira-jsm skill. Requires JSM-licensed tenant + agent or admin role. NOT for core Jira issue ops (jira-issue); NOT for project admin (jira-admin). |
jira-lifecycle | Drive JIRA workflow lifecycle via the jira-as CLI wrapper: transition through statuses, assign/unassign, resolve/reopen, manage versions and components. Routed by mk:jira-lifecycle skill. NOT for issue CRUD (jira-issue); NOT for comments (jira-collaborate); NOT for bulk transitions (jira-bulk). |
jira-ops | Inspect JIRA-side cache + project context discovery via the jira-as CLI wrapper. Diagnostic surface: cache-status, cache-clear, discover-project. Routed by mk:jira-ops skill. NOT for issue CRUD; NOT for project admin (jira-admin). |
jira-relationships | Manage JIRA issue relationships via the jira-as CLI wrapper: link / unlink, blockers, dependencies, clone, bulk-link. Routed by mk:jira-relationships skill. NOT for sprint/epic relationships (jira-agile); NOT for parent/subtask (jira-agile). |
jira-search | Find JIRA issues by criteria via the jira-as CLI wrapper. Use for: 'search jira', 'find issues where X', 'export search results', JQL filter management. Routed by mk:jira-search skill. NOT for single-issue CRUD (jira-issue); NOT for bulk write ops (jira-bulk). |
jira-time | Manage JIRA time tracking via the jira-as CLI wrapper: log work, list/edit/delete worklogs, set estimates, generate time reports, bulk-log. Routed by mk:jira-time skill. NOT for sprint capacity (jira-agile). |
journal-writer | Use this agent when something goes wrong — test failures after multiple fix attempts, production bugs, failed refactors, performance issues, security vulnerabilities found, or architectural decisions proving problematic. Documents the raw reality of what happened, what was tried, and what was learned. Use proactively after Phase 6 (Reflect) or when escalation occurs. Not for routine project documentation. |
orchestrator | Task router for every incoming request. Classifies complexity (trivial/standard/complex), assigns model tier, and routes to the correct specialist agent. Use this agent at the start of every task. It never writes code — only makes routing decisions. |
planner | Product and engineering planning agent. Runs a two-lens review (product + engineering) on every task and produces a structured plan file before implementation begins. Use when starting any standard or complex task. Enforces Gate 1 — no code without an approved plan. Not for implementation or review verdicts. |
project-manager | Cross-workflow delivery tracker. Aggregates plan, test, review, contract, and cost state into a classified, evidence-based status report (done / in progress / blocked / not started). Use proactively after phase completions, after multi-agent parallel runs, and when the user asks "what's done", "what's blocked", or "status / progress". For forward-looking "what should I do next" advice, use mk:help instead — PM is backward-looking. Reads only; writes status reports co-located inside each plan dir. Never edits plans, verdicts, or code. |
researcher | Use this agent when you need to research technical topics, evaluate libraries or frameworks, find documentation, or gather information before making decisions. Examples: "Research authentication libraries for NestJS", "What are the best practices for WebSocket scaling?", "Compare Prisma vs TypeORM vs Drizzle for our API." Use proactively when a task requires understanding external tools, libraries, or patterns before implementation. Not for implementation, plans, verdicts, or project documentation. |
reviewer | Structural code review agent that performs deep 5-dimension reviews and enforces Gate 2 — no code ships without a passing review verdict. Use in Phase 4 after developer completes implementation and tester confirms green phase. Not for runtime-evaluation or security verdicts. |
security | Risk-triggered deep security audit specialist for Phase 2 (pre-implementation) and Phase 4 (review). Issues BLOCK verdicts that halt the pipeline for critical vulnerabilities. Auto-activates on changes touching auth, payments, user data, API endpoints, encryption, or another flagged risk surface; the deterministic post-write scan runs on every write in all modes. Not for general structural review verdicts. |
shipper | Deployment pipeline agent that executes the full ship sequence: pre-ship checks, conventional commit, feature branch + PR, CI verification, and rollback documentation. Use in Phase 5 after Gate 2 passes. Never commits directly to main. Not for implementation or review approval. |
story-sizer | Heuristic pre-ticket Fibonacci sizing for a paste-mode batch of user stories. Read-only at Jira; writes Story Sizing Report locally. Auto-create mode delegates ticket creation to mk:jira-issue + mk:jira-collaborate; never reads Jira credentials directly. Forked from mk:story-sizer skill. |
tester | Test-writing agent. In TDD mode (--tdd / MEOWKIT_TDD=1), writes failing tests before implementation (red phase) and verifies they pass after (green phase). In default mode (TDD off), writes tests when invoked but does not block the developer. Use in Phase 2 and after implementation. Anti-rationalization rules (no test minimization, no mock substitution) apply in BOTH modes. |
ui-ux-designer | Use when frontend work requires UI/UX design decisions — component design, design systems, wireframes, visual review, accessibility audits, or responsive layout. Activated by mk:cook and mk:bootstrap when frontend is detected. Not for production source implementation. |