mx-workflow
CLAUDE.md1 starsChanged 3 months agoMITView on GitHub
The mx-workflow plugin empowers developers to move faster through automation, guidance, and multi-agent collaboration. Every command should save time, reduce cognitive load, or improve code quality. Type /mx:help to see a quick reference card for all available commands. Each command is a Markdown file with YAML frontmatter: Use /mx:version to bump versions. It handles everything in one step: The command updates: - plugin.json (version field) - .claude-plugin/marketplace.json (plugins[0].version field) - CHANGELOG.md — moves [Unreleased] content to the new version section…
- Reads credentials
- Commits and pushes
In this repository5 other files it gives its agents.
- commands/agents.mdAGENTS.md
- comment-analyzerSkill
- hallucination-checkSkill
- silent-failure-hunterSkill
- type-design-analyzerSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
19 rules. About 0 are common, 10 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
Use /mx:create-command <name> <purpose> to scaffold
- Very specific: line 45
Test with /my-command in Claude Code
- Very specific: line 46
Update the documentation site in docs/ — add or revise pages so the live docs stay in sync
- Distinctive: line 51
Start with a focused purpose (e.g., code review, performance analysis)
- Distinctive: line 52
Keep agents reusable across multiple commands
- Distinctive: line 53
Document expected inputs and outputs
- Distinctive: line 59
Use sensible defaults; override sparingly
- Distinctive: line 63
Use Claude Code's built-in tools to test commands locally
- Distinctive: line 65
Update README if adding new commands or significant changes
- Very specific: line 69
Use /mx:version to bump versions.
- Very specific: line 104
Never use capitalized directory names (e.g., .agents/PRDs/ is wrong).
- Distinctive: line 108
Always update CHANGELOG.md: when making changes to the plugin:
- Very specific: line 109
Add entries under [Unreleased] as you work — don't leave it for later
- Very specific: line 110
Use the correct category: Added, Changed, Fixed, Removed
- Very specific: line 112
When shipping a batch of work, bump the version and move [Unreleased] to a new version section
- Very specific: line 119
After bumping: create a GitHub Release via gh release create v{version} with the changelog section as release notes.
- Distinctive: line 125
Avoid hardcoding assumptions.
- Distinctive: line 126
All agents should fail gracefully with actionable feedback
- Distinctive: line 127
Keep commands focused; break complex workflows into steps
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
mx-workflow Plugin Development Guidelines
Orchestration
- No dev server, no ports, no database. This is a Claude Code plugin repo — commands and agents as Markdown files.
- Ship / publish:
/mx:version <patch|minor|major>bumpsplugin.json+marketplace.json+CHANGELOG.mdand tags. Thengh release create v{version}publishes the release. - Single public repo (
joshtune/mx-workflow).
Philosophy
The mx-workflow plugin empowers developers to move faster through automation, guidance, and multi-agent collaboration. Every command should save time, reduce cognitive load, or improve code quality.
Architecture
Structure
- Commands (
/commands): User-facing slash commands (Markdown frontmatter + instructions) - Agents (
/agents): Specialized analyzers for code review, testing, debugging - References (
/references): Configuration and mappings (scope mappings, agent browser)
Commands at a Glance
Type /mx:help to see a quick reference card for all available commands.
Command Format
Each command is a Markdown file with YAML frontmatter:
---
description: "One-line description"
allowed-tools: [Bash, Read, Grep]
---
Your instruction prompt here...Adding New Commands
- Create
commands/my-command.md - Use
/mx:create-command <name> <purpose>to scaffold - Define clear inputs, outputs, and which tools are needed
- Test with
/my-commandin Claude Code - Update the documentation site in
docs/— add or revise pages so the live docs stay in sync
Adding New Agents
- Create
agents/mx-my-analyzer.md - Start with a focused purpose (e.g., code review, performance analysis)
- Keep agents reusable across multiple commands
- Document expected inputs and outputs
Configuration
- Environment variables in
.env.example - Scope mappings in
references/scope-mappings.md - Use sensible defaults; override sparingly
Testing
- Use Claude Code's built-in tools to test commands locally
- For agents, invoke via Task tool to verify behavior
- Update README if adding new commands or significant changes
Version Management
Use /mx:version to bump versions. It handles everything in one step:
/mx:version patch # 1.0.1 → 1.0.2
/mx:version minor # 1.0.1 → 1.1.0
/mx:version major # 1.0.1 → 2.0.0
/mx:version 2.1.0 # explicit versionThe command updates:
plugin.json(versionfield).claude-plugin/marketplace.json(plugins[0].versionfield)CHANGELOG.md— moves[Unreleased]content to the new version section- Creates a git tag
v{version}
Manual bumps — if you must update versions by hand, keep both files and the changelog in sync.
Documentation
- README.md: Installation, usage, configuration
- Inline help: Commands have built-in descriptions
- Frontmatter:
descriptionfield appears in autocomplete
Output Directory Convention
Commands that generate artifacts write to .agents/ using all-lowercase-hyphenated subdirectories:
.agents/prds/— PRD documents.agents/rca-reports/— Root cause analysis reports.agents/reports/— General reports (suppression audits, etc.).agents/feasibility/— Feasibility reports from/mx:feasibility.agents/evidence/<slug>/— Verification evidence from/mx:verify(videos, screenshots, coverage,report.md)
Lessons are the exception: /mx:lesson writes to .claude/lessons/ in the target project and is meant to be committed (shared team memory), unlike .agents/ artifacts.
Never use capitalized directory names (e.g., .agents/PRDs/ is wrong).
Changelog & Versioning Policy
Always update CHANGELOG.md when making changes to the plugin:
- Add entries under
[Unreleased]as you work — don't leave it for later - Use the correct category:
Added,Changed,Fixed,Removed - Reference the ticket ID (e.g., EIT-XX) when applicable
- When shipping a batch of work, bump the version and move
[Unreleased]to a new version section
When to bump versions:
patch— bug fixes, typo corrections, doc-only changesminor— new commands, new agents, new features, non-breaking improvementsmajor— breaking changes to existing command behavior or plugin structure
After bumping: create a GitHub Release via gh release create v{version} with the changelog section as release notes.
Quality Standards
- Commands should run in under 2 minutes for common paths
- Error messages should guide users toward solutions
- Avoid hardcoding assumptions; use environment variables
- All agents should fail gracefully with actionable feedback
- Keep commands focused; break complex workflows into steps
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

