[日本語版](../../user-guide/quick-start.md)

# Quick Start Guide

> **Start with the [Tutorial](./tutorial.md).** It walks the core of CommandMate — contract,
> verification gates, evidence — on a sample repository in about fifteen minutes.
>
> **The slash commands on this page belong to the CommandMate repository only.** `/work-plan`,
> `/tdd-impl` and the rest live in CommandMate's own `.claude/commands`; they are not installed into
> your repository. The portable equivalents are the official Catalog Skills (`cmate-verify`,
> `cmate-task-contract`, and others).

Get started with a development flow using CommandMate's slash commands and agents for Claude Code.

---

## Prerequisites

CommandMate must be installed and running.

```bash
# Install (first time only)
npm install -g commandmate
commandmate init --defaults

# Start the server
commandmate start --daemon
```

See the [CLI Setup Guide](./cli-setup-guide.md) for details.

---

## The minimum loop, on any agent

The `/work-plan` and `/tdd-impl` commands below are **Claude Code slash commands**, and they live in
the CommandMate repository's own `.claude/commands` at that. CommandMate's core loop — **contract in,
send, verification gate out** — runs with the same commands on any agent.

A contract is YAML, and what reaches the agent is the plain text composed from it. A gate is a shell
command run in the worktree's working directory, and pass or fail is that command's exit code.
Neither branches on the agent. **The only thing that changes is how you name the target.**

```bash
# name the target with --instance (a CLI tool id resolves to that tool's primary instance)
commandmate send <worktree-id> --contract .commandmate/tasks/<task>.yaml --instance opencode
commandmate wait <worktree-id> --instance opencode --verify
echo $?   # 0=passed / 20=a gate failed / 21=no work evidence / 10=waiting for an answer
```

Swap `opencode` for `claude`, `codex`, `command-code` and so on and it is the same round on that
agent. `wait` has no `--agent`, so **write `--instance` on both `send` and `wait`** — name it on
only one and the other waits on the worktree's default agent.

For the full round with OpenCode and Command Code — how to confirm where the target resolved, and
what genuinely does differ per agent — see
[the tutorial's appendix](./tutorial.md#appendix-run-the-same-loop-with-opencode-or-command-code).

---

## 5-Minute Development Flow

### Step 1: Review the Issue

Check Issues on GitHub and decide which one to work on.

```bash
# List issues
gh issue list

# View a specific issue
gh issue view 123
```

### Step 2: Create a Work Plan

Use the `/work-plan` command to create a work plan.

```
/work-plan 123
```

Output includes:
- Task breakdown
- Dependency diagram
- Quality check items
- Deliverables checklist

### Step 3: TDD Implementation

Use the `/tdd-impl` command for test-driven development.

```
/tdd-impl feature-name
```

TDD cycle:
1. **Red**: Write a failing test
2. **Green**: Write minimal implementation to pass
3. **Refactor**: Improve the code

### Step 4: Check Progress

Use the `/progress-report` command to check progress.

```
/progress-report 123
```

### Step 5: Create a PR

Use the `/create-pr` command to automatically create a Pull Request.

```
/create-pr
```

Auto-generated content:
- PR title (Conventional Commits format)
- Change description
- Test results
- Checklist

---

## Commonly Used Commands

| Command | Description | When to Use |
|---------|-------------|-------------|
| `/work-plan` | Create a work plan | When starting an Issue |
| `/tdd-impl` | TDD implementation | When implementing features |
| `/progress-report` | Progress report | For regular reports, completion checks |
| `/create-pr` | Auto-create PR | When implementation is complete |

---

## Development Flow Diagram

```
[Review Issue]
    |
    v
[/work-plan] --> Work Plan Document
    |
    v
[Create Branch]
    |
    v
[/tdd-impl] --> Tests & Implementation
    |
    v
[/progress-report] --> Progress Check
    |
    v
[/create-pr] --> Create PR
    |
    v
[Review & Merge]
```

---

## Quality Check Commands

Run these commands during development to ensure quality:

```bash
# Lint
npm run lint

# Type check
npx tsc --noEmit

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# Build
npm run build
```

---

## Troubleshooting

### Command Not Found

Check that command files exist in the `.claude/commands/` directory.

```bash
ls -la .claude/commands/
```

### Tests Failing

1. Check the error message
2. Review the related test file
3. Fix the implementation
4. Re-run tests

```bash
npm run test:unit -- --verbose
```

### Cannot Create PR

1. Check for uncommitted changes
2. Verify CI checks pass

```bash
git status
npm run lint && npx tsc --noEmit && npm run test:unit && npm run build
```

---

## Next Steps

- [CLI Setup Guide](./cli-setup-guide.md) - Installation and troubleshooting
- [Commands Guide](./commands-guide.md) - Detailed command usage
- [Agents Guide](./agents-guide.md) - Sub-agent details
- [Workflow Examples](./workflow-examples.md) - Practical usage examples

---

## Related Documentation

- [CLAUDE.md](../../../CLAUDE.md) - Project guidelines
- [README.md](../../../README.md) - Project overview
