# Contributing

## Local Development

```bash
# Clone the repository
git clone https://github.com/anthropics/dev-flow.git
cd dev-flow

# Build dow + assemble + deploy locally (Claude Code example)
bash devtools/deploy-local.sh claude

# Verify installation
dow self-check
```

`deploy-local.sh` automates:
1. Compile dow (requires Rust toolchain)
2. Assemble plugin bundle (`devtools/assemble.sh`)
3. Install dow binary to `~/.local/bin/`
4. Deploy plugin to the target agent directory

### Individual Steps

```bash
# Build dow only
cd dow && cargo build --release

# Assemble plugin only
bash devtools/assemble.sh claude    # or codex / kiro / all

# Inspect assembled output
ls dist/claude/
```

## Project Structure

```
dev-flow/
├── dow/                        # Rust CLI source
│   ├── src/
│   │   ├── commands/           # Subcommands (status, setup, iterate, doctor...)
│   │   ├── hooks/              # Hook implementations
│   │   ├── dashboard/          # Dashboard web server (axum + SSE)
│   │   └── core/               # Shared libraries (config, platform, archive_db...)
│   ├── dashboard-frontend/     # Static frontend assets (D3, embedded at build)
│   ├── tests/                  # Integration tests
│   ├── references/             # Reference docs and templates (inject prompts)
│   └── Cargo.toml
├── plugin/                     # Shared plugin content (agent-agnostic)
│   ├── commands/               # Slash command definitions (.md)
│   └── agents/                 # Sub-agent prompt templates
├── targets/                    # Agent-specific configuration
│   ├── claude/                 # plugin.json + hooks.json
│   ├── codex/                  # plugin.json + hooks.json
│   └── kiro/                   # agents/dev-flow/config.json
├── dist/                       # Assembled output (from assemble.sh)
│   ├── claude/
│   ├── codex/
│   └── kiro/
├── install/                    # User-facing install scripts
│   ├── install.sh
│   └── install.ps1
├── devtools/                   # Development-only scripts
│   ├── assemble.sh             # Assemble plugin/ + targets/ → dist/
│   ├── assemble.ps1
│   ├── deploy-local.sh         # Build + assemble + deploy locally
│   └── deploy-local.ps1
├── npm/                        # npm wrapper (platform binary distribution)
├── vscode-extension/           # VS Code extension (dashboard webview)
├── docs/                       # Persistent project documentation
└── .dev-doc/                   # Workflow state (STATUS, CHANGELOG, tasks, issues)
```

## Development Conventions

- Shared content (commands, agents) lives in `plugin/` — one source, all agents. Skills are generated by `assemble.sh` into `dist/`.
- Agent-specific config (plugin.json, hooks.json) lives in `targets/<agent>/`.
- Hooks call the global `dow` binary directly — no relative paths or `${CLAUDE_PLUGIN_ROOT}`.
- Command prompts use runtime-neutral language (sub-agent template). Claude uses `Agent`, Codex uses `spawn_agent`, Kiro uses subagent.
- After adding a new command, register it in `targets/claude/plugin.json` commands array.
- After modifying `plugin/` or `targets/`, verify with `bash devtools/deploy-local.sh <agent>`.
- Never run `dow` commands inside `dow/` directory — it would create `.dev-doc/` in the source tree. Use `cd dow && cargo test` for testing (tests run in tmpdir isolation).

## Release Process

1. `dow version --bump patch` (or minor/major)
2. `git tag v<version> && git push --tags`
3. GitHub Actions builds 5-platform binaries + assembles bundles → publishes to Release
4. Users run `dow update` to get the new version

## Testing

```bash
# Rust unit + integration tests
cd dow && cargo test

# Manual integration testing (isolated directory)
mkdir -p tmp/test_target_project
cd tmp/test_target_project
dow init --name test --mode fast
dow self-check
```

> **Important**: Never test dow in the dev-flow repo root or any production project. Always use `tmp/test_target_project` for manual testing to avoid polluting workflow state.