claudeflow - Workflow Orchestration for AI-Assisted Development

Workflow commands for seamless end-to-end feature development with AI coding assistants. Works with Claude Code, OpenCode, and other AI development tools.

What's New in v2

claudeflow v2.0.0 is a major release with breaking changes:

Standalone package - No external dependencies (ClaudeKit/STM removed)
Simplified installation - Just npm install and claudeflow setup
Tool-agnostic - Works with Claude Code, OpenCode, and other AI tools
Lower requirements - Node.js 20+ (down from 22.14+)
Streamlined workflow - Focus on workflow commands only

See CHANGELOG.md for full details.

Quick Start

Installation

Prerequisites: Node.js 20+ Check version: node --version | Install: https://nodejs.org

Install claudeflow globally via your preferred package manager:

npm

npm install -g @33strategies/claudeflow

yarn

yarn global add @33strategies/claudeflow

pnpm

pnpm add -g @33strategies/claudeflow

Setup

After installation, run the setup command:

claudeflow setup

Choose your installation mode:

1) Global - Install to ~/.claude/ (available in all projects)
2) Project - Install to ./.claude/ (this project only)

Quick decision:

Solo developer or want commands everywhere? → Global mode
Team project or want version control? → Project mode
Both? → You can do both! They work together via configuration hierarchy.

The setup will:

Check prerequisites (Node.js 20+, npm)
Copy custom workflow commands to your chosen location
Set up configuration files

What This Package Provides

claudeflow provides workflow commands for AI-assisted feature development:

Custom Workflow Commands

/brainstorm:start: Structured brainstorming with comprehensive documentation
/brainstorm:clarify: Resolve open questions interactively
/brainstorm:spec: Transform brainstorm into validated specification
/feedback:add: Quick capture of feedback items after testing
/feedback:resolve: Batch analyze and resolve pending feedback
/spec:doc-update: Parallel documentation review based on specs

Enhanced Spec Commands

/spec:create: Detects output path and creates specs in feature directories
/spec:decompose: Incremental mode preserves completed work
/spec:execute: Session resume capability with implementation tracking
/spec:migrate: Migrates existing specs to feature-directory structure

Key Features

Complete end-to-end workflow from brainstorming to deployment
Task tracking via doc/specs/<slug>/03-tasks.md
Session continuity across implementation runs
Interactive question resolution in specifications

Verify Installation

Check that everything is set up correctly:

claudeflow doctor

This diagnostic command checks:

Node.js version (need 20+)
npm availability
Claude Code CLI (optional - other AI tools supported)
.claude/ directory structure
Command files presence

Troubleshooting

"Command not found: claudeflow"

Ensure npm global bin is in your PATH
Try: npm list -g @33strategies/claudeflow
Reinstall: npm install -g @33strategies/claudeflow

"Commands not loading in Claude Code"

Run: claudeflow doctor
Verify files exist in ~/.claude/commands/ (global) or ./.claude/commands/ (project)
Restart Claude Code

Installation Issues

Run the diagnostic command for detailed information:

claudeflow doctor

Migration from install.sh

If you previously used the bash script installation:

Uninstall old version:

# Global installation
rm -rf ~/.claude

# OR Project installation
rm -rf .claude

Install via npm:
```
npm install -g @33strategies/claudeflow
```

Run setup:

# Global (if you used install.sh user)
claudeflow setup --global

# OR Project (if you used install.sh project)
claudeflow setup --project

Verify installation:
```
claudeflow doctor
```

Note: The migration only affects the installation method, not your feature work or task data.

Package Security

claudeflow is published with npm provenance attestations and SLSA Level 2 compliance. All releases are built and published via GitHub Actions with cryptographic verification.

For details on verifying package authenticity, supply chain security, and security best practices, see docs/SECURITY.md.

Update Management

claudeflow checks for updates automatically once per week (every 7 days). This check runs in the background and doesn't block command execution.

Manual update check:

npm outdated -g @33strategies/claudeflow

When updates are available, you'll see a notification:

╭───────────────────────────────────────────────────╮
│                                                   │
│   Update available: 1.3.0                        │
│   Current version:  1.2.0                        │
│   Run: npm install -g @33strategies/claudeflow   │
│                                                   │
╰───────────────────────────────────────────────────╯

To update:

# npm
npm update -g @33strategies/claudeflow

