commandmate 0.42.2 → 0.44.0

package/docs/en/user-guide/workflow-examples.md

@@ -0,0 +1,463 @@
+[日本語版](../../user-guide/workflow-examples.md)
+
+# Workflow Examples
+
+Practical workflow examples using CommandMate's commands and agents.
+
+---
+
+## 1. New Feature Development Flow
+
+A standard workflow for developing a new Issue.
+
+### Step 1: Review the Issue
+
+```bash
+# List issues
+gh issue list
+
+# View the target issue
+gh issue view 123
+```
+
+### Step 2: Create a Work Plan
+
+```
+/work-plan 123
+```
+
+**Output example**:
+```markdown
+## Issue: Add Dark Mode
+**Issue number**: #123
+**Size**: M
+**Priority**: High
+
+### Task Breakdown
+- [ ] Task 1.1: Theme type definitions
+- [ ] Task 1.2: Create theme context
+- [ ] Task 1.3: Implement UI components
+- [ ] Task 2.1: Unit tests
+...
+```
+
+### Step 3: Automated Development
+
+```
+/pm-auto-dev 123
+```
+
+**Execution**:
+1. TDD implementation (test creation -> implementation -> refactoring)
+2. Acceptance testing
+3. Code quality improvement
+4. Progress report creation
+
+### Step 4: Create PR
+
+```
+/create-pr
+```
+
+**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
+- Coverage: 85%
+```
+
+---
+
+## 2. Bug Fix Flow
+
+A workflow for fixing issues when bugs are discovered.
+
+### Step 1: Bug Report
+
+A bug is discovered by a user or yourself.
+
+### Step 2: Automated Investigation & Fix
+
+```
+/bug-fix API error occurring
+```
+
+**Execution phases**:
+
+**Phase 1: Bug Investigation**
+- Error log analysis
+- Root cause identification
+
+```markdown
+## Investigation Summary
+
+**Root cause**: Timeout setting too short
+**Impact scope**: All users
+**Severity**: high
+```
+
+**Phase 2: Solution Proposals**
+```markdown
+## Solutions (by priority)
+
+1. [High] Change timeout setting (30 min)
+2. [Medium] Add retry logic (1 hour)
+
+Which solution would you like to implement?
+```
+
+**Phase 3-6: Fix, Test & Report**
+- TDD fix implementation
+- Acceptance testing
+- Progress report
+
+### Step 3: Create PR
+
+```
+/create-pr
+```
+
+---
+
+## 3. Refactoring Flow
+
+A workflow for improving code quality.
+
+### Step 1: Identify Targets
+
+```
+/refactoring src/lib/utils.ts
+```
+
+### Step 2: Analysis & Execution
+
+**Output example**:
+```
+Refactoring Complete
+
+## Refactoring Applied
+- Split long functions
+- Removed duplicate code
+- Improved naming
+
+## Quality Metrics Improvement
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Coverage | 75.0% | 85.0% | +10.0% |
+| ESLint errors | 5 | 0 | -5 |
+```
+
+### Step 3: Verify Tests
+
+```bash
+npm run test:unit
+npm run lint
+npx tsc --noEmit
+```
+
+---
+
+## 4. Emergency Response Flow
+
+A workflow for emergency response when production issues occur.
+
+### Step 1: Assess the Situation
+
+```bash
+# Check recent logs
+tail -100 logs/error.log
+
+# Check environment variables
+cat .env.production
+```
+
+### Step 2: Emergency Fix
+
+```
+/bug-fix API error occurring in production
+```
+
+**Setting severity to critical**:
+- Prioritize implementing Solution 1
+- Run tests
+- Prepare for immediate deployment
+
+### Step 3: Create hotfix Branch
+
+```bash
+git checkout -b hotfix/critical-api-fix
+```
+
+### Step 4: Create PR (emergency merge)
+
+```
+/create-pr
+```
+
+---
+
+## 5. Fully Automated Development Flow
+
+A flow where you just specify an Issue number and development runs to completion automatically.
+
+### Execution
+
+```
+/pm-auto-dev 166
+```
+
+### Auto-execution Details
+
+```
+Phase 1: Issue information gathered
+  - Issue #166: Add new feature
+  - Acceptance criteria: 3 items
+  - Implementation tasks: 5 items
+
+Phase 2: TDD Implementation (Iteration 1/3)
+  - Launching tdd-impl-agent...
+  - Coverage: 85%
+  - Tests: 15/15 passed
+
+Phase 3: Acceptance Testing
+  - Launching acceptance-test-agent...
+  - Test scenarios: 3/3 passed
+
+Phase 4: Refactoring
+  - Launching refactoring-agent...
+  - Coverage: 85% -> 88%
+
+Phase 5: Progress Report
+  - Launching progress-report-agent...
+  - Report created
+
+Issue #166 development complete!
+```
+
+### After Completion
+
+```
+/create-pr
+```
+
+---
+
+## 6. Standalone TDD Execution Flow
+
+A flow for running just TDD implementation.
+
+### Execution
+
+```
+/tdd-impl new API endpoint
+```
+
+### TDD Cycle
+
+**Red Phase**:
+```typescript
+// tests/unit/api.test.ts
+it('should return data', async () => {
+  const result = await fetchData()
+  expect(result).toBeDefined()
+})
+```
+
+**Green Phase**:
+```typescript
+// src/lib/api.ts
+export async function fetchData() {
+  return { data: 'test' }
+}
+```
+
+**Refactor Phase**:
+- Improve code
+- Re-run tests
+
+### Result
+
+```
+TDD Implementation Complete
+
+## Test Results
+- Total: 5 tests
+- Passed: 5
+- Coverage: 90%
+
+## Static Analysis
+- ESLint: 0 errors
+- TypeScript: 0 errors
+```
+
+---
+
+## 7. Contract-Based Parallel Development Flow
+
+Delegate several issues to separate worktrees in parallel and decide whether each
+one is done **from an exit code rather than by reading the agent's report**. The
+gates in `.commandmate/verify.yaml` adjudicate — not the worker's "all done!"
+message.
+
+Prerequisite: `commandmatedev send --help` lists `--contract` and `wait --help`
+lists `--verify` (the contract flags exist only on develop builds).
+
+### Step 1: Draft an execution contract and place it in the worktree
+
+Write `.commandmate/tasks/issue-<N>.yaml` **inside the target worktree**, one per
+issue. The spec is [task-contract.md](../../design/task-contract.md); a worked
+example ships as `.commandmate/tasks/example.yaml`.
+
+```yaml
+version: 1
+title: "Issue #1600: add a dark mode toggle"
+goal: |
+  Implement https://github.com/Kewton/CommandMate/issues/1600.
+  Acceptance criteria:
+  - a toggle appears in the header
+  - the selected theme survives a reload
+scope:
+  allow:
+    - "src/components/layout/**"
+    - "tests/unit/components/**"
+  deny: []
+verify:
+  gates: [lint, typecheck, unit]   # omit the key to run every gate (recommended)
+success:
+  requireWorkEvidence: true
+  requireScopeClean: true
+```
+
+The contract does not have to be committed. The `work-evidence` and `scope` gates
+exclude the contract file itself from the change set, so dropping a contract into
+a worktree never makes it look like work was done.
+
+### Step 2: Send with the contract
+
+`--contract` composes the goal into the message body, so **do not pass a message
+argument** (passing both exits 2). The task id is printed on stdout.
+
+```bash
+WT=$(commandmatedev ls --branch "feature/1600" --quiet)
+TASK_ID=$(commandmatedev send "$WT" \
+  --contract .commandmate/tasks/issue-1600.yaml \
+  --instance claude --auto-yes --duration 3h)
+```
+
+Name the target with `--instance`, not `--agent`. `wait` does not accept
+`--agent`, so naming the agent only on `send` leaves the `wait` in Step 3
+watching the worktree's default agent (Issue #1638).
+
+Right after sending, run `commandmatedev capture "$WT"` to confirm the worker
+actually started. `send` can exit 0 while the text sits unsubmitted in the composer.
+
+### Step 3: Wait, then verify
+
+```bash
+commandmatedev wait "$WT" --instance claude --on-prompt human --verify --timeout 10800
+echo "exit=$?"
+```
+
+Without `--on-prompt human`, every detected prompt returns exit 10 immediately.
+`--verify` runs every gate **after** completion is detected and turns the result
+into the exit code.
+
+### Step 4: Branch on the exit code
+
+| exit | Meaning | What to do |
+|------|---------|-----------|
+| `0` | Done, verification passed | Move on to the PR (`/create-pr`) |
+| `20` | Verification failed | `commandmatedev verify "$WT" --json` to find the failing gate, then re-instruct with its `logTail`. Cap at 2 retries |
+| `21` | No work evidence | `commandmatedev capture "$WT"` to tell an unsubmitted composer from a permission prompt or a session that never launched |
+| `10` | Prompt detected | `commandmatedev respond "$WT" "yes"`, then wait again |
+| `124` | Timed out | Inspect with capture |
+
+```bash
+# On exit 20: which gate failed?
+commandmatedev verify "$WT" --json
+```
+
+The verdict stays queryable afterwards, and a worktree id is enough — you never
+need to have kept the task id:
+
+```bash
+commandmatedev task list "$WT" --limit 5     # id / status / agent / gates / title
+commandmatedev task show "$TASK_ID"          # contract + the verification run that judged it
+```
+
+### Running them in parallel
+
+Repeat steps 1–4 per issue: independent issues in parallel, strongly dependent
+ones in sequence. If you supervise with the
+[orchestrate-monitor skill](../../../.claude/skills/orchestrate-monitor/SKILL.md),
+give it the task-status hook as well:
+
+```bash
+.claude/skills/orchestrate-monitor/scripts/monitor.sh \
+  --hooks .claude/skills/orchestrate-monitor/scripts/hooks-git.sh \
+  --hooks .claude/skills/orchestrate-monitor/scripts/hooks-task.sh \
+  --interval 20 --idle-threshold 8 "$WT" ...
+```
+
+The tmux session an intervention is sent to is derived from the poll's
+`cliToolId`, so no option is needed even for a fleet running several agents
+(#1601). Only a non-default instance needs to be named, as
+`<worktree-id>@<instance-id>` (e.g. `w1@codex-2`).
+
+**The monitor's `COMPLETE` is not a merge verdict.** The verdict is the exit code
+from step 3. The monitor only decides when to go look.
+
+---
+
+## Best Practices for Command Usage
+
+### 1. Start with a Plan
+
+```
+/work-plan -> /pm-auto-dev -> /create-pr
+```
+
+### 2. Regular Progress Checks
+
+```
+/progress-report 123
+```
+
+### 3. Thorough Quality Checks
+
+```bash
+npm run lint
+npx tsc --noEmit
+npm run test:unit
+npm run build
+```
+
+### 4. Commit Message Convention
+
+```
+feat(scope): add new feature
+fix(scope): fix bug
+refactor(scope): refactor code
+test(scope): add tests
+docs(scope): update documentation
+```
+
+---
+
+## Related Documentation
+
+- [Quick Start Guide](./quick-start.md) - 5-minute development flow
+- [Commands Guide](./commands-guide.md) - Command details
+- [Agents Guide](./agents-guide.md) - Agent details

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "commandmate",
-  "version": "0.42.2",
-  "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
+  "version": "0.44.0",
+  "description": "No long blocks of time? Run an AI team from your phone. Git worktree sessions, task contracts and verification gates for Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity and Command Code.",
   "keywords": [
+    "ai-agents",
     "claude-code",
     "codex-cli",
     "gemini-cli",
-    "agent-cli",
-    "cli-orchestration",
-    "ai-coding",
-    "git-worktree",
     "coding-agent",
-    "session-manager",
+    "agent-orchestration",
+    "git-worktree",
+    "verification-gates",
+    "mobile",
     "tmux",
     "cli",
     "developer-tools"
@@ -32,7 +32,16 @@
     ".next/",
     "!.next/cache",
     "public/",
+    "docs/en/user-guide/quick-start.md",
+    "docs/en/user-guide/commands-guide.md",
+    "docs/en/user-guide/webapp-guide.md",
+    "docs/en/user-guide/workflow-examples.md",
+    "docs/en/user-guide/cli-setup-guide.md",
+    "docs/en/user-guide/agents-guide.md",
+    "docs/en/user-guide/cmate-schedules-guide.md",
+    "docs/en/architecture.md",
     "scripts/hooks/",
+    "scripts/opencode-v2/",
     ".env.example",
     "release-notes/"
   ],
@@ -140,5 +149,8 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.2"
+  },
+  "overrides": {
+    "@xmldom/xmldom": "^0.9.12"
   }
 }

package/release-notes/0.43.0.json

@@ -0,0 +1,130 @@
+{
+  "version": "0.43.0",
+  "date": "2026-09-30",
+  "highlight": {
+    "ja": "OpenCode V2 をエージェントとして使えるようになりました。起動・状態表示・承認や質問への応答・スケジュールまで、これまでの OpenCode と同じ場所で扱えます。",
+    "en": "OpenCode V2 is now available as an agent. Launching, status, answering approvals and questions, and schedules all work in the same places as the existing OpenCode."
+  },
+  "added": [
+    {
+      "ja": "OpenCode V2 をエージェントとして選べるようになり、起動・終了と状態の表示ができるようになりました。",
+      "en": "You can now choose OpenCode V2 as an agent, start and stop it, and see its status."
+    },
+    {
+      "ja": "OpenCode V2 の承認と質問に、画面・スマホ・CLI・Auto-Yes から答えられるようになりました。",
+      "en": "You can now answer OpenCode V2 approvals and questions from the screen, your phone, the CLI, or Auto-Yes."
+    },
+    {
+      "ja": "OpenCode V2 の入力欄で「/」を打つと、スラッシュコマンドの候補が出るようになりました。",
+      "en": "Typing / in the OpenCode V2 input now shows slash command suggestions."
+    },
+    {
+      "ja": "OpenCode V2 で、実際に返答したモデル名が画面と capture に出るようになりました。",
+      "en": "OpenCode V2 now shows the model that actually replied, on screen and in capture."
+    },
+    {
+      "ja": "OpenCode V2 でも、エージェント切り替えやコマンドパレットのクイックキーが使えるようになりました。",
+      "en": "Quick keys such as agent switching and the command palette now work with OpenCode V2."
+    },
+    {
+      "ja": "OpenCode V2 のトークン・費用・コンテキストの使用量が、これまでの OpenCode と同じ場所に出るようになりました。",
+      "en": "OpenCode V2 token, cost, and context usage now appear in the same place as for the existing OpenCode."
+    },
+    {
+      "ja": "スケジュールで OpenCode V2 を指定でき、モデルやエージェントなどの実行オプションも渡せるようになりました。",
+      "en": "Schedules can now run OpenCode V2 and pass run options such as the model and agent."
+    },
+    {
+      "ja": "OpenCode V2 のダイアログカードに、モデルを切り替えるキーが出るようになりました。",
+      "en": "OpenCode V2 dialog cards now show the keys for switching models."
+    },
+    {
+      "ja": "日次確認の対象に OpenCode V2 が加わりました。",
+      "en": "The daily health check now covers OpenCode V2."
+    },
+    {
+      "ja": "新しい commandmate reply コマンドで、セッションの最新の返答を読めるようになりました。",
+      "en": "The new commandmate reply command reads a session's latest reply."
+    }
+  ],
+  "improved": [
+    {
+      "ja": "OpenCode V2 の Build と Plan の切り替えが入力欄の横のボタンになり、今のエージェントが表示されるようになりました。",
+      "en": "Switching between Build and Plan in OpenCode V2 is now a button next to the input, and it shows the current agent."
+    },
+    {
+      "ja": "Skill の互換表で、OpenCode V2 は Skill を足したあとに開始し直さなくてよいことを示すようにしました。",
+      "en": "The Skill compatibility table now shows that OpenCode V2 does not need a restart after a Skill is added."
+    },
+    {
+      "ja": "commandmate ask が、会話が長すぎてモデルの上限を超えたときに、完了ではなく失敗として返すようになりました。",
+      "en": "commandmate ask now reports a failure, not a completed turn, when the conversation is over the model's context limit."
+    },
+    {
+      "ja": "起動したばかりの Command Code にすぐ送ったとき、「起動中」として返すようになりました。",
+      "en": "Sending to a Command Code session that has only just started is now reported as still starting."
+    }
+  ],
+  "fixed": [
+    {
+      "ja": "新しいセッションを起動した直後の送信が、約 1 分待たされて失敗することがある問題を直しました。",
+      "en": "Fixed the first send to a new session sometimes waiting about a minute and then failing."
+    },
+    {
+      "ja": "起動直後の Claude で、使っているモデル名が表示されない問題を直しました。",
+      "en": "Fixed the model name not showing for a Claude session that had just started."
+    },
+    {
+      "ja": "Auto-Yes が飛ばした画面の警告が、同じ画面の間に何度も出る問題を直しました。",
+      "en": "Fixed the warning for a screen Auto-Yes skipped repeating while the same screen stayed up."
+    },
+    {
+      "ja": "OpenCode V2 の返答が履歴に記録されない問題を直しました。",
+      "en": "Fixed OpenCode V2 replies not being recorded in History."
+    },
+    {
+      "ja": "OpenCode V2 の返答に番号付きのリストがあると、応答待ちと誤って扱われ、Auto-Yes が番号を送ってしまう問題を直しました。",
+      "en": "Fixed numbered lists in OpenCode V2 replies being treated as a question, which made Auto-Yes send a number."
+    },
+    {
+      "ja": "OpenCode V2 でダイアログが開いたまま送信すると、本文が消える問題を直しました。",
+      "en": "Fixed the message being lost when sending while an OpenCode V2 dialog was open."
+    },
+    {
+      "ja": "OpenCode V2 で、引数なしのスラッシュコマンドが実行されない問題を直しました。",
+      "en": "Fixed OpenCode V2 slash commands without arguments not running."
+    },
+    {
+      "ja": "OpenCode V2 の承認の文言や、保留中の承認への Auto-Yes の応答を直しました。",
+      "en": "Fixed OpenCode V2 approval wording and Auto-Yes answers to pending approvals."
+    },
+    {
+      "ja": "OpenCode V2 の承認や質問を待つ間の注意文が、チャットに記録されてしまう問題を直しました。",
+      "en": "Fixed the notice shown while OpenCode V2 waits on an approval or question being recorded in the chat."
+    },
+    {
+      "ja": "OpenCode V2 を起動すると、プロジェクトの package.json が書き換えられる問題を直しました。",
+      "en": "Fixed starting OpenCode V2 writing to the project's package.json."
+    },
+    {
+      "ja": "OpenCode V2 を opencode という名前で入れている環境でも、正しく起動するようにしました。",
+      "en": "OpenCode V2 now starts correctly when it is installed under the name opencode."
+    },
+    {
+      "ja": "OpenCode と OpenCode V2 を取り違えることがある問題を直しました。",
+      "en": "Fixed OpenCode and OpenCode V2 sometimes being mixed up."
+    },
+    {
+      "ja": "OpenCode V2 のスケジュールが worktree で動くようにし、画面から作れてしまう不正なスケジュールを防ぎました。",
+      "en": "OpenCode V2 schedules now run in the worktree, and invalid schedules can no longer be created from the screen."
+    },
+    {
+      "ja": "日次確認で、codex の更新ダイアログや設定ファイル、OpenCode のモデル選択と入力履歴の扱いに関する問題を直しました。",
+      "en": "Fixed daily health check issues with the codex update dialog and config file, and with OpenCode model selection and input history."
+    },
+    {
+      "ja": "commandmate verify が、別の作業で一時的にできたファイルを自分の違反として数える問題を直しました。",
+      "en": "Fixed commandmate verify counting temporary files from other work as its own violations."
+    }
+  ]
+}