Claude Workflows — What It Does & Why You Need It

The Problem

Claude Code is Powerful. But Unstructured.

Without workflows, every conversation starts from zero. Claude doesn't remember your process, your conventions, or where you left off.

💥

No Process Memory

You explain the same architecture decisions, coding conventions, and git flow every single session. Claude forgets everything when context resets.

💡

Persistent Workflow State

Claude Workflows stores decisions in YAML state files and context snapshots. Resume any workflow days later with full context intact.

💥

Inconsistent Quality

Sometimes Claude writes great code. Sometimes it skips tests, ignores conventions, or creates a PR without review. No guarantees.

💡

Quality Gates at Every Boundary

Mandatory review checklists before every PR. Language-specific coding rules loaded before implementation. Focused checks on changed files only.

💥

No Structure for Complex Tasks

Building a feature? Claude jumps straight to code. No spec, no plan, no brainstorming alternatives. You get the first thing it thinks of.

💡

Phased Execution with Approvals

Gather requirements → write spec → brainstorm approaches → plan → implement → test → review → PR. Each phase gets your approval.

💥

Every Task Treated the Same

A 3-line config fix and a major feature get the same treatment: "Here's the code." No adaptation to complexity or risk level.

💡

23 Specialized Workflows

Hotfixes are fast and minimal. Features are thorough. Refactors have behavioral contracts. Each workflow is purpose-built for its task.

What It Does

A Workflow Engine for Claude Code

It installs structured skills, rules, and checklists into your project that guide Claude through disciplined software development

Skills: Step-by-Step Instructions

Each workflow is a skill — a markdown file with detailed phase-by-phase instructions that Claude follows. When you type /claude-workflows:new-feature, Claude reads the skill and executes each phase in order, writing output documents and updating state along the way.

23 skills covering the full dev lifecycle
Each skill has 3-8 phases with approval gates
Phase outputs persist as markdown for context recovery
Skills compose — new-feature delegates to brainstorm
Create your own skills with /claude-workflows:compose-skill

1# You type:

2/claude-workflows:new-feature user-authentication

4# Claude executes 8 phases:

5Phase 1: GATHER — collects requirements

6Phase 2: SPEC — writes formal specification

7Phase 3: BRAINSTORM — explores approaches with you

8Phase 4: PLAN — creates phased impl plan

9Phase 5: BRANCH — creates git branch

10Phase 6: IMPLEMENT — builds it phase by phase

11Phase 7: TEST — verifies correctness

12QUALITY GATE — checks 55+ review items

13Phase 8: PR — pushes & creates pull request

Rules: Coding Standards on Autopilot

Language-specific DO/DON'T rules are loaded before Claude writes any code. These aren't suggestions — they're directives. "Never use !! in Kotlin." "No any type in TypeScript." Claude follows them without you having to repeat them.

7 language rule files: Kotlin, Compose, TypeScript, React, Python, Swift, Go
Auto-loaded based on project.language config
Team conventions layer on top of language rules
Rules focus on real mistakes, not obvious defaults

# plugin-bundled rules/kotlin.md

## Null Safety

DO: Use ?.let {}, Elvis ?:, requireNotNull()

DON'T: Use !! — ever. No exceptions.

## Coroutines

DO: Use viewModelScope, Flow

DON'T: Use GlobalScope — causes leaks

## Sealed Classes

DO: Exhaustive when on sealed types

DON'T: Add else branch for sealed types

Review Checklists: Quality You Can Trust

Before every PR, Claude runs a self-review against severity-rated checklists. Critical items (hardcoded secrets, SQL injection, missing auth) must pass. The focused gate only checks items relevant to the files that actually changed.

55+ items in the general checklist (architecture, security, performance, testing)
Language-specific checklists add 20-30 targeted checks
Severity levels: Critical blocks merge, High should fix, Medium/Low are advisory
Team checklists for domain-specific standards
Focused gate: security files get all security checks, UI files get XSS checks

