CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.7.0 - 2026-07-03

Added

• New rule in skills/ratatoskr/SKILL.md ### Question discipline: internal/mechanical decisions are the agent's, never the user's. Two paragraphs — "Whose decision is it?" and "'You need my sign-off' is not 'ask a technical question' — but it is still a sign-off." The only decisions put to the user are product decisions (what a person using the product sees, does, or experiences); everything about how the work is built — where a rule lives, which internal structure holds it, one internal shape versus another, which of several equally-fine methods to use — is the agent's to settle with a sensible choice, even when there is no obvious default. Pre-send test made explicit: could a non-technical person answer this from everyday, real-world understanding of the product alone? — if answering it would take engineering knowledge, it is not their decision. Corollary for the case that motivated the rule: when a repo policy, protected area, or approval step requires the user's explicit go-ahead before an internal change, the agent still owns which internal option to use but must not skip or quietly bypass the required yes — it asks for that yes purely as the real-world consequence (e.g. "add a safeguard so the brand look can't be quietly changed in one corner of the app later — good?"), never as a menu of internal options. Origin: a real incident where an agent converted "consent required for an internal change" into a machinery question a non-technical product owner could not answer. Lab-validated (.lab/, untracked, researcher workflow, subagent battery reproducing the incident): the no-internal-offload score on the two failing scenarios rose from ~3.8/10 to ~9.3/10 (primary composite 7.65 → 9.33), while the plain-language axis, a genuine-product-fork control (which must still be asked), and the never-speak-in-code / no-estimates / no-ceremony guards all held with zero verified leaks. The fix holds both edges: it stops offloading the mechanism and stops the opposite failure of silently skipping a genuinely-required sign-off. Subtractive of nothing; +24 lines, one block. A reinforcement variant (matching Red-flags + Common-mistakes rows) measured at parity with no lift and was left out.

0.6.0 - 2026-06-26

Added

• Plugin-bundled session-start activation hook for every platform we integrate with (Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, Cursor) so the discipline is applied from the very first turn of every session — automatically, without the agent asking or debating whether to use it, and without per-user setup. The hook fires at session start on every source (startup / resume / clear / compact, or each platform's equivalent) — so the rule is also re-asserted right after a context compaction, where it is otherwise most likely to fade — and injects a short activation instruction. Wiring, verified against each platform's current official docs: one shared script, hooks/ratatoskr-session-start.sh, selects the host's stdout envelope by a $1 argument (claude/codex → hookSpecificOutput.additionalContext, copilot → flat additionalContext kept under the 10 KB cap, cursor → snake_case additional_context). hooks/hooks.json provides the Claude Code SessionStart hook and is also auto-discovered by Codex (which shares Claude's schema and sets CLAUDE_PLUGIN_ROOT for compatibility, so it needs no file of its own). hooks/copilot-hooks.json and hooks/cursor-hooks.json (both {"version":1,"hooks":{"sessionStart":[…]}}) are bundled via a hooks field added to the Copilot marketplace plugin entry (./hooks/copilot-hooks.json) and the Cursor manifest (hooks/cursor-hooks.json). The activation message lives once, in the script, and carries no behaviour of its own: it only activates the skill; every rule remains self-contained in skills/ratatoskr/SKILL.md. Caveats to verify on installed versions: Copilot ${PLUGIN_ROOT} substitution inside hook command strings is documented for plugin paths but not explicitly for hook strings; Cursor documents no plugin-root variable, so the command uses a path relative to the plugin root; and Codex issue #17331 questions whether plugin-bundled hooks load on all versions.

Changed

