By ycomplex
Harmony project management integration for Claude Code — MCP tools and workflow skills
Use when the user wants to finish, complete, wrap up, land, or merge their current work. Triggers on phrases like "finish", "done", "wrap up", "land this", "merge", "ship it", or "we're done". This is the exit point for ALL development work in this project — it handles the full merge-and-cleanup sequence. In opinionated-mode projects it also drives the releasing + verifying activities; in manual-mode projects it behaves exactly as before.
Clarify a ticket's intent into a specification (Idea → Clarified). Triggers on "clarify B-123", "what does this ticket mean", "harmony clarify", or picking up an Idea-state ticket. Dialogues with the human, queries domain knowledge first, drafts a clarification, and files it as a brief for accept/edit/defer.
Drive one ticket through the gate sequence end to end. Default = pause at every gate for the human's decision (controlled). Optional per-run delegation — `--pause-at <gate>` (auto-advance up to a gate), `--unattended` (auto-advance to the hard floor), or `--escalate` (auto-advance, but surface any gate genuinely worth a human opinion). A non-discretionary risk-class FLOOR (auth / data-migration / irreversible-destructive / shared-core) surfaces a delegated gate for a human under EVERY delegating mode, regardless of dial or agent judgment. Triggers on "conduct B-123", "harmony conduct", "run B-123 through the flow", "drive this ticket to verified". The conductor orchestrates the plumbing BETWEEN gates; at a controlled gate it hands the decision to the human, and an auto-advanced gate still records the SAME Accepted decision a controlled run would.
Decompose a clarified ticket into a child hierarchy (Clarified → Decomposed). Triggers on "decompose B-123", "break this down", "harmony decompose", or picking up a Clarified ticket. Applies the manageability rule; even "no decomposition needed" is an explicit decision. Files a proposal brief; on accept, creates children at Idea state.
Make a design decision on one sub-track (Decomposed → Designed). Triggers on "design B-123", "harmony design-decide B-123 --track ux-ui", "decide the technical approach". Runs one of three sub-tracks — Product Design, Technical Design, UX/UI Design — querying domain knowledge, drafting a typed decision, and filing it as a brief. State advances to Designed only when all required sub-tracks are accepted.
Admin access level
Server config contains admin-level keywords
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
Tools for Harmony project management — a CLI for your terminal and an MCP server plugin for Claude Code.
Manage your Harmony tasks, epics, milestones, and more from the terminal.
npm install -g @harmony-ad/harmony
Or run directly with npx:
npx @harmony-ad/harmony --help
# Log in with your API token
harmony login --token <your-api-token>
# List tasks
harmony tasks list
# Get a specific task
harmony tasks get B-42
# Create a task
harmony tasks create --title "Fix login bug" --priority high --status "To Do"
# Update a task
harmony tasks update B-42 --status "In Progress"
# JSON output for scripting
harmony tasks list --json
| Command | Description |
|---|---|
harmony login | Add a project (provide API token) |
harmony logout <name> | Remove a project |
harmony projects | List logged-in projects |
harmony project info | Show current project details |
harmony project switch <name> | Switch active project |
harmony tasks list|get|create|update | Task CRUD |
harmony tasks query | Advanced search with filters |
harmony tasks comments|comment | View/add comments |
harmony tasks bulk-create|bulk-update | Bulk operations |
harmony epics list|create|update | Manage epics |
harmony labels list|create|manage | Manage labels |
harmony milestones list|create|update|ship | Manage milestones |
harmony cycles list|create|update | Manage cycles |
harmony subtasks list|add|update|delete | Manage subtasks |
harmony ac list|add|update|delete | Acceptance criteria |
harmony tests list|add|update|delete | Test cases |
harmony docs list|get|create|update | Project documents |
harmony members list | List workspace members |
harmony activity <task-id> | Task activity timeline |
Log in to multiple projects and switch between them:
harmony login --token <token-a>
harmony login --token <token-b> --name my-other-project
harmony projects # see all, * marks active
harmony project switch my-other-project
Config is stored in ~/.harmony/config.json.
--json): machine-readable output for scripting and pipingThis package also serves as a Claude Code plugin, providing an MCP server and workflow skills.
MCP Server — gives Claude Code direct access to Harmony:
Workflow Skills:
Inside Claude Code, add the marketplace and install the plugin:
/plugin marketplace add ycomplex/harmony-plugin
/plugin install harmony-plugin@ycomplex
Restart Claude Code for the hooks and MCP server to take effect:
/exit
Then start claude again. On first startup, the plugin automatically installs dependencies and builds the MCP server (~10 seconds).
Configure your API token:
/harmony-setup
This saves the token to .claude/settings.local.json (gitignored) and verifies the connection.
Restart Claude Code one more time for the MCP server to pick up the token.
To receive automatic updates, run /plugin, go to the Marketplaces tab, select ycomplex, and enable auto-update.
If you prefer to set the token without /harmony-setup:
direnv — Create .envrc in your project root:
export HARMONY_API_TOKEN="hmy_your_token_here"
Claude Code settings — Create .claude/settings.local.json in your project root:
{
"env": {
"HARMONY_API_TOKEN": "hmy_your_token_here"
}
}
Shell profile — Add export HARMONY_API_TOKEN="hmy_your_token_here" to ~/.zshrc or ~/.bashrc.
The plugin's SessionStart hook automatically installs dependencies and builds the TypeScript MCP server on first use. Subsequent sessions skip the build if dist/index.js already exists.
The MCP server starts automatically when the plugin is enabled and provides tools prefixed with mcp__harmony__ (e.g., mcp__harmony__get_task).
npx claudepluginhub ycomplex/harmony-plugin --plugin harmony-pluginHarness-native ECC operator layer - 67 agents, 271 skills, 92 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses
Superpowers Plus core skills library for Claude Code: planning, execution routing, TDD, debugging, and collaboration workflows
Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).
Claude harness - A harness for solo developers (Vibecoders) to handle full-cycle contract development.
Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
Tools to maintain and improve CLAUDE.md files - audit quality, capture session learnings, and keep project memory current.