Repository navigation
Commit 8965e08
docs(refactor): multi-target marketplace design + per-cluster TODO checklists (#341)
## Summary
Refines the multi-target marketplace refactor design under
`doc/refactor/` and adds per-cluster TODO checklists driving sequential
implementation. The design now grounds every OpenCode-specific claim
against opencode.ai/docs and the upstream `anomalyco/opencode` repo,
with the few unverifiable claims either retracted or marked open at
upstream.
The refactor is split into seven clusters:
- **00 — Cleanup / Precondition** — one-time source-side prose cleanup
of skill bodies (move Claude-only hook/cache plumbing to
`references/{topic}.md`; rephrase tool-name rules
platform-agnostically). No platform-runtime dependencies; benefits
Claude Code today and unblocks every future target.
- **01 — Design Platform API** — goal-based `platform-runtime` skill
exposing 13 operations (`project initial-setup`, `session capture`, six
permission ops, `metrics capture`, `subagent dispatch`, `health-check`,
etc.) with per-target implementations. Documents the executor resolution
per target and the bootstrap invocation root list.
- **02 — Build System** — `marketplace/targets/` framework with
`TargetBase`, registry, Claude drift detection, OpenCode emitter
(singular `skill/`/`agent/`/`command/` directory layout matching the
`opencode-marketplace` CLI), bounded body transforms (`Skill:` directive
rewrite + slash-command rewrite per `transforms.md`), and dual-emit for
`user-invocable: true` skills.
- **03 — Refactor for Portability** — replace direct
`.claude/settings.json` writes, `~/.claude/plugins/cache/` reads, and
Claude-only hook installs with `platform-runtime` calls; make
`tools-script-executor` target-aware (same `{bundle}:{skill}:{script}`
notation, two resolvers).
- **04 — Validate and Document** — drift-check + OpenCode-generation CI
gates, full unit + integration test plan, port refactor plans into
canonical `doc/*` files and delete `doc/refactor/`.
- **05 — Distribution** — move `marketplace.json` to repo root for
native Claude plugin discovery, build/release/Pages CI workflows,
install/update docs for both platforms.
- **06 — Developer Workflow** — `sync-opencode` skill plus three
OpenCode inner-loop options (deploy-to-global, `OPENCODE_CONFIG_DIR`
with plural staging, `opencode-marketplace install`).
### OpenCode claims grounded against docs
- `OPENCODE_SESSION_ID` / PR #9289 → closed unmerged. `session capture`
and `metrics capture` return `no-op` on OpenCode with documented
`reason`/`alternative` (manual `--total-tokens` fallback).
- `#8892` "Anthropic models ignore instructions array" → real, open
upstream. PR #11316 was claimed as a fix but is closed unmerged.
Documented as a known limitation.
- OpenCode skill loading is **LLM-driven**, not runtime-parsed — the
body emitter rewrites every standalone `Skill: bundle:skill` line into
an explicit `skill` tool-call instruction (the most reliable cue per
OpenCode docs).
- OpenCode's TUI does **not** invoke skills via `/skill-name`;
user-invocable skills are dual-emitted as both a skill (agent-loaded)
and a command (TUI-invocable as `/{bundle}-{skill}`).
- `OPENCODE_CONFIG_DIR` precedence corrected — env-var-pointed config
loads **before** `.opencode/`, so committed project content shadows it
(not the inverse the design originally claimed).
- `~/.opencode/plugins/cache/` does not exist — corrected to
`~/.config/opencode/plugins/**` and `~/.config/opencode/skills/**`.
- "opencode-statusline plugin" alternative does not exist — replaced
with the built-in `/statusline` TUI command and a reference to the open
feature request anomalyco/opencode#8619.
### Per-cluster TODO checklists
Every cluster now has a sibling `todo.md` driving sequential
implementation:
- **Core Rules**: one item at a time; advance only after implementation
+ testing + documentation done; feature-branch only.
- **Briefing**: read `plan.md`, `principles.md`, `README.md` (plus
prerequisite-cluster `plan.md` files where applicable) before touching
anything; stop and ask if unclear.
- **Setup**: branch creation, prerequisite-cluster confirmation.
- **Tasks**: per-cluster checklist with up to three boxes per task
(implementation / testing / documentation).
- **Quality Gate** (run **once** post-tasks): `quality-gate` then
`verify` via the executor with ≥10 min timeout; both must return
`status: success`.
- **Ship**: concrete `git push` + `ci pr prepare-body` + `ci pr create`
+ `ci pr wait-for-comments` + `ci pr comments` + reply chain
(`prepare-comment --for thread-reply` → `thread-reply` →
`resolve-thread`).
- **Close**: `ci pr merge --strategy squash --delete-branch` + `git
switch main && git pull`.
All script invocations use the canonical executor notation `python3
.plan/execute-script.py plan-marshall:tools-integration-ci:ci ...` per
CLAUDE.md hard rule (no direct `gh`).
## Test plan
- [x] All design contradictions surfaced by two full audit passes have
been corrected (body-verbatim claims, executor-on-OpenCode no-op claims,
SessionStart-on-OpenCode claims, six-vs-seven discovery root count,
`mapping.json` / `frontmatter-rules.json` field duplication, agent-count
error).
- [x] Every OpenCode-specific claim verified against opencode.ai/docs
and `anomalyco/opencode` issues/PRs.
- [x] CI integration script interfaces verified against the live
executor — `prepare-body`, `prepare-comment`, `create`,
`wait-for-comments`, `comments`, `reviews`, `reply`, `thread-reply`,
`resolve-thread`, `merge` — including a confirmation that `--plan-id` is
a pure path-handle (no plan-marshall plan needs to exist).
- [ ] Implementation of any of the seven clusters is **not** part of
this PR — this PR ships the design + TODO scaffolding only. Each
cluster's `todo.md` will drive its own follow-up PR.
---------
Co-authored-by: Oliver Wolff <[email protected]>
Co-authored-by: Claude <[email protected]>1 parent fcc253a commit 8965e08
18 files changed
Lines changed: 3513 additions & 0 deletions
File tree
- doc/refactor
- 00-cleanup-precondition
- 01-design-platform-api
- 02-build-system
- 03-refactor-for-portability
- 04-validate-and-document
- 05-distribution
- 06-developer-workflow
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
0 commit comments