• Recast skills/ratatoskr/SKILL.md from a mixed communication-plus-workflow skill into a pure communication layer. Ratatoskr now governs only what the agent says to the user and how it phrases it — plain language (never speak in code), an honest register, disciplined questions, no time/effort estimates, no process theater — and no longer dictates how the work is sequenced or run. This removes the collision with workflow skills (e.g. Superpowers) that own their own brainstorm → spec → plan → implement flow: the communication axis and the workflow axis now compose instead of competing. The former mandatory read-back ("What I think you're asking for:") and plain-language close are kept as optional utterance templates — clean shapes for phrasing a restatement of intent or a report of a result — no longer required steps tied to a phase. Destructive-operation safety is reduced to a single plain-language floor — name the irreversible effect in concrete terms and get one clear yes — replacing the two-distinct-turns ritual and the four-box pre-execution checklist. The frontmatter description and the former ## When to use / ## When NOT to use sections were rewritten to match: a standing communication discipline in effect on every user-facing turn regardless of the methodology driving the work, with the previous change-request / destructive / compliance trigger language removed so the skill is no longer pattern-matched as a methodology. Subtractive edit — no new rules or philosophy; the kept sections retain their original voice, tables, and examples. Lab-validated (.lab/, untracked): trigger A/B parity at ceiling, the kept rules (never-speak-in-code, no-estimates, no-ceremony) hold under adversarial pressure, and the new single-yes floor passes 5/5. The one jargon family that still leaked under code-baiting — delete/purge vocabulary, the skill's flagship destructive scenario — is now covered by an added row in the never-speak-in-code table.
• Rewrote the communication core of skills/ratatoskr/SKILL.md from a plain-language banlist (framed as a "floor for non-technical users" with a "translate the jargon on first use" escape) into a hard, universal never-speak-in-code rule. The real intent: you can hand a repository to a product or business person and give them an agent that talks to them clearly. People never read the code the agent writes — they may not know the language or how to program at all — so the agent must never name a code or repository artifact (file, function, field, table, "the lock file / schema / migration") and never use engineering jargon, to any user, including one who says they are technical or who introduces code terms first. It speaks only in what a person using the product sees, does, or experiences. Added: a dedicated "Handling code-bait" section (when the user pulls toward code — "walk me through the schema", "just tell me the fields", "I write code every day" — acknowledge the goal, answer in product outcomes and trade-offs, hold the line; the agent still does all the technical work, it just never narrates it in code); a top-level pre-send "Required: never name the code" four-box gate (twin to the no-estimates gate, so the rule survives long sessions instead of decaying); "never speak in code" elevated to a co-equal Core principle; plus an updated frontmatter description and Red-flag entries. De-duplicated the destructive-command checklist to one authoritative copy with a pointer. The hard guarantees (two-gate destructive confirmation, no time/effort estimates) are preserved unchanged.
• Validated empirically before shipping (researcher workflow in .lab/, untracked) against an objective leak-count metric chosen for noise-robustness. A code-baiting battery — a self-described-technical user demanding code mechanics plus a destructive wipe; a non-technical product owner with a destructive request and deadline pressure; an after-the-work status report — scored by 3 blind evaluators that list and count every reference to a named code artifact or piece of engineering jargon. The rewrite took total leaks from a median of 38 (≈34 on the code-bait dialogue) to 0 across all three evaluators, with product-framing 9–10/10 and every destructive / no-estimate guarantee still PASS. An earlier "consequence-first" variant — which led with the product consequence but still allowed jargon as supporting detail — was measured and rejected: it leaked heavily under this stricter bar. Archived in .lab/archives/.
• Slimmed the frontmatter description of skills/ratatoskr/SKILL.md to a trigger-only form (frontmatter 1404 → 868 chars, back under the 1024-char spec limit). The previous description restated the rules themselves (never-speak-in-code, no-estimates, no-ceremony, question discipline); per skill-authoring guidance a description that summarizes the workflow becomes a shortcut the agent follows instead of reading the body. It now states only when to load (every user-facing turn, including the three carve-outs) and ends with "Read the skill body for the actual rules; do not act on this description alone." The always-on framing and per-carve-out counters are preserved.
• De-duplicated the skill body. The four hoisted top-level ## Required: sections (opening, destructive checklist, no-estimates, never-name-code) restated rules whose full text also lived in their natural homes — the same drift trap as the old destructive checklist. They are replaced by one compact ## Non-negotiables digest (one line per hard rule + a pointer), so each rule now lives once: the opening emphasis folded into Phase B, the full destructive four-box checklist into the Second confirmation gate, and no-estimates / never-speak-in-code remain in the Cross-cutting rules. Body went 827 → 753 lines with no rule content lost. (Supersedes the "top-level pre-send Required: never name the code four-box gate" noted above.)
• Reduced the SessionStart hook (hooks/ratatoskr-session-start.sh) to activation-only: removed the never-speak-in-code paragraph it had been duplicating from the body, restoring the hook's stated property of carrying no rules of its own. It now only activates the skill and points at the body for the rules.
• Validated this consolidation empirically before shipping (researcher A/B in .lab/, untracked): baseline (HEAD) vs slimmed treatment. Carve-out trigger rate held at 3/3 in both arms; a code-bait / estimate-pressure / destructive-wipe compliance battery showed parity (0 code leaks, 0 estimate leaks, two-gate held without execution in both arms). Adopted on parity plus the objective wins (spec-limit compliance, drift removal, shorter body).