# yarn
yarn global upgrade @33strategies/claudeflow

# pnpm
pnpm update -g @33strategies/claudeflow

Document Organization

All documents related to a feature are organized in a single directory:

doc/specs/
└── <feature-slug>/
    ├── 01-brainstorm.md        # Brainstorming and research
    ├── 02-specification.md     # Validated specification
    ├── 03-tasks.md             # Task breakdown
    ├── 04-implementation.md    # Implementation summary
    └── 05-feedback.md          # Post-implementation feedback log

Benefits:

All related documents in one place
Clear lifecycle progression (01 → 02 → 03 → 04)
Easy to find and navigate
Git-friendly tracking

Example:

doc/specs/add-user-auth-jwt/
├── 01-brainstorm.md        # Created by /brainstorm:start
├── 02-specification.md     # Created by /brainstorm:spec (after /brainstorm:clarify)
├── 03-tasks.md             # Created by /spec:decompose
├── 04-implementation.md    # Created by /spec:execute
└── 05-feedback.md          # Created by /feedback:add (after testing)

Repository Structure

claudeflow/ (@33strategies/claudeflow npm package)
├── package.json                      # npm package metadata
├── bin/
│   └── claudeflow.js                 # CLI entry point
├── lib/
│   ├── setup.js                      # Installation logic
│   └── doctor.js                     # Diagnostic command
├── scripts/
│   └── verify-files.js               # Pre-publish file verification
│
├── .claude/                          # Custom configuration (distributed in package)
│   ├── commands/                     # Custom slash commands
│   │   ├── brainstorm/               # Brainstorming workflow commands
│   │   │   ├── start.md              # Structured brainstorming workflow
│   │   │   ├── clarify.md            # Resolve open questions
│   │   │   └── spec.md               # Transform brainstorm to spec
│   │   └── spec/
│   │       ├── create.md             # Enhanced spec creation
│   │       ├── decompose.md          # Incremental task breakdown
│   │       ├── execute.md            # Session-aware implementation
│   │       ├── feedback.md           # Post-implementation feedback
│   │       ├── doc-update.md         # Documentation review
│   │       └── migrate.md            # Spec structure migration
│   ├── settings.json.example         # Example configuration
│   └── README.md                     # Component documentation
│
├── .claude-plugin/                   # Plugin metadata
│   └── plugin.json                   # Package metadata
│
├── templates/                        # Configuration templates
│   ├── project-config/               # Project-level templates
│   │   ├── settings.json             # Team settings
│   │   ├── settings.local.json.example
│   │   ├── CLAUDE.md                 # Project instructions
│   │   ├── CLAUDE.local.md.example
│   │   └── .gitignore.example
│   └── user-config/                  # User-level templates
│       ├── settings.json             # Personal global settings
│       └── CLAUDE.md                 # Personal preferences
│
├── docs/                             # Documentation
│   ├── DESIGN_RATIONALE.md          # Design validation & best practices
│   └── ...
│
├── .github/
│   └── workflows/
│       └── release.yml               # CI/CD automation
├── .releaserc.json                   # Semantic-release config
├── .npmignore                        # Package exclusion rules
├── LICENSE                           # MIT License
├── CHANGELOG.md                      # Version history (auto-generated)
└── README.md                         # This file

Configuration

Configuration Hierarchy

Claude Code uses a 5-tier precedence system:

Enterprise policies (highest) - IT-managed, cannot be overridden
CLI arguments - Temporary session overrides
Local settings (.claude/settings.local.json) - Personal, gitignored
Project settings (.claude/settings.json) - Team, committed
User settings (~/.claude/settings.json) - Personal global defaults

Available Commands

/brainstorm:start

Structured brainstorming workflow that enforces complete investigation for any code-change task (bug fix or feature). Produces comprehensive brainstorm documentation including:

Intent & assumptions
Pre-reading log
Codebase mapping
Root cause analysis (for bugs)
Research findings
Clarification questions

Usage: /brainstorm:start Fix chat UI auto-scroll bug when messages exceed viewport height

/brainstorm:clarify

Resolve open questions in a brainstorm or specification document interactively. This command:

Reads the document and detects unanswered questions
Presents each question with context and options
Records answers in strikethrough format (audit trail)
Re-validates and loops until all questions resolved
Shows progress: "Question 3 of 12"

Key Features:

