Multi-agent workflow orchestration for Claude Code -- branch-per-task development with automated QA, codebase guardian, and crash recovery.
# 1. Add the marketplace
/plugin marketplace add ParkerM2/claude-workflow-marketplace
# 2. Install the plugin
/plugin install claude-workflow@ParkerM2-claude-workflow-marketplaceOr from the terminal (outside a Claude Code session):
claude plugin marketplace add ParkerM2/claude-workflow-marketplace
claude plugin install claude-workflow@ParkerM2-claude-workflow-marketplace# Clone the repository
git clone https://github.com/ParkerM2/create-claude-workflow.git
# Add as a local plugin (from within a Claude Code session)
/plugin add ./create-claude-workflow# Via marketplace (auto-updates on session start if enabled)
/plugin update claude-workflow@ParkerM2-claude-workflow-marketplace
# Or refresh the whole marketplace
/plugin marketplace update ParkerM2-claude-workflow-marketplace- Open any project in Claude Code
- Run
/setup-workflowto configure project paths (project rules file, architecture file, progress directory) - Run
/agent-teamto execute a pre-planned feature - The plugin handles: planning, branching, agent spawning, QA, merge, and cleanup
| Command | Description |
|---|---|
/agent-team |
Execute a pre-planned feature -- reads task files from /new-plan, spawns agents with thin prompts |
/new-plan |
Deep technical planning -- analyzes codebase, designs architecture, decomposes into agent-ready tasks with wave ordering |
/setup-workflow |
First-time project setup -- config, infrastructure, agent discovery, docs, CLAUDE.md |
/connect-atlassian |
Connect Jira + Confluence -- guided API token setup for Atlassian integration |
/deep-research |
Conversational deep research -- phased investigation with user checkpoints, iterative cross-referencing, and multi-layered validation |
/resume |
Crash recovery -- scans progress files, detects errors and blockers, auto-resumes or presents options to user |
/settings |
Workflow settings hub -- guard permissions, agent audit, and performance audit |
/status |
Quick progress summary -- shows completion percentage, task states, branch status, and active blockers |
/track |
Emit a tracking event to the JSONL progress log -- records checkpoints, task state, errors, blockers, and QA results |
The plugin ships with three built-in agents. Additional agents can be defined manually in .claude/agents/.
| Agent | Role |
|---|---|
| Team Leader | Orchestrator for multi-agent feature development. Decomposes tasks, manages branches, spawns agents in waves, merges workbranches. Does not write implementation code. |
| QA Reviewer | Per-task quality gate. Reviews code changes, runs automated checks, verifies acceptance criteria, and updates documentation on PASS. Maximum 3 rounds per task. |
| Codebase Guardian | Final structural integrity check on merged feature branches. Runs 7 checks covering architecture compliance, import health, type safety, test coverage, documentation, and security. |
Per-project configuration is stored in .claude/workflow.json. Run /setup-workflow to create or update it.
{
"projectRulesFile": "CLAUDE.md",
"architectureFile": "docs/ARCHITECTURE.md",
"progressDir": ".claude/progress",
"branching": {
"baseBranch": "auto",
"featurePrefix": "feature",
"workPrefix": "work",
"enforce": "warn",
"protectedBranches": ["main", "master"],
"useWorktrees": true,
"worktreeDir": ".worktrees"
},
"guards": {
"branchGuard": true,
"destructiveGuard": true,
"configGuard": true
}
}| Setting | Default | Purpose |
|---|---|---|
projectRulesFile |
CLAUDE.md |
File containing coding standards and project conventions |
architectureFile |
docs/ARCHITECTURE.md |
File describing project structure and design decisions |
progressDir |
.claude/progress |
Directory for JSONL event logs and rendered progress files |
branching.baseBranch |
auto |
Base branch for feature branches (auto detects main or master) |
branching.featurePrefix |
feature |
Prefix for feature branches (e.g., feature/my-feature) |
branching.workPrefix |
work |
Prefix for task branches (e.g., work/my-feature/task-1) |
branching.enforce |
warn |
Branch protection mode: warn, block, or off |
branching.protectedBranches |
["main", "master"] |
Branches protected from direct commits |
branching.useWorktrees |
true |
Use git worktrees for agent isolation |
branching.worktreeDir |
.worktrees |
Directory for worktree checkouts |
guards.branchGuard |
true |
Enable/disable branch protection hook |
guards.destructiveGuard |
true |
Enable/disable destructive command blocking |
guards.configGuard |
true |
Enable/disable workflow file protection |
Three modes control how much ceremony the workflow applies. Set in your project rules file or override per-invocation.
| Strict (default) | Standard | Fast | |
|---|---|---|---|
| Planning gate | Required | Required | Required |
| Pre-flight checks | Yes | No | No |
| QA rounds (max) | 3 | 2 | 1 |
| Codebase Guardian | Yes | Yes (auto-fix trivial) | No |
| Performance logging | Yes | No | No |
| Wave fence | Full verify | Quick verify | No fence |
| Context budget check | Yes | Yes | No |
Override per-invocation: /agent-team -- mode: fast
Every feature is developed on isolated branches with per-task QA. Agents work in git worktrees for true parallel isolation:
<base-branch>
└── feature/<name> ← team-leader creates this
├── .worktrees/<name>/task-1/ ← agent 1 worktree (isolated)
├── .worktrees/<name>/task-2/ ← agent 2 worktree (parallel)
└── .worktrees/<name>/task-3/ ← agent 3 worktree (parallel)
- Plan -- Team Leader reads the playbook, decomposes the feature into tasks with wave ordering
- Branch -- Creates
feature/<name>from the configured base branch - Execute -- Each agent gets an isolated git worktree; agents in the same wave work truly in parallel
- QA -- QA Reviewer runs in each agent's worktree. FAIL = agent fixes (up to 3 rounds). PASS = docs updated.
- Merge -- Work branches rebase onto
feature/and merge--no-ff, worktrees are cleaned up - Guard -- Codebase Guardian runs final integrity check on the merged
feature/branch - PR -- Feature branch is ready for pull request
Branch prefixes, base branch, enforcement mode, and worktree usage are all configurable via .claude/workflow.json.
Ten hooks run automatically to protect against common mistakes:
| Hook | Trigger | Protection |
|---|---|---|
session-start |
Session start/resume/compact | Loads workflow context, branching config, and active feature status |
compact-reinject |
After context compaction | Re-injects Phase Gate Protocol and workflow state after compaction |
safety-guard |
Before Bash commands | Blocks destructive operations (rm -rf, git reset --hard, etc.) |
workflow-enforcer |
Before Bash/Edit/Write/TaskStop | Enforces workflow phase rules and task lifecycle |
init-gate |
Before TeamCreate/Agent | Blocks agent spawning when prerequisite setup hasn't completed |
config-guard |
Before Edit/Write | Prevents modification of workflow config files |
tracking-emitter |
After tool use / TeammateIdle / TaskCompleted / Stop | Emits JSONL tracking events for workflow observability |
teammate-quality |
TeammateIdle | Runs quality checks on teammate output when idle |
task-validator |
TaskCompleted | Validates task output meets acceptance criteria |
proof-ledger |
After tool use | Records proof-of-work entries for audit trail |
claude-workflow/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── .claude/
│ ├── docs/ # Plugin documentation
│ │ ├── internal/ # Dev logs, plans
│ │ ├── plans/ # Feature plans, research
│ │ ├── research/ # Audits, references
│ │ └── customize-quick-start/ # User customization guides
│ └── progress/ # JSONL event logs (per-feature)
│ ├── index.md # Top-level dashboard
│ └── <feature>/
│ ├── events.jsonl # Append-only event log
│ └── current.md # Active task state
├── commands/ # Slash commands (loaded on /invoke)
│ ├── agent-team.md # Execute pre-planned feature with thin spawns
│ ├── new-plan.md # Deep technical planning
│ ├── setup-workflow.md # First-time project setup
│ ├── connect-atlassian.md # Jira + Confluence integration
│ ├── deep-research.md # Conversational deep research
│ ├── resume.md # Crash recovery
│ ├── settings.md # Guard permissions + audits hub
│ ├── status.md
│ └── track.md
├── agents/ # Agent definitions (loaded on spawn)
│ ├── team-leader.md
│ ├── qa-reviewer.md
│ └── codebase-guardian.md
├── prompts/ # Reference docs and templates
│ ├── implementing-features/ # Playbook, QA templates, workflow modes
│ │ ├── AGENT-WORKFLOW-PHASES.md
│ │ └── THIN-SPAWN-TEMPLATE.md
│ └── settings/ # Sub-flows for /settings (guards, audits)
├── hooks/ # Enforcement hooks
│ ├── hooks.json
│ ├── config.js # Shared config reader (repo root, branching)
│ ├── session-start.js
│ ├── compact-reinject.js # Re-injects phase gates after context compaction
│ ├── safety-guard.js # Combined branch + destructive guard
│ ├── workflow-enforcer.js # Workflow phase rules and task lifecycle
│ ├── init-gate.js # Blocks premature agent spawning
│ ├── config-guard.js
│ ├── tracking-emitter.js # JSONL tracking event emitter
│ ├── tracking.js
│ ├── teammate-quality.js # Teammate output quality checks
│ ├── task-validator.js # Task completion validation
│ ├── proof-ledger.js # Proof-of-work audit trail
│ ├── ticket.js
│ └── tracker.js
├── skills/ # Internal skills
│ ├── workflow-setup/
│ └── using-workflow/
└── marketplace/ # Marketplace distribution metadata
MIT