# Pre-PR Quality Gate

[CRITICAL] No hardcoded secrets PASS

[CRITICAL] Input validation PASS

[CRITICAL] SQL injection prevention PASS

[HIGH] Follows project patterns PASS

[HIGH] All errors handled PASS

[HIGH] Tests exist PASS

[MEDIUM] No N+1 queries PASS

[MEDIUM] Function length <40 PASS

Result: ALL CLEAR — creating PR

State: Never Lose Your Place

Claude Workflows uses a 3-layer persistence model so you can close your terminal, come back tomorrow, and pick up exactly where you left off. State files use YAML frontmatter for reliable parsing. Context snapshots capture key decisions at every phase boundary.

Layer 1: State file — current phase, branch, retry count, phase history
Layer 2: Phase outputs + Context section — full details from every phase, key decisions in state file
Layer 3: Git + Knowledge graph — commits, branches, and cross-workflow decision learning

# .workflows/current-state.md

---

workflow: new-feature

feature: user-authentication

phase: IMPLEMENT

branch: feature/user-authentication

retry_count: 0

---

## Phase History

GATHER COMPLETED 01-gather.md

SPEC COMPLETED 02-spec.md

BRAINSTORM COMPLETED 03-brainstorm.md

PLAN COMPLETED 04-plan.md

IMPLEMENT ACTIVE

How Phases Flow

Every Workflow is a State Machine

Phases execute sequentially with quality checks at boundaries. Error recovery is built in.

/claude-workflows:start → GATHER → SPEC → BRAINSTORM → PLAN → BRANCH

IMPLEMENT → TEST → QUALITY GATE → PR → CHAIN → next

■ Think & Decide ■ Build & Verify ■ Quality Gate ■ Ship & Chain

23 Workflow Skills

The Right Process for Every Task

Purpose-built workflows for every development scenario, from emergency hotfixes to full features

⚙️

New Feature

Complete feature lifecycle from requirements to merged PR

What it does: Gathers requirements (from Jira, Figma, or interactively), writes a formal spec, brainstorms implementation approaches with you, creates a phased plan ordered by architecture layers, builds it commit-by-commit with build checks, runs tests, then creates a PR after passing quality gates.

/claude-workflows:new-feature <name>

🔥

Hotfix

Emergency production fix, optimized for speed

What it does: Diagnoses the crash from stack traces, Crashlytics, or log files. Pinpoints the root cause. Applies the absolute minimum fix (1-5 lines ideal, warns if >15). Writes a mandatory regression test that fails without the fix. Creates PR to production with cherry-pick plan for dev branch.

/claude-workflows:hotfix <description>

🔄

Refactor

Restructure code with behavioral guarantees

What it does: Maps the full dependency graph (inbound + outbound). Documents a behavioral contract BEFORE touching code. Plans an incremental migration where every step compiles and passes tests. Uses parallel deprecation: new code alongside old, migrate consumers one by one, delete old only when zero references remain.

/claude-workflows:refactor <target>

🔎

Code Review

Systematic PR review with inline comments

What it does: Fetches the PR diff, categorizes files by architecture layer, reads each changed file in full (not just the diff). Checks against loaded checklists with 4 severity levels: error (blocks), warning, suggestion, nitpick. Generates inline comments with actionable fixes. Submits via GitHub API.

/claude-workflows:review <pr-number>

💡

Brainstorm

Interactive design exploration with structured techniques

What it does: Facilitates a collaborative conversation (never solo analysis). Uses techniques: Trade-off Matrix, Six Thinking Hats, SCAMPER, Reverse Brainstorm, Constraint Mapping. Three depth levels based on complexity. Scores options with weighted criteria. Surfaces relevant past decisions from the knowledge graph. You decide — Claude facilitates.

/claude-workflows:brainstorm --topic "..."

🧪

Test Generation

