From 0ee94abca7dde8356709d712b2dbf735b029f2b8 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Mon, 13 Jul 2026 14:54:03 -0500 Subject: docs(runtime): skill parity resolves to one bootstrap resolution rule All 29 skill and command bodies are markdown, so a single sentence in the future non-Claude entry file (a /name reference resolves to the skill or command file, read and follow it) carries the whole library. Auto-invocation degrades to by-name, which the publish flow already uses. flush stays Claude-only, owned by the session-plumbing child. --- .../design/2026-07-13-runtime-portability-inventories.org | 15 +++++++++++++++ todo.org | 4 ++-- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/design/2026-07-13-runtime-portability-inventories.org b/docs/design/2026-07-13-runtime-portability-inventories.org index 98fe74d..e04f9cf 100644 --- a/docs/design/2026-07-13-runtime-portability-inventories.org +++ b/docs/design/2026-07-13-runtime-portability-inventories.org @@ -48,6 +48,21 @@ One wording gap: knowledge-base.md's "Capture, then promote" section names harne Verdict: no build. One approved sentence in knowledge-base.md closes it. +* Skill and command parity + +What rulesets ships: 11 skills (SKILL.md, model-invokable — add-tests, debug, five-whys, flush, frontend-design, pairwise-tests, playwright-js, playwright-py, review-code, root-cause-trace, voice) and 18 commands (plain .md prompts under =.claude/commands/=, user-invoked). Every body is markdown instructions; nothing executable lives in the registration layer. + +The load-bearing observation: a =/name= reference is just a pointer to a file on disk. Any harness that reads files can execute all 29 artifacts through one resolution rule in its bootstrap entry file: "a skill or command reference (=/voice=, =/review-code=, =/brainstorm=) resolves to =~/.claude/skills//SKILL.md= or =~/.claude/commands/.md= — read the file and follow it." That single sentence, emitted by the instruction-bootstrap install target, makes the whole library portable with zero per-skill work. commits.md's existing "/voice unavailable — walk the patterns inline" fallback generalizes the same way. + +What that rule does not carry: + +- Auto-invocation. Claude Code triggers skills from their descriptions; other harnesses won't. The high-value auto-triggers (voice and review-code inside the publish flow) don't actually need it — commits.md invokes them by name at fixed flow points, and the resolution rule covers a by-name invocation. The convenience triggers (debug, frontend-design firing on topic match) degrade to on-request. Acceptable. +- Native slash registration. Codex-style harnesses have their own custom-prompt mechanism; the 18 commands could also be registered there for ergonomics (an optional install nicety, not a requirement — the resolution rule already works). +- flush. Its mechanics are Claude Code's (/clear, the self-inject resume hook). Explicitly not ported; the session-plumbing child owns that surface. +- Harness built-ins (code-review ultra, plan mode, artifacts). Not rulesets' to port; flows that name them need per-runtime alternatives or graceful absence, same as today when they're unavailable. + +Verdict: no per-skill porting matrix needed. One resolution sentence in the bootstrap entry file (instruction-bootstrap child), optional native registration as an install nicety, flush explicitly excluded. + * Decisions for Craig All four approved by Craig, 2026-07-13: diff --git a/todo.org b/todo.org index b7cb19c..2ad3709 100644 --- a/todo.org +++ b/todo.org @@ -263,8 +263,8 @@ Craig asked what's left to run ChatGPT or a local LLM as the agent. Assessment: *** TODO Instruction bootstrap per runtime An install target that emits the non-Claude entry file (=AGENTS.md= for Codex-style agents; assembled system prompt for a local harness) pointing at =protocols.org= and the agent-neutral rules. Resolves the spec's "generic instruction-file strategy" blocker. Overlaps the shared-source thread of the =Multiple agent-source improvements= task (line ~150) — reconcile rather than build twice. -*** TODO Skill parity across runtimes -The user-invoked skills (voice, review-code, flush, …) are Claude Code registrations wrapping portable markdown prompts. Decide per skill: re-register in the target harness's custom-command system, or fold into =.ai/workflows/= (already runtime-neutral). Model-invoked skills need a per-harness answer or graceful absence (commits.md already defines the /voice-unavailable fallback pattern). +*** 2026-07-13 Mon @ 14:52:38 -0500 Skill parity resolved — one resolution rule, no per-skill matrix +Analysis in [[file:docs/design/2026-07-13-runtime-portability-inventories.org]] (Skill and command parity section). All 29 artifacts (11 skills + 18 commands) are markdown bodies; a single resolution sentence in the bootstrap entry file ("a /name reference resolves to the skill/command file — read and follow it") makes the library portable to any file-reading harness. Auto-invocation degrades to by-name invocation (the publish flow already invokes by name), native slash registration is an optional install nicety, flush is explicitly excluded (session-plumbing child owns it). Folds into the instruction-bootstrap child's build. *** 2026-07-13 Mon @ 13:34:17 -0500 Hook parity inventoried — only two hooks carry real porting work Full mapping in [[file:docs/design/2026-07-13-runtime-portability-inventories.org]]. AskUserQuestion deny is moot off Claude (no popup tool to deny); PostToolUse validators survive via the bundles' git pre-commit hooks; clear-resume folds into the session-plumbing child; session-title is cosmetic. Real gaps: PreCompact priority-save (prose downgrade) and Stop wrap-teardown (Codex notify / manual elsewhere) — decisions in the VERIFY below. -- cgit v1.2.3