commandmate 0.42.2 → 0.44.0

package/docs/en/user-guide/commands-guide.md

@@ -0,0 +1,467 @@
+[日本語版](../../user-guide/commands-guide.md)
+
+# Commands Guide
+
+A detailed guide to the slash commands available in CommandMate.
+
+> **These commands ship with the CommandMate repository, not with the `commandmate` package.**
+> They live in `.claude/commands/*.md` in this repository and are picked up by an agent CLI whose
+> working directory is a checkout of it. They are **not** installed by `npm install -g commandmate`,
+> and typing them in another repository produces an `Unknown command` rather than a run. To use them
+> elsewhere, copy the `.md` files into that repository's `.claude/commands/`. Agent Skills, which are
+> distributed and installed per worktree, are a different mechanism — see
+> [Agent Skills Distribution](./skills.md).
+
+---
+
+## Command List
+
+The four most-used commands, with their full descriptions further down this page:
+
+| Command | Description | Priority |
+|---------|-------------|----------|
+| `/work-plan` | Issue-based work plan creation | High |
+| `/create-pr` | Automatic PR creation | High |
+| `/progress-report` | Progress report generation | High |
+| `/tdd-impl` | TDD implementation | High |
+
+### All 27 Commands
+
+Every command in `.claude/commands/`. Follow the link for the full definition of each one.
+
+| Command | What it does |
+|---------|--------------|
+| [`/acceptance-test`](../../../.claude/commands/acceptance-test.md) | Run acceptance tests automatically against an Issue's requirements |
+| [`/apply-review`](../../../.claude/commands/apply-review.md) | Fold review findings back into the implementation |
+| [`/architecture-review`](../../../.claude/commands/architecture-review.md) | Design review, risk assessment, and improvement proposals |
+| [`/bug-fix`](../../../.claude/commands/bug-fix.md) | Fully automate investigating a defect, proposing a fix, and applying it |
+| [`/cause-analysis`](../../../.claude/commands/cause-analysis.md) | Analyze the root cause of the symptom in an Issue and append cause and countermeasures to it |
+| [`/create-pr`](../../../.claude/commands/create-pr.md) | Create a pull request, generating the title and description |
+| [`/current-situation`](../../../.claude/commands/current-situation.md) | Write up a defect precisely and file it as a new Issue |
+| [`/design-policy`](../../../.claude/commands/design-policy.md) | Support architecture design, technology selection, and design decisions |
+| [`/issue-create`](../../../.claude/commands/issue-create.md) | Create GitHub Issues in bulk from an Issue split plan |
+| [`/issue-enhance`](../../../.claude/commands/issue-enhance.md) | Analyze an Issue and fill in what is missing by asking the user |
+| [`/issue-split`](../../../.claude/commands/issue-split.md) | Split a feature into Issues and organize the dependencies |
+| [`/issues-exec-plan`](../../../.claude/commands/issues-exec-plan.md) | Analyze whether several Issues can run in parallel and file an epic Issue holding the execution plan |
+| [`/multi-stage-design-review`](../../../.claude/commands/multi-stage-design-review.md) | Run a four-stage design-document review (normal, consistency, impact, security) and apply the findings |
+| [`/multi-stage-issue-review`](../../../.claude/commands/multi-stage-issue-review.md) | Run a multi-stage Issue review (normal, impact scope) twice and apply the findings |
+| [`/orchestrate`](../../../.claude/commands/orchestrate.md) | Orchestrate several Issues in parallel (prepare, develop, PR, merge, UAT, fix loop, finish) |
+| [`/pm-auto-design2dev`](../../../.claude/commands/pm-auto-design2dev.md) | Automate design review through implementation (design review, work plan, TDD implementation) |
+| [`/pm-auto-dev`](../../../.claude/commands/pm-auto-dev.md) | Automate Issue development end to end (TDD, tests, report) |
+| [`/pm-auto-issue2dev`](../../../.claude/commands/pm-auto-issue2dev.md) | Automate Issue review through implementation (Issue review, design review, work plan, TDD implementation) |
+| [`/pr-merge-pipeline`](../../../.claude/commands/pr-merge-pipeline.md) | Automate PR creation, CI, sequential merges, and integration verification across several Issues |
+| [`/progress-report`](../../../.claude/commands/progress-report.md) | Produce a development progress summary and report blockers |
+| [`/refactoring`](../../../.claude/commands/refactoring.md) | Improve code quality, apply design patterns, and pay down technical debt |
+| [`/tdd-impl`](../../../.claude/commands/tdd-impl.md) | Implement to a high standard using test-driven development |
+| [`/uat`](../../../.claude/commands/uat.md) | Automate planning, reviewing, running, and reporting user acceptance tests on real machines |
+| [`/uat-fix-loop`](../../../.claude/commands/uat-fix-loop.md) | Automate the loop of failed UAT, feature-branch fix, new PR, re-merge, and re-run |
+| [`/work-plan`](../../../.claude/commands/work-plan.md) | Draw up a concrete work plan for one Issue |
+| [`/worktree-cleanup`](../../../.claude/commands/worktree-cleanup.md) | Clean up the Git worktree environments for the given Issue numbers |
+| [`/worktree-setup`](../../../.claude/commands/worktree-setup.md) | Build the Git worktree environments for the given Issue numbers |
+
+---
+
+## /work-plan
+
+### Overview
+
+A command that creates a detailed work plan on a per-issue basis and formulates implementation task details.
+
+### Usage
+
+```
+/work-plan [Issue number or summary]
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Issue number | Optional | Target GitHub Issue number |
+
+### Output
+
+1. **Issue summary** - Title, size, priority
+2. **Task breakdown** - Implementation, test, and documentation tasks
+3. **Dependency diagram** - Mermaid-format dependencies
+4. **Quality check items** - Required checks list
+5. **Deliverables checklist** - Completion criteria
+6. **Execution contract** - Declares the goal, the allowed change scope, and the verification gates (spec: [task-contract.md](../../design/task-contract.md))
+
+### Output Example
+
+```markdown
+## Issue: Add Dark Mode
+**Issue number**: #123
+**Size**: M
+**Priority**: High
+
+### Task Breakdown
+
+#### Implementation Tasks (Phase 1)
+- [ ] **Task 1.1**: Theme type definitions
+  - Deliverable: `src/types/theme.ts`
+```
+
+### Output Location
+
+- Work plan: `dev-reports/issue/{issue_number}/work-plan.md`
+- Execution contract: `.commandmate/tasks/issue-{issue_number}.yaml` (Git-tracked; include it in PR review)
+
+### Best Practices
+
+- Always run before starting an Issue
+- Review the plan with stakeholders
+- Re-run when the plan changes
+
+---
+
+## /create-pr
+
+### Overview
+
+A command that automates Pull Request creation. It auto-generates the title and description from Issue information.
+
+### Usage
+
+```
+/create-pr [options]
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Issue number | Optional | Explicitly specify (auto-detected from branch name if omitted) |
+| --draft | Optional | Create as a Draft PR |
+
+### Preconditions
+
+All of the following must be satisfied:
+
+- No uncommitted changes
+- All CI checks pass
+  - `npm run lint`
+  - `npx tsc --noEmit`
+  - `npm run test:unit`
+  - `npm run build`
+
+### Output
+
+1. **PR title** - Conventional Commits format
+2. **PR description** - Changes, test results, checklist
+3. **Labels** - Inherited from Issue
+
+### Output Example
+
+```markdown
+## Summary
+
+Added dark mode feature.
+
+Closes #123
+
+## Changes
+
+### Added
+- Theme toggle component
+- Dark mode styles
+
+## Test Results
+
+- Unit Tests: 15/15 passed
+- ESLint: 0 errors
+- TypeScript: 0 errors
+```
+
+### Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Issue number detection failed | Branch name doesn't follow convention | Explicitly specify the Issue number |
+| CI check failed | lint/test/build error | Fix the error and re-run |
+| Uncommitted changes | Changes not staged | `git add` & `git commit` |
+
+---
+
+## /progress-report
+
+### Overview
+
+A command that aggregates results from each development phase and creates a progress report.
+
+### Usage
+
+```
+/progress-report [Issue number]
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Issue number | Optional | Target GitHub Issue number |
+
+### Output
+
+1. **Summary** - Issue number, status
+2. **Phase-by-phase results** - TDD, test results
+3. **Quality metrics** - Coverage, static analysis errors
+4. **Blockers** - Issues, problems
+5. **Next steps** - Recommended actions
+
+### Output Example
+
+```markdown
+# Progress Report - Issue #123
+
+## Summary
+**Issue**: #123 - Add Dark Mode
+**Status**: Success
+
+## Phase Results
+
+### TDD Implementation
+- Coverage: 85%
+- Tests: 15/15 passed
+- Static analysis: 0 errors
+
+## Next Steps
+1. Create PR
+2. Request review
+```
+
+### Best Practices
+
+- Run regularly to visualize progress
+- Address blockers early
+- Run as a final check upon completion
+
+---
+
+## /tdd-impl
+
+### Overview
+
+A command that implements high-quality code following the Test-Driven Development (TDD) methodology.
+
+### Usage
+
+```
+/tdd-impl [feature name]
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Feature name | Optional | Name of the feature to implement |
+
+### TDD Cycle
+
+```
++---------+
+|   Red   | <-- Write a failing test
++----+----+
+     |
+     v
++---------+
+|  Green  | <-- Minimal implementation to pass
++----+----+
+     |
+     v
++---------+
+|Refactor | <-- Improve code
++----+----+
+     |
+     +--------> Repeat
+```
+
+### Output
+
+1. **Implementation** - Created/modified files
+2. **Test results** - Pass/fail counts, coverage
+3. **Static analysis results** - ESLint, TypeScript error counts
+4. **Commits** - Created commits
+
+### Output Example
+
+```
+TDD Implementation Complete
+
+## Implementation
+- src/lib/theme.ts
+- src/components/ThemeToggle.tsx
+
+## Test Results
+- Total: 10 tests
+- Passed: 10
+- Coverage: 85%
+
+## Static Analysis
+- ESLint: 0 errors
+- TypeScript: 0 errors
+
+## Commits
+- abc1234: feat(theme): add dark mode toggle
+```
+
+### Completion Criteria
+
+- All tests pass
+- Coverage 80% or above
+- Zero static analysis errors
+- Commits complete
+
+---
+
+## Command File Locations
+
+```
+.claude/
+├── commands/
+│   ├── work-plan.md
+│   ├── create-pr.md
+│   ├── progress-report.md
+│   └── tdd-impl.md
+├── agents/
+│   ├── tdd-impl-agent.md
+│   └── progress-report-agent.md
+└── prompts/
+    ├── tdd-impl-core.md
+    └── progress-report-core.md
+```
+
+---
+
+## Best Practices
+
+### 1. Command Execution Order
+
+```
+/work-plan -> /tdd-impl -> /progress-report -> /create-pr
+```
+
+### 2. Thorough Quality Checks
+
+Verify before running commands:
+
+```bash
+npm run lint
+npx tsc --noEmit
+npm run test:unit
+npm run build
+```
+
+### 3. Commit Message Convention
+
+Use Conventional Commits format:
+
+```
+feat(scope): add new feature
+fix(scope): fix bug
+docs(scope): update documentation
+test(scope): add tests
+refactor(scope): refactor code
+```
+
+---
+
+## CLI Tool Standard Slash Commands
+
+CommandMate supports Claude Code and Codex CLI. Each CLI tool has its own slash commands, and CommandMate automatically filters the available commands based on the selected CLI tool.
+
+### Claude Code Commands (16 types)
+
+Standard commands displayed when the Claude tab is selected.
+
+| Command | Description | Category |
+|---------|-------------|----------|
+| `/clear` | Clear conversation history and start fresh | Session |
+| `/compact` | Compress context to save capacity | Session |
+| `/resume` | Continue a previous conversation | Session |
+| `/rewind` | Reset conversation or code to a previous state | Session |
+| `/config` | Open settings interface | Settings |
+| `/model` | Switch the AI model | Settings |
+| `/permissions` | View/update tool access permissions | Settings |
+| `/status` | Display current status information | Monitoring |
+| `/context` | Display context usage as a color grid | Monitoring |
+| `/cost` | Display token usage and cost statistics | Monitoring |
+| `/review` | Code review current changes | Git |
+| `/pr-comments` | Display pull request comments | Git |
+| `/help` | List available slash commands | Utility |
+| `/doctor` | Check for installation issues | Utility |
+| `/export` | Export conversation to file or clipboard | Utility |
+| `/todos` | List current TODO entries | Utility |
+
+### Codex CLI Commands (10 types)
+
+Dedicated commands displayed when the Codex tab is selected.
+
+| Command | Description | Category |
+|---------|-------------|----------|
+| `/new` | Start a new conversation | Session |
+| `/undo` | Undo the last change | Session |
+| `/logout` | Log out from the current account | Session |
+| `/quit` | Exit Codex CLI | Session |
+| `/approvals` | Manage approval policies | Settings |
+| `/diff` | Show change diff | Git |
+| `/mention` | Manage @mentions | Utility |
+| `/mcp` | Manage MCP server connections | Utility |
+| `/init` | Initialize a project | Utility |
+| `/feedback` | Send feedback | Utility |
+
+### How to Use Commands
+
+1. Type `/` in the message input field to see available commands
+2. Only commands for the selected CLI tool (Claude / Codex) are displayed
+3. Select a command or type it directly and send
+
+---
+
+## Skills List
+
+Skills are Claude Code extensions that automate specific workflows.
+
+| Skill | Description | Arguments |
+|-------|-------------|-----------|
+| `/release` | Release automation | `patch` / `minor` / `major` / version number |
+| `/rebuild` | Server restart | None |
+
+### /release
+
+#### Overview
+
+Releases a new version. Automates the following:
+
+- Version update in package.json / package-lock.json
+- CHANGELOG.md update
+- Git tag creation and push
+- GitHub Releases creation
+
+#### Usage
+
+```
+/release patch      # Patch version bump (0.1.0 -> 0.1.1)
+/release minor      # Minor version bump (0.1.0 -> 0.2.0)
+/release major      # Major version bump (0.1.0 -> 1.0.0)
+/release 1.0.0      # Direct version specification
+```
+
+#### Preconditions
+
+- Must be on the main branch
+- No uncommitted changes
+- Synced with remote
+
+#### Details
+
+See the [Release Guide](../../release-guide.md) for details.
+
+---
+
+## Related Documentation
+
+- [Quick Start Guide](./quick-start.md) - 5-minute development flow
+- [Release Guide](../../release-guide.md) - Release procedures and skill details
+- [CLAUDE.md](../../../CLAUDE.md) - Project guidelines

package/docs/en/user-guide/quick-start.md

@@ -0,0 +1,231 @@
+[日本語版](../../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