commandmate 0.43.0 → 0.44.1

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.43.0",
-  "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.1",
+  "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,6 +32,14 @@
     ".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",
@@ -141,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.44.0.json

@@ -0,0 +1,82 @@
+{
+  "version": "0.44.0",
+  "date": "2026-10-03",
+  "highlight": {
+    "ja": "エージェントに読ませるだけで導入まで案内してくれるセットアップガイドを加えました。スマホからのログインと公開の安全性も改善しています。",
+    "en": "A setup guide your agent can read and follow now walks you through installation. Phone login and remote access are also safer."
+  },
+  "added": [
+    {
+      "ja": "チャットの吹き出しで、worktree 内の画像を表示できるようになりました。",
+      "en": "Chat bubbles now show images from the worktree."
+    },
+    {
+      "ja": "チャットの吹き出しで、worktree 内の動画を再生できるようになりました。",
+      "en": "Chat bubbles now play videos from the worktree."
+    },
+    {
+      "ja": "Command Code の計画レビュー画面で、チャット面からコメント・送信・承認・取り消しができるようになりました。承認の前には確認が出ます。",
+      "en": "In Command Code's plan review, you can now comment, submit, approve, or cancel from the chat view. Approving asks for confirmation first."
+    },
+    {
+      "ja": "ペアリングの QR を失くしたとき、公開を張り直さずに新しいリンクを出せるようになりました。",
+      "en": "If you lose the pairing QR code, you can now get a new link without restarting remote access."
+    },
+    {
+      "ja": "エージェントに読ませて導入を進めてもらうセットアップガイドを追加しました。",
+      "en": "Added a setup guide that your agent can read to walk you through installation."
+    }
+  ],
+  "improved": [
+    {
+      "ja": "Command Code の計画レビュー画面に、CLI からコメント・送信・承認・取り消しを送れるようになりました。",
+      "en": "The CLI can now comment on, submit, approve, or cancel a Command Code plan review."
+    },
+    {
+      "ja": "画面の出力がまだ無いとき、確認ダイアログの見方を案内するようになりました。",
+      "en": "When there is no output yet, capture now tells you how to see a waiting confirmation screen."
+    },
+    {
+      "ja": "Command Code が自分で書く設定ファイルを、作業の変更として数えなくなりました。",
+      "en": "Settings files that Command Code writes for itself are no longer counted as your changes."
+    }
+  ],
+  "fixed": [
+    {
+      "ja": "停止したはずのサーバーが残り、ログインなしで公開されてしまうことがある問題を直しました。",
+      "en": "Fixed a case where a server that should have stopped stayed up and could be exposed without login."
+    },
+    {
+      "ja": "トンネル越しにログインしようとすると localhost に移動してしまう問題を直しました。",
+      "en": "Fixed logging in through a tunnel sending you to localhost."
+    },
+    {
+      "ja": "Claude Code の信頼の確認で、終了を選んでしまい最初の送信が届かない問題を直しました。",
+      "en": "Fixed Claude Code's trust prompt sometimes choosing to exit, so the first message was not delivered."
+    },
+    {
+      "ja": "初めて使うときに、送信・同期・応答のエラーが誤った対処を案内していた問題を直しました。",
+      "en": "Fixed send, sync, and respond errors pointing first-time users to the wrong fix."
+    },
+    {
+      "ja": "npm にまだ出ていない版で更新ボタンが押せてしまう問題を直しました。",
+      "en": "Fixed the Update button being available for a version not yet published to npm."
+    },
+    {
+      "ja": "大きすぎる画像を開いたとき、正しく「大きすぎる」と伝えるようになりました。",
+      "en": "Opening an image that is too large now correctly says it is too large."
+    },
+    {
+      "ja": "Codex のモデル選択画面に Auto-Yes が答えてしまう問題を直しました。",
+      "en": "Fixed Auto-Yes answering Codex's model selection screen."
+    },
+    {
+      "ja": "Claude の /effort の選択画面を正しく認識するようになりました。",
+      "en": "Claude's /effort selection screen is now recognized correctly."
+    },
+    {
+      "ja": "依存パッケージの脆弱性を解消しました。",
+      "en": "Resolved security vulnerabilities in dependencies."
+    }
+  ]
+}

package/release-notes/0.44.1.json

@@ -0,0 +1,54 @@
+{
+  "version": "0.44.1",
+  "date": "2026-10-04",
+  "highlight": {
+    "ja": "エージェントの起動中は、途中の画面の代わりに「起動中…」と経過時間を表示するようになりました。",
+    "en": "While an agent is starting, the screen now shows that it is starting and how long it has taken, instead of a half-drawn session."
+  },
+  "added": [
+    {
+      "ja": "エージェントの起動中は「起動中…」の案内を出し、5 秒を超えると経過時間も表示するようになりました。",
+      "en": "While an agent starts, a starting notice is shown, with the elapsed time after five seconds."
+    }
+  ],
+  "improved": [
+    {
+      "ja": "エージェントを起動するときに打ち込むコマンドの行が、ターミナルに残らなくなりました。",
+      "en": "The command line typed to launch an agent no longer stays in the terminal."
+    },
+    {
+      "ja": "remote コマンドで、ペアリングの期限の時刻と残り時間が QR コードの下に表示されるようになりました。",
+      "en": "The remote command now shows when the pairing expires and how much time is left, under the QR code."
+    }
+  ],
+  "fixed": [
+    {
+      "ja": "インスタンスを止めると、そのインスタンスの Auto Yes も切れるようにしました。",
+      "en": "Stopping an instance now also turns off its Auto Yes."
+    },
+    {
+      "ja": "シェルのプロンプトが長い環境で、Claude を終了した後に次の送信が失敗する問題を直しました。",
+      "en": "Fixed the next message failing after exiting Claude when the shell prompt is long."
+    },
+    {
+      "ja": "エージェントの起動に 30 秒以上かかったとき、画面が送信失敗と表示する問題を直しました。",
+      "en": "Fixed the screen reporting a failed send when an agent took more than 30 seconds to start."
+    },
+    {
+      "ja": "起動中に止めてすぐ起動し直すと、起動中の案内が早く消える問題を直しました。",
+      "en": "Fixed the starting notice disappearing early when an agent was stopped and started again right away."
+    },
+    {
+      "ja": "OpenCode V2 の承認で、選択肢が出ているのに「選択肢を読み取れませんでした」と表示される問題を直しました。",
+      "en": "Fixed OpenCode V2 approvals saying the options could not be read while the options were shown."
+    },
+    {
+      "ja": "ログイン画面を開いている間に、エラーになる通信をくり返していた問題を直しました。",
+      "en": "Fixed the login page repeatedly making requests that failed."
+    },
+    {
+      "ja": "期限切れのペアリングを、remote status が使用済みと表示する問題を直しました。",
+      "en": "Fixed remote status showing an expired pairing as used."
+    }
+  ]
+}