Removed

• The five-phase workflow backbone of skills/ratatoskr/SKILL.md — the methodology axis that belongs to a workflow skill, not a communication one. Cut: Phase A "silent research" as a required step (along with the existing-feature-discovery and disambiguation-ordering rules); the A–E phase sequence framing ("the five phases", "terminal state", and the engage / don't-engage "five-phase ceremony" logic); the Phase B/C approval gate that halted work until explicit confirmation; the second confirmation gate for permanent / compliance operations (the two-distinct-exchanges sequence plus the four-box pre-execution checklist and its pressure-handling script); the Phase D "implementation within locked scope" rules (mid-flight material discovery, scope-creep / "while you're in there" handling, adjacent-improvement parking); and the mandate to render a close after every code modification. The communication content these sections carried — plain language, honesty, the question shape, a minimal irreversible-action floor, and the read-back / close formats — is preserved in the kept sections.

0.5.0 - 2026-06-07

Changed

• Rewrote the frontmatter description of skills/ratatoskr/SKILL.md so the skill is always-on: it now states it loads on every user-facing turn without exception, framed as a standing communication discipline rather than an activity-specific tool. The former trailing "Skip only when…" clause — naming a complete written spec for verbatim implementation, a pure internal refactor, and a tightly-scoped locked fix — acted as a skip hook: a skill-selector pattern-matches those words and drops the skill entirely. It is replaced with explicit per-case counters ("load it even when a written spec says implement verbatim, even for a pure internal rename, and even for an already-locked fix — the skill itself decides how light to keep the turn"). Those three cases now set aside only the heavier five-phase ceremony, never the skill. No change to the skill body or mechanics; consistent with the existing ## When NOT to use section (cross-cutting rules always apply; only the ceremony is skipped).
• Validated empirically before shipping (researcher workflow in .lab/, untracked). Skill-selection subagents over a 13-message battery (10 product turns including the 3 carve-outs + 3 edge turns): the rewrite took the verbatim-spec turn from 0/3 → 3/3 triggering in a clean A/B, with every product turn triggering. Surfaced a methodology gotcha now recorded: Agent-tool subagents inherit the live session skill registry (the previously-committed description), so mid-session A/B runs are confounded by the old "Skip only when…" text and must be isolated with a neutral skill name. The clean (isolated) result predicts post-commit behavior, since a new session registers the new text at startup. See .lab/archives/validate-description-trigger/summary.md.

0.4.0 - 2026-06-06

Added

• New cross-cutting rule "No ceremony, no machinery names" in skills/ratatoskr/SKILL.md. The agent must never surface the internal machinery in a user-facing turn — no skill / plugin / tool / mode / protocol names (its own or any other), no internal phase or step labels ("Phase B", "the second gate", "the five-phase ceremony"), and no ceremonial self-narration ("I'm invoking…", "per my skill…", "entering research mode"). It describes only what is actually happening, in plain words, and does the internal work silently. Includes a wrong/right translation table, an applies-even-when list (technical user, user asks which tool, a convention elsewhere says to announce the skill), and cross-references to the plain-language and stake-recognition rules. Applies to every user-facing turn regardless of audience. Reinforced by an entry in ## When to use, the frontmatter description, a Red flag bullet, and a Common mistakes row.

Changed

• Renamed the skill liaison → ratatoskr as part of unifying the Yggdrasil family (the world-tree + its keepers). Updated the skill identifier (skills/ratatoskr/SKILL.md name:), the skill directory, plugin.json/marketplace.json names, and the install command to ratatoskr@ratatoskr-marketplace; rebranded README.md around the courier metaphor and added a shared "Part of the Yggdrasil family" block. No behavioral change to the skill body (only name: + the H1 title changed). The GitHub repo rename LiaisonSkill → RatatoskrSkill and push are pending.
• Rewrote README.md and the public-facing marketing copy (.claude-plugin/plugin.json and .claude-plugin/marketplace.json descriptions + keywords) for ease of adoption and shareability: a stakes-first hook, install commands above the fold, an accurate disambiguation-then-proposal demo, a "the features are the bans" table, an ecosystem-positioning table (user→intent / intent→code / code→architecture), a collapsible FAQ, and an honest "what it doesn't claim" section. Corrected the install instructions to use /reload-plugins (the previously documented /plugin reload is not a real command) and documented the marketplace-update upgrade path. No change to skill mechanics — skills/liaison/SKILL.md is untouched.
• Validated empirically before shipping (researcher workflow in .lab/, untracked): research/audit → four strategy-diverse README drafts → blind multi-evaluator scoring → synthesis with grafts → adversarial accuracy/credibility/friction critics (29 defects) → fix. A decisive same-panel blind head-to-head (5 evaluators, randomized order) preferred the new README 5/5 over baseline, composite +2.1 (8.6 vs 6.5). See .lab/summary.md.

0.3.0 - 2026-05-30

Changed

• Restructured the Question discipline cross-cutting rule in skills/liaison/SKILL.md into an explicit clarifying-question protocol: one decision per clarifying turn; verify the premise before asking and re-pose the question if a stated fact later proves false; a fixed shape for a real fork (Context / Question / Options / Recommended default), rendered as an explicit list, with a "keep simple questions simple" allowance so a binary or low-stakes disambiguation can still use a one-line closed question + veto; and an explicit carve-out that the protocol governs clarifying QUESTIONS only and never overrides the Phase B read-back (which still bundles the whole scoped decision set into one confirm/veto). Preserves the prior rule's intent — ask only real forks, never leading, past-behavior / present-pain framing, state-the-default-and-offer-a-veto. The prior ≤5-question ceiling is dropped: real forks are not capped (a genuinely multi-fork task may legitimately span many clarifying turns), with only a floor retained (≥1 clarifying turn on a destructive or ambiguous ask) and a guard against padding with non-real questions. Applies on every user-facing turn, including pure question / explanation turns.
• Validated empirically before shipping (A/B harness in .lab/, untracked): five candidate skill variants × scripted dialogues on a generic-SaaS fixture × Sonnet ×5, each transcript scored by 3 blind Haiku evaluators on a 5-dimension rubric (question quality, plain-language, proportionality, gate integrity, no-estimates). The structured format landed within measurement noise of baseline on the composite (no regression) with a small directional gain on proportionality. Two further proposals were measured and dropped: an "autonomous mode" clause (it measurably weakened the destructive-op two-gate) and an audience-based relaxation of the plain-language rule (its benefit could not be demonstrated, and it added a judgment call to a deliberately bright-line rule). See .lab/summary.md.

0.2.0 - 2026-05-26

Changed

• Broadened skill scope in skills/liaison/SKILL.md. The skill now engages on every user-facing turn about the codebase or product — both change requests (which run the full five-phase ceremony) AND pure questions / explanations / translations between technical and user-visible terms (which run cross-cutting rules only, no Phase B / C / E ceremony). Description, ## When to use, and ## When NOT to use sections updated to reflect this. The cross-cutting rules (Plain-language discipline, No time or effort estimates, Question discipline) apply to every user-facing turn regardless of whether a change is happening; the five-phase ceremony is what's skipped when no change is involved, not the skill itself. The previous "investigative / diagnostic work" exclusion is removed accordingly.

Added

• New top-level "Required: no time or effort estimates" section in skills/liaison/SKILL.md, mirroring the destructive-op gate's structure: a 4-box checklist (abstract pattern descriptions to avoid copy-targets) that the agent runs against every draft before sending; an applies-even-when list naming authority claims, time pressure, sunk cost, and ballpark framings as non-overrides; a STOP anchor for "this person clearly knows what they're doing, so a number from me is safe" reasoning; and a cross-reference to the detailed mechanics in Cross-cutting rules. Forbids producing any time, duration, or calendar claim in any user-facing turn — including the agent's own meta-work duration, stakeholder messaging the agent crafts for the user to relay, and hypothetical example estimates the agent constructs as templates.
• Detailed cross-cutting rule "No time or effort estimates" in the same file. Explains the asymmetric harm (inflated estimate kills viable work as "too expensive"; deflated estimate creates downstream commitments the work cannot meet) and grounds the rule in the actual cause: numbers come from training data of human-team estimates carrying overheads agents do not have. Names the three specific failure modes that leak under pressure with explicit phrasing forbidden for each. Provides a literal pressure-handling script (modelled on the destructive-op gate's script) the agent uses verbatim under repeated estimate pressure. Carves out what is still allowed (reversibility vocabulary; product feature parameters described abstractly; dollar / API-call cost with named units; factual measurements the agent actually performed; time-boxes the user proposes). Reinforced by a Red flag bullet and a Common mistakes row.
• Stress-test harness for the rule in .lab/ (untracked). Battery of 11 multi-turn pressure scenarios (in .lab/workspace/scenarios.json), LLM-judge compliance metric (Haiku), multi-evaluator refusal-quality metric (3 Haiku evaluators per response, median). Multi-baseline measurement protocol (≥3 runs per model per experiment) to distinguish signal from per-run noise (~20pt variance per Sonnet baseline). Validated final rule form across 5 Sonnet + 3 Opus runs: aggregate compliance 0.79 (Sonnet mean 0.70 / Opus mean 0.93, with 2 of 3 Opus runs hitting perfect 1.00) vs initial-rule baseline 0.62 (Sonnet 0.60 / Opus 0.70) — improvement of +17% Sonnet / +33% Opus on the same battery. See .lab/summary.md for the eight-experiment journey, the methodology lessons, and the one remaining persistent edge case (Sonnet on multi-turn ballpark pressure with embedded self-meta-work duration) that text-only iteration could not fully close.

0.1.0 - 2026-05-25

Added

• Initial release of the liaison skill (skills/liaison/SKILL.md). Five-phase dialogue protocol — silent research → structured proposal → halt for confirmation → implementation within locked scope → plain-language close — for serving as the sole interface between a user (technical or not) and the codebase on user-visible work. Mandatory "What I think you're asking for:" opening. Required two-gate confirmation for permanent or compliance-relevant operations (separate distinct exchanges, never a single combined warning+ask). Plain-language vocabulary discipline with explicit forbidden-jargon list. User-executable verification steps in the close. Pressure-handling rules for "just do it" requests on destructive operations.
• Claude Code plugin scaffolding: .claude-plugin/plugin.json (manifest) and .claude-plugin/marketplace.json (single-plugin marketplace listing). Installable via /plugin marketplace add krzysztofdudek/LiaisonSkill then /plugin install liaison@liaison-marketplace. Single-file drop-in works for any agent that reads markdown skills.
• MIT license, README, CLAUDE.md with versioning workflow.