Coverage analysis, branch mapping, categorized tests

What it does: Analyzes the target's public API, maps every code branch (happy, error, edge, state, concurrency). Plans tests tagged [HAPPY] [ERROR] [EDGE] [STATE] [INTEGRATION]. Writes them with Given/When/Then naming. Runs coverage checks against a configurable target (default 90%). Reports gaps with reasons.

/claude-workflows:test <target>

🔨

Extend Feature

Add capabilities without breaking existing behavior

What it does: Analyzes the existing feature's code, identifies extension points where new behavior attaches without modifying existing code. Prefers new files over modifications. Guarantees: no signature changes, no test assertion changes, no behavior alterations. Runs full compatibility verification.

/claude-workflows:extend-feature <name>

⚡

CI Fix

Auto-diagnose and fix failing CI/CD pipelines

What it does: Fetches CI failure logs via gh CLI. Classifies: compile error, test failure, lint violation, dependency issue, config error, timeout, or flaky test. Applies targeted fix per category. Pushes and monitors the retry. If it fails again, loops up to 3 times with new diagnosis each round.

/claude-workflows:ci-fix

🚢

Migrate

Dependencies, APIs, architecture, databases

What it does: Documents current state before any changes. Evaluates migration strategies (big bang, incremental, parallel run, strangler fig). Creates a plan where every step independently compiles and passes tests. Type-specific guidance: dependency version bumps, API version swaps, architectural pattern migrations, database schema changes with reversible migrations.

/claude-workflows:migrate <type>

🚀

Release

Changelog, version bump, branch, PR, tag

What it does: Generates changelog from git history categorized by conventional commit type. Detects and bumps version in the right file (build.gradle, package.json, Cargo.toml, pyproject.toml, etc.). Creates release branch, PR to production with quality gate, and provides tagging commands for post-merge.

/claude-workflows:release <version>

🏠

New Project

Bootstrap a project with full Claude Code setup

What it does: Scans for build system markers (Gradle, npm, Cargo, go.mod, etc.), detects architecture patterns, extracts git conventions from history. Generates .workflows/config.yml and CLAUDE.md with build commands, architecture summary, and code conventions. Sets up task tracking scaffolding.

/claude-workflows:new-project

📃

Templates

Reuse specs and plans from past workflows

What it does: Save a completed workflow's spec + plan as a reusable template with parameter placeholders. Next time you build a similar feature, /claude-workflows:template use api-endpoint user-mgmt pre-populates the spec and plan, skipping GATHER and SPEC entirely. Templates track usage count.

/claude-workflows:template save|list|use

NEW

🔧

Skill Composer

Build custom workflow skills interactively

What it does: Asks what the skill does, what phases it has, what each phase produces, whether it needs brainstorming or creates a PR. Generates a properly structured SKILL.md with YAML frontmatter, orchestration integration, phase output paths, and error handling. You fill in the phase-specific logic.

/claude-workflows:compose-skill <name>

NEW

📊

Metrics

Track workflow velocity, bottlenecks, and trends

What it does: Reads telemetry data (JSON lines logged after every phase). Shows completion rates, average durations, bottleneck phases, and per-workflow breakdowns. /metrics trends compares your last 10 workflows vs previous 10 for velocity changes and REPLAN frequency.

/claude-workflows:metrics [trends]

NEW

🔌

Git Flow

Branch, commit, PR, merge using your project's conventions

What it does: Creates branches from configured patterns (feature/{name}, hotfix/{name}). Validates commit messages against your format (conventional, angular, simple). Creates PRs with configured base branch, reviewers, labels, and draft mode. Merges with configured strategy (squash/merge/rebase). Warns on protected branches.

/claude-workflows:git-flow branch|commit|pr|merge

📚

Learn

Capture and reuse successful patterns

What it does: Extracts reusable patterns from completed workflows: architecture decisions, implementation patterns, testing strategies, problem resolutions. Stores as markdown with tags. Patterns used 2+ times are marked "proven" and surface automatically during future brainstorming sessions.

