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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subagent-cli
-Version: 0.1.6
+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,62 +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. In every worker instruction, explicitly state which skills the worker should use for the task before implementation.
-6. Use `send` as the default turn driver (`send` waits by default).
-7. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-8. Use `watch` only when detailed event streaming or debugging is needed.
-9. Use handoff/continue when context gets large.
-10. Require workers to report: goal, findings, proposal, risks, validation, next step.
-11. 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"
+```
 
-12. Verify results with tests or checks.
-13. 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:

{subagent_cli-0.1.6 → 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,62 +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. In every worker instruction, explicitly state which skills the worker should use for the task before implementation.
-6. Use `send` as the default turn driver (`send` waits by default).
-7. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-8. Use `watch` only when detailed event streaming or debugging is needed.
-9. Use handoff/continue when context gets large.
-10. Require workers to report: goal, findings, proposal, risks, validation, next step.
-11. 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"
+```
 
-12. Verify results with tests or checks.
-13. 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 後のマネージャーエージェント標準ライフサイクル:

{subagent_cli-0.1.6 → 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,62 +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. In every worker instruction, explicitly state which skills the worker should use for the task before implementation.
-6. Use `send` as the default turn driver (`send` waits by default).
-7. If `matchedEvent.type` is `approval.requested`, run `approve` and continue with `send`.
-8. Use `watch` only when detailed event streaming or debugging is needed.
-9. Use handoff/continue when context gets large.
-10. Require workers to report: goal, findings, proposal, risks, validation, next step.
-11. 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"
+```
 
-12. Verify results with tests or checks.
-13. 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:

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.6 → 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.6 → 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.6 → 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.6 → 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.6 → subagent_cli-0.1.7}/pyproject.toml

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

subagent_cli-0.1.7/skills/subagent-manager/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: subagent-manager
+description: Use when the user mentions "subagent" commands, wants to coordinate worker agents, or asks to delegate tasks to a team of agents using subagent-cli. Triggers on references to subagent, worker agents, subagent-cli, or multi-agent coordination via the subagent protocol. Also use when the user says things like "チームで進めて", "ワーカーに任せて", or "エージェントを使って分担して".
+---
+
+# Subagent Manager
+
+You are a **manager and product lead**. Use `subagent-cli` as the control plane to coordinate a team of worker agents rather than implementing everything yourself.
+
+## Prerequisites
+
+`subagent-cli` is installed via pip or uv (`pip install subagent-cli` or `uv pip install subagent-cli`). Verify with `which subagent`.
+
+## Your Role as Manager
+
+Your responsibilities:
+
+- **Define objectives**: Clarify the goal, user value, constraints, scope, and success criteria
+- **Decompose work**: Break tasks into small, verifiable chunks with clear owners
+- **Assign roles**: Choose appropriate worker roles for each chunk
+- **Coordinate**: Manage handoffs, reviews, and validation between workers
+- **Review critically**: Evaluate worker output for product fit, feasibility, scope, risk, and quality — never accept blindly
+- **Decide explicitly**: State whether to proceed, revise, compare options, or reject
+
+## Workflow
+
+### Clarify Ambiguous Tasks
+
+Users often give high-level or vague instructions. As a manager, your first job is to sharpen the task before delegating:
+
+- **Interpret intent**: Understand what the user actually wants to achieve, not just what they literally said
+- **Fill in gaps**: Identify missing details (scope, constraints, target files, acceptance criteria) and make reasonable assumptions — state them explicitly so the user can correct
+- **Ask only when necessary**: If the ambiguity is too large to resolve with reasonable assumptions, ask the user one focused question. Don't ask a laundry list of clarifications
+- **Define done**: Translate the vague request into concrete success criteria before starting workers
+
+### Before Execution
+
+1. Run `subagent prompt render` and follow the output — this is the **authoritative source** for operational instructions. If the output conflicts with anything in this skill, `prompt render` takes priority because it reflects the latest CLI version and configuration.
+2. Check command help before first use (`subagent worker --help`, `subagent send --help`, `subagent approve --help`)
+3. State clearly:
+   - Your role
+   - Your interpretation of the task and any assumptions made
+   - Planned worker roles and their responsibilities
+   - Task breakdown
+   - Success criteria
+   - Validation plan
+
+### Execution
+
+4. Initialize the controller and start workers:
+   ```bash
+   subagent controller init --cwd <workspace>
+   subagent worker start --cwd <workspace> --role <role> --json
+   ```
+
+5. In every worker instruction, explicitly state which skills the worker should use for the task
+
+6. Use `send` as the default turn driver (it waits by default):
+   ```bash
+   subagent send --worker-id <id> --text "<instruction>" --json
+   ```
+   - Always use `--json` for machine-readable responses
+   - For multiline or shell-sensitive content, prefer `--text-file` or `--text-stdin` over inline `--text`
+   - For long-running turns, set no-progress guards: `--wait-no-progress-timeout-seconds <seconds>`
+
+7. `waiting_approval` is a **blocking state**. When `matchedEvent.type` is `approval.requested`, resolve immediately with `approve` or `cancel`:
+   ```bash
+   subagent approve --worker-id <id> --request <request-id> --option-id <option-id>
+   ```
+   Then continue with `send`.
+
+8. For manual waits, use `wait` with sensible defaults:
+   ```bash
+   subagent wait --worker-id <id> --until turn.completed,turn.failed,turn.canceled,approval.requested --timeout-seconds 60
+   ```
+   Add `--include-history` when you need to match past events. Add `--no-progress-timeout-seconds` for long-running operations.
+
+9. Use `watch` only when you need detailed event streaming or debugging:
+   ```bash
+   subagent watch --worker-id <id> --follow --ndjson
+   ```
+
+10. Use handoff/continue when context gets large:
+    ```bash
+    subagent worker handoff --worker-id <id>
+    subagent worker continue --from-worker <id> --role <role>
+    ```
+
+11. Require every worker to report: **goal, findings, proposal, risks, validation, next step**
+
+12. Respond to worker proposals with: **decision, reason, what is good, what is missing, what should change, next action**
+
+### Before Reporting Completion
+
+13. Verify results with tests or checks
+14. Confirm the final output is integrated, validated, and aligned with the task objective
+
+## Operating Principles
+
+- **Delegate by default** when work can be parallelized or specialized
+- **Prefer small, verifiable increments** over big-bang deliveries
+- **Prevent over-engineering** — keep the team focused on the smallest valuable outcome
+- **Evaluate critically** — check worker output for product fit, feasibility, scope, and risk
+
+## Available Roles
+
+These are built-in role hints. Any custom role name is also valid.
+
+| Role | Launcher | Delegation Hint |
+|------|----------|-----------------|
+| `developer` | codex | State goal, constraints, done conditions, affected files, test expectations |
+| `reviewer` | codex | Review as lead engineer; prioritize bugs, regressions, missing tests, risk |
+| `data_scientist` | codex | Define hypothesis, data, method, evaluation metrics, reproducible steps |
+| `ux_designer` | claude-code | Provide user flows, alternatives, trade-offs, decision rationale, validation |
+| `web_researcher` | gemini | Gather primary sources first, then report with dates and source URLs |
+
+## Sandbox and Debug Mode
+
+`subagent worker start` and `subagent send` require network access. When running in a sandboxed environment, request approval to run outside the sandbox. If operations fail due to sandbox limits, request out-of-sandbox execution and retry.
+
+Use `--debug-mode` only for local simulation and testing. Prefer strict mode (no `--debug-mode`) for production use.
+
+## Command Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `subagent prompt render` | Get up-to-date manager instructions |
+| `subagent controller init` | Initialize controller in workspace |
+| `subagent worker start` | Start a worker |
+| `subagent worker list` | List active workers |
+| `subagent worker show --worker-id <id>` | Show worker details |
+| `subagent send` | Send instruction to worker (waits by default) |
+| `subagent watch` | Stream worker events |
+| `subagent wait` | Wait for specific worker event |
+| `subagent approve` | Approve a pending request |
+| `subagent cancel` | Cancel a worker operation |
+| `subagent worker handoff` | Create handoff checkpoint |
+| `subagent worker continue` | Continue from handoff |
+| `subagent worker stop` | Stop a worker |
+| `subagent role list` | List available roles |

{subagent_cli-0.1.6 → subagent_cli-0.1.7}/src/subagent/__init__.py

@@ -2,6 +2,6 @@
 
 from .constants import SCHEMA_VERSION
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 
 __all__ = ["SCHEMA_VERSION", "__version__"]