From 8ed0960e389d28782bf8de90c79303347f1575f7 Mon Sep 17 00:00:00 2001 From: 3metaJun <251347867+3metaJun@users.noreply.github.com> Date: Fri, 11 Sep 2026 13:08:13 +0800 Subject: [PATCH 1/2] fix: align harness adapters with official docs --- README.md | 2 + adapters/opencode.json | 11 +---- adapters/pi.json | 11 +---- docs/harness-adapters.md | 47 +++++++++++++++++++++ docs/pi-e2e-evidence.md | 27 ++++++++++++ scripts/install.test.mjs | 11 +++-- skills/recall/references/history-sources.md | 26 ++++++++++++ 7 files changed, 111 insertions(+), 24 deletions(-) create mode 100644 docs/harness-adapters.md create mode 100644 docs/pi-e2e-evidence.md diff --git a/README.md b/README.md index 8ab9998..77fc7a0 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,8 @@ the remote fixture and temporary credentials were removed afterward. - `skills/` contains the canonical, harness-neutral skill files. - `adapters/` contains per-harness frontmatter changes. - `profiles/harnesses.json` defines supported harnesses and default paths. +- `docs/harness-adapters.md` records the official skill and session rules used + by each Harness adapter. - `profiles/artifacts.json` defines optional artifacts and documents unsupported harness-owned surfaces. - `profiles/skills.json` defines the canonical skill inventory. diff --git a/adapters/opencode.json b/adapters/opencode.json index f853de8..0967ef4 100644 --- a/adapters/opencode.json +++ b/adapters/opencode.json @@ -1,10 +1 @@ -{ - "removeFrontmatter": { - "show-me-your-work": ["metadata"] - }, - "frontmatter": { - "show-me-your-work": { - "compatibility": "Node.js 18 or newer is required for scripts/log.mjs." - } - } -} +{} diff --git a/adapters/pi.json b/adapters/pi.json index f853de8..0967ef4 100644 --- a/adapters/pi.json +++ b/adapters/pi.json @@ -1,10 +1 @@ -{ - "removeFrontmatter": { - "show-me-your-work": ["metadata"] - }, - "frontmatter": { - "show-me-your-work": { - "compatibility": "Node.js 18 or newer is required for scripts/log.mjs." - } - } -} +{} diff --git a/docs/harness-adapters.md b/docs/harness-adapters.md new file mode 100644 index 0000000..e4a6416 --- /dev/null +++ b/docs/harness-adapters.md @@ -0,0 +1,47 @@ +# Harness adapter reference + +This page records the vendor rules that shape mstack's adapters. The links point +to the official documentation used for each entry. + +## Skill locations and frontmatter + +| Harness | User skill root | Project skill root | Supported optional fields | +| --- | --- | --- | --- | +| Codex | `~/.agents/skills/` | `.agents/skills/` | Agent Skills fields; Codex-specific `agents/openai.yaml` lives beside each skill | +| Claude Code | `~/.claude/skills/` | `.claude/skills/` | `name`, `description`, and Claude invocation fields | +| OpenCode | `~/.config/opencode/skills/` | `.opencode/skills/` | `license`, `compatibility`, and `metadata` | +| pi | `~/.pi/agent/skills/` | `.pi/skills/` | `license`, `compatibility`, `metadata`, `allowed-tools`, and `disable-model-invocation` | + +Sources: + +- [Codex skills](https://learn.chatgpt.com/docs/build-skills) and [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) +- [Claude Code skills](https://code.claude.com/docs/en/skills) +- [OpenCode skills](https://opencode.ai/docs/skills) +- [pi skills](https://pi.dev/docs/latest/skills) + +The canonical tree keeps the Agent Skills fields that all supported Harnesses +can read. `adapters/claude.json` removes the `metadata` field from +`show-me-your-work` because Claude Code does not list that field in its skill +frontmatter reference. OpenCode and pi retain the field because their official +references support it. + +## Delegation and session records + +Codex stores agent configuration in `.codex/agents/*.toml`. Claude Code stores +subagent definitions in `.claude/agents/`. OpenCode defines agents in its +configuration and invokes them through the agent interface. pi does not require +a separate agent file for skill use; it loads skills through discovery or the +`--skill` flag. + +Pi sessions are JSONL files under `~/.pi/agent/sessions/` by default. The +`PI_CODING_AGENT_SESSION_DIR` variable and `--session-dir` flag select another +root. Session records can form a tree through `id` and `parentId`, so a history +reader follows the active leaf instead of assuming that file order is one +linear transcript. Use `pi --export ` or `/export` when an HTML +record is needed. `--no-session` creates no persistent record. + +The [pi session format](https://pi.dev/docs/latest/session-format), [pi +sessions](https://pi.dev/docs/latest/sessions), and [pi environment variables](https://pi.dev/docs/latest/environment-variables) +pages define these rules. The repository-specific history procedure is in +[`skills/recall/references/history-sources.md`](../skills/recall/references/history-sources.md). + diff --git a/docs/pi-e2e-evidence.md b/docs/pi-e2e-evidence.md new file mode 100644 index 0000000..c4cb33e --- /dev/null +++ b/docs/pi-e2e-evidence.md @@ -0,0 +1,27 @@ +# pi end-to-end evidence + +The three requested skills ran through pi `0.85.1` in a disposable Git +workspace on 2026-09-11. The installer copied all 50 skills into the workspace +project root at `.pi/skills/`. + +Each command used pi's documented non-interactive mode, disabled session writes, +and allowed only read tools: + +```text +pi -p --no-session --tools read,grep,find,ls -- "/skill:meta-mode Smoke check only. Do not edit files or delegate. Reply exactly mstack-meta-mode-ok." +pi -p --no-session --tools read,grep,find,ls -- "/skill:architect Smoke check only. Do not edit files or delegate. Reply exactly mstack-architect-ok." +pi -p --no-session --tools read,grep,find,ls -- "/skill:create-verification-skill Inspect this disposable repository. Do not create files or run an app. Reply exactly mstack-create-verification-skill-ok." +``` + +Observed output: + +```text +mstack-meta-mode-ok +mstack-architect-ok +mstack-create-verification-skill-ok +``` + +The run proves skill discovery and invocation through pi. It does not claim +that `create-verification-skill` drove an application, because this smoke +workspace has no application to launch. + diff --git a/scripts/install.test.mjs b/scripts/install.test.mjs index 4345bd1..6bf526b 100644 --- a/scripts/install.test.mjs +++ b/scripts/install.test.mjs @@ -158,10 +158,13 @@ test("installs harness-specific frontmatter and preserves conflicts", () => { const pi = readFileSync(piPath, "utf8"); assert.match(codex, /^metadata:/m); assert.doesNotMatch(codex, /^compatibility:/m); - for (const adapted of [claude, opencode, pi]) { - assert.match(adapted, /^compatibility:/m); - assert.doesNotMatch(adapted, /^metadata:/m); - assert.doesNotMatch(adapted, /The included logger requires/i); + assert.match(claude, /^compatibility:/m); + assert.doesNotMatch(claude, /^metadata:/m); + assert.doesNotMatch(claude, /The included logger requires/i); + for (const adapted of [opencode, pi]) { + assert.match(adapted, /^metadata:/m); + assert.match(adapted, /^ requirements:/m); + assert.doesNotMatch(adapted, /^compatibility:/m); } const marker = join(env.HARNESS_SKILLS_CODEX_DIR, "blast-radius", "marker.txt"); diff --git a/skills/recall/references/history-sources.md b/skills/recall/references/history-sources.md index da43864..37c317c 100644 --- a/skills/recall/references/history-sources.md +++ b/skills/recall/references/history-sources.md @@ -37,6 +37,32 @@ Use `--sanitize` whenever exported data will leave the local machine. Do not depend on OpenCode's internal database layout unless the CLI cannot provide the required authorized record. +## Pi + +Pi stores persistent sessions as JSONL trees. The default root is +`~/.pi/agent/sessions/`; project sessions are nested under a slugged directory +(`----`, with `/`, `\\`, and `:` replaced by `-`), and files are named +`_.jsonl`. Set `PI_CODING_AGENT_SESSION_DIR` or pass +`--session-dir ` when using a custom root; the CLI flag takes precedence. + +Prefer `pi -r`/`/resume` for interactive discovery and `pi --export ` (or +`/export`) when a readable HTML transcript is needed. For programmatic recall, +parse JSONL entries by `type` and follow the `id`/`parentId` tree from the active +leaf; do not treat the file as a linear transcript. Session versions 1 and 2 +are migrated to version 3 when loaded. `--no-session` and RPC clients started +with `--no-session` do not create a persistent session. + +Limit scans to the active workspace's slug and use the newest matching session +metadata before opening message contents. Session records can contain tool +outputs and extension data, so keep raw reads local unless the user explicitly +authorizes sharing. + +Official references: [skills](https://pi.dev/docs/latest/skills), +[sessions](https://pi.dev/docs/latest/sessions), +[session format](https://pi.dev/docs/latest/session-format), +[environment variables](https://pi.dev/docs/latest/environment-variables), +and [RPC mode](https://pi.dev/docs/latest/rpc). + ## Shared project records Repository history, pull requests, issues, documentation, project chat, and From e58b9ffdf352ad8e9cfd9797168a7fce130c94b3 Mon Sep 17 00:00:00 2001 From: 3metaJun <251347867+3metaJun@users.noreply.github.com> Date: Fri, 11 Sep 2026 13:33:53 +0800 Subject: [PATCH 2/2] fix: correct adapter documentation and evidence --- docs/harness-adapters.md | 22 +++++++++++----------- docs/pi-e2e-evidence.md | 24 ++++++++++++++---------- scripts/install.test.mjs | 3 +-- 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/harness-adapters.md b/docs/harness-adapters.md index e4a6416..db76b50 100644 --- a/docs/harness-adapters.md +++ b/docs/harness-adapters.md @@ -8,7 +8,7 @@ to the official documentation used for each entry. | Harness | User skill root | Project skill root | Supported optional fields | | --- | --- | --- | --- | | Codex | `~/.agents/skills/` | `.agents/skills/` | Agent Skills fields; Codex-specific `agents/openai.yaml` lives beside each skill | -| Claude Code | `~/.claude/skills/` | `.claude/skills/` | `name`, `description`, and Claude invocation fields | +| Claude Code | `~/.claude/skills/` | `.claude/skills/` | `name`, `description`, `license`, `compatibility`, `metadata`, and Claude invocation fields | | OpenCode | `~/.config/opencode/skills/` | `.opencode/skills/` | `license`, `compatibility`, and `metadata` | | pi | `~/.pi/agent/skills/` | `.pi/skills/` | `license`, `compatibility`, `metadata`, `allowed-tools`, and `disable-model-invocation` | @@ -20,18 +20,19 @@ Sources: - [pi skills](https://pi.dev/docs/latest/skills) The canonical tree keeps the Agent Skills fields that all supported Harnesses -can read. `adapters/claude.json` removes the `metadata` field from -`show-me-your-work` because Claude Code does not list that field in its skill -frontmatter reference. OpenCode and pi retain the field because their official -references support it. +can read. Claude Code accepts `metadata` but does not act on its contents, so +`adapters/claude.json` removes that map and surfaces the logger requirement in +the `compatibility` field instead. OpenCode and pi retain `metadata` because +their official references support it. ## Delegation and session records -Codex stores agent configuration in `.codex/agents/*.toml`. Claude Code stores -subagent definitions in `.claude/agents/`. OpenCode defines agents in its -configuration and invokes them through the agent interface. pi does not require -a separate agent file for skill use; it loads skills through discovery or the -`--skill` flag. +Codex stores agent configuration in `.codex/agents/*.toml` and +`~/.codex/agents/*.toml`. Claude Code stores subagent definitions in +`.claude/agents/`. OpenCode stores agent definitions in `.opencode/agents/` or +`~/.config/opencode/agents/`. pi does not require a separate agent file for +skill use; it loads skills through discovery, the `--skill` flag, or the +`/skill:name` command. Pi sessions are JSONL files under `~/.pi/agent/sessions/` by default. The `PI_CODING_AGENT_SESSION_DIR` variable and `--session-dir` flag select another @@ -44,4 +45,3 @@ The [pi session format](https://pi.dev/docs/latest/session-format), [pi sessions](https://pi.dev/docs/latest/sessions), and [pi environment variables](https://pi.dev/docs/latest/environment-variables) pages define these rules. The repository-specific history procedure is in [`skills/recall/references/history-sources.md`](../skills/recall/references/history-sources.md). - diff --git a/docs/pi-e2e-evidence.md b/docs/pi-e2e-evidence.md index c4cb33e..60378cb 100644 --- a/docs/pi-e2e-evidence.md +++ b/docs/pi-e2e-evidence.md @@ -2,15 +2,16 @@ The three requested skills ran through pi `0.85.1` in a disposable Git workspace on 2026-09-11. The installer copied all 50 skills into the workspace -project root at `.pi/skills/`. +project root at `.pi/skills/` with `HARNESS_SKILLS_PI_DIR=/.pi/skills`. -Each command used pi's documented non-interactive mode, disabled session writes, -and allowed only read tools: +Each command used pi's documented non-interactive mode, approved the project so +project-local skills were discoverable, emitted JSONL events, kept a session +directory for inspection, and allowed only read tools: ```text -pi -p --no-session --tools read,grep,find,ls -- "/skill:meta-mode Smoke check only. Do not edit files or delegate. Reply exactly mstack-meta-mode-ok." -pi -p --no-session --tools read,grep,find,ls -- "/skill:architect Smoke check only. Do not edit files or delegate. Reply exactly mstack-architect-ok." -pi -p --no-session --tools read,grep,find,ls -- "/skill:create-verification-skill Inspect this disposable repository. Do not create files or run an app. Reply exactly mstack-create-verification-skill-ok." +pi -p --approve --mode json --session-dir .pi/e2e-sessions --tools read,grep,find,ls -- "/skill:meta-mode Read the installed skill before answering. Reply exactly mstack-meta-mode-ok." +pi -p --approve --mode json --session-dir .pi/e2e-sessions --tools read,grep,find,ls -- "/skill:architect Read the installed skill before answering. Reply exactly mstack-architect-ok." +pi -p --approve --mode json --session-dir .pi/e2e-sessions --tools read,grep,find,ls -- "/skill:create-verification-skill Read the installed skill before answering. Do not create files or run an app. Reply exactly mstack-create-verification-skill-ok." ``` Observed output: @@ -21,7 +22,10 @@ mstack-architect-ok mstack-create-verification-skill-ok ``` -The run proves skill discovery and invocation through pi. It does not claim -that `create-verification-skill` drove an application, because this smoke -workspace has no application to launch. - +Each JSONL session contains a user `message_start` event whose text includes the +resolved `` block, +followed by the marker in the assistant `message_end` event. The run proves +project skill discovery and invocation through pi. The marker prompts exercise +loading only. They do not claim that the skills completed their full workflows. +In particular, `create-verification-skill` did not drive an application because +this smoke workspace has no application to launch. diff --git a/scripts/install.test.mjs b/scripts/install.test.mjs index 6bf526b..e5cb10d 100644 --- a/scripts/install.test.mjs +++ b/scripts/install.test.mjs @@ -160,10 +160,9 @@ test("installs harness-specific frontmatter and preserves conflicts", () => { assert.doesNotMatch(codex, /^compatibility:/m); assert.match(claude, /^compatibility:/m); assert.doesNotMatch(claude, /^metadata:/m); - assert.doesNotMatch(claude, /The included logger requires/i); for (const adapted of [opencode, pi]) { assert.match(adapted, /^metadata:/m); - assert.match(adapted, /^ requirements:/m); + assert.match(adapted, /^ requirements: Node\.js 18 or newer for scripts\/log\.mjs$/m); assert.doesNotMatch(adapted, /^compatibility:/m); }