Skip to content

Commit 981c029

Browse files
cuioss-oliverclaude
andcommitted
fix(refactor-docs): purge body-verbatim/executor-no-op stale claims; verify OpenCode specifics
Full re-pass after the body-transforms + target-aware-executor + dual-emit changes landed. Found and corrected internal contradictions and one round of verifiably-wrong OpenCode claims. Body-verbatim contract was stale in README and principles after we added mechanical line-level transforms. Both files now point at marketplace/targets/opencode/transforms.md as the bounded transform spec. Executor-on-OpenCode contradictions purged across clusters 01, 03, and 04: - "Executor pattern: No-op (OpenCode does not use executor)" -> now writes the OpenCode bash permission for the executor (which is generated on both targets per cluster 01 "Executor Resolution Per Target") - "OpenCode no-op executor" integration test -> now verifies the OpenCode bash permission is added - "Direct script execution (no execute-script.py)" target note -> retracted - ensure-executor declared applicable on both targets (writes appropriate bash permission); cleanup-scripts/migrate-executor flagged as TBD SessionStart-on-OpenCode contradictions purged across cluster 01 and 04: - "Session Hook Setup: project initial-setup installs a SessionStart hook" -> qualified as Claude only; OpenCode skips hook installation - "If hooks are not installed, session capture returns error" -> split per target: Claude returns error, OpenCode returns no-op (matches earlier api-surface section) - "Fresh project init" integration test split into Claude and OpenCode variants with target-specific verification Verifiably-wrong OpenCode claims corrected via web research: - ~/.opencode/plugins/cache/** does not exist -> ~/.config/opencode/plugins/** and ~/.config/opencode/skills/** per opencode.ai/docs/plugins - "install opencode-statusline plugin" alternative does not exist (anomalyco/opencode#8619 is an open feature request) -> use built-in /statusline TUI command - "permissions are per-agent, not a flat top-level object" -> OpenCode supports BOTH top-level and per-agent (per-agent overrides global) - "OpenCode does not have SlashCommand equivalent" -> retracted; OpenCode commands ARE invocable as /{bundle}-{skill} per the dual-emit design - "All 10 plan-marshall agents" -> 8 (actual count); marketplace total 11 Other internal inconsistencies fixed: - mapping.json/frontmatter-rules.json had duplicated required_fields and optional_fields -> mapping.json owns the dictionaries; frontmatter-rules owns the validation contract; no field duplicated across files - Skill discovery root count mismatched ("six" said in cluster 01/04 prose while tables listed seven including $OPENCODE_CONFIG_DIR/skills/) -> prose now reads "documented skill discovery roots plus the env-var override" - Cluster 06 sync-opencode invoked via direct script path (CLAUDE.md hard- rule violation) -> now uses canonical executor notation, matching the later snippet in the same file - Cluster 03 motivation only mentioned platform-runtime abstraction -> now also covers source-side prose cleanup Co-Authored-By: Claude <[email protected]>
1 parent 5fe4585 commit 981c029

7 files changed

Lines changed: 37 additions & 35 deletions

File tree

‎doc/refactor/01-design-platform-api/plan.md‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ python3 .plan/execute-script.py plan-marshall:platform-runtime:platform_runtime
112112

113113
**Claude:** Create `.plan/`, seed `marshal.json` with `runtime.target: claude`, ensure `.plan/temp/` exists. Install `SessionStart` hook in `.claude/settings.json` that captures `session_id` into `$CLAUDE_CODE_SESSION_ID` environment variable.
114114

115-
**OpenCode:** Same, but `runtime.target: opencode`. OpenCode does not currently expose the session id to the shell environment (tracked at upstream issue #9292; PR #9289 was closed unmerged), so no SessionStart-equivalent hook is installed. `session capture` returns `no-op` on OpenCode (see below); automatic token-usage capture is unsupported and callers fall back to manual `--total-tokens`. `.plan/execute-script.py` IS generated on OpenCode — same notation contract `{bundle}:{skill}:{script}`, but with an OpenCode-aware resolver that searches OpenCode's six skill discovery roots (see Executor Resolution Per Target below).
115+
**OpenCode:** Same, but `runtime.target: opencode`. OpenCode does not currently expose the session id to the shell environment (tracked at upstream issue #9292; PR #9289 was closed unmerged), so no SessionStart-equivalent hook is installed. `session capture` returns `no-op` on OpenCode (see below); automatic token-usage capture is unsupported and callers fall back to manual `--total-tokens`. `.plan/execute-script.py` IS generated on OpenCode — same notation contract `{bundle}:{skill}:{script}`, but with an OpenCode-aware resolver that searches OpenCode's documented skill discovery roots plus the `$OPENCODE_CONFIG_DIR/skills/` env-var override (see Executor Resolution Per Target below).
116116

117117
### `session capture`
118118

@@ -140,7 +140,7 @@ python3 .plan/execute-script.py plan-marshall:platform-runtime:platform_runtime
140140
| `--permissions` | List of patterns |
141141

142142
**Claude:** Patch `.claude/settings.local.json` `permissions.allow` array.
143-
**OpenCode:** Patch `./opencode.json` or `~/.config/opencode/opencode.json` `agent.{name}.permission` object (permissions are per-agent, not a flat top-level object).
143+
**OpenCode:** Patch `./opencode.json` or `~/.config/opencode/opencode.json`. OpenCode supports both top-level `permission` (global default) and per-agent `agent.{name}.permission` (overrides global); per-agent rules take precedence. The runtime writes whichever scope the caller selects (typically top-level for global, per-agent for agent-specific).
144144

145145
**Note:** This is the low-level primitive. Skills should prefer `permission analyze` and `permission fix` for hygienic permission management. When only a raw list write is needed, use `permission configure`.
146146

@@ -213,8 +213,8 @@ summary:
213213
| Permission | Claude Code | OpenCode |
214214
|------------|-------------|----------|
215215
| Plan file access | `Edit(.plan/**)`, `Write(.plan/**)` | `agent.{name}.permission: { "edit": { ".plan/**": "allow" }, "read": { ".plan/**": "allow" } }` |
216-
| Plugin cache access | `Read(~/.claude/plugins/cache/**)` | `agent.{name}.permission: { "read": { "~/.opencode/plugins/cache/**": "allow" } }` (if applicable) |
217-
| Executor pattern | `Bash(python3 .plan/execute-script.py *)` | No-op (OpenCode does not use executor) |
216+
| Plugin cache access | `Read(~/.claude/plugins/cache/**)` | `permission: { "read": { "~/.config/opencode/plugins/**": "allow", "~/.config/opencode/skills/**": "allow" } }` |
217+
| Executor pattern | `Bash(python3 .plan/execute-script.py *)` | `permission: { "bash": { "python3 .plan/execute-script.py *": "allow" } }` (OpenCode also generates `.plan/execute-script.py` — see Executor Resolution Per Target) |
218218

219219
### `permission ensure-wildcards`
220220

@@ -227,7 +227,7 @@ summary:
227227
| `--dry-run` | Preview changes without applying |
228228

229229
**Claude:** Scans `marketplace/.claude-plugin/marketplace.json` and `*/.claude-plugin/plugin.json`. Generates `Skill(bundle:*)` and `SlashCommand(/bundle:*)` entries.
230-
**OpenCode:** Scans marketplace and generates `agent.{name}.permission.skill: { "bundle:*": "allow" }` and command patterns. **Note:** OpenCode does not have `SlashCommand` equivalent; command permissions may be no-op or mapped to agent permissions.
230+
**OpenCode:** Scans marketplace and generates `permission.skill: { "{bundle}-*": "allow" }` and `permission.command: { "{bundle}-*": "allow" }` entries. OpenCode commands ARE invocable as `/{bundle}-{skill}` per the dual-emit design — see [02 — Build System](02-build-system) "User-Invocable Skills (Dual Emission)".
231231

232232
### `permission ensure-steps`
233233

@@ -525,8 +525,8 @@ Examples:
525525
```toon
526526
status: no-op
527527
operation: session configure-display
528-
reason: OpenCode does not support terminal title hooks
529-
alternative: Use --type none or install opencode-statusline plugin
528+
reason: OpenCode has no plugin-driven status-line hook (issue anomalyco/opencode#8619)
529+
alternative: Use --type none, or use OpenCode's built-in /statusline TUI command for an interactive status line
530530
```
531531

532532
```toon
@@ -538,9 +538,9 @@ alternative: Pass --total-tokens manually
538538

539539
## Session Hook Setup
540540

541-
**One-time configuration per project.**
541+
**One-time configuration per project (Claude only).**
542542

543-
`project initial-setup` installs a `SessionStart` hook that captures the platform's session identifier and makes it available as an environment variable to all subsequent tool calls.
543+
On Claude, `project initial-setup` installs a `SessionStart` hook that captures the platform's session identifier and makes it available as an environment variable to all subsequent tool calls. On OpenCode no hook is installed (see "OpenCode Hook" below).
544544

545545
### Claude Code Hook
546546

@@ -577,9 +577,8 @@ Neither Claude Code nor OpenCode exposes a reliable programmatic API to discover
577577

578578
### Fallback
579579

580-
If hooks are not installed, `session capture` returns `error` with code `hook_not_configured`. The calling skill can either:
581-
1. Run `marshall-steward` (which calls `project initial-setup`) to install hooks
582-
2. Accept manual `--total-tokens` input and skip automatic capture
580+
- **Claude:** if `project initial-setup` has not been run, the hook is missing and the env var is unset. `session capture` returns `error` with code `hook_not_configured`. The calling skill can either run `marshall-steward` (which calls `project initial-setup`) to install the hook, or accept manual `--total-tokens` input and skip automatic capture.
581+
- **OpenCode:** no hook is expected; `session capture` always returns `no-op` with the documented `reason`/`alternative`. The calling skill must continue and accept manual `--total-tokens` input where token capture is needed.
583582

584583
## What Stays Out
585584

‎doc/refactor/02-build-system/plan.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -144,17 +144,15 @@ Tool and model mappings (see [01 — Design Platform API](01-design-platform-api
144144
"opus": "claude-opus-4-7",
145145
"sonnet": "claude-sonnet-4-6",
146146
"haiku": "claude-haiku-4-5-20251001"
147-
},
148-
"required_fields": ["description"],
149-
"optional_fields": ["model", "mode"]
147+
}
150148
}
151149
```
152150

153151
**Note:** The generator adds the `anthropic/` provider prefix when writing `opencode.json`, so model IDs here are without prefix.
154152

155153
#### Configuration: `marketplace/targets/opencode/frontmatter-rules.json`
156154

157-
Uses `tool_permissions` and `model_map` from `mapping.json` (loaded by the frontmatter engine at runtime).
155+
Owns the frontmatter-shape rules (which fields are required, which are optional). Loads `tool_permissions` and `model_map` from `mapping.json` at runtime — `mapping.json` owns the dictionaries; `frontmatter-rules.json` owns the validation contract. No field is duplicated across the two files.
158156

159157
```json
160158
{
@@ -194,7 +192,7 @@ Agents with `Task` or `Skill` in their `tools:` frontmatter are **not** Claude-o
194192

195193
**Implementation note:** Permissions are set in agent frontmatter (`tools:` field) or `opencode.json` (`agent.{name}.permission`), not at `task` invocation time. The `subagent dispatch` operation returns invocation parameters only (no permissions field in TOON response).
196194

197-
**Impact:** All 10 plan-marshall agents are included in OpenCode output with proper permission mapping. They function via OpenCode's `task` tool for subagent dispatch and `skill` tool for skill loading.
195+
**Impact:** All 8 plan-marshall agents (and the additional 3 in other bundles, 11 total across the marketplace) are included in OpenCode output with proper permission mapping. They function via OpenCode's `task` tool for subagent dispatch and `skill` tool for skill loading.
198196

199197
**Build failure on unmapped tools:** If an agent uses a tool that has no entry in `frontmatter-rules.json`'s `tool_permissions` map, the target generator logs an error and exits with code 2. Silent exclusion is prohibited — every skipped agent must be a conscious decision. To add support for a new tool, update the JSON config.
200198

‎doc/refactor/03-refactor-for-portability/plan.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@ All calls go through the executor: `python3 .plan/execute-script.py plan-marshal
88

99
## Why This Cluster Exists
1010

11-
Skills hardcode `.claude/settings.local.json`, `~/.claude/plugins/cache/`, and Claude-specific hook instructions. These must be abstracted behind `platform-runtime` before multi-target generation is meaningful.
11+
Skills hardcode `.claude/settings.local.json`, `~/.claude/plugins/cache/`, and Claude-specific hook instructions. Two parallel cleanups are needed before multi-target generation is meaningful:
12+
13+
1. **Behavioural abstraction** — replace direct settings/hook/path manipulation with goal-based `platform-runtime` calls.
14+
2. **Source-side prose cleanup** — move Claude-only mechanism descriptions (terminal title plumbing, session-id resolver, hook plumbing) out of skill bodies and into `references/{topic}.md`; rephrase tool-name rules platform-agnostically. This benefits both targets — skill bodies become focused on workflow steps instead of one platform's plumbing.
1215

1316
## Scope
1417

@@ -52,7 +55,7 @@ Search all skill bodies for:
5255
| `marshall-steward` | Write hooks to `.claude/settings.local.json` | `platform-runtime session configure-display` |
5356
| `marshall-steward` | Patch `.claude/settings.local.json` permissions | `platform-runtime permission configure` |
5457
| `tools-permission-doctor` | Read `~/.claude/settings.json`, `.claude/settings.json`; Claude-specific anti-patterns | `platform-runtime permission analyze --checks <checks>` |
55-
| `tools-permission-fix` | Write to `~/.claude/settings.json`, `.claude/settings.json`; `ensure-executor` / `cleanup-scripts` / `migrate-executor` are Claude-specific executor operations | `platform-runtime permission fix --operation <op>`; `ensure-executor`/`cleanup-scripts`/`migrate-executor` return `no-op` on OpenCode |
58+
| `tools-permission-fix` | Write to `~/.claude/settings.json`, `.claude/settings.json`; `ensure-executor` adds the `Bash(python3 .plan/execute-script.py *)` permission; `cleanup-scripts` and `migrate-executor` operate on Claude-cache-located scripts | `platform-runtime permission fix --operation <op>`. `ensure-executor` applies on **both targets** (the executor exists on both — see [01 — Design Platform API](01-design-platform-api) "Executor Resolution Per Target"); on OpenCode it writes `permission.bash: { "python3 .plan/execute-script.py *": "allow" }`. Treatment of `cleanup-scripts` and `migrate-executor` on OpenCode is TBD (see open question in cluster 04). |
5659
| `workflow-permission-web` | Read `WebFetch(...)` strings from `.claude/settings*.json` | `platform-runtime permission web-analyze --scope <scope>`; `platform-runtime permission web-apply --add/--remove` |
5760
| `tools-script-executor` | Generates `.plan/execute-script.py` using `~/.claude/plugins/cache/` paths; bootstrap reads `~/.claude/plugins/cache/` | Target-aware generator: reads `runtime.target` from `marshal.json` and emits the matching resolver template (Claude resolver searches plugin cache; OpenCode resolver searches OpenCode's six skill discovery roots). Notation `{bundle}:{skill}:{script}` is unchanged — only the resolver behind it differs. See [01 — Design Platform API](01-design-platform-api) "Executor Resolution Per Target". |
5861
| `tools-file-ops` | Worktree paths under `.claude/worktrees/` hardcoded | Use `marshal.json` `worktree.path` (target-configurable, default `.claude/worktrees/` for Claude, `.opencode/worktrees/` for OpenCode) |
@@ -184,7 +187,7 @@ This cluster is complete when:
184187
5. `bootstrap_plugin.py` handles multi-platform path resolution
185188
6. `marketplace/adapters/` retired (logic in `marketplace/targets/`)
186189
7. `tools-permission-doctor`, `tools-permission-fix`, and `workflow-permission-web` delegate all settings file I/O to `platform-runtime` permission operations
187-
8. Executor-specific operations (`ensure-executor`, `cleanup-scripts`, `migrate-executor`) return `no-op` on OpenCode target
190+
8. `ensure-executor` is implemented on both targets (writes the appropriate bash permission for the generated `.plan/execute-script.py`); `cleanup-scripts` and `migrate-executor` resolution on OpenCode is decided per the cluster 04 open question and either implemented or returns documented `no-op`
188191
9. `tools-script-executor` is target-aware: same notation `{bundle}:{skill}:{script}` resolves correctly via the Claude-cache resolver on Claude and the OpenCode-skill-roots resolver on OpenCode
189192
10. Claude-only hook/cache documentation has been moved out of skill bodies and into per-skill `references/{topic}.md`
190193
11. Tool-name rules in skill bodies are platform-agnostic (no `EnterPlanMode`/`AskUserQuestion`/`Agent(subagent_type=…)` etc. in instructional rules)

‎doc/refactor/04-validate-and-document/plan.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The OpenCode target generates output under `target/opencode/` (see [02 — Build
6767
| `platform-runtime` router | Correct target dispatch based on `runtime.target` |
6868
| `ClaudeRuntime` | Settings patch, hook write, session ID capture |
6969
| `OpenCodeRuntime` | Config patch, no-op behavior |
70-
| `SessionStart` hook | Installed by `project initial-setup`, sets `$CLAUDE_CODE_SESSION_ID` |
70+
| `SessionStart` hook (Claude only) | Installed by `project initial-setup` on Claude, sets `$CLAUDE_CODE_SESSION_ID`. On OpenCode `project initial-setup` skips hook installation; verify nothing is written. |
7171
| `session capture` | Reads env var, stores in `status.json` via `manage-status` |
7272
| `metrics capture` | Reads stored session ID, locates transcript, sums usage |
7373
| TOON output | All operations return valid TOON |
@@ -77,21 +77,22 @@ The OpenCode target generates output under `target/opencode/` (see [02 — Build
7777
| Body transform — `Skill:` directive | Standalone-line `Skill: {bundle}:{skill}` rewrites to `Call the \`skill\` tool with \`{ name: "{bundle}-{skill}" }\` before continuing.` Inline `` `Skill: foo:bar` `` references in prose are untouched. |
7878
| Body transform — slash command | `/{user-invocable-skill-name}` rewrites to `/{bundle}-{user-invocable-skill-name}` for every known user-invocable skill. Path-like substrings (`path/to/foo`) are not matched. |
7979
| Executor resolver — Claude | `python3 .plan/execute-script.py plan-marshall:manage-status:manage_status get …` resolves under `~/.claude/plugins/cache/plan-marshall/*/skills/manage-status/scripts/manage_status.py` |
80-
| Executor resolver — OpenCode | Same notation resolves under the first match across the six OpenCode skill roots (`$OPENCODE_CONFIG_DIR/skills/`, `.opencode/skills/`, `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/`), at directory `plan-marshall-manage-status/scripts/manage_status.py`. Returned path is absolute. |
80+
| Executor resolver — OpenCode | Same notation resolves under the first match across OpenCode's documented skill discovery roots plus the env-var override — `$OPENCODE_CONFIG_DIR/skills/` (when set), `.opencode/skills/`, `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` — at directory `plan-marshall-manage-status/scripts/manage_status.py`. Returned path is absolute. |
8181

8282
### Integration Tests
8383

8484
| Scenario | How to Test |
8585
|----------|-------------|
86-
| Fresh project init | Run `project initial-setup` (via `marshall-steward`), verify `.plan/`, `marshal.json`, and SessionStart hook installed |
86+
| Fresh project init (Claude) | Run `project initial-setup --target claude` (via `marshall-steward`), verify `.plan/`, `marshal.json` with `runtime.target: claude`, the SessionStart hook is installed in `.claude/settings.json`, and `.plan/execute-script.py` is generated with the Claude-cache resolver |
87+
| Fresh project init (OpenCode) | Run `project initial-setup --target opencode`, verify `.plan/`, `marshal.json` with `runtime.target: opencode`, **no** SessionStart-equivalent hook is written, and `.plan/execute-script.py` is generated with the OpenCode-skill-roots resolver |
8788
| Session capture | Run `session capture`, verify `session_id` stored in `status.json` via `manage-status` |
8889
| Permission config | Run `permission configure`, verify settings file updated |
8990
| Permission analyze | Run `permission analyze --checks all --scope both`, verify TOON output with findings array |
9091
| Permission fix normalize | Run `permission fix --operation normalize --scope project --dry-run`, verify defaults added, duplicates removed |
9192
| Permission ensure wildcards | Run `permission ensure-wildcards --scope project`, verify all bundle skill wildcards present |
9293
| Permission ensure steps | Run `permission ensure-steps --marshal .plan/marshal.json --scope project`, verify missing `project:{skill}` steps have matching skill permissions |
9394
| Permission web analyze | Run `permission web-analyze --scope both`, verify domain categorization and duplicate detection |
94-
| OpenCode no-op executor | Run `permission fix --operation ensure-executor` on OpenCode target, verify `status: no-op` with reason |
95+
| OpenCode `ensure-executor` | Run `permission fix --operation ensure-executor` on OpenCode target, verify `permission.bash: { "python3 .plan/execute-script.py *": "allow" }` is added to the resolved opencode.json |
9596
| Bundle sync (Claude) | Run target generator, verify skills mirrored to `~/.claude/plugins/cache/` via `sync-plugin-cache` |
9697
| Bundle sync (OpenCode) | Run target generator, verify output under `target/opencode/`; deploy via `sync-opencode` or `OPENCODE_CONFIG_DIR` |
9798
| Drift detection | Introduce intentional orphan in `plugin.json`, verify CI fails |
@@ -143,9 +144,9 @@ The six cluster plan documents in `doc/refactor/` (`README.md`, `principles.md`,
143144
- Generated output — best-effort support
144145
- All agents mapped with `task`/`skill` permissions (subagent dispatch and skill loading supported)
145146
- Model aliases preserved (`opus` → `anthropic/claude-opus-4-7`); no forced downgrades to cheaper models
146-
- No terminal title hooks
147-
- No automatic token usage extraction (requires `--total-tokens` manual input)
148-
- Direct script execution (no `execute-script.py`)
147+
- No platform-driven status-line / terminal-title hook (anomalyco/opencode#8619); built-in `/statusline` TUI command available as alternative
148+
- No automatic token usage extraction (requires `--total-tokens` manual input — see `session capture` no-op on OpenCode)
149+
- `.plan/execute-script.py` is generated with the OpenCode-skill-roots resolver — same `{bundle}:{skill}:{script}` notation as Claude, different resolution table
149150

150151
## Acceptance Criteria
151152

‎doc/refactor/06-developer-workflow/plan.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,8 +154,8 @@ target/opencode/
154154
Copy generated skills to `~/.config/opencode/skills/` using a deployment script:
155155

156156
```bash
157-
# Deploy script (to be created)
158-
python3 marketplace/bundles/plan-marshall/skills/sync-opencode/scripts/sync_opencode.py \
157+
# Deploy via the canonical executor notation (CLAUDE.md hard rule — never invoke scripts by direct path)
158+
python3 .plan/execute-script.py plan-marshall:sync-opencode:sync_opencode \
159159
--source target/opencode/ \
160160
--target ~/.config/opencode/
161161
```

0 commit comments

Comments
 (0)