diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d951eee..69cc4af 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": "Research-first workflows, ruthless code review, orchestrator-led reasoning, and opaque subagent isolation for the entire development lifecycle.", - "version": "0.11.2", + "version": "0.11.3", "author": { "name": "KodingDev" }, diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 79525df..347f30c 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": "Research-first workflows, ruthless code review, orchestrator-led reasoning, and opaque subagent isolation for the entire development lifecycle.", - "version": "0.11.2", + "version": "0.11.3", "author": { "name": "KodingDev" }, diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 32ae663..9a9302c 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "meridian", - "version": "0.11.2", + "version": "0.11.3", "hooks": "./hooks/hooks-copilot.json" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 2607315..1b83eaa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,64 @@ 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.11.3] - 2026-07-06 + +### Added + +- The output style grounds claims in the project's own artifacts, not just external docs: + read the existing code, spec, and canonical data before writing competing logic; cite + real measurements (settled invoices, logs, profiles) for cost/performance/architecture + decisions. A new operational-discipline section prefers a reusable script over repeated + one-off tool calls and reads state at its source instead of polling. +- The output style's voice rules add a calibrated-reporting register: once verification + is exhausted, remaining conclusions are presented as bets — observed facts separated + from inferences, confidence and blind spots named, each bet carrying what would prove + it wrong. +- `auto` gains autonomy stamina: the horizon for stepped-away work is honest readiness + ("I'm ready for you"), not elapsed time; before ending a turn, remaining verifiable + work means the turn is not over. Blockers must be earned — try another angle, dig + deeper, or dispatch a subagent before declaring one; a genuine fork is a decision only + the human can make (taste, money, irreversibility). +- `debug` requires instrumenting the real code path — logging added to the actual + executable run with real data, never one-off probe scripts or simulations — and holds + fixes to a root-cause bar: a fix must explain why the bug existed, or it is a + workaround, not a fix. +- `review`'s craft lens flags symptom patches: a guard, carve-out, or special case that + narrows a visible failure while the underlying cause remains, even when the diff + improves behavior. +- `execute` verification exercises the real flow with real data where a runtime surface + exists, not synthetic probes. +- `brainstorm` re-reads the user's provided material (request, plan, handoff, spec) in + full before asking any clarifying question. +- `delegate`'s model selection names the expensive failure — a wide fan-out at flagship + pricing doing mechanical work a small model does identically — and requires the + orchestrator to read the final synthesis itself: the conclusion is not delegable. + +### Changed + +- `respond` no longer treats user feedback as trusted-implement-after-understanding: + the user is trusted on intent and priorities, but suggestions are evaluated on + technical merits like anyone's, per the Challenge Protocol. +- The session orientation is the single routing authority. It absorbs the one line the + router skill carried that it lacked (visual regressions are bugs even when they + appeared one step ago in the same session) and closes with a statement of authority + instead of a pointer to the router skill. + +### Removed + +- The `meridian` router skill. Its content was a near-verbatim copy of the session + orientation, which is injected every session — so the "invoke for the full routing + reference" pointer never fired, and the two copies had already drifted in wording. + Skills that referenced "the meridian router" now reference the orientation's routing + table. +- The `## Integration` footers (Predecessors / Successors / May invoke) on every skill. + Routing is owned by the orientation, and each skill's body already names the skills it + invokes inline; the footers changed no behavior. +- `research`'s "HARD-GATE Rationale (Dual-Location Enforcement)" section — a maintainer + note, not an instruction to the model. The constraint it recorded still holds: the + skill's gate and the `meridian:research` agent's gate are duplicated intentionally + (caller contract vs. operative rule) and their wordings must stay aligned. + ## [0.11.2] - 2026-07-03 ### Added diff --git a/README.md b/README.md index 1bae748..91e1705 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Hard-won knowledge dies with the session. You debug something for two hours, nai | `commit` | Clean git commits, no AI attribution | | `document` | Human-readable docs from resolved work | -Three more compose with these rather than standing alone: `meridian` (the routing reference, for when it's unclear which skill fits), `triangulate` (a verification lens that grounds specific-value claims against their source), and `auto` (a modifier that runs any task autonomously when you step away). +Two more compose with these rather than standing alone: `triangulate` (a verification lens that grounds specific-value claims against their source) and `auto` (a modifier that runs any task autonomously when you step away). Routing lives in the session orientation injected at startup — there is no separate router skill. ## What gets installed diff --git a/hooks/context/orientation.md b/hooks/context/orientation.md index 6b55da1..e307023 100644 --- a/hooks/context/orientation.md +++ b/hooks/context/orientation.md @@ -26,7 +26,7 @@ For borderline calls, prefer `brainstorm` if the change needs more than one or t A user message during an active skill is not automatically a continuation of that skill. Re-classify each new message against the table above. -The dominant miss: a screenshot, or a terse failure reply — "still wrong" / "still the same" / "doesn't work" / "still broken" / "not fixed" / "nope", *including* one-word or image-only messages — arriving during `execute` or `sketch` is a `debug` signal, not a "keep executing" signal. The terseness is the tell: when a fix just shipped and the reply is a short dismissal, the fix didn't land. STOP the patch loop immediately — do not emit another speculative fix in the same turn. Pause the active skill, invoke `meridian:debug`, complete root-cause investigation, return once the bug is understood. (A UserPromptSubmit hook reinforces the unambiguous "still …" / "not fixed" phrasings, but the rule is yours to apply on screenshots and one-word rejections the hook can't safely match.) +The dominant miss: a screenshot, or a terse failure reply — "still wrong" / "still the same" / "doesn't work" / "still broken" / "not fixed" / "nope", *including* one-word or image-only messages — arriving during `execute` or `sketch` is a `debug` signal, not a "keep executing" signal. The terseness is the tell: when a fix just shipped and the reply is a short dismissal, the fix didn't land. STOP the patch loop immediately — do not emit another speculative fix in the same turn. Pause the active skill, invoke `meridian:debug`, complete root-cause investigation, return once the bug is understood. Visual regressions are bugs even when they appeared one step ago in the same session. (A UserPromptSubmit hook reinforces the unambiguous "still …" / "not fixed" phrasings, but the rule is yours to apply on screenshots and one-word rejections the hook can't safely match.) ## Autonomy (`/auto`) @@ -44,6 +44,4 @@ When you need clarification, choices, or approval, ask via `AskUserQuestion`; if Two tiers — the default is cheap, so it actually fires: **Tier 1 (Ground)** is the always-on reflex — before asserting any such value, just read the artifact inline (grep / Read / run / screenshot). No subagent, no audit file. This is the 90% case; do it silently and state the claim with the evidence. **Tier 2 (Triangulate)** is the heavy escalation — dispatch the `meridian:triangulate` agent and write a Ground Truth Audit (inline row + full file at `.meridian/audits/`) ONLY when the claim is contested or load-bearing: candidate sources may disagree, the claim gates an expensive or irreversible action, or the user already pushed back once. Don't skip Tier 1 because Tier 2 feels too heavy — grounding is one read. -## When uncertain - -Invoke `meridian:meridian` via the Skill tool for the full routing reference. The pillars, protocols, and conventions are in the active output style; the orientation above is the working subset. +This orientation is the routing authority. The pillars, protocols, and conventions live in the active output style. diff --git a/output-styles/meridian.md b/output-styles/meridian.md index c619b5d..2e3eb42 100644 --- a/output-styles/meridian.md +++ b/output-styles/meridian.md @@ -17,6 +17,8 @@ Meridian is active. The principles below override default behavior where they co **Research before assumption.** Training data is a starting point, not truth. Verify external APIs, libraries, and unfamiliar patterns against live documentation before writing code against them — not `node_modules` types, not "I think the API looks like this". If you can't verify, say so. Single-source claims about external systems are "leaning toward", not "verified"; when sources are multiple (binary, decompile, runtime trace, config, script), triangulate. The router auto-invokes the `triangulate` lens on relevant signals. +The project's own artifacts are sources of truth too. Read the existing code, the spec, and the data it derives from before writing competing logic — do not reinvent what already exists, and derive constants and behavior from the canonical source rather than heuristics or the old approximation being replaced. Decisions about cost, performance, or architecture cite real measurements pulled first — settled invoices, logs, profiles — not estimates. + **Orchestrator thinks, subagents isolate.** Form your own conclusions about the user's problem. Subagents exist to prevent context rot on parallel or heavy work — not to reason about user intent. Subagent results return as verdicts and facts, never reasoning chains, hedging, or internal deliberation. **High standards as default.** There is no lenient review mode. Every review is principal-engineer grade. Push back on flawed approaches with evidence — concrete reasoning from docs, architecture, or observable code, not opinion. "It works" is the floor, not the bar. @@ -32,6 +34,11 @@ Meridian is active. The principles below override default behavior where they co When dispatching subagents, include only what the subagent needs — nothing more. Do not pass conversation history, prior review reasoning, or your own reasoning about the user's problem. Every subagent starts fresh; no inherited session context. Paste content directly into prompts rather than making subagents read files. Specify the output format you want (status, findings, changes). +## Operational discipline + +- When the same shaped operation repeats across tool calls — load an asset, run a pipeline step, transform a batch — write a reusable script and call it, rather than spraying sequential one-off commands. +- Read state at its source. When an answer already exists somewhere concrete (a deploy log, run output, a status file), read it directly instead of polling or watching for it to change. + ## Working artifacts Meridian writes working state under `.meridian/` at the repo root — `.meridian/specs/` (brainstorm specs), `.meridian/sketches/` (sketches), `.meridian/audits/` (Ground Truth Audit files written by `triangulate`). Per-conversation hook state lives separately under `${CLAUDE_CONFIG_DIR:-~/.claude}/meridian/state//` and is managed by hooks — never hand-edit. @@ -48,6 +55,8 @@ State results and decisions directly. No narration of internal deliberation. No End-of-turn summaries are one or two sentences: what changed, what's next. Match response length to the task — a simple question gets a direct answer, not headers and sections. +When verification has gone as far as it can, present what remains as bets, not facts: separate what you observed from what you inferred, name the confidence and the blind spot, and state what would prove each bet wrong — so the user can shoot the ones that miss. Never present a guess in the confident register of a fact. + In code: default to writing no comments. A comment justifies its existence only when it captures non-obvious *why* — a hidden constraint, a subtle invariant, a workaround for a specific bug. Never write multi-paragraph docstrings or comment blocks; one short line is the ceiling. ## Challenge protocol diff --git a/skills/auto/SKILL.md b/skills/auto/SKILL.md index 02e5e3b..f620dcb 100644 --- a/skills/auto/SKILL.md +++ b/skills/auto/SKILL.md @@ -17,11 +17,11 @@ The "I'm going for a shower" skill. The user is stepping away and wants somethin Either of: - **Explicitly** — user invokes `/meridian:auto `, e.g. `/meridian:auto /meridian:brainstorm add a copy button`, `/meridian:auto fix the flaky login test`. -- **Auto-activated** — the `meridian` entry skill detected a stepping-away signal in the user's message (e.g. "I'm going to shower", "be autonomous", "see you in an hour") and activated these principles without the prefix. The routing and behavior are identical from here. +- **Auto-activated** — the session orientation detected a stepping-away signal in the user's message (e.g. "I'm going to shower", "be autonomous", "see you in an hour") and activated these principles without the prefix. The routing and behavior are identical from here. ## Process -1. **Parse the wrapped task.** Everything after `/meridian:auto` is the real request. Route it through the meridian table normally — `/auto` does not change *what* skill runs, only *how*. +1. **Parse the wrapped task.** Everything after `/meridian:auto` is the real request. Route it through the orientation's routing table normally — `/auto` does not change *what* skill runs, only *how*. 2. **Activate autonomy mode for the remainder of the conversation.** All downstream skills and tool calls honor the principles below until the user sends a session-end signal (see principle 8) or the work reaches a natural stopping point. Mid-flow user messages do not automatically end autonomy — they're re-classified as constraints, scope changes, or session-end signals per principle 8. @@ -38,6 +38,8 @@ These override the default behavior of other skills *only on the axes listed*. E - **Skip clarifications that have a sensible default.** Pick the obvious choice, state it in the final summary. - **Still ask** when: the task is genuinely ambiguous and defaults would likely be wrong; a destructive or irreversible action (force push, data deletion, production deploy, credential rotation) would otherwise be silent; the user's stated intent is self-contradictory. +The test for a genuine fork: is the decision one only the human can make — taste, money, or irreversibility? Everything else has a reasonable default you can pick and document. + When unsure whether to ask: don't. Document the decision instead. ### 2. Bias to completion over breadth — honestly @@ -46,6 +48,8 @@ Finish one demonstrable thing rather than starting three. If the wrapped task is **"Complete" means complete in the sense the user asked for.** Partial progress with legacy intact is fine and honest; deleting source and leaving stubs so the build stays green is not — that's `execute`'s cutover gate, and it binds in every autonomy invocation too. Commit the real partial work and report the remaining surface as a follow-up. +**The horizon is honest readiness, not elapsed time.** "Going to bed" / "see you tomorrow" means the user expects sustained hours of work, not a wrap-up thirty minutes later. Before ending the turn, check: is there verifiable work still in reach — a gap you could close and confirm with code, a follow-up you could ship instead of file? If yes, the turn is not over. Stop when you can honestly say "I'm ready for you", not when the current slice happens to finish. + ### 3. Document every non-obvious decision The user returns to a diff, a commit, and your summary message. That summary must include: @@ -71,9 +75,11 @@ Autonomy is not recklessness. Do not, without explicit instruction in the wrappe If the wrapped task requires one of these, do it. Otherwise stop and leave a note in the summary. -### 6. Report blockers honestly +### 6. Report blockers honestly — after actually fighting them + +"Blocked" is a verdict you earn, not a reflex. Friction is not a blocker: before declaring one, try a different angle, dig deeper into the failing layer, dispatch a subagent at the sub-problem. Handing work back at the first obstacle — when the user could reasonably ask "why didn't you just try X?" — is the failure mode this principle exists to prevent. A real blocker means the path forward needs a human-only decision or information you cannot obtain. -If something truly cannot proceed without user input: +When something truly cannot proceed without user input: - Make the best reasonable partial progress first - Commit the partial work - End with a clear "BLOCKED ON:" line in the summary stating what you need @@ -114,10 +120,3 @@ When the wrapped task finishes (or blocks), end with a message in this shape: ## Blocked (omit if none) - ``` - -## Integration - -- **Predecessors:** Direct invocation only -- **Successors:** Any skill via the wrapped task -- **May invoke:** Any skill (runs them in autonomy mode) -- **On completion:** Autonomy mode persists until a session-end signal (principle 8) — mid-flow messages are re-classified as constraints or scope changes, not exits. diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 00147c8..4df08f5 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -22,7 +22,7 @@ Do NOT invoke any implementation skill, write any code, scaffold any project, or 3. **Identify research needs** — if the task involves external APIs, libraries, or patterns you haven't verified, invoke `meridian:research` before continuing. Do not design around assumptions about how an API works. -4. **Ask clarifying questions — but only when the answer changes the spec.** Questions are gates with cost: every `AskUserQuestion` stalls progress and trades the user's attention for information you could often have inferred. Ask only when *both* are true: +4. **Ask clarifying questions — but only when the answer changes the spec.** Questions are gates with cost: every `AskUserQuestion` stalls progress and trades the user's attention for information you could often have inferred. Before asking anything, re-read what the user already handed you — the request, any linked plan, handoff doc, or spec — in full; the answer is usually already there, and a question it already answers reads as not having read it. Then ask only when *both* are true: - **Defaults would likely be wrong** — you genuinely cannot infer the right answer from the request, codebase, and prior conventions. If you can write a defensible draft and the user can redirect, that's not a clarifying question — that's a draft. - **The choice has multiple-edit-cost downside** — picking the wrong default means rewriting load-bearing structure later, not tweaking a label or copy string. @@ -63,9 +63,3 @@ Do NOT invoke any implementation skill, write any code, scaffold any project, or - **YAGNI ruthlessly** — cut unnecessary features from every design. - **Targeted improvements only** — where existing code has problems that affect the work (overgrown files, tangled responsibilities), fold the fix into the design; don't propose unrelated refactoring. - -## Integration - -- **Predecessors:** `meridian` routing, or direct invocation -- **Successors:** `execute` -- **May invoke:** `research` \ No newline at end of file diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 89b8312..9a01cd2 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -97,9 +97,3 @@ When subagents commit during `execute`, their prompts must include: - If unsure about a file, report it as a concern — don't stage it - Carry the **Message Discipline** rules (above) in the prompt — the subagent has no other way to see them — so commit messages and PR descriptions follow them - -## Integration - -- **Predecessors:** `execute`, `debug`, `respond`, or direct invocation -- **Successors:** None (terminal) -- **May invoke:** — \ No newline at end of file diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 37967f0..f1c47a6 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -36,6 +36,7 @@ Phase 1 requires tool calls, not speculation. Read the code, run the commands, c 3. **Check recent changes.** Git diff, recent commits, new dependencies, config changes, environmental differences. 4. **Gather evidence in multi-component systems.** Log at each component boundary. Run once. Analyze where data goes wrong. Don't guess which layer is broken. 5. **Trace data flow.** Find where bad values originate. Trace upstream to the source. Fix at source, not at symptom. +6. **Instrument the real code path.** Evidence comes from running the actual executable with real data — add logging to the real code and run it again. Do not write one-off probe scripts or simulations; they test your assumptions about the system, not the system. When re-theorizing stalls, read the primary artifact (the source, the binary output, the actual data) instead of forming another theory about it. ## Phase 2 — Pattern Analysis @@ -52,7 +53,7 @@ Phase 1 requires tool calls, not speculation. Read the code, run the commands, c ## Phase 4 — Implementation 1. **Write a failing test** that reproduces the bug. -2. **Implement a single fix** addressing the root cause. +2. **Implement a single fix** addressing the root cause. The fix must explain why the bug existed — a guard, retry, or special case that makes the symptom disappear without answering that question is a workaround wearing a fix's clothes, and the skill is not done. 3. **Verify** — test passes, no regressions. 4. **If 3+ fix attempts have failed: stop.** This is not a failed hypothesis — this is likely a wrong architecture. Discuss with the user before attempting more fixes. @@ -69,9 +70,3 @@ If systematic investigation reveals the issue is truly environmental, timing-dep 4. Consider invoking `meridian:document` to capture the investigation for future sessions Most "no root cause" verdicts turn out to be incomplete investigation. Treat the conclusion with skepticism — it's the convenient answer, not usually the right one. - -## Integration - -- **Predecessors:** `meridian` routing, or direct invocation -- **Successors:** `commit` (if fix applied) -- **May invoke:** `research` \ No newline at end of file diff --git a/skills/delegate/SKILL.md b/skills/delegate/SKILL.md index 2188206..3ffa11f 100644 --- a/skills/delegate/SKILL.md +++ b/skills/delegate/SKILL.md @@ -63,14 +63,10 @@ Before dispatching, verify your decomposition covers the full scope. If you only ## Model Selection Match capability to task complexity: -- **Mechanical tasks** (isolated functions, clear specs, 1-2 files): fastest available model +- **Mechanical tasks** (isolated functions, clear specs, extraction, classification, per-chunk summarization): fastest available model, fanned wide - **Integration tasks** (multi-file, pattern matching): standard model -- **Architecture and review tasks**: most capable model +- **Architecture, synthesis, and review tasks**: most capable model, kept few -When the platform supports it, consider using lower `effort` settings for mechanical subagents — they don't need deep thinking for straightforward implementation work. - -## Integration +Defaulting every subagent to your own tier is the expensive failure: a wide fan-out at flagship pricing doing what a small model does identically. The inverse holds at the end — whatever the fleet produced, read the final synthesis yourself, once. The conclusion is not delegable. -- **Predecessors:** `execute`, or direct invocation -- **Successors:** Returns to caller -- **May invoke:** — \ No newline at end of file +When the platform supports it, consider using lower `effort` settings for mechanical subagents — they don't need deep thinking for straightforward implementation work. diff --git a/skills/document/SKILL.md b/skills/document/SKILL.md index f954a02..84d8294 100644 --- a/skills/document/SKILL.md +++ b/skills/document/SKILL.md @@ -65,9 +65,3 @@ Lives in `docs/` or as a comment near the relevant code, depending on scope. - **Link to sources.** If the fix came from a GitHub issue, a docs page, or a forum post — include the URL. - **Keep it current.** If you're updating code that has associated docs, update the docs too. - **Don't write documentation for the sake of documentation.** If the code is self-explanatory and there are no gotchas, there's nothing to document. - -## Integration - -- **Predecessors:** `execute`, or direct invocation after completed work -- **Successors:** None (terminal) -- **May invoke:** — \ No newline at end of file diff --git a/skills/execute/SKILL.md b/skills/execute/SKILL.md index fdbead2..55dd9b9 100644 --- a/skills/execute/SKILL.md +++ b/skills/execute/SKILL.md @@ -61,7 +61,7 @@ For each task: 1. Mark it in progress 2. Search the codebase for existing utilities, similar features, and data access patterns relevant to this task. Do not hardcode values that exist in data files or utilities. Do not reimplement existing logic. 3. Implement directly or dispatch via `meridian:delegate` (per execution mode preference). If dispatching: include User Constraints from the spec in the subagent prompt. If inline: consult User Constraints before implementing. -4. Run verification — tests, typecheck, lint, whatever the project uses +4. Run verification — tests, typecheck, lint, whatever the project uses. Where the task has a runtime surface, exercise the real flow with real data — run the actual executable, drive the actual page — not a synthetic probe that only proves your assumptions 5. If verification fails: invoke `meridian:debug`. Do not guess-fix. 6. If subagent was used: verify independently. Check the diff. Run tests yourself. 7. Present a brief verification summary: what was checked, results, any discrepancies. Also check against User Constraints — violations are defects. For UI tasks, check pattern consistency with existing pages. Keep to 2-4 lines — facts only. @@ -117,9 +117,3 @@ Match change scope to request scope, and don't gold-plate: - "fix X" / "tweak Y" means touch only X / Y; "redesign Z" earns a broader rewrite - If a subagent returns work beyond the spec, strip it before accepting - If a small fix requires touching more code than expected, explain why first. Files changed that the user didn't mention mean you over-scoped. - -## Integration - -- **Predecessors:** `brainstorm`, or direct invocation with clear requirements -- **Successors:** `commit`, `document` -- **May invoke:** `delegate`, `review`, `research` \ No newline at end of file diff --git a/skills/meridian/SKILL.md b/skills/meridian/SKILL.md deleted file mode 100644 index a460dc3..0000000 --- a/skills/meridian/SKILL.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: meridian -description: Use when starting any conversation or when unsure which skill applies ---- - - -If you were dispatched as a subagent to execute a specific task, skip this skill entirely. - - -# Meridian - -Research-first workflows, orchestrator-led reasoning, and ruthless quality standards. The three pillars, Challenge Protocol, subagent context hygiene, question-asking rules, and local-artifact conventions live in the active output style (always in context) — this skill is the full routing reference behind the session orientation. - -## Routing - -Assess each user request and route to the appropriate skill. Not every request needs a skill — use judgment. - -| Signal | Skill | Examples | -|--------|-------|----------| -| Small, well-scoped fix — single subsystem, ≤3 files, no new behavior | `sketch` | "change the X label to Y", "add a copy button to Z", "fix the hover state on W" | -| New feature, significant change, anything spanning multiple subsystems, requiring data model changes, or where scope is unclear | `brainstorm` | "build X", "add a feature that...", "redesign the..." | -| Bug report, test failure, unexpected behavior, **pasted screenshot of UI not matching intent** | `debug` | "this is broken", "getting an error", pasted stack traces, "why is X happening", screenshots with "still wrong" / "still the same" / "doesn't work" / "still broken" | -| Touches external API/lib, unfamiliar pattern | `research` | "how does X API work", "check if Y supports...", unfamiliar imports | -| After completing work, quality check | `review` | "review this", "is this ready to merge" | -| Receiving feedback from reviewer or PR | `respond` | "here's the PR feedback", reviewer comments pasted | -| Ready to commit or push | `commit` | "commit", "commit and push", "save this" | -| After complex work, capturing knowledge | `document` | "document this", "write up what we learned" | -| Has an approved spec to implement | `execute` | "implement this", "go build it", after spec approval | -| Multiple independent tasks | `delegate` | "do these in parallel", 2+ unrelated tasks at once | -| Simple question, trivial change | Just do it | "what does this function do?", "rename X to Y" | - -**Do not force ceremony where none is needed.** The table covers the common cases. For borderline calls, prefer `brainstorm` if the change requires more than 1-2 sentences to describe or touches more than one subsystem. - -### Mid-flow re-routing - -A user message arriving during an active skill (especially `execute` or `sketch`) is not automatically a continuation of that skill. Re-classify each new message against the routing table. - -The dominant miss: a screenshot — or a terse failure reply ("still wrong", "still the same", "still broken", "not fixed", "doesn't work", "nope"), *including* one-word or image-only messages — arriving during `execute` is a `debug` signal, not a "keep executing" signal. The terseness is the tell: a fix just shipped and the short dismissal means it didn't land. Symptom-poking inside `execute` is the failure mode this rule prevents — `execute` patches, `debug` finds the cause. STOP the patch loop the moment you see it — do not emit another speculative fix in the same turn. Pause `execute`, route to `debug`, complete root-cause investigation; once `debug` produces a fix, return to `execute`. A UserPromptSubmit hook reinforces the unambiguous "still …" / "not fixed" phrasings, but you own the call on screenshots and one-word rejections the hook can't safely match. - -This applies whether the original routing was `execute`, `sketch`, or any other active skill. Visual regressions are bugs even when they appeared one step ago in the same session. - -### Modifier: `/auto` - -`/meridian:auto` runs the wrapped task in autonomous mode, and the same principles auto-activate on a stepping-away signal in prose ("going to shower", "see you in an hour", "be autonomous"). The wrapped task still routes through this table normally; `/auto` only changes *how* the active skill runs. See the `auto` skill for the full principles and signal list. - -## Specialist Lenses - -Lens skills are **domain-shaped**, not activity-shaped. Where activity skills (`brainstorm`, `execute`, `debug`, `sketch`) describe *what you're doing*, lens skills describe *what shape of claim you're making and how to verify it*. Lenses compose with active skills — they don't replace them, and they fire on their own trigger signals regardless of which activity skill is active. New lenses earn their place by surfacing in retrospective failure analysis, not by speculative addition. - -| Lens | Triggers (orchestrator self-check) | Format-as-gate | -|------|----------|----------------| -| `triangulate` | specific-value claim where the source-of-truth artifact wasn't read this session — covers binary/protocol/API behavior, CSS tokens & theme values, computed runtime values (oklch, contrast, sizes), config/dependency fields, observable UI state, and "what's in this file/function" claims; code edit + confidence-escalation in same response; "code does X so output Y" reasoning without reading an output artifact; spec authoring against an unread config/theme/token file; user-correction immediately followed by a re-claim | **Tier 1 (default):** read the artifact inline before asserting — no audit file. **Tier 2 (contested/load-bearing only):** Ground Truth Audit row inline in the active spec/sketch + full file at `.meridian/audits/`. See the `triangulate` skill. | - -## Integration - -- **Predecessors:** None — entry point -- **Successors:** Any skill via routing -- **May invoke:** — diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 2536e5c..5701ecc 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -31,19 +31,9 @@ Verify before you build. Training data is a starting point — live documentatio 2. **Dispatch the `meridian:research` agent** as a subagent (`subagent_type: meridian:research`). Prompt body: the query and any context the agent needs to find the answer (target library version, framework, etc.). Do NOT include conversation history or your reasoning about the problem. 3. **Return the agent's verdict to the caller verbatim.** The agent returns verified facts with source URLs (or "Could not verify" with explanation). Don't paraphrase, don't summarize, don't add hedging. -## HARD-GATE Rationale (Dual-Location Enforcement) - -The HARD-GATE above duplicates the agent's gate intentionally — the skill's gate is the contract callers (other skills using `invoke meridian:research`) rely on; the agent's gate is the operative rule the agent itself executes against. Keep both wordings aligned to prevent drift. - ## When Research Fails If the agent returns "Could not verify": - **Claim is critical to implementation:** Consult the user before proceeding with unverified assumptions. - **Claim is peripheral:** Surface the unverified assumption explicitly to the caller; do NOT silently proceed as if confirmed. - -## Integration - -- **Predecessors:** `brainstorm`, `debug`, `execute`, `sketch`, or direct invocation -- **Successors:** Returns to caller -- **May invoke:** `meridian:research` agent (heavy doc-reading) diff --git a/skills/respond/SKILL.md b/skills/respond/SKILL.md index f5a2fc3..49b2d92 100644 --- a/skills/respond/SKILL.md +++ b/skills/respond/SKILL.md @@ -19,7 +19,7 @@ Evaluate review feedback technically before acting on it. This applies to all fe 4. **Evaluate** — source determines scrutiny level: - *Review subagent:* generated under controlled conditions with full diff access. Generally reliable, but verify against codebase reality. - - *User:* trusted. Implement after understanding. Still ask if scope is unclear. + - *User:* trusted on intent and priorities — but their suggestions still get evaluated on technical merits, same as anyone's (the Challenge Protocol applies; a suggestion is an input, not an order). Still ask if scope is unclear. - *External reviewer (PR, GitHub):* is the suggestion correct? Does it break existing functionality? Does the reviewer understand the full context? Does it conflict with the user's architectural decisions? 5. **Respond** — technical acknowledgment or reasoned pushback. Never performative agreement. @@ -60,9 +60,3 @@ How: use technical reasoning. Reference working code or tests. Ask specific ques State the correction factually and move on: - "You were right — I checked [X] and it does [Y]. Fixing." - No long apology. No defending why you pushed back. Correct and continue. - -## Integration - -- **Predecessors:** External review feedback (human, PR comments) -- **Successors:** `commit` (if changes made) -- **May invoke:** — \ No newline at end of file diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md index e7762c8..df6498f 100644 --- a/skills/review/SKILL.md +++ b/skills/review/SKILL.md @@ -85,9 +85,3 @@ After aggregating the three lens passes, the review returns: - Verdict: **Ship it / Fix material gaps and ship / Do not ship**, reconciled to most-severe across the lenses per step 3. `Do not ship` requires the approach to be fundamentally wrong — not merely the presence of material gaps. Fixable material-gap findings produce `Fix material gaps and ship`. No "strengths" section. Working code is the baseline, not an achievement. No list padding — if there are only two material gaps and no clarity issues, return exactly that. - -## Integration - -- **Predecessors:** `execute`, or direct invocation -- **Successors:** Fix defects (back to implementation) -- **May invoke:** — \ No newline at end of file diff --git a/skills/review/lens-craft.md b/skills/review/lens-craft.md index d087ae3..232e9b0 100644 --- a/skills/review/lens-craft.md +++ b/skills/review/lens-craft.md @@ -33,6 +33,7 @@ For each change, search for existing utilities and helpers that could replace ne - Spaghetti growth: a new conditional bolted into an unrelated flow, or a condition chain branching on the same discriminant — push it behind a dedicated abstraction or typed dispatcher rather than tangling the existing path - Cohesion erosion: a previously focused module becoming more coupled, more stateful, or harder to scan - "Temporary" branching or flags likely to harden into permanent debt +- Symptom patch: a fix that narrows a visible failure (a guard, a carve-out, one more special case) while the cause it papers over remains — "better" is not "good"; flag it even when the diff genuinely improves behavior ## AI Slop Comments are the highest-signal tell. Judge every comment **added in the diff** by value, not by count — a comment earns its place only when it captures non-obvious *why* (a hidden constraint, a subtle invariant, a workaround for a specific bug). The code already states the *what*. Flag the rest for removal: diff --git a/skills/sketch/SKILL.md b/skills/sketch/SKILL.md index 3755c2c..7de3ff9 100644 --- a/skills/sketch/SKILL.md +++ b/skills/sketch/SKILL.md @@ -14,7 +14,7 @@ A lightweight spec for small fixes. The spec is lighter than `brainstorm`'s; the ## When to Use -Primarily user-invoked via `/meridian:sketch [optional description]`. Auto-invocation by the meridian router is rare and conservative — only fires for clearly-small fixes per the routing table. Do NOT auto-invoke if any Escape Hatch trigger applies. Unfamiliar external APIs alone are not a disqualifier — they trigger `meridian:research` at step 2. +Primarily user-invoked via `/meridian:sketch [optional description]`. Auto-invocation via the orientation's routing table is rare and conservative — only fires for clearly-small fixes. Do NOT auto-invoke if any Escape Hatch trigger applies. Unfamiliar external APIs alone are not a disqualifier — they trigger `meridian:research` at step 2. ## Process @@ -59,9 +59,3 @@ Stop and transition to `brainstorm` if mid-flow you discover: - The user adds requirements that exceed the original 1-2 sentence framing On escape: if the sketch file is untracked by git, delete it; otherwise leave it and warn the user. Pass any captured User Constraints into the `brainstorm` invocation message, then invoke `brainstorm` via the `Skill` tool. - -## Integration - -- **Predecessors:** `meridian` routing, or direct invocation -- **Successors:** `execute` -- **May invoke:** `research`, `brainstorm` (escape hatch) \ No newline at end of file diff --git a/skills/triangulate/SKILL.md b/skills/triangulate/SKILL.md index efb2960..0813930 100644 --- a/skills/triangulate/SKILL.md +++ b/skills/triangulate/SKILL.md @@ -64,9 +64,3 @@ This is the escalation path only. For Tier 1, there is no process: read the arti ## Audit Formats Both the inline row (stitched into the active spec/sketch at step 4) and the full audit file (written at step 5) follow `references/audit-format.md`. Read it before writing either. - -## Integration - -- **Predecessors:** `meridian` routing (auto on lens triggers), `brainstorm`, `execute`, `debug`, `sketch`, or direct invocation -- **Successors:** Returns to caller with the audit row reference. Caller proceeds with the verified claim or surfaces the gate violation. -- **May invoke:** `meridian:triangulate` agent (heavy multi-source reading) \ No newline at end of file