subagent-cli 0.1.5__tar.gz → 0.1.7__tar.gz

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subagent-cli
-Version: 0.1.5
+Version: 0.1.7
 Summary: Protocol-agnostic worker orchestration CLI
 Author: niitsuma-t
 License: MIT License
@@ -101,6 +101,10 @@ From local artifacts:
 pip install dist/subagent_cli-*.whl
 ```
 
+## Terminal Demo 🎬
+Recorded asciinema session:
+- [![asciicast](https://asciinema.org/a/Cxfk7i9wOOpZB17F.svg)](https://asciinema.org/a/Cxfk7i9wOOpZB17F)
+
 ## Quick Start ⚡
 1. Bootstrap your local config.
 ```bash
@@ -114,61 +118,19 @@ subagent config init --scope user
 subagent controller init --cwd .
 ```
 
-4. Hand off from here to your manager agent (Codex / Claude Code).  
-Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
-Use this instruction template:
-
-```text
-Act as the manager and product lead for this repository.
-
-Use subagent-cli as the control plane and progress this task by coordinating a small team of worker agents rather than acting as a solo implementer.
-
-Your role:
-
-* Define the objective, user value, constraints, scope, and success criteria.
-* Break the work into small chunks with clear owners.
-* Assign worker roles intentionally.
-* Coordinate handoffs, reviews, and validation.
-* Review worker proposals critically and give actionable feedback.
-* Make explicit decisions on whether to proceed, revise, compare options, or reject.
-
-Default behavior:
-
-* Delegate by default when useful.
-* Prefer small, verifiable increments.
-* Prevent over-engineering and keep the team focused on the smallest valuable outcome.
-* Do not accept worker output blindly; evaluate it for product fit, feasibility, scope, risk, and validation quality.
-
-Before execution:
-
-1. Run `subagent prompt render --target manager` and follow that output.
-2. Check command help before execution (`subagent worker --help`, `subagent send --help`, `subagent approve --help`).
-3. State:
-   * your role
-   * planned worker roles
-   * task breakdown
-   * success criteria
-   * validation plan
-
-During execution:
-
-4. Start and coordinate workers with subagent-cli.
-5. Use `send` as the default turn driver (`send` waits by default).
-6. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-7. Use `watch` only when detailed event streaming or debugging is needed.
-8. Use handoff/continue when context gets large.
-9. Require workers to report: goal, findings, proposal, risks, validation, next step.
-10. Respond to worker proposals with: decision, reason, what is good, what is missing, what should change, and next action.
-
-Before reporting completion:
+4. Install the recommended manager skill (after this repository is pushed to GitHub).
+```bash
+npx skills add "github/otakumesi/subagent-cli"
+```
 
-11. Verify results with tests or checks.
-12. Confirm the final output is integrated, validated, and aligned with the task objective.
+5. Hand off from here to your manager agent (Codex / Claude Code).  
+Use an instruction like this:
 
-If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
+```text
+<what to do that you want>
 
-Task to execute:
-<your task here>
+Use subagent commands to delegate tasks to a team of agents and coordinate their progress.
+Use the "subagent-manager" skill.
 ```
 
 After handoff, the manager agent's standard lifecycle is:
@@ -176,28 +138,37 @@ After handoff, the manager agent's standard lifecycle is:
 
 For a single command that sends and waits for terminal-or-approval events:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --json
+subagent send --worker-id <worker-id> --text "<instruction>" --json
 ```
 
 Opt out of waiting when needed:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+subagent send --worker-id <worker-id> --text "<instruction>" --no-wait --json
 ```
 
-For shell-safe input (recommended when text includes backticks, `$()`, redirects, etc.):
+For multiline or shell-safe input (recommended):
 ```bash
-subagent send --input - --json <<'JSON'
-{
-  "workerId": "<worker-id>",
-  "text": "Use commands like `echo hello` literally; do not execute them."
-}
-JSON
+cat > instruction.txt <<'TEXT'
+Use commands like `echo hello` literally; do not execute them.
+TEXT
+subagent send --worker-id <worker-id> --text-file ./instruction.txt --json
 ```
-`workerId` is required in JSON input payloads.
+
+stdin variant:
+```bash
+cat ./instruction.txt | subagent send --worker-id <worker-id> --text-stdin --json
+```
+
+Advanced automation can still use structured JSON input via `--input` (JSON key: `workerId`; CLI flag: `--worker-id`).
 
 Manual wait mode (advanced cursor control) still exists:
 ```bash
-subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+subagent wait --worker-id <worker-id> --until turn_end --timeout-seconds 60 --json
+```
+
+To include historical events in matching:
+```bash
+subagent wait --worker-id <worker-id> --include-history --until turn_end --timeout-seconds 60 --json
 ```
 
 For local simulation/testing without a real ACP launcher:
@@ -213,7 +184,7 @@ subagent worker start --cwd . --debug-mode
 ```bash
 subagent launcher probe <launcher-name> --json
 ```
-- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
+- If `worker start` fails with a backend error (for example `BACKEND_TIMEOUT`, `BACKEND_SOCKET_UNREACHABLE`, `BACKEND_LAUNCHER`), inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
 - For cut-down local testing without backend connectivity:
 ```bash
 subagent worker start --cwd . --debug-mode

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/README.ja.md

@@ -58,6 +58,10 @@ pip install subagent-cli
 pip install dist/subagent_cli-*.whl
 ```
 
+## ターミナルデモ 🎬
+録画した asciinema セッション:
+- [![asciicast](https://asciinema.org/a/Cxfk7i9wOOpZB17F.svg)](https://asciinema.org/a/Cxfk7i9wOOpZB17F)
+
 ## クイックスタート ⚡
 1. ローカル設定ファイルを初期化します。
 ```bash
@@ -71,61 +75,19 @@ subagent config init --scope user
 subagent controller init --cwd .
 ```
 
-4. ここからマネージャーエージェント（Codex / Claude Code）へ handoff します。  
-マネージャー側の最初の手順として `subagent prompt render --target manager` を実行させてください。  
-以下のテンプレートを使えます:
-
-```text
-Act as the manager and product lead for this repository.
-
-Use subagent-cli as the control plane and progress this task by coordinating a small team of worker agents rather than acting as a solo implementer.
-
-Your role:
-
-* Define the objective, user value, constraints, scope, and success criteria.
-* Break the work into small chunks with clear owners.
-* Assign worker roles intentionally.
-* Coordinate handoffs, reviews, and validation.
-* Review worker proposals critically and give actionable feedback.
-* Make explicit decisions on whether to proceed, revise, compare options, or reject.
-
-Default behavior:
-
-* Delegate by default when useful.
-* Prefer small, verifiable increments.
-* Prevent over-engineering and keep the team focused on the smallest valuable outcome.
-* Do not accept worker output blindly; evaluate it for product fit, feasibility, scope, risk, and validation quality.
-
-Before execution:
-
-1. Run `subagent prompt render --target manager` and follow that output.
-2. Check command help before execution (`subagent worker --help`, `subagent send --help`, `subagent approve --help`).
-3. State:
-   * your role
-   * planned worker roles
-   * task breakdown
-   * success criteria
-   * validation plan
-
-During execution:
-
-4. Start and coordinate workers with subagent-cli.
-5. Use `send` as the default turn driver (`send` waits by default).
-6. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-7. Use `watch` only when detailed event streaming or debugging is needed.
-8. Use handoff/continue when context gets large.
-9. Require workers to report: goal, findings, proposal, risks, validation, next step.
-10. Respond to worker proposals with: decision, reason, what is good, what is missing, what should change, and next action.
-
-Before reporting completion:
+4. （このリポジトリを GitHub に push 後）推奨の manager スキルをインストールします。
+```bash
+npx skills add "github/otakumesi/subagent-cli"
+```
 
-11. Verify results with tests or checks.
-12. Confirm the final output is integrated, validated, and aligned with the task objective.
+5. ここからマネージャーエージェント（Codex / Claude Code）へ handoff します。  
+以下のような指示文を使えます:
 
-If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
+```text
+<what to do that you want>
 
-Task to execute:
-<your task here>
+Use subagent commands to delegate tasks to a team of agents and coordinate their progress.
+Use the "subagent-manager" skill.
 ```
 
 handoff 後のマネージャーエージェント標準ライフサイクル:
@@ -133,28 +95,37 @@ handoff 後のマネージャーエージェント標準ライフサイクル:
 
 単発で送信して、終了イベントまたは承認要求まで待機する例:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --json
+subagent send --worker-id <worker-id> --text "<instruction>" --json
 ```
 
 待機を無効化する例:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+subagent send --worker-id <worker-id> --text "<instruction>" --no-wait --json
 ```
 
-シェル解釈事故を避ける安全な入力方法（`--input` 推奨）:
+複数行やシェル解釈事故を避ける安全な入力方法（推奨）:
 ```bash
-subagent send --input - --json <<'JSON'
-{
-  "workerId": "<worker-id>",
-  "text": "`echo hello` や $(uname) を文字列として扱い、実行しないこと。"
-}
-JSON
+cat > instruction.txt <<'TEXT'
+`echo hello` や $(uname) を文字列として扱い、実行しないこと。
+TEXT
+subagent send --worker-id <worker-id> --text-file ./instruction.txt --json
 ```
-JSON 入力では `workerId` が必須です。
+
+stdin 版:
+```bash
+cat ./instruction.txt | subagent send --worker-id <worker-id> --text-stdin --json
+```
+
+高度な自動化では、構造化 JSON 入力 `--input` も使えます（JSON キーは `workerId`、CLI フラグは `--worker-id`）。
 
 手動待機モード（高度なカーソル制御）:
 ```bash
-subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+subagent wait --worker-id <worker-id> --until turn_end --timeout-seconds 60 --json
+```
+
+履歴イベントも対象に含める場合:
+```bash
+subagent wait --worker-id <worker-id> --include-history --until turn_end --timeout-seconds 60 --json
 ```
 
 実 launcher なしでローカルシミュレーションする場合:
@@ -170,7 +141,7 @@ subagent worker start --cwd . --debug-mode
 ```bash
 subagent launcher probe <launcher-name> --json
 ```
-- `worker start` が `BACKEND_UNAVAILABLE` で失敗する場合は、`<workspace>/.subagent/state/runtimes/`（既定）または `$SUBAGENT_STATE_DIR/runtimes/`（上書き時）のログを確認してください。
+- `worker start` がバックエンド系エラー（例: `BACKEND_TIMEOUT` / `BACKEND_SOCKET_UNREACHABLE` / `BACKEND_LAUNCHER`）で失敗する場合は、`<workspace>/.subagent/state/runtimes/`（既定）または `$SUBAGENT_STATE_DIR/runtimes/`（上書き時）のログを確認してください。
 - バックエンド接続なしの簡易テスト:
 ```bash
 subagent worker start --cwd . --debug-mode

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/README.md

@@ -58,6 +58,10 @@ From local artifacts:
 pip install dist/subagent_cli-*.whl
 ```
 
+## Terminal Demo 🎬
+Recorded asciinema session:
+- [![asciicast](https://asciinema.org/a/Cxfk7i9wOOpZB17F.svg)](https://asciinema.org/a/Cxfk7i9wOOpZB17F)
+
 ## Quick Start ⚡
 1. Bootstrap your local config.
 ```bash
@@ -71,61 +75,19 @@ subagent config init --scope user
 subagent controller init --cwd .
 ```
 
-4. Hand off from here to your manager agent (Codex / Claude Code).  
-Ask the manager agent to run `subagent prompt render --target manager` as its first step.  
-Use this instruction template:
-
-```text
-Act as the manager and product lead for this repository.
-
-Use subagent-cli as the control plane and progress this task by coordinating a small team of worker agents rather than acting as a solo implementer.
-
-Your role:
-
-* Define the objective, user value, constraints, scope, and success criteria.
-* Break the work into small chunks with clear owners.
-* Assign worker roles intentionally.
-* Coordinate handoffs, reviews, and validation.
-* Review worker proposals critically and give actionable feedback.
-* Make explicit decisions on whether to proceed, revise, compare options, or reject.
-
-Default behavior:
-
-* Delegate by default when useful.
-* Prefer small, verifiable increments.
-* Prevent over-engineering and keep the team focused on the smallest valuable outcome.
-* Do not accept worker output blindly; evaluate it for product fit, feasibility, scope, risk, and validation quality.
-
-Before execution:
-
-1. Run `subagent prompt render --target manager` and follow that output.
-2. Check command help before execution (`subagent worker --help`, `subagent send --help`, `subagent approve --help`).
-3. State:
-   * your role
-   * planned worker roles
-   * task breakdown
-   * success criteria
-   * validation plan
-
-During execution:
-
-4. Start and coordinate workers with subagent-cli.
-5. Use `send` as the default turn driver (`send` waits by default).
-6. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-7. Use `watch` only when detailed event streaming or debugging is needed.
-8. Use handoff/continue when context gets large.
-9. Require workers to report: goal, findings, proposal, risks, validation, next step.
-10. Respond to worker proposals with: decision, reason, what is good, what is missing, what should change, and next action.
-
-Before reporting completion:
+4. Install the recommended manager skill (after this repository is pushed to GitHub).
+```bash
+npx skills add "github/otakumesi/subagent-cli"
+```
 
-11. Verify results with tests or checks.
-12. Confirm the final output is integrated, validated, and aligned with the task objective.
+5. Hand off from here to your manager agent (Codex / Claude Code).  
+Use an instruction like this:
 
-If worker startup or turn operations fail due to sandbox limits, request approval for out-of-sandbox execution and retry.
+```text
+<what to do that you want>
 
-Task to execute:
-<your task here>
+Use subagent commands to delegate tasks to a team of agents and coordinate their progress.
+Use the "subagent-manager" skill.
 ```
 
 After handoff, the manager agent's standard lifecycle is:
@@ -133,28 +95,37 @@ After handoff, the manager agent's standard lifecycle is:
 
 For a single command that sends and waits for terminal-or-approval events:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --json
+subagent send --worker-id <worker-id> --text "<instruction>" --json
 ```
 
 Opt out of waiting when needed:
 ```bash
-subagent send --worker <worker-id> --text "<instruction>" --no-wait --json
+subagent send --worker-id <worker-id> --text "<instruction>" --no-wait --json
 ```
 
-For shell-safe input (recommended when text includes backticks, `$()`, redirects, etc.):
+For multiline or shell-safe input (recommended):
 ```bash
-subagent send --input - --json <<'JSON'
-{
-  "workerId": "<worker-id>",
-  "text": "Use commands like `echo hello` literally; do not execute them."
-}
-JSON
+cat > instruction.txt <<'TEXT'
+Use commands like `echo hello` literally; do not execute them.
+TEXT
+subagent send --worker-id <worker-id> --text-file ./instruction.txt --json
 ```
-`workerId` is required in JSON input payloads.
+
+stdin variant:
+```bash
+cat ./instruction.txt | subagent send --worker-id <worker-id> --text-stdin --json
+```
+
+Advanced automation can still use structured JSON input via `--input` (JSON key: `workerId`; CLI flag: `--worker-id`).
 
 Manual wait mode (advanced cursor control) still exists:
 ```bash
-subagent wait --worker <worker-id> --until turn_end --timeout-seconds 60 --json
+subagent wait --worker-id <worker-id> --until turn_end --timeout-seconds 60 --json
+```
+
+To include historical events in matching:
+```bash
+subagent wait --worker-id <worker-id> --include-history --until turn_end --timeout-seconds 60 --json
 ```
 
 For local simulation/testing without a real ACP launcher:
@@ -170,7 +141,7 @@ subagent worker start --cwd . --debug-mode
 ```bash
 subagent launcher probe <launcher-name> --json
 ```
-- If `worker start` fails with `BACKEND_UNAVAILABLE`, inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
+- If `worker start` fails with a backend error (for example `BACKEND_TIMEOUT`, `BACKEND_SOCKET_UNREACHABLE`, `BACKEND_LAUNCHER`), inspect runtime logs under `<workspace>/.subagent/state/runtimes/` (default) or `$SUBAGENT_STATE_DIR/runtimes/` (when overridden).
 - For cut-down local testing without backend connectivity:
 ```bash
 subagent worker start --cwd . --debug-mode

subagent_cli-0.1.7/config.example.yaml

@@ -0,0 +1,97 @@
+launchers:
+  codex:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/codex-acp"
+    env: {}
+
+  claude-code:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "@zed-industries/claude-agent-acp"
+    env: {}
+
+  gemini:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "@google/gemini-cli"
+      - "--experimental-acp"
+    env: {}
+
+  opencode:
+    backend:
+      kind: acp-stdio
+    command: opencode
+    args:
+      - acp
+    env: {}
+
+  cline:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "cline"
+      - "--acp"
+    env: {}
+
+  github-copilot:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "@github/copilot-language-server"
+      - "--acp"
+    env: {}
+
+  kiro:
+    backend:
+      kind: acp-stdio
+    command: npx
+    args:
+      - -y
+      - "@kirodotdev/cli"
+      - acp
+    env: {}
+
+roleDefaults:
+  promptLanguage: en
+  responseLanguage: same_as_manager
+
+roleHints:
+  developer:
+    preferredLauncher: codex
+    delegationHint: "State goal, constraints, done conditions, affected files, and test expectations."
+    # Optional: list skill names the agent should explicitly invoke for this role.
+    recommendedSkills: []
+  reviewer:
+    preferredLauncher: claude-code
+    delegationHint: "Review as a lead engineer; prioritize bugs, regressions, missing tests, and risk."
+    recommendedSkills: []
+  research_analyst:
+    preferredLauncher: gemini
+    delegationHint: "Gather primary sources first, then report with dates and source URLs."
+    recommendedSkills: []
+  ux_designer:
+    preferredLauncher: claude-code
+    delegationHint: "Provide user flows, alternatives, trade-offs, decision rationale, and validation metrics."
+    recommendedSkills: []
+  data_scientist:
+    preferredLauncher: codex
+    delegationHint: "Define hypothesis, required data, method, evaluation metrics, and reproducible steps."
+    recommendedSkills: []
+
+defaults:
+  launcher: codex
+  role: developer

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/docs/ARCHITECTURE.md

@@ -5,13 +5,13 @@
 - Local control plane: `subagentd` process for bootstrap/status, heartbeat, worker runtime health checks, and auto-restart attempts.
 - Runtime state: sqlite-backed `StateStore` for controllers, controller instances, workers, event journal, approval requests, and handoff snapshots.
 - Runtime adapter: per-worker ACP runtime process (`subagent.worker_runtime`) with unix-socket IPC (`runtime_service`).
-- Config registry: loader for `launchers` / `profiles` / `packs` / `defaults` from config.
+- Config registry: loader for `launchers` / `roleHints` / `roleDefaults` / `defaults` from config.
 
 ## Current v1 Scope (Implemented)
 - `config`: `init` (user/project config template generation)
-- `launcher/profile/pack`: `list`, `show`
+- `launcher/role`: `list`, `show`
 - `launcher`: `probe`
-- `prompt`: `render` (manager/worker)
+- `prompt`: `render` (manager)
 - `controller`: `init`, `attach`, `status`, `recover`, `release`
 - `worker`: `start`, `list`, `show`, `inspect`, `stop`, `handoff`, `continue`
 - turn operations: `send`, `watch`, `wait`, `approve`, `cancel`

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/docs/examples/checkpoint.json

@@ -3,8 +3,7 @@
   "workerId": "w_123",
   "controllerId": "ctl_abc123",
   "launcher": "codex",
-  "profile": "worker-default",
-  "packs": ["repo-conventions"],
+  "role": "worker-default",
   "cwd": "/path/to/workspace",
   "state": "handoff_ready",
   "sourceTurnId": "turn_07",

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/docs/examples/normalized-event.ndjson

@@ -1,4 +1,4 @@
-{"schemaVersion":"v1","eventId":"ev_01","ts":"2026-03-01T22:00:00Z","workerId":"w_123","type":"worker.started","data":{"launcher":"codex","profile":"worker-default","state":"idle"}}
+{"schemaVersion":"v1","eventId":"ev_01","ts":"2026-03-01T22:00:00Z","workerId":"w_123","type":"worker.started","data":{"launcher":"codex","role":"worker-default","state":"idle"}}
 {"schemaVersion":"v1","eventId":"ev_02","ts":"2026-03-01T22:00:05Z","workerId":"w_123","type":"turn.started","data":{"turnId":"turn_01"}}
 {"schemaVersion":"v1","eventId":"ev_03","ts":"2026-03-01T22:00:12Z","workerId":"w_123","type":"progress.message","data":{"role":"assistant","text":"STATUS: Investigating flaky payments retry test."}}
 {"schemaVersion":"v1","eventId":"ev_04","ts":"2026-03-01T22:00:20Z","workerId":"w_123","type":"turn.completed","data":{"turnId":"turn_01","state":"idle"}}

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/docs/examples/worker-continue-flow.md

@@ -1,13 +1,13 @@
 # Worker Continue Flow (v1)
 
 1. Create handoff from previous worker:
-`subagent worker handoff --worker w_123`
+`subagent worker handoff --worker-id w_123`
 
 2. Start a new worker from the handoff artifact:
-`subagent worker continue --from-worker w_123 --launcher codex --profile worker-default`
+`subagent worker continue --from-worker w_123 --launcher codex --role worker-default`
 
 3. Watch normalized events from the new worker:
-`subagent watch --worker w_456 --follow --ndjson`
+`subagent watch --worker-id w_456 --follow --ndjson`
 
 4. Continue by sending a new instruction:
-`subagent send --worker w_456 --text "Proceed with the minimal fix and add regression coverage."`
+`subagent send --worker-id w_456 --text "Proceed with the minimal fix and add regression coverage."`

{subagent_cli-0.1.5 → subagent_cli-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subagent-cli"
-version = "0.1.5"
+version = "0.1.7"
 description = "Protocol-agnostic worker orchestration CLI"
 readme = "README.md"
 requires-python = ">=3.11"