zen

Claude Code Zen Workflow

日本語版はこちら / Japanese

Universal Issue-Driven Development Workflow for Claude Code

Overview

Claude Code Zen Workflow is a Claude Code plugin that provides a complete Issue-driven development workflow. It works with any software development project regardless of language or framework.

Features

• Universal: No dependency on specific tech stacks
• Automated: Auto-detection and auto-configuration
• Customizable: Flexible configuration via YAML
• Integrated: GitHub Projects, notifications (Slack/Discord/Teams)
• Smart Reviews: Dynamic multi-reviewer code review
• Sprint Management: Optional Iteration/Sprint support with team execution
• TDD Light Mode: Generate test skeletons from acceptance criteria before implementation
• Preflight Check: Unified pre-execution verification across all commands
• Local Work Memory: Compact-resilient work state management with lock/resuming support
• Implementation Contract: Structured Issue template format for clear specifications

Installation

zen Workflow uses a two-step installation: first register the marketplace, then install the plugin from it.

Step 1: Add the marketplace

/plugin marketplace add B16B1RD/cc-zen-workflow

Step 2: Install the plugin

/plugin install zen@zen-marketplace

Verify installation: Run /zen:init to confirm the plugin is working.

Quick Start

/zen:init

This will:

1. Detect your project type
2. Set up GitHub Projects integration
3. Generate Issue/PR templates
4. Create configuration file

Commands

Command	Description
/zen:init	Initial setup wizard
/zen:workflow	Show workflow guide
/zen:issue:list	List Issues
/zen:issue:create	Create new Issue
/zen:issue:start	Start work (end-to-end: branch → implementation → PR → review)
/zen:issue:update	Update work memory
/zen:issue:close	Check Issue completion
/zen:issue:edit	Edit existing Issue interactively
/zen:pr:create	Create draft PR
/zen:pr:ready	Mark as Ready for review
/zen:pr:review	Multi-reviewer review
/zen:pr:fix	Address review feedback
/zen:pr:cleanup	Post-merge cleanup
/zen:lint	Run quality checks
/zen:template:reset	Regenerate templates
/zen:sprint:list	List Sprints (optional)
/zen:sprint:current	Current sprint details (optional)
/zen:sprint:plan	Sprint planning (optional)
/zen:sprint:execute	Execute sprint Issues sequentially (optional)
/zen:sprint:team-execute	Execute sprint Issues in parallel with worktree-based teams (optional)
/zen:resume	Resume interrupted work
/zen:skill:suggest	Analyze context and suggest applicable skills

Workflow

/zen:issue:create → /zen:issue:start (Implementation → /zen:lint → /zen:pr:create → /zen:pr:review → /zen:pr:fix) → /zen:pr:ready → Merge → /zen:pr:cleanup

Note: /zen:issue:start executes the complete end-to-end flow: branch creation, implementation, quality checks, draft PR creation, self-review, and review fixes - all in one continuous process. See Phase 5: End-to-End Execution for details.

Status Transitions:

Todo → In Progress → In Review → Done
 ↑         ↑            ↑         ↑
Create   Start Work   Set Ready  Merged

Configuration

Create zen-config.yml in your project root:

version: "1.0"

project:
  type: webapp  # generic | webapp | library | cli | documentation

github:
  projects:
    enabled: true

branch:
  base: "main"       # Base branch for feature branches (use "develop" for Git Flow)
  release: "main"    # Release branch for production deployments
  pattern: "{type}/issue-{number}-{slug}"

commit:
  style: conventional

# Optional: Sprint/Iteration management
iteration:
  enabled: false  # Set true to enable

See Configuration Reference for all options.

Troubleshooting

Issue	Solution
Context limit reached during long-running commands	Run /clear then /zen:resume to continue

Documentation

• Full Specification
• Configuration Reference
• Best Practices Alignment
• 日本語ドキュメント

Requirements

• GitHub CLI (gh) - Required for GitHub operations

License

MIT License - See LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

Made with 🧘 zen