wdi

# WDI Workflows

![Tests](https://github.com/whitedoeinn/dev-plugins-workflow/actions/workflows/test.yml/badge.svg)
![Plugin Validation](https://github.com/whitedoeinn/dev-plugins-workflow/actions/workflows/validate-plugin.yml/badge.svg)

Claude Code plugin providing compound-engineering workflows, development standards, and project scaffolding for White Doe Inn projects.

**Version:** 0.4.8 | **License:** MIT | [Architecture](docs/architecture.md) | [Troubleshooting](docs/troubleshooting.md) | [Contributing](CONTRIBUTING.md) | [Standards](docs/standards/) | **[New Contributor? Start Here](docs/COLLABORATOR-GUIDE.md)**

## Quick Start

Run in any project:

```bash
curl -sSL https://raw.githubusercontent.com/whitedoeinn/dev-plugins-workflow/main/install.sh | bash
```

Or clone and run locally:

```bash
git clone https://github.com/whitedoeinn/dev-plugins-workflow
cd dev-plugins-workflow
./install.sh
```

For full environment setup (machine deps, agent workspace, Claude Code config):

```bash
wdi setup
```

## Commands

### Workflow Commands

| Command | Description |
|---------|-------------|
| `/wdi:workflow-feature` | Feature workflow - quick idea OR full build (Plan → Work → Review → Compound) |
| `/wdi:workflow-feature #N` | Continue existing issue from where it left off |
| `/wdi:workflow-enhanced-ralph` | Quality-gated feature execution with research agents and type-specific reviews |
| `/wdi:workflow-milestone` | Create and manage milestones that group related features for delivery |
| `/wdi:workflow-setup` | Set up and verify plugin dependencies |
| `/wdi:triage-ideas` | Review idea backlog, identify clusters, prioritize |

### Skills (Auto-Invoked)

| Skill | Trigger | Description |
|-------|---------|-------------|
| `workflow-commit` | "commit these changes" | Smart commit with tests, auto-docs, and changelog |
| `workflow-auto-docs` | "update the docs" | Detect and fix documentation drift when commands/skills change |
| `workflow-config-sync` | "check my config" | Validate environment against baseline, auto-remediate drift |

### CLI Commands

| Command | Description |
|---------|-------------|
| `wdi setup` | Full environment setup: machine deps, agent workspace, Claude Code config |
| `wdi setup --verify` | Check environment without making changes |
| `wdi doctor` | Quick dependency check |

### Standards Commands

| Command | Description |
|---------|-------------|
| `/wdi:standards-new-repo` | Create a new repository following WDI naming and structure standards |
| `/wdi:standards-new-subproject` | Add a new subproject to a mono-repo following standards |
| `/wdi:standards-check` | Validate current repository against WDI development standards |
| `/wdi:standards-update` | Impact analysis and guided updates when changing development standards |
| `/wdi:standards-new-command` | Create a new command and update all dependent files |

### Frontend Commands

| Command | Description |
|---------|-------------|
| `/wdi:frontend-setup` | Install WDI design tokens to project (shadcn copy pattern) |

### Help Commands

| Command | Description |
|---------|-------------|
| `/wdi:help` | Quick reference card for all topics |
| `/wdi:help status` | Current session info, activity stats, and cost context |
| `/wdi:help cost` | Cost-aware AI usage (Clawdbot vs Claude Code billing) |
| `/wdi:help models` | Model selection guidance (when to use Opus/Sonnet/Haiku) |
| `/wdi:help workflow` | Feature workflow phases and handoff patterns |
| `/wdi:help thinking` | Thinking/reasoning toggle explained |
| `/wdi:help commands` | All WDI commands listed |

## Requirements

- Claude Code CLI
- `compound-engineering` plugin (installed automatically by `install.sh`)
- `gh` CLI authenticated (for GitHub Issue creation)

## Installation

### Option 1: Bootstrap Script (Recommended)

```bash
curl -sSL https://raw.githubusercontent.com/whitedoeinn/dev-plugins-workflow/main/install.sh | bash
```

This installs both `compound-engineering` and `wdi` plugins.

### Option 2: Manual Installation

```bash
# Add compound-engineering marketplace
/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin

# Install compound-engineering
/plugin install compound-engineering

# Add wdi marketplace
/plugin marketplace add https://github.com/whitedoeinn/dev-plugins-workflow

# Install wdi
/plugin install wdi
```

## Updating

### Automatic Updates (Default)

Plugin updates happen automatically on session start:
1. **First restart** - SessionStart hook downloads new plugin files
2. **Second restart** - Claude loads the updated plugin

This two-restart requirement is a Claude Code limitation. The hook clears the plugin cache and reinstalls to work around a bug in `plugin update` that doesn't re-download changed files.

### Manual Update

Re-run the install script:

```bash
curl -sSL https://raw.githubusercontent.com/whitedoeinn/dev-plugins-workflow/main/install.sh | bash
```

### If Updates Aren't Working

Nuclear reset (clears all plugin state):

```bash
rm -rf ~/.claude/plugins/cache/wdi-marketplace/
curl -sSL https://raw.githubusercontent.com/whitedoeinn/dev-plugins-workflow/main/install.sh | bash
```

See [troubleshooting.md](docs/troubleshooting.md) for more details.

## Workflow Details

### /wdi:workflow-feature

One command for the entire feature lifecycle:

```bash
/wdi:workflow-feature              # Start something new
/wdi:workflow-feature #45          # Continue existing issue
```

**Two entry points:**
| Mode | What Happens |
|------|--------------|
| **Quick idea** | One sentence → Issue created → Done (30 seconds) |
| **Build something** | Full workflow: Pre-flight → Learnings Search → Plan → Work → Review → Compound |

**The issue IS the document.** No separate plan files. The GitHub issue accumulates everything:
- Body: Problem, solution, plan
- Comments: Progress at each phase
- Labels: Current phase (`phase:planning`, `phase:working`, etc.)
- Close comment: Outcome and summary

📊 **Detailed diagram:** [docs/workflows/feature-workflow-diagram.md](docs/workflows/feature-workflow-diagram.md)

**Note:** The workflow commits directly to main with quality gates. Feature branches are not used by design ([#44](https://github.com/whitedoeinn/dev-plugins-workflow/issues/44)).

Flags:
- `--yes` / `-y` - Auto-continue through phases
- `--plan` - Stop after planning phase

### workflow-commit skill

Smart commit with quality gates. **Auto-invoked** when you say "commit these changes" or similar.

1. Stage changes (interactive or all)
2. Run tests (pytest, npm test based on file types)
3. Auto-update documentation (if commands/skills changed)
4. Generate commit message
5. Update changelog (`docs/changelog.md`)
6. Push

Flags (pass to Claude when requesting commit):
- `--yes` - Auto-accept defaults
- `--summary` - Generate fun changelog summary
- `--skip-tests` - Skip tests

## Cross-Platform Support

Works on macOS, Linux, and Windows (WSL). The install script automatically detects your platform.

## How It Works

This plugin uses Claude Code's markdown-based command system. Commands are defined as markdown files in `commands/` - the markdown IS the implementation. Skills in `skills/` auto-invoke based on context (e.g., say "commit these changes" to trigger the commit skill).

The plugin builds on top of `compound-engineering` which provides:
- **Research agents** for codebase analysis
- **Review agents** for code quality checks
- **Workflow skills** for planning and documentation
- **Frontend skills** for UI implementation (`frontend-design`, `design-iterator`)

See [docs/architecture.md](docs/architecture.md) for detailed diagrams.

## Templates

### Daily Changelog Automation

GitHub Action templates for automatic daily commit summaries.

| Template | Cost | Best For |
|----------|------|----------|
| [daily-changelog.yml](docs/templates/workflows/daily-changelog.yml) | Free | Most projects |
| [daily-changelog-claude.yml](docs/templates/workflows/daily-changelog-claude.yml) | ~$0.01-0.05/run | Teams wanting AI-enhanced summaries |

**Quick Setup (Bash version):**
```bash
# Copy to your project
cp docs/templates/workflows/daily-changelog.yml .github/workflows/

# Enable workflow permissions in GitHub:
# Settings > Actions > General > Workflow permissions > Read and write
```

**Claude-Enhanced Setup:**
```bash
# Copy to your project
cp docs/templates/workflows/daily-changelog-claude.yml .github/workflows/daily-changelog.yml

# Add your API key as a repository secret:
# Settings > Secrets and variables > Actions > New repository secret
# Name: ANTHROPIC_API_KEY
# Value: (your key from console.anthropic.com)
```

Both run at midnight Eastern Time and can be triggered manually from the Actions tab.

## Troubleshooting

Common issues and solutions are documented in [docs/troubleshooting.md](docs/troubleshooting.md).

Quick fixes:
- **"Unknown skill: commit"** → Plugin not installed. Run `install.sh`
- **Commands not found** → Restart Claude Code after installation
- **"Environment cannot be auto-fixed"** → Follow the remediation steps shown, then say "check my config"
- **"gh not authenticated"** → Run `gh auth login` to authenticate GitHub CLI
- **New machine?** → Run `wdi setup` for full environment bootstrap
- **Setup verification** → Run `wdi setup --verify` to check without changing anything

## Development Standards

This plugin enforces WDI development standards. Key conventions:

| Standard | Document |
|----------|----------|
| Repository naming | [REPO-STANDARDS.md](docs/standards/REPO-STANDARDS.md) |
| Project structure | [PROJECT-STRUCTURE.md](docs/standards/PROJECT-STRUCTURE.md) |
| File naming | [FILE-NAMING.md](docs/standards/FILE-NAMING.md) |
| Branch naming | [BRANCH-NAMING.md](docs/drafts/BRANCH-NAMING.md) *(draft - not implemented)* |
| Commit messages | [COMMIT-STANDARDS.md](docs/standards/COMMIT-STANDARDS.md) |
| Claude Code plugins | [CLAUDE-CODE-STANDARDS.md](docs/standards/CLAUDE-CODE-STANDARDS.md) |
| Frontend development | [FRONTEND-STANDARDS.md](docs/standards/FRONTEND-STANDARDS.md) |

Quick reference: [knowledge/standards-summary.md](knowledge/standards-summary.md)

### Key Conventions

- **Repos:** No `wdi-` prefix (org name provides context)
- **Commands:** Use `/wdi:*` prefix with domain-prefixed names (e.g., `/wdi:workflow-feature`)
- **Mono-repos:** Cluster by domain (`marketing-ops`, `business-ops`)
- **Plugins:** Standalone repos (`dev-plugins-*`)
- **Branches:** Workflow uses main; if using branches manually: `feature/`, `fix/`, `hotfix/`, `docs/`, `experiment/`

## Team Onboarding

Add this to each project's README:

```markdown
## Claude Code Setup

This project uses custom Claude Code workflows. First-time setup:

\`\`\`bash
curl -sSL https://raw.githubusercontent.com/whitedoeinn/dev-plugins-workflow/main/install.sh | bash
\`\`\`

Available commands:
- `/wdi:workflow-feature` - Full feature workflow
- `/wdi:standards-check` - Validate against WDI standards

Skills (auto-invoked):
- `workflow-commit` - Say "commit these changes" for smart commit with tests and changelog

To update: `./install.sh update`
```