Supports multi-select for questions requiring multiple choices
Detects external edits to prevent data loss
Backward compatible (skips if no questions exist)
Re-entrant (skips already-answered questions)
Save-as-you-go for recoverability

Usage: /brainstorm:clarify doc/specs/<slug>/01-brainstorm.md

Example:

/brainstorm:clarify doc/specs/my-feature/01-brainstorm.md
# → System detects 5 open questions
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Question 1 of 5
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Package Manager Support
# → User selects: npm, yarn, pnpm (all three)
# → Document updated with strikethrough answer
# → Continues with questions 2-5
# → Final summary shows 5 questions resolved

Answer Format (Audit Trail):

Questions are marked as resolved using strikethrough format:

Before:

1. **ClaudeKit Version Compatibility**
   - Option A: Pin exact version
   - Option B: Use caret range

After:

1. ~~**ClaudeKit Version Compatibility**~~ (RESOLVED)
   **Answer:** Use caret range (^1.0.0)
   **Rationale:** Automatic updates, test compatibility in CI/CD

   Original context preserved:
   - Option A: Pin exact version
   - Option B: Use caret range

This format provides a complete audit trail showing both the original question and the final decision.

/brainstorm:spec

Transform a brainstorm document into a validated, implementation-ready specification. This command:

Reads and synthesizes the brainstorm document
Interactively gathers decisions from the user
Creates a detailed specification using /spec:create
Validates it with /spec:validate
Presents a summary with next steps

Usage: /brainstorm:spec doc/specs/<slug>/01-brainstorm.md

Note: Run /brainstorm:clarify first to resolve any open questions before creating the specification.

/feedback:add

Quick capture of feedback items after manual testing. This command:

Locates the specification (auto-selects most recent if not specified)
Creates or loads 05-feedback.md file
Loops to capture multiple feedback items
Saves each item immediately (save-as-you-go)
Presents summary and next steps

Usage: /feedback:add or /feedback:add doc/specs/my-feature/02-specification.md

Example:

/feedback:add
# → Auto-selects most recent specification
# → "What feedback do you have?"
# → User enters: "Login button should be more prominent"
# → FB-1 added.
# → "What feedback do you have?" (loop continues)
# → User selects "Done"
# → Summary: 3 feedback item(s) added
# → Next: Run /feedback:resolve to analyze and resolve

/feedback:resolve

Batch analyze and resolve all pending feedback items. This command:

Locates the feedback file (auto-selects most recent if not specified)
Loads all pending items from 05-feedback.md
Analyzes all items in parallel using domain experts
Presents each item with analysis for user decision (implement/defer/out-of-scope)
Updates specification with approved changes
Logs resolutions in 05-feedback.md

Integrates with incremental /spec:decompose and resume /spec:execute for seamless iteration.

Usage: /feedback:resolve or /feedback:resolve doc/specs/my-feature/05-feedback.md

Example:

/feedback:resolve
# → Auto-selects most recent feedback file
# → "3 pending feedback item(s)"
# → Analyzes all items in parallel
# → Presents FB-1 with analysis
# → User selects: "Implement"
# → Presents FB-2 with analysis
# → User selects: "Defer" (reason: "Not enough time")
# → Presents FB-3 with analysis
# → User selects: "Out of scope"
# → Updates specification with FB-1 changes
# → Summary: 1 implement, 1 defer, 1 out of scope
# → Next: Run /spec:decompose to create new tasks

/spec:doc-update

Review all documentation to identify what needs to be updated based on a new specification file. Launches parallel documentation expert agents to review each doc file for:

Deprecated content
Content requiring updates
Missing content for new features

Usage: /spec:doc-update doc/specs/text-generator-spec.md

Enhanced Spec Commands

/spec:create

Creates specifications in feature directories at doc/specs/<slug>/02-specification.md.

Usage: /spec:create Add user authentication with JWT tokens

/spec:decompose

Breaks down specifications into tasks with incremental mode that preserves completed work. Creates task breakdown in doc/specs/<slug>/03-tasks.md.

Usage: /spec:decompose doc/specs/add-user-auth/02-specification.md

Incremental Mode: Automatically detects when spec changelog has been updated and creates only new tasks for changes.

/spec:execute

Implements tasks with session resume capability. Reads implementation summary to skip completed tasks and continue from previous progress. Creates/updates doc/specs/<slug>/04-implementation.md.

