Skip to content

Commit 8965e08

Browse files
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

‎AGENTS.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# AGENTS.md
2+
3+
Guidelines for AI assistants working in the plan-marshall repository.
4+
5+
## What This Repository Is
6+
7+
A **Claude Code Marketplace** with 10 bundles of skills, agents, and commands for CUI (Common User Interface) Open Source projects. Source format IS Claude Code native. Multi-target distribution to OpenCode is in design phase (see `doc/refactor/`).
8+
9+
## Quick Commands
10+
11+
Build system: Pyprojectx wrapper (`./pw`), Python 3.12+ required.
12+
13+
```bash
14+
./pw verify # Full: mypy + ruff + pytest
15+
./pw compile [module] # mypy on bundle (e.g. pm-dev-java)
16+
./pw module-tests [module] # pytest on test/ or test/<module>
17+
./pw quality-gate [module] # ruff + mypy (no tests)
18+
./pw lint / ./pw lint-fix # ruff check / fix
19+
./pw fmt # ruff format
20+
```
21+
22+
**Module filtering**: Most commands accept a bundle name (e.g. `plan-marshall`, `pm-dev-java`) to scope to a single bundle. Omit for all.
23+
24+
## Executor Pattern (CRITICAL)
25+
26+
All marketplace scripts run through the generated executor — never by direct path:
27+
28+
```bash
29+
python3 .plan/execute-script.py {bundle}:{skill}:{script} [subcommand] [args...]
30+
```
31+
32+
Examples:
33+
- `python3 .plan/execute-script.py plan-marshall:build-python:python_build run --command-args "verify"`
34+
- `python3 .plan/execute-script.py plan-marshall:manage-files:manage-files add --plan-id my-plan --file task.md`
35+
36+
**Regenerate executor** after bundle changes: `/marshall-steward`
37+
38+
## Hard Rules
39+
40+
- **`.plan/` access via scripts only** — Never Read/Write/Edit `.plan/` files directly. Use `python3 .plan/execute-script.py` with manage-* scripts.
41+
- **Bash: one command per call** — No `&&`, `;`, `|`, loops, `$()`, subshells. Use dedicated tools or multiple Bash calls.
42+
- **No shell file operations** — Use Glob/Grep/Read/Edit tools, not `ls`, `find`, `cat`, `grep`.
43+
- **Structured queries first** — Before Glob/Grep for navigation, try `architecture files --module X` or `architecture which-module --path P`.
44+
- **CI operations via abstraction** — All PR/issue/CI work goes through `plan-marshall:tools-integration-ci:ci` scripts. Never `gh` or `glab` directly.
45+
46+
## File Formats
47+
48+
- **Skills/Agents/Commands**: Markdown with YAML frontmatter (name, description, tools/permissions)
49+
- **Scripts**: Python and Bash in `skills/*/scripts/`
50+
- **Standards**: Markdown (some AsciiDoc templates)
51+
- **Config**: JSON for `plugin.json`, `marketplace.json`
52+
53+
## Documentation Standards
54+
55+
- **No version history** — Never add changelogs, "RECENT CHANGES", or dated sections
56+
- **No timestamps** — No dates or version numbers in document content
57+
- **No duplication** — Cross-reference instead of duplicating
58+
- **Current state only** — Document present requirements, not transitions
59+
60+
## Architecture
61+
62+
```
63+
marketplace/
64+
├── .claude-plugin/marketplace.json # Master marketplace manifest
65+
├── adapters/ # Multi-target export (being retired)
66+
└── bundles/ # 10 production bundles
67+
└── {bundle}/
68+
├── .claude-plugin/plugin.json # Bundle manifest
69+
├── agents/ # Task agents (*.md)
70+
├── commands/ # Slash commands (*.md)
71+
└── skills/
72+
└── {skill}/
73+
├── SKILL.md # Skill definition
74+
├── standards/ # Detailed standards (*.md)
75+
├── scripts/ # Python/Bash scripts
76+
└── templates/ # Document/code templates
77+
78+
test/ # pytest tests for scripts
79+
doc/ # Documentation (AsciiDoc)
80+
doc/refactor/ # Multi-target distribution design plans
81+
```
82+
83+
## Plugin Cache Sync
84+
85+
After editing skills/agents/commands in `marketplace/bundles/`, sync to Claude Code plugin cache:
86+
87+
```bash
88+
/sync-plugin-cache
89+
```
90+
91+
This copies to `~/.claude/plugins/cache/plan-marshall/` via rsync `--delete`.
92+
93+
## Multi-Target Distribution (In Design)
94+
95+
See `doc/refactor/` for the 7-cluster plan to distribute to both Claude Code and OpenCode:
96+
97+
| Cluster | Document | Topic |
98+
|---------|----------|-------|
99+
| 00 | `00-cleanup-precondition/plan.md` | Source-side prose cleanup of skill bodies (precondition) |
100+
| 01 | `01-design-platform-api/plan.md` | `platform-runtime` API (13 operations) |
101+
| 02 | `02-build-system/plan.md` | Target generator, OpenCode emitter |
102+
| 03 | `03-refactor-for-portability/plan.md` | Skill rewrites for portability |
103+
| 04 | `04-validate-and-document/plan.md` | Test plan, acceptance criteria |
104+
| 05 | `05-distribution/plan.md` | CI/CD, artifact hosting, installation |
105+
| 06 | `06-developer-workflow/plan.md` | Developer inner loop (both platforms) |
106+
107+
**Current state**: `marketplace/adapters/opencode_adapter.py` generates OpenCode output but is being replaced by `marketplace/targets/` framework per the refactor plan.
108+
109+
## Key Files for Context
110+
111+
- `CLAUDE.md` — Full project context for Claude Code (more detailed than this file)
112+
- `doc/build-structure.adoc` — Build system details
113+
- `pyproject.toml` — Tool configs (ruff, mypy, pytest)
114+
- `build.py` — Build script with module filtering
115+
- `marketplace/.claude-plugin/marketplace.json` — Master marketplace manifest
116+
117+
## Git Commit Guidelines
118+
119+
- Git commit Co-Authored-By line: Use `Co-Authored-By: opencode/{model-version}` — include model name and version, no email address, no marketing claims.
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# 00 — Cleanup / Precondition
2+
3+
## Objective
4+
5+
Strip Claude-Code-specific plumbing prose from skill bodies as a one-time source-side cleanup, **before** the multi-target refactor begins. The work is platform-agnostic improvement: cleaner source benefits Claude Code today and unblocks OpenCode (and any future target) tomorrow.
6+
7+
## Why This Cluster Exists
8+
9+
Several skill bodies currently mix **workflow instructions** (steps the agent should take) with **platform plumbing documentation** (descriptions of Claude Code hook events, cache paths, settings files, and tool-taxonomy rules naming specific Claude tools). The plumbing prose is:
10+
11+
1. **Not beneficial on Claude either** — it documents implementation details of mechanisms that exist outside the skill's workflow scope. Reference docs are the right home.
12+
2. **Misleading on OpenCode** — the prose describes Claude-only mechanisms that have no equivalent (or a different equivalent), so the agent reading the body sees instructions tied to a platform it isn't running on.
13+
3. **A precondition for clean target generation** — until skill bodies stop coupling themselves to one platform's tool names and filesystem layout, no body emitter can produce a clean OpenCode artifact, and no body transform can bridge the gap because the LLM has to interpret the prose against the wrong target.
14+
15+
This cluster is therefore **a precondition**, not a workaround. It runs first so the rest of the refactor (clusters 01–06) operates on already-clean source.
16+
17+
## Scope
18+
19+
### In scope
20+
21+
Source-side, pure prose changes to skill bodies and their `references/` siblings:
22+
23+
- Move Claude-only mechanism descriptions out of skill bodies into `references/{topic}.md`
24+
- Rephrase tool-name rules platform-agnostically (no specific tool names in rules; describe the *role* instead)
25+
- Remove `.claude/` filesystem references from prose that aren't part of `platform-runtime` call sites
26+
- Remove cache/session-resolver descriptions from skill bodies
27+
28+
### Out of scope
29+
30+
- Any change to behaviour or the operations skills perform (those are addressed in [03 — Refactor for Portability](../03-refactor-for-portability/plan.md))
31+
- The `platform-runtime` API design ([01](../01-design-platform-api/plan.md))
32+
- The target generator framework ([02](../02-build-system/plan.md))
33+
- Body transforms applied at emit time ([02](../02-build-system/plan.md) "Body Transforms")
34+
- Any new skill, agent, or command
35+
36+
This cluster never runs `platform-runtime` calls, never adds `runtime.target` to `marshal.json`, never touches the executor. It is pure source housekeeping.
37+
38+
## Audit Checklist
39+
40+
Search every skill body in `marketplace/bundles/*/skills/*/SKILL.md` for these patterns:
41+
42+
| Pattern | Violation | Fix |
43+
|---------|-----------|-----|
44+
| Claude tool name in a rule (e.g. `EnterPlanMode`, `ExitPlanMode`, `AskUserQuestion`, `Agent(subagent_type=…)`, `TaskCreate`, `Task:`, etc.) | Couples skill prose to one target's tool taxonomy | Rephrase platform-agnostically — describe the *role* (e.g. "the host platform's plan-mode tools", "the user-question tool", "an unconstrained generic subagent"). Do not name a specific tool in instructional rules. |
45+
| Skill body section describing a Claude Code hook mechanism (terminal title, statusLine, `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop`, etc.) | Documentation for a Claude-only mechanism inside a workflow body | Move section into `marketplace/bundles/{bundle}/skills/{skill}/references/{topic}.md` |
46+
| Skill body section describing a Claude-only cache or session-resolver pipeline (e.g. `~/.cache/plan-marshall/sessions/...`, transcript-file walking, JSONL parsing) | Same as above — documents plumbing, not workflow | Move section into `references/{topic}.md` |
47+
| `.claude/` path mentioned in passing prose outside of a `platform-runtime` call site | Couples skill prose to one target's filesystem layout | Either rephrase to use `platform-runtime` (if it describes a call), or remove the prose if it described platform plumbing now living in `references/`. |
48+
| `~/.claude/...` path in prose outside of `platform-runtime` call sites | Same as above | Same as above |
49+
50+
## Concrete Cleanup Tasks
51+
52+
The walk-through of the `plan-marshall` entry skill identified these specific items. Other skills are swept against the audit checklist as a follow-up.
53+
54+
### `plan-marshall` (entry skill at `marketplace/bundles/plan-marshall/skills/plan-marshall/SKILL.md`)
55+
56+
| Issue | Action |
57+
|-------|--------|
58+
| "Terminal Title Integration" section (~25 lines describing `SessionStart`/`UserPromptSubmit`/`PostToolUse`/etc. hooks and `.claude/settings.local.json`) | Move to `marketplace/bundles/plan-marshall/skills/plan-marshall/references/terminal-title.md`. Add a one-line pointer in the SKILL body for users who want details. |
59+
| "Session ID Resolver" section (~15 lines describing the Claude-only hook-populated cache at `~/.cache/plan-marshall/sessions/...`) | Move to `references/session-id-resolver.md`. Add a one-line pointer in the SKILL body. |
60+
| Rule "Never use Claude Code's built-in `EnterPlanMode` or `ExitPlanMode`" | Rephrase as "Never use the host platform's built-in plan-mode tools — this skill implements its own plan system" |
61+
| Rule "All user interactions use `AskUserQuestion` tool with proper YAML structure" | Rephrase as "All user interactions use the user-question tool with proper YAML structure" (omit the platform-specific tool name) |
62+
| Rule "Never spawn `Agent(subagent_type=\"general-purpose\")`" | Rephrase as "Never spawn an unconstrained generic subagent — always specify a plan-marshall agent or skill" |
63+
64+
### Other bundles (sweep)
65+
66+
Apply the audit checklist to every skill body in:
67+
68+
| Bundle | Expected scope of cleanup |
69+
|--------|---------------------------|
70+
| plan-marshall | Already largely covered above; sweep remaining skills (`marshall-steward`, `phase-*`, etc.) for any leftover Claude tool-name rules and `.claude/` prose |
71+
| pm-plugin-development | Possible plugin-path references in `plugin-doctor`, `plugin-create`, `plugin-maintain` |
72+
| pm-dev-java | Likely clean (Java standards) |
73+
| pm-dev-java-cui | Likely clean |
74+
| pm-dev-frontend | Likely clean |
75+
| pm-dev-frontend-cui | Likely clean |
76+
| pm-dev-oci | Likely clean |
77+
| pm-dev-python | Likely clean |
78+
| pm-documents | Likely clean |
79+
| pm-requirements | Likely clean |
80+
81+
A bundle is "clean" for this cluster's purposes when no audit-checklist pattern matches. Findings get logged and fixed in the same pass.
82+
83+
## What Cleanup Does NOT Touch
84+
85+
These remain untouched by this cluster — they are the next cluster's concern:
86+
87+
- `platform-runtime` call sites (e.g. `python3 .plan/execute-script.py plan-marshall:platform-runtime:platform_runtime …`) — those are added in [03](../03-refactor-for-portability/plan.md), not removed here
88+
- `Skill: bundle:skill` directives — the source line stays as-is; the OpenCode emitter rewrites them mechanically per [02](../02-build-system/plan.md) "Body Transforms"
89+
- `/skill-name` slash references in usage examples — same; the emitter rewrites them per [02](../02-build-system/plan.md) "Body Transforms"
90+
- `user-invocable: true` frontmatter — left as-is; the emitter dual-emits per [02](../02-build-system/plan.md) "User-Invocable Skills (Dual Emission)"
91+
- Any `.claude/settings.local.json` write that **is** a behavioural call (e.g. inside a marshall-steward step that patches settings) — those move to `platform-runtime permission configure` calls in [03](../03-refactor-for-portability/plan.md)
92+
93+
## Verification
94+
95+
This cluster is complete when:
96+
97+
1. No skill body contains a Claude tool name (`EnterPlanMode`, `ExitPlanMode`, `AskUserQuestion`, `Agent(subagent_type=…)`, `TaskCreate`, `Task:`, etc.) inside an instructional rule. Rules describe the *role*, not the tool.
98+
2. No skill body contains a section describing a Claude-only hook mechanism (terminal title, status-line, `SessionStart`, `UserPromptSubmit`, `PostToolUse`, etc.). Such content lives in `references/{topic}.md`.
99+
3. No skill body contains a section describing a Claude-only cache or session-resolver pipeline. Same — `references/{topic}.md`.
100+
4. Every `.claude/` and `~/.claude/...` mention in skill bodies is either:
101+
- inside a `platform-runtime` call site (left as-is for cluster 03 to refactor), or
102+
- removed because it described platform plumbing now living in `references/`.
103+
5. The `plan-marshall` entry skill has its "Terminal Title Integration" and "Session ID Resolver" sections moved to `references/terminal-title.md` and `references/session-id-resolver.md` respectively, with a one-line pointer remaining in the SKILL body.
104+
6. `./pw verify` passes — cleanup must not regress anything on Claude Code (this is the canary).
105+
7. A grep over `marketplace/bundles/*/skills/*/SKILL.md` for the audit-checklist patterns returns no hits (or hits are explicitly classified as out-of-scope for this cluster — e.g. lines inside fenced code blocks demonstrating something).
106+
107+
## Dependencies
108+
109+
**None.** This is the precondition cluster. It must complete before [03 — Refactor for Portability](../03-refactor-for-portability/plan.md) starts, because cluster 03's behavioural rewrites apply on top of clean source. Clusters 01, 02, 05, and 06 do not depend on cluster 00 directly but benefit from running on cleaned-up source.
110+
111+
## Why This Is a Standalone Cluster
112+
113+
Pulling cleanup out of cluster 03 has three benefits:
114+
115+
1. **Risk separation.** Source prose changes are low-risk and reviewable independently of the platform-runtime API design and skill-behaviour rewrites in cluster 03. A bad rephrase is a one-line fix; a bad `platform-runtime permission configure` migration may break the wizard.
116+
2. **Faster Claude Code wins.** Skill bodies focused on workflow rather than plumbing are a Claude-Code-only improvement that lands without waiting for any of the multi-target work.
117+
3. **Clean precondition for any future target.** A cluster-00 sweep happens once. Future targets (Cursor, Codex, others) inherit the cleaned source without revisiting prose.

0 commit comments

Comments
 (0)