@doingdev/opencode-claude-manager-plugin 0.1.64 → 0.1.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +106 -120
  2. package/dist/claude/claude-agent-sdk-adapter.js +1 -1
  3. package/package.json +13 -13
package/README.md CHANGED
@@ -1,48 +1,37 @@
1
- # OpenCode Claude Manager Plugin
1
+ # @doingdev/opencode-claude-manager-plugin
2
2
 
3
- This package provides an OpenCode plugin that lets an OpenCode-side agent hierarchy orchestrate Claude Code sessions through a stable local bridge.
3
+ OpenCode plugin that adds a manager-style orchestration layer over Claude Code sessions. A `cto` agent reads the repo, asks focused questions, and delegates to named engineers who each run work in their own persistent Claude Code session.
4
4
 
5
- ## Overview
5
+ Useful when you want OpenCode to investigate first, split work across named engineers with session continuity, and keep git and review controls at the manager layer.
6
6
 
7
- Use this when you want OpenCode to act like a real technical lead over Claude Code instead of being a thin relay. The plugin gives you a CTO agent that can ask better questions, explicitly assign named engineers, reuse each engineer's Claude session for continuity, preserve wrapper-level engineer memory, compare multiple plans, and keep git/review work at the manager layer.
7
+ ## What it adds
8
8
 
9
- ## Features
10
-
11
- - Runs Claude Code tasks from OpenCode through `@anthropic-ai/claude-agent-sdk`.
12
- - Creates a persistent named team: `Tom`, `John`, `Maya`, `Sara`, and `Alex`.
13
- - Reuses one Claude Code session per engineer within the active CTO team.
14
- - Reloads prior engineer wrapper context so each named subagent can prompt Claude better over time.
15
- - Uses named engineer subagents for live delegated work while keeping both wrapper memory and Claude session continuity underneath.
16
- - Keeps session babysitting out of the normal user flow — no public reset/fresh-session controls.
17
- - Discovers repo-local Claude metadata from `.claude/skills`, `.claude/commands`, `CLAUDE.md`, and settings hooks.
18
- - Git integration: diff, commit, and reset from the manager layer.
19
- - Tool approval policy for governing which Claude Code tools are allowed.
20
- - Persists local team state and transcripts under `.claude-manager/` for continuity and inspection.
9
+ - `cto` orchestrator that reads, delegates, reviews diffs, and owns all manager tools. Never edits files directly.
10
+ - Five persistent general engineers — `tom`, `john`, `maya`, `sara`, `alex` — each backed by its own Claude Code session that survives across assignments in the same CTO session.
11
+ - `team-planner` that runs two engineers in parallel and returns a single synthesized plan.
12
+ - `browser-qa` browser verification specialist using Playwright-oriented prompting. Does not implement code.
13
+ - Manager tools for team state, git, transcript/history inspection, and tool approval policy.
14
+ - Local runtime state under `.claude-manager/` persisted across turns.
21
15
 
22
16
  ## Requirements
23
17
 
24
- - Node `22+`
18
+ - Node `>=22`
25
19
  - OpenCode with plugin loading enabled
26
- - Access to Claude Code / Claude Agent SDK on the machine where OpenCode is running
27
-
28
- ## Installation
20
+ - Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) available to the Node process
21
+ - Git - required for the git tools
22
+ - OpenCode Playwright skill/command - required for `browser-qa`
29
23
 
30
- Install from the npm registry:
24
+ ## Install
31
25
 
32
26
  ```bash
33
27
  pnpm add @doingdev/opencode-claude-manager-plugin
28
+ # npm install @doingdev/opencode-claude-manager-plugin
29
+ # yarn add @doingdev/opencode-claude-manager-plugin
34
30
  ```
35
31
 
36
- Or for local development in this repo:
37
-
38
- ```bash
39
- pnpm install
40
- pnpm run build
41
- ```
42
-
43
- ## OpenCode Config
32
+ ## Setup
44
33
 
45
- Add the plugin to your OpenCode config:
34
+ Add the plugin to `opencode.json` in your project root:
46
35
 
47
36
  ```json
48
37
  {
@@ -50,137 +39,134 @@ Add the plugin to your OpenCode config:
50
39
  }
51
40
  ```
52
41
 
53
- If you are testing locally, point OpenCode at the local package or plugin file using your normal local plugin workflow.
42
+ Agents register automatically at runtime. No manual agent entries needed.
54
43
 
55
- ## OpenCode tools
44
+ ## Key concepts
56
45
 
57
- ### CTO orchestration
46
+ **Delegation model.** The CTO reads the repo and context, decides what to do, and sends work to a named engineer via the `claude` tool. The engineer runs that assignment inside its own Claude Code session. The CTO never edits files directly.
58
47
 
59
- - Use the built-in OpenCode `task` tool to delegate to named engineers: `tom`, `john`, `maya`, `sara`, `alex`.
60
- - `team_status` — inspect the current CTO team's engineer bindings, Claude session IDs, busy flags, and context snapshots.
48
+ **Engineer persistence.** Each engineer's Claude Code session persists within a CTO session. A follow-up assignment to the same engineer resumes with prior context, which helps with multi-step tasks or when the engineer already understands a subsystem.
61
49
 
62
- ### Engineer bridge
50
+ **Modes.** When delegating, the CTO picks a mode:
51
+ - `explore` — read-only investigation. No file edits.
52
+ - `implement` — hands-on implementation work.
53
+ - `verify` — tests, lint, spot-checks after changes.
63
54
 
64
- - `claude` — available only inside named engineer subagents. Sends work through that engineer's persistent Claude Code session.
65
- - `mode` (required) — `explore`, `implement`, or `verify`.
66
- - `message` (required) — the work to do.
67
- - `model` (optional) — `claude-opus-4-6` or `claude-sonnet-4-6`.
55
+ **Teams.** Each CTO session has its own team. State is keyed by CTO session ID under `.claude-manager/teams/`.
68
56
 
69
- ### Git operations
57
+ ## Agents
70
58
 
71
- - `git_diff` — review all uncommitted changes (staged + unstaged).
72
- - `git_commit` — stage all changes and commit with a message.
73
- - `git_reset` — hard reset + clean (destructive).
59
+ | Agent | Role |
60
+ |---|---|
61
+ | `cto` | Orchestrator. Reads, delegates, reviews, owns manager tools. Does not edit files. |
62
+ | `tom`, `john`, `maya`, `sara`, `alex` | General engineers. Each exposes only the `claude` tool backed by its own persistent Claude Code session. |
63
+ | `team-planner` | Thin wrapper around `plan_with_team`. Runs two engineers in parallel, returns a synthesized plan. |
64
+ | `browser-qa` | Browser verification specialist. Uses Playwright-oriented prompting. Does not implement code. |
74
65
 
75
- ### Inspection
66
+ ## Tools
76
67
 
77
- - `list_transcripts` — list available session transcripts or inspect a specific transcript by ID.
78
- - `list_history` — list saved CTO teams for the worktree or inspect one team by ID.
68
+ ### Engineer tool
79
69
 
80
- ### Tool approval
70
+ Each general engineer exposes one tool:
81
71
 
82
- - `approval_policy` — view the current tool approval policy.
83
- - `approval_decisions` — view recent tool approval decisions.
84
- - `approval_update` — add/remove rules, enable/disable approval, or clear decision history. Policy uses a **deny-list**: tools not matching any rule are **allowed**; use explicit **deny** rules to block. `defaultAction` is always `allow` (cannot be set to deny).
72
+ | Tool | Parameters | Notes |
73
+ |---|---|---|
74
+ | `claude` | `mode` (`explore`/`implement`/`verify`), `assignment` (text), optional `model` | Model choices: `claude-opus-4-6` or `claude-sonnet-4-6`. Defaults to the session default. |
85
75
 
86
- ## Agent hierarchy
76
+ ### CTO tools
87
77
 
88
- The plugin registers a CTO + named engineer team through the OpenCode plugin `config` hook:
78
+ | Tool | Description |
79
+ |---|---|
80
+ | `team_status` | Show current team: engineers, sessions, context levels. |
81
+ | `reset_engineer` | Clear a stuck engineer's Claude session, wrapper history, or both. |
82
+ | `git_diff` | Diff with optional path filter, staged flag, or ref. |
83
+ | `git_commit` | Commit staged changes with a message and optional file list. |
84
+ | `git_reset` | **Destructive.** Runs `git reset --hard HEAD && git clean -fd`. |
85
+ | `git_status` | Short status and cleanliness check. |
86
+ | `git_log` | Recent commit log. |
87
+ | `list_transcripts` | List saved Claude session transcripts in `.claude-manager/transcripts/`. |
88
+ | `list_history` | List saved team state in `.claude-manager/teams/`. |
89
+ | `approval_policy` | Read the active tool approval policy. |
90
+ | `approval_decisions` | Read the logged approval decisions. |
91
+ | `approval_update` | Update the tool approval policy. |
89
92
 
90
- - **`cto`** (primary agent) — owns the outcome, finds missing requirements, spawns named engineers with the Task tool, compares plans, reviews diffs, and manages git.
91
- - **`tom`**, **`john`**, **`maya`**, **`sara`**, **`alex`** (subagents) — thin named engineer wrappers. Each uses the `claude` tool and keeps one persistent Claude Code session.
92
- - **`team-planner`** (subagent) — thin planning wrapper that runs `plan_with_team` so the UI shows live planning activity.
93
- - **Claude Code sessions** — the underlying execution layer. One session per engineer inside the active team.
93
+ ### team-planner tool
94
94
 
95
- These are added to OpenCode config at runtime by the plugin, so they do not require separate manual `opencode.json` entries.
95
+ | Tool | Description |
96
+ |---|---|
97
+ | `plan_with_team` | Runs two general engineers in parallel on the same planning task, then synthesizes one recommended plan. `browser-qa` is not part of the planning pool. |
96
98
 
97
- ## Quick Start
99
+ ## Approval policy
98
100
 
99
- Typical flow inside OpenCode:
101
+ Each engineer's Claude Code session runs under a tool approval manager. The policy is **deny-list based**: unmatched tools stay allowed and `defaultAction` is always `allow`.
100
102
 
101
- 1. Ask the `cto` agent for the work.
102
- 2. Let `cto` investigate lightly, then spawn one or more named engineers with the Task tool.
103
- 3. Review changes with `git_diff`, then commit or reset.
104
- 4. Inspect saved Claude history with `list_transcripts` or saved team state with `list_history` / `team_status`.
103
+ Rule fields:
104
+ - `pattern` — glob matching the tool name.
105
+ - `inputPattern` (optional) — substring match against tool input.
106
+ - `action` — `allow` or `deny`.
107
+ - `message` (optional) — shown when the rule fires.
105
108
 
106
- Example tasks:
109
+ Default rules block patterns like `rm -rf /`, `git push --force`, and `git reset --hard`. Read the active policy with `approval_policy`, inspect logged decisions with `approval_decisions`, and change rules with `approval_update`.
107
110
 
111
+ ## Workflows
112
+
113
+ **Investigate then implement:**
108
114
  ```text
109
- Ask CTO to send Tom to implement the new validation logic in src/auth.ts, then review with git_diff.
115
+ Ask cto to inspect the failing billing tests, send tom to implement the smallest safe fix, then review with git_diff.
110
116
  ```
111
117
 
112
- For a larger feature where you want investigation first and then a stronger combined plan:
113
-
118
+ **Dual-engineer planning:**
114
119
  ```text
115
- Ask CTO to inspect the billing feature scope, then use team-planner to run two independent investigations and synthesize the best implementation plan.
120
+ Ask cto to use team-planner to produce a two-engineer plan for adding SSO to the auth module.
116
121
  ```
117
122
 
118
- ## Local Development
119
-
120
- Clone the repo and run:
121
-
122
- ```bash
123
- pnpm install
124
- pnpm run lint
125
- pnpm run typecheck
126
- pnpm run test
127
- pnpm run build
123
+ **Browser verification:**
124
+ ```text
125
+ Ask cto to send browser-qa to verify the signup flow on http://localhost:3000 and report failures.
128
126
  ```
129
127
 
130
- The compiled plugin output is written to `dist/`.
128
+ **Reuse engineer context:**
129
+ ```text
130
+ Ask cto to send john to add error handling to the function he just implemented.
131
+ ```
131
132
 
132
- ## Publishing
133
+ **Inspect state before committing:**
134
+ ```text
135
+ Ask cto to run git_diff, summarize the changes, then run git_commit with a descriptive message.
136
+ ```
133
137
 
134
- This package is configured for the npm scope `@doingdev`.
138
+ ## State
135
139
 
136
- This repository uses npm trusted publishing with GitHub Actions OIDC, so you do not need an `NPM_TOKEN` secret once npm is configured correctly.
140
+ Runtime state is local to the worktree and gitignored:
137
141
 
138
- Before the first automated publish, configure npm trusted publishing for `@doingdev/opencode-claude-manager-plugin` on npmjs.com:
142
+ ```text
143
+ .claude-manager/
144
+ teams/ # One JSON file per CTO session (team ID)
145
+ transcripts/ # Claude session event logs
146
+ approval-policy.json # Active policy, if customized
147
+ debug.log # NDJSON debug log from plugin hooks
148
+ ```
139
149
 
140
- 1. Open the package settings on npmjs.com.
141
- 2. Go to the `Trusted Publisher` section.
142
- 3. Choose `GitHub Actions`.
143
- 4. Set the GitHub owner/user to your account or org.
144
- 5. Set the repository name.
145
- 6. Set the workflow filename to `publish.yml`.
146
- 7. Leave the environment name empty unless you later add a GitHub Actions environment back to the workflow.
150
+ - State is not shared across machines or worktrees.
151
+ - Continuity is strongest within a single CTO session. Restarting the CTO session starts a new team.
152
+ - Undo at the CTO level propagates to engineer wrapper sessions and inner Claude Code sessions.
147
153
 
148
- Notes for trusted publishing:
154
+ ## Limits and caveats
149
155
 
150
- - npm trusted publishing requires GitHub-hosted runners.
151
- - npm recommends Node `22.14.0+` with npm CLI `11.5.1+`; the workflows use Node `24`.
152
- - Provenance is generated automatically by npm for trusted publishes from public GitHub repositories.
156
+ - Context usage tracking is heuristic, not exact SDK-reported truth. Actual token counts may differ.
157
+ - `browser-qa` returns `PLAYWRIGHT_UNAVAILABLE: <reason>` if the Playwright skill or command is missing.
158
+ - `plan_with_team` runs two general engineers. `browser-qa` is excluded from the planning pool.
159
+ - `git_reset` is destructive and immediate. Run `git_diff` first to inspect state.
160
+ - Engineer context degrades if sessions are reset or if the CTO session is restarted mid-task.
153
161
 
154
- Release flow:
162
+ ## Development
155
163
 
156
164
  ```bash
157
- pnpm login
158
- pnpm whoami
159
- pnpm version patch
165
+ pnpm install
160
166
  pnpm run lint
161
167
  pnpm run typecheck
162
168
  pnpm run test
163
169
  pnpm run build
164
170
  ```
165
171
 
166
- Then publish from GitHub by either:
167
-
168
- - creating a GitHub Release, or
169
- - running the `Publish` workflow manually from the Actions tab
170
-
171
- After trusted publishing is working, you can tighten npm package security by disabling token-based publishing for the package in npm settings.
172
-
173
- ## Limitations
174
-
175
- - Claude slash commands and skills come primarily from filesystem discovery; SDK probing is available but optional.
176
- - Session state is local to the repo under `.claude-manager/` and is ignored by git.
177
- - The strongest team continuity comes when engineers are spawned from the active `cto` session; the plugin maps named engineers back to that active team automatically.
178
- - Context tracking is heuristic-based; actual SDK context usage may differ slightly.
179
-
180
- ## Scripts
181
-
182
- - `pnpm run build`
183
- - `pnpm run typecheck`
184
- - `pnpm run lint`
185
- - `pnpm run format`
186
- - `pnpm run test`
172
+ `dist/` is generated output. Do not edit it directly.
package/dist/claude/claude-agent-sdk-adapter.js CHANGED
@@ -120,7 +120,7 @@ export class ClaudeAgentSdkAdapter {
120
120
  async getTranscript(sessionId, cwd) {
121
121
  const messages = await this.sdkFacade.getSessionMessages(sessionId, cwd ? { dir: cwd } : undefined);
122
122
  return messages.map((message) => ({
123
- role: message.type,
123
+ role: message.type === 'user' ? 'user' : 'assistant',
124
124
  sessionId: message.session_id,
125
125
  messageId: message.uuid,
126
126
  text: extractText(message.message),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@doingdev/opencode-claude-manager-plugin",
3
- "version": "0.1.64",
3
+ "version": "0.1.65",
4
4
  "description": "OpenCode plugin that orchestrates Claude Code sessions.",
5
5
  "keywords": [
6
6
  "opencode",
@@ -29,21 +29,21 @@
29
29
  "node": ">=22.0.0"
30
30
  },
31
31
  "dependencies": {
32
- "@anthropic-ai/claude-agent-sdk": "^0.2.81",
33
- "@opencode-ai/plugin": "^1.2.27",
34
- "zod": "^4.1.8"
32
+ "@anthropic-ai/claude-agent-sdk": "^0.2.89",
33
+ "@opencode-ai/plugin": "^1.3.13",
34
+ "zod": "^4.3.6"
35
35
  },
36
36
  "devDependencies": {
37
- "@eslint/js": "^9.22.0",
38
- "@types/node": "^24.5.2",
39
- "@vitest/coverage-v8": "^4.1.0",
40
- "eslint": "^9.22.0",
41
- "globals": "^15.15.0",
42
- "knip": "^6.0.2",
37
+ "@eslint/js": "^10.0.1",
38
+ "@types/node": "^25.5.0",
39
+ "@vitest/coverage-v8": "^4.1.2",
40
+ "eslint": "^10.1.0",
41
+ "globals": "^17.4.0",
42
+ "knip": "^6.1.1",
43
43
  "prettier": "^3.8.1",
44
- "typescript": "^5.9.3",
45
- "typescript-eslint": "^8.57.1",
46
- "vitest": "^4.1.0"
44
+ "typescript": "^6.0.2",
45
+ "typescript-eslint": "^8.58.0",
46
+ "vitest": "^4.1.2"
47
47
  },
48
48
  "scripts": {
49
49
  "build": "tsc -p tsconfig.build.json",