Agent automation plugins for Claude Code, with shared Codex support for portable planning and discovery workflows.
This repository contains five Claude Code plugins. plan-cycle and refactor-discovery are also packaged for Codex from shared source trees.
| Plugin | Claude Code | Codex | Description |
|---|---|---|---|
| automate | /automate |
- | Expert advisor that helps you decide and create the right Claude Code automation (skills, hooks, subagents, permissions, etc.) |
| develop-cycle | /develop-cycle |
- | Structured development workflow with analysis, implementation, validation, and mandatory checkpoint before commit/push |
| plan-cycle | /plan-cycle |
plan-cycle skill |
File-based planning with annotation cycles. Persistent markdown plans you can edit and refine iteratively |
| takeaway | /takeaway |
- | Structured feedback extraction. Interviews the user, distills observations into portable principles for continuous improvement |
| refactor-discovery | /refactor-discovery |
refactor-discovery skill |
Research methodology for surfacing non-obvious structural smell leads before promoting refactor candidates |
# Add the marketplace (once)
/plugin marketplace add elmisi/claude-code-automation
# Install the plugin(s) you want
/plugin install automate
/plugin install develop-cycle
/plugin install plan-cycle
/plugin install takeaway
/plugin install refactor-discoveryRestart Claude Code after installation to activate.
This repository exposes a Codex marketplace at .agents/plugins/marketplace.json.
Add elmisi/claude-code-automation as a Codex marketplace, then install plan-cycle or refactor-discovery. Codex reads the plugins from:
plugins/plan-cycle/.codex-plugin/plugin.json
plugins/refactor-discovery/.codex-plugin/plugin.json
The Claude Code and Codex manifests point to the same plugin skill directories, so workflow updates are shared by both tools.
Auto-update is disabled by default for third-party plugins. To enable automatic updates:
/plugin → Marketplaces tab → elmisi → Enable auto-update
Or update manually anytime:
/plugin marketplace update elmisi
/reload-plugins# For automate: clean up all created automations first (optional but recommended)
/automate-cleanup
# Uninstall any plugin
/plugin uninstall <plugin-name>Automations created by /automate continue to work independently after uninstallation. If you reinstall the plugin later, it will automatically detect and re-register existing automations.
An expert advisor that helps you decide and create the right automation for your needs.
Schemas updated: May 2026 — 29 hook events, 4 hook handler types, MCP/LSP Servers, Agent Teams, full model IDs.
Claude Code offers multiple automation mechanisms: skills, hooks, subagents, permissions, CLAUDE.md, custom commands, MCP servers, LSP servers, and agent teams. Each serves a different purpose, but choosing the right one isn't always obvious.
Common questions:
- Should I use a hook or a skill?
- When do I need a subagent vs a regular skill?
- How do I enforce a rule that Claude MUST follow, not just "should" follow?
- What if I use
--dangerously-skip-permissions? - When should I set up an MCP server vs a hook?
- Do I need an agent team or just a subagent?
This plugin acts as an expert advisor. You describe what you want to automate, it interviews you to understand your exact needs, then creates the right files in the right places.
/automate <your topic>/automate semantic versioning on every commit
/automate block push without explicit approval
/automate TUI project conventions
/automate security review for all PRs
/automate API design guidelines
/automate integrate GitHub tools via MCP
/automate set up TypeScript language server
/automate run tests before every commit
The plugin interviews you to understand exactly what you need:
Q: When should this happen? → Always, on every commit
Q: Must it be guaranteed, or just a guideline? → Guaranteed — block the commit if tests fail
Q: Should Claude decide which tests to run? → Yes, based on the changed files
"A Skill alone won't work — Claude can skip skills. You need a Hook to guarantee tests run on every commit. But since Claude should intelligently pick which tests based on changed files, you also need a Skill for the logic. I'll create both."
Files created:
| File | Purpose |
|---|---|
~/.claude/settings.json |
Hook: blocks git commit unless tests pass |
~/.claude/skills/test-runner/SKILL.md |
Skill: analyzes changes, picks relevant tests |
Both files are validated against schemas and registered for easy management (/automate-list).
The twist: had you answered "just a guideline" instead, the plugin would create a single CLAUDE.md rule — no hooks, no skills. Same topic, different needs, completely different automation.
- Auto-updates: Fetches the latest Claude Code documentation to stay current with new features
- Interviews you: Asks specific questions about timing, scope, and requirements
- Decides: Uses a decision matrix to pick the right automation type
- Explains: Tells you what it chose and why, with alternatives considered
- Creates: Generates the necessary files in the correct locations
- Validates: Checks all files against schemas before writing
- Verifies: Ensures all components of a combination are complete
- Tests: Shows you how to test and use your new automation
| Need | Solution |
|---|---|
| Must happen EVERY time, no exceptions | Hook |
| Control what Claude can/cannot do | Permissions |
| Domain knowledge applied automatically | Skill |
| Complex workflow invoked manually | Skill (with disable-model-invocation: true) |
| Separate context for analysis/review | Subagent |
| Simple global rule | CLAUDE.md |
| Shortcut for frequent prompt | Custom Command |
| External tool/service integration | MCP Server |
| Code intelligence (diagnostics, hover) | LSP Server |
| Parallel multi-agent orchestration | Agent Team (experimental) |
- Hook + Skill: Guaranteed execution (hook) with complex logic (skill)
- Permissions + CLAUDE.md: Technical block + explanation of why
- Skill + Subagent: Workflow definition + isolated deep analysis
- MCP Server + Skill: External tool access + workflow orchestration
- Agent Team + Skill: Multi-agent orchestration + domain knowledge
All automations created by this plugin are tracked in a registry (~/.claude/automations-registry.json). Each management command is a separate skill for instant tab-completion and faster execution:
| Command | Description |
|---|---|
/automate-list |
List all tracked automations with options to view, edit, delete, or export |
/automate-edit <name> |
Modify an existing automation (name, description, behavior, scope) |
/automate-delete <name> |
Remove an automation with confirmation |
/automate-export [file] |
Export all automations to a portable JSON file |
/automate-import <file> |
Import automations from another machine with conflict resolution |
/automate-verify |
Health-check all registered automations — detects missing files or hook entries and offers to repair them |
/automate-cleanup |
Pre-uninstall: remove all automations created by this plugin (with option to keep selected ones) |
/automate-help |
Show full command reference |
Hooks vs Skills
- Hooks are scripts that run automatically at specific events. They're deterministic and guaranteed.
- Skills are knowledge/workflows that Claude applies with intelligence. They're advisory.
- Use hooks when something MUST happen. Use skills when Claude needs to think.
Permissions caveat — If you use --dangerously-skip-permissions, permission rules won't work. The plugin will suggest using hooks as an alternative for guaranteed blocks.
MCP Servers — Expose external tools to Claude via the Model Context Protocol. Tools appear as mcp__<server>__<tool> and can be matched in hook matchers. Supports stdio, http, sse, and ws transports.
LSP Servers — Provide code intelligence features (diagnostics, hover, completions) via the Language Server Protocol. The language server binary must be installed separately.
Agent Teams (experimental) — Enable parallel multi-agent orchestration. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Subagents for clean context — Run in isolated context windows. Use them for code review (unbiased, separate from the code that was just written), deep investigation (reads many files without polluting your main context), or specialized analysis (security, performance, etc.).
A structured development workflow that guides Claude through analysis, implementation, validation, and a mandatory checkpoint before commit/push.
/develop-cycle add user authentication with JWT tokens
/develop-cycle fix the race condition in the payment queue
/develop-cycle refactor the API layer to use dependency injectionThe workflow has 6 phases:
- Analysis and Planning — Understand the task, study the codebase, clarify ambiguities, propose an approach, define the plan
- Setup — Create a working branch from the main branch
- Implementation — Write code and tests following the approved plan
- Validation — Run pre-commit/lint and tests. Mandatory checkpoint: Claude stops and waits for your explicit OK before committing
- Iteration — If you request changes, Claude applies them and re-validates
- Finalization — Commit, push, and update docs if needed (only after your approval)
The key feature is the mandatory checkpoint after validation passes. Claude will never commit or push autonomously — it always stops to show you the results and waits for your explicit approval.
Pre-commit commands, test commands, and the main branch name are read from your project's CLAUDE.md file, so the workflow adapts to any project.
File-based planning with annotation pipeline. Creates persistent markdown plans with composable analysis skills.
| Command | Description |
|---|---|
/plan-cycle <request> |
Research codebase and write a detailed plan file |
/plan-cycle:plan-impact <plan-path> |
Codebase impact analysis — finds overlaps, obsolescence, broken conventions, ripple effects |
/plan-cycle:plan-quality <plan-path> |
Code quality review — checks plan against configurable quality criteria |
/plan-cycle add cursor-based pagination to the list endpoint
/plan-cycle refactor the auth module to use JWT tokens
/plan-cycle migrate the database from MongoDB to PostgreSQL/plan-cycle <request> → writes plan + ops companion file
/plan-cycle:plan-impact <plan> → annotates codebase-level issues
/plan-cycle:plan-quality <plan> → annotates quality violations
"annotate" → adds only new > **NOTE**: lines
"review" → processes all annotations, updates plan
"finalize" → verifies consistency, rewrites gaps
... repeat until approved ...
"approved" → plan is ready for execution
- Research — Claude reads the relevant codebase deeply before writing anything
- Write plan — A detailed markdown plan with context, approach, code snippets, edge cases, and a task breakdown. A companion ops file is written alongside with operational instructions.
- Analyze — Run
/plan-cycle:plan-impactand/or/plan-cycle:plan-qualityto get automated annotations - Review — Process all
> **NOTE**:annotations, integrate them into the plan, remove resolved ones - Finalize — Verify the plan is self-contained (executable by a fresh agent in a new session without context), operative, coherent, and robust. Rewrites sections directly where gaps are found.
- Approve — Iterate until the plan is right, then approve it
The ops companion file describes the three core operations (annotate, review, finalize) so any coding agent can work with the plan — the plugin skills handle the analysis passes (impact and quality). Operation dispatch is literal: annotate only adds > **NOTE**: lines, while review is the operation that processes existing notes.
The key insight: a markdown file is shared mutable state between you and any number of agents. You can think at your own pace, point at the exact spot where something is wrong, and write the correction right there.
Inspired by Boris Tane's annotation cycle workflow.
Structured feedback extraction for continuous improvement. Interviews the user, distills observations into portable principles.
/takeaway plan-cycle
/takeaway develop-cycle
/takeaway <any skill, tool, or workflow>- Identify — Classifies the target (skill, tool, plugin, workflow) and its scope (universal or project-specific)
- Interview — Extracts observations from the user with concrete examples
- Evidence file — Writes
takeaway-<target>-evidence.md, the session retrospective with project-specific detail - Distillation — Collapses patterns by root theme and strips project-specific vocabulary
- Lessons file — Writes
takeaway-<target>-lessons.md, tool-agnostic principles an improving agent can consume - Iterate — The user reviews and annotates both files until approved
The two-file split is deliberate: evidence is traceable and project-bound, lessons are portable across projects and tools.
Research methodology to surface non-obvious structural smell leads, preserve uncertainty, and promote only mature findings into refactor candidates.
# Full project — discover all areas, investigate everything
/refactor-discovery
# Scoped — focus on a specific part, auto-extend to adjacent areas
/refactor-discovery src/services/payment
/refactor-discovery the UserService class
/refactor-discovery error handling in the checkout flow- Pin snapshot — Anchors the entire pass to a commit SHA for reproducible evidence
- Discover areas — Analyzes the project structure and identifies 3-8 investigation areas optimized for parallel execution. When given a specific target, resolves it and discovers adjacent areas (inbound/outbound imports, shared types, tests) that must be investigated to avoid blind spots.
- Area investigation — Spawns one subagent per area when available, with a serial fallback for runtimes that do not support plugin agents. Each area runs the full cycle: enumerate files, read for intent, scan with structural lenses, capture commit-anchored evidence, and triage into smell leads, promoted candidates, research tasks, or leave-alone verdicts.
- Synthesis — Reads all per-area notes, clusters leads, resolves layering conflicts, assigns stable IDs (
SL<N>smell lead,R<N>refactor,RT<N>research task,DI<N>document-intent), and builds dependency edges. - Discovery document — Produces
docs/refactor-discovery/<date>/discovery.mdwith executive summary, investigation leads, promoted candidates, research tasks, prioritized roadmap (Do next / Do later / Do not do now), lens coverage, and open questions. - Self-checks — Runs coherence gates before reporting: promoted candidates pass the why gate, leads state lens and promotion condition, temporal claims cite commit evidence, and dependency references resolve.
The investigation is governed by 9 prioritized principles (readability > essentiality > cognitive load > abstraction via naming > tell-don't-ask > fail fast > CQS > least surprise > comments for "why") plus eight discovery lenses: temporal coupling, change amplification, shotgun ceremony, semantic drift, asymmetric abstractions, hidden policy, test gravity, and negative space.
Smells do not need to become advice immediately. The plugin records them as SL<N> leads until the "why" gate is strong enough to promote them to R<N> refactor candidates, or until missing runtime/domain evidence makes them RT<N> research tasks.
The methodology reference (docs/methodology.md inside the plugin) defines the complete framework: principles, investigation discipline, scoring rules, cross-cutting signals, synthesis checks, anti-patterns to avoid, and output templates.
docs/refactor-discovery/
registry.md # Index of all passes
2026-05-07/
discovery.md # The deliverable — leads, candidates, research tasks
area-api.md # Per-area investigation note
area-components.md
area-services.md
...
| Type | Command | Tests | Description |
|---|---|---|---|
| Structure | ./tests/scripts/run-tests.sh structure |
129 | File structure, JSON validity, marketplace manifests, fixture validation, version sync, negative validation, JSON guard |
| Fixture | ./tests/scripts/run-tests.sh e2e |
20 | Creates expected outputs in sandbox and validates their structure |
| Interactive | ./tests/scripts/run-tests.sh interactive |
5 | Runs actual Claude commands to test the skill end-to-end (consumes tokens) |
Structure and fixture tests are deterministic and run in CI. Interactive tests are qualitative smoke tests that verify skills produce reasonable output with a real Claude instance — local only.
Contributions are welcome! See CONTRIBUTING.md for development setup, architecture overview, and how to add new automation types.
MIT