Usage: /spec:execute doc/specs/add-user-auth/02-specification.md

Session Continuity: When you run /spec:execute multiple times on the same spec, it reads 04-implementation.md to understand what work has already been completed. This allows you to:

Work on large features across multiple sessions without re-doing completed tasks
Return to implementation after testing/feedback cycles
Maintain a complete history of all sessions (Session 1, Session 2, etc.)
Seamlessly integrate feedback workflow: implement → test → /feedback:add → /feedback:resolve → /spec:decompose (incremental) → /spec:execute (resume)

/spec:migrate

Migrates existing specs from flat structure to feature-directory structure.

Usage: /spec:migrate

Standard Workflow

This repository implements a complete end-to-end workflow for feature development:

┌─────────────────────────────────────────────────────────────────┐
│                   BRAINSTORM PHASE                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                 /brainstorm:start <task-brief>
                   (Custom Command)
                              │
                   Creates brainstorm doc
                   with research & analysis
                              │
                              ▼
               /brainstorm:clarify <brainstorm-doc>
                   (Resolve open questions)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   SPECIFICATION PHASE                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
          /brainstorm:spec <brainstorm-doc>
          (Custom, calls /spec:create & /spec:validate)
                              │
              Creates validated specification
                              │
                              ▼
            /spec:decompose <spec-file>
                              │
              Breaks spec into tasks
              (creates 03-tasks.md)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  IMPLEMENTATION PHASE                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
            /spec:execute <spec-file>
                              │
              Implements tasks
              (updates 03-tasks.md status)
                              │
                              ▼
                    Manual Testing
                              │
                   Discover issues or
                   improvement opportunities
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FEEDBACK PHASE                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              /feedback:add (capture items)
                              │
              Loop to add multiple items
              (save-as-you-go)
                              │
                              ▼
             /feedback:resolve (batch analyze)
                              │
              For each pending item:
              • Parallel analysis
              • User decision
                              │
                   ┌──────────┴──────────┬────────────┐
                   │                     │            │
               Implement Now           Defer     Out of Scope
                   │                     │            │
        Update spec changelog       Log for later    Log only
                   │                     │            │
                   └──────────┬──────────┴────────────┘
                              │
                              ▼
       /spec:decompose (incremental - if any "implement")
                              │
       /spec:execute (resume)
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    COMPLETION PHASE                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
           /spec:doc-update <spec-file>
                              │
        Reviews & updates documentation
                              │
                              ▼
               git commit & push
                              │
                              ▼
                          DONE! 🎉

Key Workflow Steps

Brainstorm → Comprehensive investigation and research
Clarify → Resolve open questions interactively
Specification → Validated, implementation-ready spec
Decomposition → Tasks broken down in 03-tasks.md
Implementation → Iterative execution with task status tracking
Feedback → Process post-implementation feedback with structured decisions (implement/defer/out-of-scope)
Completion → Documentation updates and git workflow

Usage Examples

Complete Workflow Example

# Step 1: Start with brainstorming
/brainstorm:start Add user authentication with JWT tokens
# → Creates: doc/specs/add-user-auth-jwt/01-brainstorm.md

# Step 2: Resolve any open questions
/brainstorm:clarify doc/specs/add-user-auth-jwt/01-brainstorm.md
# → Interactively resolves all open questions

# Step 3: Transform to validated specification
/brainstorm:spec doc/specs/add-user-auth-jwt/01-brainstorm.md
# → Creates: doc/specs/add-user-auth-jwt/02-specification.md (validated & complete)

# Step 4: Break down into tasks
/spec:decompose doc/specs/add-user-auth-jwt/02-specification.md
# → Creates: doc/specs/add-user-auth-jwt/03-tasks.md

# Step 5: Start implementation
/spec:execute doc/specs/add-user-auth-jwt/02-specification.md
# → Implements tasks, updates status in 03-tasks.md

# Step 6: Continue implementing (loop back to step 5 if needed)
/spec:execute doc/specs/add-user-auth-jwt/02-specification.md
# → Resume mode: skips completed work

# Step 7: Manual testing (discover feedback items)
# Test the implemented feature manually

# Step 8: Capture feedback items
/feedback:add doc/specs/add-user-auth-jwt/02-specification.md
# → Loop to capture multiple feedback items
# → Each item saved immediately

