From 63fa16e83b59f29c8ffc81ee675f2ca46f857457 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 15 Oct 2026 09:21:54 +0000 Subject: [PATCH] feat: add retro flow and defer craft review to project style Add a user-owned retro flow that turns session, branch, or pull request friction into checks and instruction changes. Teach respond to triage automated reviewer findings, settle observable forks by experiment, explain measured numbers, and write the failing test first in execute. The craft lens now applies the project's style authority before its own checklist. --- .claude-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .plugin/plugin.json | 2 +- CHANGELOG.md | 14 ++++++++++ README.md | 5 +++- behavior/professional-engineering.md | 4 +-- eval/scenarios/negative.yaml | 9 ++++++ skills/execute/SKILL.md | 11 ++++---- skills/respond/SKILL.md | 10 +++++++ skills/retro/SKILL.md | 41 ++++++++++++++++++++++++++++ skills/retro/agents/openai.yaml | 2 ++ skills/review/lens-craft.md | 7 +++-- test/meridian-consistency.test.mjs | 2 +- 13 files changed, 97 insertions(+), 14 deletions(-) create mode 100644 skills/retro/SKILL.md create mode 100644 skills/retro/agents/openai.yaml diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b6625d7..4392727 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "meridian", "description": "Professional engineering discipline with user-owned workflows and model-specific corrections.", - "version": "0.13.0", + "version": "0.14.0", "author": { "name": "KodingDev" }, diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index c9ab6f4..c4595ea 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "meridian", "description": "Professional engineering discipline with user-owned workflows and model-specific corrections.", - "version": "0.13.0", + "version": "0.14.0", "author": { "name": "KodingDev" }, diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 1ea5079..80e547b 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "meridian", - "version": "0.13.0", + "version": "0.14.0", "hooks": "./hooks/hooks-copilot.json" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 179d34b..7fdb1bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,20 @@ All notable changes to Meridian are recorded here. The format follows to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). History before 0.11.0 lives in the git log. +## [0.14.0] - 2026-10-15 + +### Added + +- `retro`, a user-owned flow that reviews a session, branch, or pull request for friction and proposes the strongest durable fix for each finding: a failing check first, then a deleted or rewritten instruction, then new text. It is report-only unless the user asks for the changes. +- `respond` triages automated reviewer findings as claims: fix when a realistic failure path exists and the fix is in proportion, dismiss with the traced path otherwise, and ask the user before dismissing a security finding. +- The professional standard settles observable forks by experiment instead of asking the user, and requires a measured number to be explained before it is reported or acted on. +- `execute` writes the failing test first when a task adds or fixes behavior and a test seam exists. + +### Changed + +- The craft review lens defers to the project's style authority: project instructions and any installed style skill. Its checklist covers only what that authority leaves open. The one-call-helper and docstring lines no longer contradict style guides that require doc comments on exports or allow a named extraction. +- The README documents removing the 0.6-era `claude-plugins` install, whose forced routing hook still loads alongside a current install. + ## [0.13.0] - 2026-07-25 ### Added diff --git a/README.md b/README.md index 7f103ba..cfdc015 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ These run only when you invoke them. One flow never silently enrolls you in anot | `execute` | Implement an approved spec or clear scope with proportionate verification | | `review` | Perform a focused, report-only code review | | `document` | Capture requested durable engineering knowledge | +| `retro` | Turn friction from a session, branch, or pull request into checks and instruction changes | | `auto` | Grant elevated autonomy for reversible, in-scope work | Invoking a flow authorizes its ordinary documented behavior. Separate approval is still required for destructive operations, unrequested external effects, material scope expansion, and unresolved high-cost choices. @@ -90,6 +91,8 @@ The state base is host-specific, such as `CODEX_HOME` for Codex. GitHub Copilot /plugin install meridian@meridian ``` +Meridian 0.6 and earlier shipped from the `KodingDev/claude-plugins` marketplace, with a session hook that forced the `meridian` routing skill on every request. Remove that install before you add this one, or both load. `/plugin` lists installed plugins with their marketplace. If your organization syncs plugins for you, update the synced source to this repository. + ### Cursor Install Meridian from the Cursor plugin marketplace, or enable third-party skills and install the Claude plugin bundle. @@ -100,7 +103,7 @@ Install the same plugin bundle through the host's plugin support. Meridian ships ## Project policy -Use repository instructions for requirements that vary by customer or environment. The included `templates/CLAUDE.md` provides optional headings for security and compliance, required verification, deployment and rollback, repository artifacts, and allowed tools. Meridian intentionally ships no AWS-, employer-, customer-, or Stella-specific defaults. +Use repository instructions for requirements that vary by customer or environment. The included `templates/CLAUDE.md` provides optional headings for security and compliance, required verification, deployment and rollback, repository artifacts, and allowed tools. Code style comes from the project too. The craft review lens applies the project's instructions and any installed style skill first, and uses its own checklist only where they are silent. Meridian intentionally ships no AWS-, employer-, customer-, or Stella-specific defaults. ## Development diff --git a/behavior/professional-engineering.md b/behavior/professional-engineering.md index 29cf452..eb32bc9 100644 --- a/behavior/professional-engineering.md +++ b/behavior/professional-engineering.md @@ -2,7 +2,7 @@ ## User agency and scope -The user owns goals, priorities, taste, acceptable tradeoffs, and workflow selection. Treat explicit instructions as authority over intent and scope while evaluating technical claims independently. Make reversible implementation decisions without ceremony. Ask before destructive actions, unrequested external effects, material scope expansion, or a genuinely high-cost fork the user must decide. +The user owns goals, priorities, taste, acceptable tradeoffs, and workflow selection. Treat explicit instructions as authority over intent and scope while evaluating technical claims independently. Make reversible implementation decisions without ceremony. Ask before destructive actions, unrequested external effects, material scope expansion, or a genuinely high-cost fork the user must decide. Before you ask about a fork, check whether running something could settle it: behavior, output, timing, layout, or whether a check catches the case. If it can, run the smallest experiment and decide from the result. Keep questions for product, taste, and priority calls that no experiment settles. ## Grounding and judgment @@ -10,7 +10,7 @@ Read the repository, instructions, current documentation, runtime evidence, and ## Correctness and evidence -Deliver the requested outcome and verify it through the highest practical real seam. Claims such as fixed, working, complete, or verified require observed evidence. When full verification is unavailable, state what was tested and what remains uncertain. Address causes rather than accumulating symptom patches. +Deliver the requested outcome and verify it through the highest practical real seam. Claims such as fixed, working, complete, or verified require observed evidence. When full verification is unavailable, state what was tested and what remains uncertain. Address causes rather than accumulating symptom patches. Before you report or act on a number you measured, such as a speedup, a regression, a latency, or an eval score, name what limits it and rule out that it measured something other than the change. ## Security and customer environments diff --git a/eval/scenarios/negative.yaml b/eval/scenarios/negative.yaml index 4667ee0..348c577 100644 --- a/eval/scenarios/negative.yaml +++ b/eval/scenarios/negative.yaml @@ -61,3 +61,12 @@ const skillCalls = context.providerResponse?.metadata?.skillCalls || []; return skillCalls.length === 0; description: "simple question uses no skill" + +- vars: + prompt: "That took longer than it should have. What went wrong?" + assert: + - type: javascript + value: | + const skillCalls = context.providerResponse?.metadata?.skillCalls || []; + return skillCalls.length === 0; + description: "reflecting on a session does not bypass manual-only retro" diff --git a/skills/execute/SKILL.md b/skills/execute/SKILL.md index f484622..22da482 100644 --- a/skills/execute/SKILL.md +++ b/skills/execute/SKILL.md @@ -31,11 +31,12 @@ Break multi-part work into dependency-ordered tasks. Keep a small change inline. For each task: 1. Search for existing interfaces, utilities, tests, and conventions before adding competing logic. -2. Implement the smallest durable change that satisfies the requirement. -3. Exercise the highest practical real seam: focused tests, typecheck, build, CLI, service, or browser behavior as appropriate. -4. If behavior fails unexpectedly, use `meridian:debug` rather than stacking speculative patches. -5. Check the diff against scope and the spec's User Constraints. -6. If a spec exists, append a concise Progress Log entry containing the task outcome, verification, deviations, and open concerns that a future agent could not recover from the diff. +2. When the task adds or fixes behavior and a test seam exists, write the failing test first and watch it fail for the expected reason. Take one behavior at a time: red, green, then refactor while the tests stay green. +3. Implement the smallest durable change that satisfies the requirement. +4. Exercise the highest practical real seam: focused tests, typecheck, build, CLI, service, or browser behavior as appropriate. +5. If behavior fails unexpectedly, use `meridian:debug` rather than stacking speculative patches. +6. Check the diff against scope and the spec's User Constraints. +7. If a spec exists, append a concise Progress Log entry containing the task outcome, verification, deviations, and open concerns that a future agent could not recover from the diff. ### 4. Finish diff --git a/skills/respond/SKILL.md b/skills/respond/SKILL.md index fd0e6d2..02b4a46 100644 --- a/skills/respond/SKILL.md +++ b/skills/respond/SKILL.md @@ -16,4 +16,14 @@ User intent, priorities, and accepted tradeoffs are authoritative. Technical exp 5. Push back concisely when a suggestion is technically wrong, breaks existing behavior, conflicts with an accepted decision, or expands scope without value. 6. Report what changed, what was declined, and the evidence supporting either result. +## Automated reviewers + +Review bots and automated security reviews find real defects. They also file non-issues and restate style preferences as defects. Treat each finding as a claim: + +- **Fix** when you can trace a realistic path from a real caller or input to the failure, and the fix costs less than what it prevents. +- **Dismiss** when the path is impossible or far-fetched, or the fix adds more code than it protects. Reply with the path you traced and the reason. +- **Ask** when the finding is about security or data exposure and you would dismiss it. The user decides. + +A bot's severity label is not evidence. Repeated findings on the same area mean the shape of the code is wrong; fix the cause, not each finding. + Avoid performative agreement, but ordinary human acknowledgment is fine. If your earlier technical conclusion was wrong, correct it directly without defensive explanation. diff --git a/skills/retro/SKILL.md b/skills/retro/SKILL.md new file mode 100644 index 0000000..5631535 --- /dev/null +++ b/skills/retro/SKILL.md @@ -0,0 +1,41 @@ +--- +name: retro +description: Review a finished session, branch, or pull request for friction, and turn each lesson into the strongest durable fix. +disable-model-invocation: true +argument-hint: "[session, branch, PR, or time range]" +--- + +# Retro + +Find what made the work slower or worse than it had to be, and fix the cause where the next session will meet it. The output is a short list of changes to checks, instructions, and skills. It is not a diary. + +Invocation authorizes a report-only retro. Apply the proposed changes only when the user asks. + +## Scope + +Review what the user names: this session, a branch, a pull request, or a time range. If nothing is named, review this session and the branch it worked on. + +## Process + +1. **Collect the evidence.** Read the session's corrections and redirections from the user, the commits and their diff, review comments, CI failures, and reverted or rewritten work. Each finding cites one of these. +2. **List the friction.** A finding is a place where work was redone, a user corrected the agent, a reviewer caught a defect, a check failed late, or effort went into a path that was abandoned. Skip friction that came from a one-off fact no rule could have supplied. +3. **Name the cause.** For each finding, pick one: + - a missing check that would have caught it; + - a project instruction that is missing, wrong, or ignored; + - a skill rule that is missing, wrong, or conflicts with another; + - a tool or environment gap; + - a gap in the agent's own judgment that no durable change addresses. +4. **Choose the strongest fix.** Prefer, in order: + 1. a check that fails: a lint rule, a test, a type, a hook, or a script; + 2. a deleted or rewritten instruction, when an existing instruction caused the friction; + 3. one new line in project instructions; + 4. a change to a skill. + A lesson that already exists as text and was still missed needs a check, not more text. A finding with no durable fix is reported and dropped. +5. **Report.** Lead with the proposed changes, strongest first. For each, give the evidence, the cause, the exact file and change, and what it prevents. Then list the findings you dropped and why, in one line each. + +## Rules + +- Propose no more changes than the evidence supports. Three precise changes beat ten vague ones. +- A proposed instruction is one imperative sentence that a model can follow without the session's context. +- Session narrative stays in chat. Changes to the repository describe the rule, never the session that produced it. +- When a skill from outside this repository caused the friction, name the skill and the line, and propose the change to the user. Do not edit an installed copy. diff --git a/skills/retro/agents/openai.yaml b/skills/retro/agents/openai.yaml new file mode 100644 index 0000000..5b1f887 --- /dev/null +++ b/skills/retro/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/skills/review/lens-craft.md b/skills/review/lens-craft.md index 232e9b0..dec812e 100644 --- a/skills/review/lens-craft.md +++ b/skills/review/lens-craft.md @@ -6,6 +6,9 @@ Ask of every change: - Is there a "code judo" move — a reframing on the existing architecture that makes this dramatically simpler, not just tidier? - Could fewer concepts, branches, or layers carry the same behavior? +## Style authority +The project's own style is the bar for this lens. Before you apply the checklist below, read the project instructions and any style skill that the project or user has installed, such as `house-style` or `golden`. Where that authority covers a dimension, apply its rules and cite them. Where it conflicts with a line below, the authority wins. The checklist covers only the dimensions that the authority leaves open. + ## Code Reuse For each change, search for existing utilities and helpers that could replace newly written code — common locations are utility directories, shared modules, and files adjacent to the changed ones. - New function that duplicates existing functionality — suggest the existing function instead @@ -14,7 +17,7 @@ For each change, search for existing utilities and helpers that could replace ne ## Simplification - Code that can be deleted entirely -- Abstractions serving one call site (inline them) +- Abstractions serving one call site whose name adds nothing over the inline code (inline them) - Utility functions for one-time operations (delete them) - Premature configurability (YAGNI) - Nested ternaries (extract to early returns or lookups) @@ -42,7 +45,7 @@ Comments are the highest-signal tell. Judge every comment **added in the diff** - Decorative section dividers (`// ── Section ──`) - Changelog comments (git history exists) - Apology comments (`// Hack: ...`, `// TODO: refactor`) -- Multi-paragraph docstrings or comment blocks where one line of *why* would do +- Multi-paragraph comment blocks where one line of *why* would do. A doc comment on an export that states its contract is not slop. Then the non-comment slop: - Gratuitous intermediate variables diff --git a/test/meridian-consistency.test.mjs b/test/meridian-consistency.test.mjs index 50fba00..a7d8e12 100644 --- a/test/meridian-consistency.test.mjs +++ b/test/meridian-consistency.test.mjs @@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url"; import { dirname, join } from "node:path"; const ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); -const MANUAL_FLOWS = ["auto", "brainstorm", "document", "execute", "review", "sketch"]; +const MANUAL_FLOWS = ["auto", "brainstorm", "document", "execute", "retro", "review", "sketch"]; const MODEL_DISCIPLINES = ["commit", "debug", "delegate", "research", "respond", "triangulate"]; /** @param {string} rel */