# Workflow Plugin for Claude Code
Structured AI development workflow with plan-first discipline. Addresses three common AI limitations: no memory across sessions, shortcut-taking, and black-box code changes.
## Core Principle
**Plan first, code later.** The first deliverable is always a plan, never code.
## Skills
| Skill | Description |
|-------|-------------|
| `workflow` | Main orchestration: Brainstorm → Plan → Execute → Verify → Close |
| `add-model` | Add new modules/components following existing codebase patterns |
| `add-rule` | Add transformation rules, mappings, or converters between concepts |
| `issue-to-pr` | Convert GitHub issues into PRs with implementation plans |
| `review-implementation` | Verify structural completeness and code quality after implementation |
| `release` | Prepare version releases, bump versions, and tag releases |
### Skill Details
**workflow** — The primary orchestrator. Manages a 5-step workflow with state persistence in `.claude/workflow-state/`. Includes gate checks between steps, fast-track mode for trivial changes, and sub-agent decomposition for large tasks.
**add-model** — Guided 5-step process for adding new modules that follow existing patterns. Gathers requirements (name, type, interface, fields, behavior, reference), then implements, tests, and registers the new module.
**add-rule** — 6-step guide for adding transformations or mappings between concepts. Emphasizes closed-loop testing (source → target → solve → extract → verify) and correctness proofs.
**issue-to-pr** — Parses GitHub issues, validates completeness against checklists, researches references, and creates plan-only PRs. Uses `gh` CLI for GitHub integration.
**review-implementation** — Auto-detects changes via `git diff`, runs structural and semantic checks, and generates a pass/fail report. Auto-invoked at the end of workflow, add-model, and add-rule skills.
**release** — 4-step release process with semver version bumping, pre-release verification, changelog generation, and tag management.
## Installation
### Prerequisites
- Claude Code version 1.0.33 or later (`claude --version`)
### Step 1: Add marketplace
```bash
claude plugin marketplace add https://github.com/pzheng460/claude-workflow-plugin.git
```
### Step 2: Install plugin
```bash
claude plugin install workflow@workflow
```
The plugin is automatically enabled after installation.
### Step 3: Verify
Restart Claude Code and the workflow skills should be available. Try `/workflow:workflow` to get started.
## Updating
```bash
claude plugin update workflow@workflow
```
Restart Claude Code to apply the update.
## Uninstalling
```bash
claude plugin uninstall workflow@workflow
```
To also remove the marketplace:
```bash
claude plugin marketplace remove workflow
```
## Usage
Skills are invoked with the `workflow:` namespace prefix:
```
/workflow:workflow # Start the main workflow
/workflow:add-model # Add a new module following existing patterns
/workflow:add-rule # Add a transformation/mapping rule
/workflow:issue-to-pr # Convert a GitHub issue to a plan PR
/workflow:review-implementation # Review implementation quality
/workflow:release # Prepare a release
```
Skills are also auto-invoked by Claude based on task context (e.g., `review-implementation` runs automatically at the end of the workflow).
## How It Works
The workflow manages state via JSON files in `.claude/workflow-state/`, ensuring steps cannot be skipped and decisions are recorded. Each workflow goes through:
1. **Brainstorm** — Align on constraints, ambiguities, and approach with the human
2. **Plan** — Produce a concrete, reviewable plan (the first deliverable)
3. **Execute** — Implement the approved plan, nothing more
4. **Verify** — Prove correctness via tests, diff traceability, and acceptance criteria
5. **Close** — Gather feedback, persist knowledge, and archive
## License
MIT