/claude-workflows:learn capture|list|apply

🔍

Diagnose

Systematic bug investigation with hypothesis testing

What it does: Reproduces the bug, generates ranked hypotheses with evidence, then eliminates them one by one using targeted tests or git bisect. Documents the confirmed root cause with exact file, line, and blast radius — without fixing it. Hands off to /hotfix or /new-feature for the fix.

/claude-workflows:diagnose <symptom>

NEW

📏

Scope

Pre-flight complexity analysis before starting work

What it does: Scans the codebase for affected files, counts layers touched, checks for breaking changes. Rates complexity: Trivial, Small, Medium, Large, or Epic. Recommends which workflow to use and suggests concrete splits for oversized tasks with dependency ordering.

/claude-workflows:scope <description>

NEW

📈

Retrospective

Analyze workflow history for process improvements

What it does: Reads telemetry and workflow history to identify wins (high success rate workflows), issues (recurring replan triggers), and bottlenecks (phases that consistently cause trouble). Generates actionable recommendations with specific config changes. Can auto-apply approved config updates.

/claude-workflows:retrospective

NEW

🛡️

Guards

Safety checks for credentials and dangerous operations

What it does: Scans staged files against configurable block/warn patterns from guards.yml. Detects hardcoded tokens (AKIA, sk-, ghp_, Bearer), protected path violations, and dangerous operations (rm -rf). BLOCK severity stops the operation. WARN prints but allows. Override logging for audit trails.

/claude-workflows:guards init|check|report

Power Features

What Makes It Different

Not just prompts — a complete orchestration engine with intelligence built in

🔗 Workflow Chaining

Configure automatic workflow succession in YAML. After /claude-workflows:new-feature completes, Claude suggests /claude-workflows:review --self. After hotfix, suggests /claude-workflows:ci-fix. Zero manual handoffs between related workflows.

📸 Context Snapshots

After every phase, key decisions are appended to the Context section in the state file (3-5 bullet points). When Claude's context window compresses old messages during long workflows, it reloads the Context section to recover all prior reasoning. No more "I forgot what we decided in Phase 2."

⚡ Adaptive Depth

Auto-detects task complexity. A 2-file config change skips SPEC and BRAINSTORM (trivial). A 15-file architectural change forces deep brainstorm with multiple techniques (complex). Override with --depth full. The right amount of process for every task.

🧠 Knowledge Graph

Decisions are extracted to knowledge.jsonl after every workflow. During future brainstorms, Claude surfaces: "Last time you had similar constraints (offline-first), you chose event sourcing — it succeeded." Your team's institutional memory, encoded.

⚗ Parallel Execution Hints

Independent sub-steps within phases are marked for parallel execution. Review's FETCH phase fires off 4 API calls concurrently instead of sequentially. Same correctness, faster completion.

🛠 18 Orchestration Rules

Universal rules that apply to every workflow: state initialization, phase outputs, skip logic, quality gates, build detection, completion, pausing, error recovery (REPLAN), skill composition, checkpoints, telemetry, dry-run, chaining, and knowledge extraction. The engine behind every skill.

Usage Guide

How to Use the Plugin

From installation to your first feature — here's exactly what to expect

Install the Plugin

Run these commands inside Claude Code. It will download the plugin and prompt you to configure 5 settings.

# Inside Claude Code
/plugin marketplace add ragaa07/claude-workflows
/plugin install claude-workflows

# You'll be asked:
# - Project type (android, react, python, swift, go, generic)
# - Team (android, ios, frontend, backend, or none)
# - Main branch name (default: main)
# - Dev branch name (default: develop)
# - Commit format (conventional, angular, simple)

What happens: The plugin's skills, rules, and checklists become available as /claude-workflows:* commands in every Claude Code session within this project.

Initialize Your Project

Run setup to detect your project's stack and create the .workflows/ directory structure.

# Inside Claude Code
/claude-workflows:setup

# Or for new projects (does setup + generates CLAUDE.md):
/claude-workflows:new-project

What happens: Creates .workflows/config.yml with your project's detected settings (build system, language, git conventions). Also creates history and learned directories for workflow state. You can customize config.yml after generation.

Start Your First Workflow

Use /start to see all available workflows, or jump straight to a specific one.

# Browse available workflows
/claude-workflows:start

# Or go directly to a specific workflow
/claude-workflows:new-feature user-authentication
/claude-workflows:hotfix null-crash-login
/claude-workflows:review 42
/claude-workflows:brainstorm --topic "caching strategy"

What happens: Claude creates a state file at .workflows/current-state.md, shows a progress indicator, and begins the first phase. For /new-feature, it starts by gathering requirements interactively.

Work Through Each Phase

Claude executes phases sequentially. Some ask for your approval before continuing, others proceed automatically.

# Typical interaction during a new-feature workflow:

# GATHER: Claude asks you questions about the feature
# SPEC: Claude writes a spec, asks "approved?"
# BRAINSTORM: Interactive back-and-forth exploring approaches
# PLAN: Claude creates an implementation plan, asks "approved?"
# BRANCH: Creates git branch automatically
# IMPLEMENT: Builds phase by phase with build checks
# TEST: Runs tests, reports coverage
# PR: Runs quality gate, creates pull request

What to expect: After each phase, Claude writes an output file (e.g., 01-gather.md) and updates the state. A progress line shows where you are: ✓GATHER ✓SPEC ▷BRAINSTORM ·PLAN ·IMPLEMENT ·TEST ·PR

Pause, Resume, and Recover

You can pause at any time and resume later — even in a new session days later.

# Pause current workflow (say "pause" at any time)
# Claude saves progress and renames state to paused-<feature>.md

# Resume later (next session, Claude auto-detects active workflows)
/claude-workflows:resume

# If build fails 3+ times, Claude triggers REPLAN
# You review the adjusted plan and approve before continuing

What to expect: On resume, Claude validates the branch, checks output files, loads the Context section (key decisions), and picks up exactly where you left off. Session hooks automatically remind you of active workflows when you start Claude Code.

Review Quality and Ship

Before every PR, Claude runs a self-review against severity-rated checklists.

# Quality gate runs automatically in PR phase
# Claude loads general + language-specific + team checklists
# Checks each Critical/High item with explicit evidence
# Fixes Critical/High violations before creating the PR

# You can also review others' PRs:
/claude-workflows:review 42 --strict

What to expect: The PR is created with a structured body: summary, changes organized by phase, test results, and quality checklist. Critical issues are fixed before the PR is created — not after.

Learn and Improve Over Time

After workflows complete, capture patterns and track metrics to improve your process.

# Capture patterns from last workflow
/claude-workflows:learn capture

# Check workflow metrics
/claude-workflows:metrics
/claude-workflows:metrics health

# Run a retrospective on recent workflows
/claude-workflows:retrospective --last 10

What to expect: Learned patterns surface automatically during future brainstorming. The knowledge graph grows with every completed workflow. Metrics show completion rates, replan frequency, and bottleneck phases.

Skip the ceremony for small tasks

Use --depth trivial to skip SPEC and BRAINSTORM for simple changes. Or use /scope first to check if you even need a full workflow.

Automate approval gates

Use --auto flag on /new-feature, /extend-feature, /refactor, or /migrate to skip interactive approvals. Useful when requirements are well-defined.

Reuse past work

After completing a good workflow, run /template save api-endpoint. Next time: /template use api-endpoint user-mgmt pre-populates spec and plan.

Customize everything

Edit .workflows/config.yml to disable brainstorm for hotfixes, change PR base branch, set max plan phases, configure merge strategy, or set up workflow chaining.