# Step 9: Resolve feedback (batch analyze and decide)
/feedback:resolve doc/specs/add-user-auth-jwt/05-feedback.md
# → Analyzes all pending items in parallel
# → Interactive decisions: implement/defer/out-of-scope
# → Updates spec with approved changes

# Step 10: If any "Implement" decisions, run incremental decompose
/spec:decompose doc/specs/add-user-auth-jwt/02-specification.md
# → Incremental mode: preserves completed tasks, creates only new ones

# Step 11: Resume implementation for new tasks
/spec:execute doc/specs/add-user-auth-jwt/02-specification.md

# Step 12: Update documentation and commit
/spec:doc-update doc/specs/add-user-auth-jwt/02-specification.md
# git add . && git commit -m "feat: add user authentication"
# git push

# All documents for this feature are now in: doc/specs/add-user-auth-jwt/

Quick Start (Skip Brainstorming)

If you already know what you need:

# Start directly with spec creation
/spec:create Add user authentication with JWT tokens

# Then follow steps 4-12 above

Migrating Existing Specs

If you have specs in the old flat structure:

# Migrate all existing specs to new structure
/spec:migrate

# This will:
# - Move specs/*.md to doc/specs/<slug>/02-specification.md
# - Move specs/*-tasks.md to doc/specs/<slug>/03-tasks.md
# - Move docs/ideation/*.md to doc/specs/<slug>/01-brainstorm.md
# - Generate migration report

Updating Documentation After Implementation

# After implementing a feature via a spec
/spec:doc-update doc/specs/add-user-auth-jwt/02-specification.md

# This will:
# - Review all docs for outdated content
# - Identify missing documentation for new features
# - Provide prioritized recommendations

Settings Management

Project Settings (.claude/settings.json - committed):

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)"],
    "deny": [".env", "**/*.key", "secrets/"]
  }
}

Personal Overrides (.claude/settings.local.json - gitignored):

Use for personal preferences that shouldn't be committed

Best Practices

1. Security First

Never commit secrets to .claude/settings.json
Use environment variable references: "API_KEY": "${API_KEY}"
Keep .env files gitignored

2. Team Collaboration

Commit .claude/settings.json and CLAUDE.md to git
Gitignore .claude/settings.local.json and CLAUDE.local.md

3. Context Optimization

Keep CLAUDE.md focused and concise
Break large tasks into smaller steps

Resources

Documentation

Installation Guide - When to use global vs project installation
Setup Guide - Detailed setup instructions
Design Rationale - Design validation and best practices
Feedback Workflow Guide - Complete guide to post-implementation feedback
GitHub Issues - Report problems

Contributing

Contributions welcome! Please:

Follow existing patterns and structure
Test changes thoroughly
Update documentation
Submit PRs with clear descriptions

License

MIT License - feel free to use and modify for your projects.

Acknowledgments

Anthropic - Claude Code CLI and AI development
Community contributors and examples

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.claude-plugin		.claude-plugin
.claude		.claude
.github/workflows		.github/workflows
bin		bin
doc/specs/v2-major-release-prep		doc/specs/v2-major-release-prep
docs		docs
lib		lib
scripts		scripts
specs		specs
templates		templates
.gitignore		.gitignore
.npmignore		.npmignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

claudeflow - Workflow Orchestration for AI-Assisted Development

What's New in v2

Quick Start

Installation

npm

yarn

pnpm

Setup

What This Package Provides

Custom Workflow Commands

Enhanced Spec Commands

Key Features

Verify Installation

Troubleshooting

"Command not found: claudeflow"

"Commands not loading in Claude Code"

Installation Issues

Migration from install.sh

Package Security

Update Management

Document Organization

Repository Structure

Configuration

Configuration Hierarchy

Available Commands

/brainstorm:start

/brainstorm:clarify

/brainstorm:spec

/feedback:add

/feedback:resolve

/spec:doc-update

Enhanced Spec Commands

/spec:create

/spec:decompose

/spec:execute

/spec:migrate

Standard Workflow

Key Workflow Steps

Usage Examples

Complete Workflow Example

Quick Start (Skip Brainstorming)

Migrating Existing Specs

Updating Documentation After Implementation

Settings Management

Best Practices

1. Security First

2. Team Collaboration

3. Context Optimization

Resources

Documentation

Contributing

License

Acknowledgments

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages