You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 981c029
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
**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.
114
114
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).
**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).
144
144
145
145
**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`.
| 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) |
218
218
219
219
### `permission ensure-wildcards`
220
220
@@ -227,7 +227,7 @@ summary:
227
227
|`--dry-run`| Preview changes without applying |
228
228
229
229
**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)".
231
231
232
232
### `permission ensure-steps`
233
233
@@ -525,8 +525,8 @@ Examples:
525
525
```toon
526
526
status: no-op
527
527
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
**One-time configuration per project (Claude only).**
542
542
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).
544
544
545
545
### Claude Code Hook
546
546
@@ -577,9 +577,8 @@ Neither Claude Code nor OpenCode exposes a reliable programmatic API to discover
577
577
578
578
### Fallback
579
579
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.
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.
158
156
159
157
```json
160
158
{
@@ -194,7 +192,7 @@ Agents with `Task` or `Skill` in their `tools:` frontmatter are **not** Claude-o
194
192
195
193
**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).
196
194
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.
198
196
199
197
**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.
Copy file name to clipboardExpand all lines: doc/refactor/03-refactor-for-portability/plan.md
+6-3Lines changed: 6 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,10 @@ All calls go through the executor: `python3 .plan/execute-script.py plan-marshal
8
8
9
9
## Why This Cluster Exists
10
10
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.
12
15
13
16
## Scope
14
17
@@ -52,7 +55,7 @@ Search all skill bodies for:
52
55
|`marshall-steward`| Write hooks to `.claude/settings.local.json`|`platform-runtime session configure-display`|
|`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).|
|`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". |
58
61
|`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:
6.`marketplace/adapters/` retired (logic in `marketplace/targets/`)
186
189
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`
188
191
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
189
192
10. Claude-only hook/cache documentation has been moved out of skill bodies and into per-skill `references/{topic}.md`
190
193
11. Tool-name rules in skill bodies are platform-agnostic (no `EnterPlanMode`/`AskUserQuestion`/`Agent(subagent_type=…)` etc. in instructional rules)
| TOON output | All operations return valid TOON |
@@ -77,21 +77,22 @@ The OpenCode target generates output under `target/opencode/` (see [02 — Build
77
77
| 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. |
78
78
| 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. |
79
79
| 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 OpenCodeskill 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. |
81
81
82
82
### Integration Tests
83
83
84
84
| Scenario | How to Test |
85
85
|----------|-------------|
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 |
87
88
| Session capture | Run `session capture`, verify `session_id` stored in `status.json` via `manage-status`|
| 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|
95
96
| Bundle sync (Claude) | Run target generator, verify skills mirrored to `~/.claude/plugins/cache/` via `sync-plugin-cache`|
96
97
| Bundle sync (OpenCode) | Run target generator, verify output under `target/opencode/`; deploy via `sync-opencode` or `OPENCODE_CONFIG_DIR`|
97
98
| 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`,
143
144
- Generated output — best-effort support
144
145
- All agents mapped with `task`/`skill` permissions (subagent dispatch and skill loading supported)
145
146
- 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
0 commit comments