Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
2 changes: 1 addition & 1 deletion .plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "meridian",
"version": "0.11.2",
"version": "0.11.3",
"hooks": "./hooks/hooks-copilot.json"
}
58 changes: 58 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 2 additions & 4 deletions hooks/context/orientation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)

Expand All @@ -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.
9 changes: 9 additions & 0 deletions output-styles/meridian.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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/<session_id>/` and is managed by hooks — never hand-edit.
Expand All @@ -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
Expand Down
21 changes: 10 additions & 11 deletions skills/auto/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <task>`, 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.

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -114,10 +120,3 @@ When the wrapped task finishes (or blocks), end with a message in this shape:
## Blocked (omit if none)
- <what I need from you>
```

## 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.
8 changes: 1 addition & 7 deletions skills/brainstorm/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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`
6 changes: 0 additions & 6 deletions skills/commit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:** —
Loading
Loading