diff --git a/CHANGELOG.md b/CHANGELOG.md index a4afeb5..207900e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ versions follow [Semantic Versioning](https://semver.org/). ### Changed - **A tooling gotcha that can falsify a verification is recorded** (`docs/LEARNINGS.md`). A subagent reported a signature line that did not match the file; reproduced directly, `head -1 ` on a 111-line file returns **`[111 more lines]`** — a placeholder, not the line. A token-optimising proxy sits in front of read commands here and can answer a read with its own summary. Measured rather than guessed: `sed -n '1p'`, `grep -m1`, `awk 'NR==1'`, `wc -l` and piped `cat … | head -1` are all exact, and bare `head` is not *always* summarised — which is worse than if it were, because a tool that usually works is one you stop checking. The rule recorded is therefore *`head` is not dependable for evidence*, with `sed`/`awk`/Python/`git show` as the reliable reads. **A proxy returning a plausible placeholder is more dangerous than one that errors**: `[111 more lines]` reads like output, not like a failure. One thing was **not** reproduced and is marked open: the subagent reported a *stale version string* rather than a placeholder, and whether the proxy can also return outdated content is unknown. +- **M2 (multi-harness) is scoped, and the scope is smaller than the milestone assumed** ([ADR 0049](docs/decisions/0049-m2-scoped-on-the-open-standards.md); **nothing in the plugin changes yet**). Two premises of `docs/ROADMAP.md` no longer held: the skill format is now an open standard ([Agent Skills](https://agentskills.io/specification)) that the fifteen skills **already validate against** — `gh skill publish . --dry-run`: zero errors, one missing optional `license` per skill — and a universal plugin manifest exists ([Agent Plugins v1.0.0](https://agent-plugins.org/specification)), while Codex's own source reads `.claude-plugin/marketplace.json`. So M2 becomes **spec conformance, neutral wording, and graceful degradation of the two logic dependencies** (`$ARGUMENTS` in 8 skills, `AskUserQuestion` in 14), with **no per-harness adapter and no new manifest**. A harness is claimed only once the eval suite has run in it — OpenCode first — and whether it honours `disable-model-invocation` on the five skills ADR 0045 keeps locked is measured before that claim. ADR 0047's `AGENTS.md` test was re-run and holds; `AGENTS.md` stays the last step. The ROADMAP's Windsurf target is requalified (now Devin Desktop), and the steps are in `PLAN.md`. ## [1.13.0] - 2026-10-09 diff --git a/PLAN.md b/PLAN.md index a666165..3298ab1 100644 --- a/PLAN.md +++ b/PLAN.md @@ -11,7 +11,13 @@ This file differs from the long-term roadmap: it describes what is happening **n ## Up next -- [ ] *(empty)* +M2 — multi-harness, in the order [ADR 0049](docs/decisions/0049-m2-scoped-on-the-open-standards.md) sets: + +- [ ] **Spec conformance** — `license: MIT` on the fifteen skills, `allowed-tools` space-separated; `gh skill publish . --dry-run` must come back without warnings on skills. +- [ ] **Neutral wording** — name the act and the place, the command as a shortcut; start with `bootstrap`, `adopt`, `apply-best-practices`, `verify-bootstrap`, `migrate`, `slim`. Eval suite on the PR. +- [ ] **Degrade `$ARGUMENTS` and `AskUserQuestion` gracefully** — 8 and 14 skills respectively; no behaviour change in Claude Code. +- [ ] **Measure OpenCode** — run the eval suite there, and check whether it honours `disable-model-invocation` on the five locked skills, before any README support claim. +- [ ] **`AGENTS.md`** — re-measure and decide in its own ADR (ADR 0047). > **Long-term milestones moved to [`docs/ROADMAP.md`](docs/ROADMAP.md)** — M1 *Loop-readiness* (loop scaffolding opt-in, `/groundrules:realize`, triage convention; ADR 0027) and M2 *Multi-harness support*. They enter "In progress" here, and get a PRD/ADR, only when actively tackled. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 2b2e756..5a1530d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -66,20 +66,22 @@ stakes. `run-loop.sh` is repositioned as the high-fidelity executor **and** the (ties into M2). Implementation deferred to a PRD: `realize` emits a `/goal`-ready condition, an interop note in the generated `loop/README.md`, and a `README.md` explanation of the two fidelity levels. -### M2 — Support harnesses beyond Claude Code +### M2 — Support harnesses beyond Claude Code — 🚧 IN PROGRESS (scoped by ADR 0049) The strategic reason the repo is named `groundrules` (harness-neutral). Keep the generated **output** -(docs/, CLAUDE.md, ADRs) harness-agnostic; only the *delivery* of the skills changes per harness -(Cursor, Codex/OpenAI, Gemini CLI, OpenCode…). Scope to be defined in its own ADR when tackled: -which harnesses first, how the Markdown SKILL instructions port vs. need per-harness adapters, and -the per-harness distribution model (there is no universal "plugin"). - -> **Start here**: [ADR 0047](decisions/0047-agents-md-deferred-to-m2.md) parks the `AGENTS.md` -> question against this milestone with the groundwork already done — the spec read, the harness -> behaviour measured (a pointer `AGENTS.md` beside a `CLAUDE.md` is read by **nothing**; an -> `@AGENTS.md` import loads both), the generated file measured at ~86% harness-neutral, and the cost -> counted at 77 references across 10 skills. Re-run its three-directory test before acting: those -> numbers are a product behaviour, not a contract. +(docs/, CLAUDE.md, ADRs) harness-agnostic; only the *delivery* of the skills changes per harness. + +> **Scoped by [ADR 0049](decisions/0049-m2-scoped-on-the-open-standards.md)** (2026-10-09). Two +> premises written here earlier no longer hold: there **is** now a universal plugin manifest +> ([Agent Plugins](https://agent-plugins.org/specification)), and the skill format is an open +> standard ([Agent Skills](https://agentskills.io/specification)) our fifteen skills already +> validate against. Windsurf, once named here as a target, is now Devin Desktop. So M2 is +> **conformance plus neutral wording**, not per-harness adapters, and a harness is claimed only once +> the eval suite has run in it — OpenCode first. Steps and their order live in the ADR; the backlog +> lives in [`PLAN.md`](../PLAN.md). +> +> `AGENTS.md` is the last step, parked by [ADR 0047](decisions/0047-agents-md-deferred-to-m2.md) +> with its measurements (re-run 2026-10-09: unchanged). ### M3 — Cross-project dashboard (companion tool) diff --git a/docs/decisions/0049-m2-scoped-on-the-open-standards.md b/docs/decisions/0049-m2-scoped-on-the-open-standards.md new file mode 100644 index 0000000..622148f --- /dev/null +++ b/docs/decisions/0049-m2-scoped-on-the-open-standards.md @@ -0,0 +1,145 @@ + +# 0049 — M2 scoped on the open standards: conformance and wording, not per-harness adapters + +**Date**: 2026-10-09 +**Status**: Accepted (scopes [M2](../ROADMAP.md); builds on [ADR 0047](0047-agents-md-deferred-to-m2.md)) + +## Context + +[M2](../ROADMAP.md) — *support harnesses beyond Claude Code* — asked its own ADR to settle three +things when tackled: **which harnesses first**, **how the Markdown skills port versus need +per-harness adapters**, and **the per-harness distribution model**, on the premise that *"there is no +universal plugin"*. It also named Windsurf as a target. Both premises have aged since they were written. + +### What changed outside, checked against primary sources on 2026-10-09 + +- **The skill format is an open standard, and ours already is it.** + [Agent Skills](https://agentskills.io/specification) defines `SKILL.md` with YAML frontmatter: + `name` and `description` required; `license`, `compatibility`, `metadata` optional; and + `allowed-tools` — *"a space-separated string of tools that are pre-approved to run. + **Experimental.** Support for this field may vary between agent implementations."* The spec does + **not** fix a discovery directory; `.agents/skills/` is the de-facto shared one. +- **Our fifteen skills validate unchanged.** `gh skill publish . --dry-run` (gh 2.101.0) against + this repository: **zero errors, exit 0**, and one warning per skill — the optional `license` field + is missing. +- **There is a universal plugin manifest now.** [Agent Plugins + v1.0.0](https://agent-plugins.org/specification) standardises `plugin.json` plus `skills/` and MCP + servers — and stops there on purpose: *"Commands, hooks, agents, rules, and LSP servers remain too + client-specific for a stable portable contract."* +- **Other harnesses read the manifests we already ship.** Codex's source lists + `.claude-plugin/marketplace.json` among the marketplace paths it reads + (`codex-rs/core-plugins/src/marketplace.rs`); Devin and Copilot are reported to read + `.claude-plugin/plugin.json` as well (research report, not re-verified here). +- **Command files are being absorbed by skills** (reported by the surveys, from vendor changelogs). Amp removed custom commands, Codex removed + `~/.codex/prompts/`, Cursor's commands URL now redirects to its *migrate commands to skills* page. + This plugin ships fifteen skills and no command files, so there is nothing to migrate. +- **Windsurf no longer exists as a product.** It is now Devin Desktop; `.windsurf/` survives only as + a fallback behind `.devin/`. Roo Code shut down on 2026-05-15. Neither is cited anywhere in this + repository except M2's own target list. + +### What was measured here + +- **The skills are ~86% harness-neutral by content** (206 of 1,411 non-empty lines name a Claude + Code mechanism; 6% for `realize` to 25% for `migrate`). A second, narrower count — lines naming + `Claude Code`, `CLAUDE.md`, `.claude/` or `/groundrules:` — gives 154 lines, **128 of them in six + skills**: `bootstrap`, `adopt`, `apply-best-practices`, `verify-bootstrap`, `migrate`, `slim`. Both + are regex counts: an order of magnitude, not a precision. +- **ADR 0047's three-directory test was re-run and holds**: `AGENTS.md` alone is read, `AGENTS.md` + beside `CLAUDE.md` is ignored, an `@AGENTS.md` import loads both. Claude Code's documentation now + states this default and adds a user setting, `claude-md-and-agents-md`, that reads both files. +- **Two dependencies sit in the logic, not the vocabulary.** `$ARGUMENTS` is read by **8** skills + (`add-adr`, `adopt`, `close`, `idea`, `learn`, `migrate`, `prd`, `verify-bootstrap`) — Codex lists + it as unsupported. `AskUserQuestion` appears in **14** skills' `allowed-tools`, and the phased, + grouped-question flow is built around it. No other harness has a tool by that name. + +## Decision + +**1. The porting target is the Agent Skills standard, not a list of harnesses.** No per-harness +adapter is written. Harnesses that read `.claude/skills/` (Cursor, OpenCode, Copilot, Amp, Devin) +take the skills as they are; those that read only `.agents/skills/` (Codex, Gemini CLI, Zed) take a +copy, and copying is the installer's job, not ours. + +**2. The work is conformance plus wording, in this order:** + +1. **Spec conformance** — add `license: MIT` to the fifteen skills, and write `allowed-tools` + space-separated. Claude Code's skills reference accepts *"a space- or comma-separated string, or a + YAML list"*, so the separator change costs Claude Code nothing. +2. **Neutral wording** — skill bodies name **the act and the place** (*record the decision as an ADR + in `docs/decisions/`*) and give the command as a shortcut, starting with the six skills that hold + most of the coupling. This is ADR 0047's argument, which stood on its own before M2. +3. **Graceful degradation of the two logic dependencies** — each skill reading `$ARGUMENTS` treats + it as *"what the user passed when invoking"* and falls back to asking; each phase built on + `AskUserQuestion` says *ask the user — with `AskUserQuestion` where available* — so the flow + survives as prose questions elsewhere. Claude Code behaviour must not change; the eval suite is + the check. +4. **`AGENTS.md`** last, as ADR 0047 parked it — re-measured then, decided in its own ADR. The + generated output's 77 references to `CLAUDE.md` are its cost, and nothing above depends on it. + +**3. Distribution: no new channel, no new manifest.** The Claude Code marketplace stays the primary +channel. Cross-harness installation already exists without our code — `gh skill install` targets +~50 harnesses and validates against the spec — and the README points at it once a harness is +measured. A root Agent Plugins `plugin.json` is **not** added: it would be a second manifest whose +version must be kept in step with `.claude-plugin/plugin.json`, for harnesses that already read the +latter. It becomes worth its upkeep when a target harness reads only the root form. + +**4. "Supported" means measured, one harness at a time.** A harness is claimed in the README only +after the eval suite has run in it. **OpenCode is first**: it is the one installed here, it reads +`.claude/skills/` and turns each skill into `/`, so it measures the wording and the degradation +work without any copying in between. Codex follows when available, because it is the hardest case — +`.agents/skills/` only, no `$ARGUMENTS`. + +**5. The locks do not travel unmeasured.** `disable-model-invocation` is outside the spec. It is +reported as honoured by Cursor, Copilot, Zed and Crush, and **not** by Codex (which uses its own +`agents/openai.yaml` `policy.allow_implicit_invocation`) nor Gemini CLI (which asks consent at every +activation instead). The five skills [ADR 0045](0045-the-lock-was-scoped-to-four-skills.md) keeps +locked because a wrong firing damages a project — `bootstrap`, `migrate`, `adopt`, `slim`, +`apply-best-practices` — are the safety question of M2. **Whether a harness honours the lock is +measured before that harness is claimed**, and where it does not, the gap is stated, not hidden. + +## Alternatives considered + +- **Per-harness adapters** (a build step emitting `.cursor/`, `.gemini/commands/*.toml`, + `.opencode/`…), the shape M2 originally assumed. Rejected: the formats it would target are the + ones being retired, every adapter is upkeep against someone else's release cycle, and it breaks + *template over code* ([ADR 0002](0002-plain-text-placeholder-substitution.md)) by introducing a generator. +- **Rename `CLAUDE.md` to `AGENTS.md` first**, since it is the most visible harness signal. Rejected + as the first move: it is the costliest change (77 references), it is independent of the skills + porting, and ADR 0047 already said it needs its own measured decision. +- **Add the Agent Plugins root `plugin.json` now**, since it is one file. Rejected for decision 3's + reason: one file is also one more version to forget at release, bought for no harness we target. +- **Claim the 46 clients the standard lists.** Rejected: a spec listing a client is not that client + running our skills well. A support claim this repository cannot reproduce is the failure class + `docs/AGENT-EVALS.md` keeps recording. + +## Consequences + +### Positive +- M2 shrinks from *build adapters for N harnesses* to *conform to one spec and stop naming the + harness* — work that improves the Claude Code experience too. +- Nothing is generated per harness, so nothing drifts per harness. +- The first support claim will rest on a run, not on a compatibility table. + +### Negative / Tradeoffs +- **`allowed-tools` is a pre-approval in Claude Code, and nothing elsewhere.** It fails safe — a + harness that ignores it asks permission more often, never less — but the smoother experience does + not travel. +- **The grouped-question flow loses its shape outside Claude Code.** Prose questions keep the + substance; whether they keep the quality is an open measurement, not a promise. +- Neutral wording is a sweep across fifteen skills, and every sweep of that size risks a behaviour + change in Claude Code. The eval suite must run on that PR (as it must on any PR touching + `skills/**`). +- Facts from the research reports that were not re-verified here (Devin and Copilot manifest + precedence, per-harness lock behaviour) stay *reported* until a measurement makes them load-bearing. + +### Neutral +- The generated project files do not change under this ADR; only the skills' wording and frontmatter + do. `AGENTS.md` is the step that touches generated output, and it has its own decision coming. + +## Notes + +- Research run 2026-10-09 by two delegated surveys; the load-bearing claims above were re-checked + against primary sources or measured on this machine before being written here. +- Related: [ADR 0047](0047-agents-md-deferred-to-m2.md) (`AGENTS.md`, step 4), + [ADR 0045](0045-the-lock-was-scoped-to-four-skills.md) (the locked skills), + [ADR 0002](0002-plain-text-placeholder-substitution.md) (no generator), + [ADR 0037](0037-executable-evals-over-agent-config.md) (the eval suite as the check). diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 15b95b9..45ee1cb 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -78,3 +78,4 @@ No ADR needed for trivial choices or implementation details. | [0046](0046-orchestrated-working-regime.md) | Orchestrated regime: the request for work carries the authorisation for the commit (amends 0036's commit rule) | Accepted | 2026-09-21 | | [0047](0047-agents-md-deferred-to-m2.md) | `AGENTS.md` deferred to M2, with the harness behaviour measured now (a pointer is read by nothing) | Accepted | 2026-09-23 | | [0048](0048-the-convention-here-the-transport-elsewhere.md) | Optional `INBOX.md`: the plugin ships the convention, the caller ships the transport (a `SessionStart` hook was refused) | Accepted | 2026-09-29 | +| [0049](0049-m2-scoped-on-the-open-standards.md) | M2 scoped on the open standards: Agent Skills conformance and neutral wording, no per-harness adapters, support claimed only where measured | Accepted | 2026-10-09 |