claude-workflow

Claude Workflow Plugin

A plugin for Claude Code that turns "build me a feature" into a tracked, reviewed, regression-tested change set — without you driving every step.

🎯 What you get

• Plain-English in, structured work out. Describe a feature. The orchestrator breaks it into a Beads epic with subtasks, routes each subtask to a domain specialist (backend / frontend / devops / qa) that already knows OWASP, performance budgets, accessibility patterns, and root-cause analysis, and ships nothing until QA approves.
• A QA gate that's a real Stop hook. Claude literally cannot release the conversation without qa-approved on the active task. The decision is recorded in Beads as a label and a comment — full audit trail, no honour system. The label alone is not enough: the Stop hook releases only when the approval comment carries a change_set_hash matching the current diff, so a forged qa-approved label (added without qa-gate.sh approve) does not pass the gate.
• Tasks survive sessions. Specialists auto-claim work via bd update --status in_progress. GitHub issue auto-linking is provided (bd-github-link.sh: posts a back-link comment on task close and parses Closes #N); its call shapes are verified by the bd-github-link L1 test against a stubbed gh, not a live round-trip. Pick up tomorrow where you left off tonight.
• A separate-context rubric grader gates every QA approval. Before QA signs off, a read-only grader subagent scores the work against a versioned rubric (default + per-domain overlays + a bugfix overlay for evidence-before-fix). The grader sees only the diff, the SPEC, and the lessons ledger — no specialist conversation context — so its verdict is independent. Iteration cap is binding and engages the escalation path on cap-hit.
• Two MCP servers ship in the box. bd-mcp exposes 21 typed Beads tools (no shell quoting bugs). code-graph-mcp exposes 7 graph tools (code_search, code_context, symbol_callers, impact_of, dead_code, dependency_path, code_index_health) backed by a tree-sitter + SQLite index. Both load automatically via .mcp.json and ${CLAUDE_PLUGIN_ROOT}.
• Regression coverage by construction. Every QA iteration runs the full test suite. A module-A edit that breaks module-B's contract is caught before approval, not after. The plugin's own test pyramid (L1 bash unit → L3 vitest unit → L3 live e2e → L3.5 mutation tier) demonstrates the pattern. Live tests are invariant-based, manual only, and the CI consumes zero API spend per PR.
• On-demand mutation sweep with a calibrated LLM judge filter. /mutation-sweep generates fault-class mutants for hook scripts, runs them in throwaway git worktrees against the free L1/L2 tiers, and routes survivors through a read-only judge subagent calibrated against a hand-labeled set (precision ≥ 0.8). Every step is dev-cycle-manual — no CI wiring, no scheduled job, no automatic paid call.
• Lessons ledger as institutional memory. LESSONS.md is append-only via lessons.sh add; the orchestrator reads it before decomposing non-trivial work; the grader reads it as part of every grading packet. The two seed lessons (parallel-agent worktree isolation; boundary-mock fidelity) shipped with v3.1.0.

⚡ Install

The plugin requires Beads (bd) ≥ 0.47 and jq. The installer fails fast if either is missing and prints the upgrade command.

Fresh install

# curl-pipe (no clone needed)
curl -fsSL https://raw.githubusercontent.com/preql-data/claude-workflow-plugin/main/install.sh | bash

# or clone-and-run
git clone https://github.com/preql-data/claude-workflow-plugin
cd claude-workflow-plugin
bash install.sh /path/to/your/project

Upgrade from v2

The installer auto-detects v2 layouts (no model: frontmatter, no .claude-plugin/plugin.json, no MCP servers) and migrates them. You can also force upgrade mode explicitly:

# auto-detects v2 and migrates
curl -fsSL https://raw.githubusercontent.com/preql-data/claude-workflow-plugin/main/install.sh | bash

# explicit upgrade
curl -fsSL https://raw.githubusercontent.com/preql-data/claude-workflow-plugin/main/install.sh | bash -s -- --upgrade

Migration copies the existing .claude/ to .claude-v2-backup-<timestamp>/ before writing v3 files, so user customizations are recoverable. Run the diff after install to see what changed:

diff -r .claude-v2-backup-*/ .claude/

Windows

irm https://raw.githubusercontent.com/preql-data/claude-workflow-plugin/main/install.ps1 | iex