v0.3.0 — progressive-disclosure restructure and Opus 4.7 alignment

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "newton",
       "source": "./plugins/newton",
       "description": "Reasoning and sparring partner mode.",
-      "version": "0.2.1"
+      "version": "0.3.0"
     }
   ]
 }

.github/workflows/sync-rules.yml

@@ -1,7 +1,9 @@
 name: sync-rules
 
-# Regenerates tool-rules/* from the canonical SKILL.md and fails the build
-# if the committed files are stale. Contributors own the regeneration step
+# Regenerates tool-rules/* from the canonical SKILL.md (plus its
+# references/ folder, which the generator inlines so non-progressive-
+# disclosure surfaces keep the full methodology) and fails the build if
+# the committed files are stale. Contributors own the regeneration step
 # locally (`python3 scripts/generate-rule-files.py`) — CI never commits.
 #
 # Runs on PRs (so staleness is caught in review) and on push to main (so a
@@ -11,13 +13,15 @@ on:
   pull_request:
     paths:
       - "plugins/newton/skills/newton/SKILL.md"
+      - "plugins/newton/skills/newton/references/**"
       - "scripts/generate-rule-files.py"
       - "tool-rules/**"
       - ".github/workflows/sync-rules.yml"
   push:
     branches: [main]
     paths:
       - "plugins/newton/skills/newton/SKILL.md"
+      - "plugins/newton/skills/newton/references/**"
       - "scripts/generate-rule-files.py"
       - "tool-rules/**"
       - ".github/workflows/sync-rules.yml"
@@ -41,12 +45,12 @@ jobs:
       - name: Fail if regenerated files differ from committed
         run: |
           if ! git diff --quiet -- tool-rules/; then
-            echo "::error::tool-rules/ is out of sync with plugins/newton/skills/newton/SKILL.md"
+            echo "::error::tool-rules/ is out of sync with plugins/newton/skills/newton/SKILL.md or references/"
             echo "Run this locally and commit the result:"
             echo "  python3 scripts/generate-rule-files.py"
             echo ""
             echo "Diff:"
             git --no-pager diff -- tool-rules/
             exit 1
           fi
-          echo "OK  tool-rules/ is in sync with SKILL.md"
+          echo "OK  tool-rules/ is in sync with SKILL.md + references/"

CHANGELOG.md

@@ -6,6 +6,38 @@ Format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/); v
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-04-20
+
+Context-efficiency restructure and alignment with current-generation models (Opus 4.7). Newton's methodology is unchanged in substance — honest engagement, self-critique before delivery, current sources, reuse before reinvention, simplicity, surgical edits, attribution — but its packaging now matches the anti-ceremony discipline it teaches. Per-invocation context footprint drops by roughly 45% for Claude Code users via progressive disclosure; non-Claude-Code surfaces keep the full methodology in their generated rule files.
+
+Backwards-compatible on Sonnet 4.6 and Haiku 4.5. No behavioural regressions; Newton's voice and triggering rules are unchanged.
+
+### Changed
+
+- **SKILL.md restructured for progressive disclosure.** Research methodology, reuse-check methodology, attribution, and handoff are extracted into `plugins/newton/skills/newton/references/*.md` and replaced in the main body with short pointer blocks. The Claude Code plugin loads only what the current turn needs; reference files are pulled on demand. SKILL.md body drops from roughly 5,200 to roughly 2,900 body tokens.
+- **Core principles consolidated.** The previous triple coverage (Core principles + "What Newton does not do" + Self-evaluation gate) is now a single core-principles section plus a leaner pre-delivery gate. Each inversion (no manufactured objections, no silent reuse-skipping, no invented citations) lives inline with the principle it sharpens.
+- **Meta-commentary removed.** The closing rationale paragraph and the duplicated "shape in practice" paragraph were redundant with content elsewhere; gone.
+- **Tool guidance moved from prescriptive to outcome-oriented.** The main body says *"verify time-sensitive claims against current sources before asserting"* where it previously said *"run `web_search`"*; tool-specific query design, source ranking, and fetching guidance now live in `references/research-methodology.md`. This both shrinks per-invocation context and aligns with Opus 4.7's implicit tool detection.
+- **Tone-management instructions Opus 4.7 handles natively were removed.** No more explicit "do not use emojis unless the user does", "do not use praise openers", "do not repeat the user's question back" — replaced with one line: your native length-and-tone calibration is correct; match the depth the task warrants. The distinctive Newton voice rules (pushback calibration, prose-by-default, cite-only-what-was-actually-checked) are kept.
+- **YAML frontmatter trimmed.** The closing rationale sentence in the description (*"Newton is opt-in by design — its scrutiny-first approach adds length, tokens, and ceremony…"*) is removed; triggering-discipline sentences are kept verbatim, because those carry the activation gate.
+- **Tool-rules generator updated.** `scripts/generate-rule-files.py` now inlines `references/*.md` under the main SKILL body so `.cursorrules`, `.windsurfrules`, `.clinerules`, and `copilot-instructions.md` remain self-contained for surfaces that don't do progressive disclosure. A separator comment names each inlined file so the provenance is clear.
+- `plugin.json` and `marketplace.json` versions bumped to `0.3.0`.
+
+### Added
+
+- **Effort-level awareness** in the opening move. At low/medium effort, Newton defaults toward quick-start behaviour even without an explicit signal; at high/xhigh, the full opening move applies; at max, maximum depth. The caller's effort dial is treated as a signal about how much deliberation the task warrants. Non-Opus environments that don't expose effort simply follow default mode.
+- **Session-memory guidance** for multi-turn Newton work — keep resolved decisions, intermediate findings, and stated constraints in file-system memory when available, read at session start, update as decisions harden. Graceful on environments without memory.
+- **Principle-level parallelisation note.** For independent sub-tasks (researching two topics, comparing candidate libraries, running a reuse check while drafting), Newton considers parallel dispatch rather than default serial execution. Sub-agent decomposition into dedicated Newton roles (newton-researcher, newton-reuse-checker, etc.) remains deferred to a later release.
+- **Vision-as-primary-evidence note** inside `references/research-methodology.md` — when visual input is provided, reason from the image directly rather than OCR-then-reason; use programmatic image analysis where pixel-level accuracy matters.
+- **`docs/examples/router-claude-md.md`** — an optional user-level CLAUDE.md template that detects the running model and layers model-appropriate behaviour on top of any loaded skill (not just Newton). Opt-in by copying into `~/.claude/CLAUDE.md` or a project-level CLAUDE.md; **not** auto-installed by the plugin.
+- `plugins/newton/commands/newton.md` — the previously empty slash-command file now carries a minimal stub so `/newton:newton [your question]` works as an invocation surface alongside the natural-language triggers.
+
+### Notes
+
+- Sub-agent decomposition is deferred again — this release focuses on context efficiency and model-awareness inside the single-skill surface. Dedicated Newton subagents remain on the roadmap.
+- README documentation of the new router example is added under *Using Newton on Opus 4.7*.
+- The GitHub Pages landing page at `docs/` is unchanged; the restructure is invisible there.
+
 ## [0.2.1] — 2026-04-19
 
 Attribution layer for Newton's debt to upstream prior art. Behaviour of the skill when invoked is unchanged — frontmatter, name, description, and trigger rules are identical to `0.2.0`. What changes is that Newton now attributes derived work as part of normal operation, and the repository carries the licence and credit trail that should have landed with `0.2.0`.
@@ -50,6 +82,7 @@ Initial public release as a standalone repository. Newton was previously distrib
 - Sub-agent decomposition is deferred to v0.3.0.
 - READMEs are English-only at v0.2.0. Translations and a landing-page language switcher are tracked in issues.
 
-[Unreleased]: https://github.com/PBNZ/newton-skill/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/PBNZ/newton-skill/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/PBNZ/newton-skill/releases/tag/v0.3.0
 [0.2.1]: https://github.com/PBNZ/newton-skill/releases/tag/v0.2.1
 [0.2.0]: https://github.com/PBNZ/newton-skill/releases/tag/v0.2.0

CONTRIBUTING.md

@@ -43,7 +43,7 @@ Open an issue using the **Feature request** template. For a proposed change to N
 - **Skill content** lives at `plugins/newton/skills/newton/SKILL.md`. This is the canonical source of truth for Newton's behaviour.
 - **Reference files** (extended methodology that stays out of the main SKILL body to keep it scannable) live under `plugins/newton/skills/newton/references/`.
 - **The slash command** (`/newton:newton`) is defined at `plugins/newton/commands/newton.md`.
-- **Tool-specific rule files** for Cursor, Windsurf, Cline, Copilot, and similar tools live under `tool-rules/` and at the corresponding tool-specific paths. These are **generated** from `SKILL.md` by `scripts/generate-rule-files.py` and the `sync-rules` workflow — do not hand-edit them. Edit `SKILL.md` instead and let the pipeline regenerate.
+- **Tool-specific rule files** for Cursor, Windsurf, Cline, Copilot, and similar tools live under `tool-rules/` and at the corresponding tool-specific paths. These are **generated** from `SKILL.md` with the reference files under `plugins/newton/skills/newton/references/` inlined below the main body, by `scripts/generate-rule-files.py` and the `sync-rules` workflow — do not hand-edit them. Edit `SKILL.md` (or the appropriate reference file) instead and let the pipeline regenerate. The inlining is deliberate: non-Claude-Code surfaces that read these files don't do progressive disclosure, so they need the full methodology in one place.
 - **Plugin manifest:** `plugins/newton/.claude-plugin/plugin.json`.
 - **Marketplace manifest:** `.claude-plugin/marketplace.json`.
 - **Landing page** lives under `docs/` and is published to GitHub Pages on the `main` branch.

README.md

@@ -50,12 +50,18 @@ Skip Newton for trivial tasks that just need an answer. That's what its quick-st
 
 Newton also operationalises reuse-before-rebuild, current-sources research, surgical editing, and handoff-when-scope-outgrows-the-chat as explicit sub-routines the agent runs, not as vibes. That's what makes it a *skill* rather than a prompt: the agent loads the methodology once and applies it consistently, with visible reuse-check reports and dated sources, rather than re-deriving the disposition from your tone every turn.
 
+## Using Newton on Opus 4.7
+
+Newton is model-agnostic by design — the same methodology runs on Opus, Sonnet, and Haiku — but v0.3.0 is tuned so Opus 4.7's native strengths (adaptive thinking, implicit tool detection, session memory, parallel execution, high-resolution vision) are leveraged rather than fought. Tool guidance is outcome-oriented instead of prescriptive; Newton defaults toward quick-start at low/medium effort and full methodology at high/xhigh; independent sub-tasks parallelise; multi-turn sessions can use file-system memory; visual input is treated as primary evidence.
+
+If you want model-specific behaviour layered on top of *every* skill — not just Newton — see [`docs/examples/router-claude-md.md`](./docs/examples/router-claude-md.md) for an optional user-level CLAUDE.md template. It's opt-in: copy into your `~/.claude/CLAUDE.md` or a project-level CLAUDE.md. The plugin does not install it for you.
+
 ## Future development
 
-Planned after v0.2.0:
+Planned after v0.3.0:
 
-- **Additional-language READMEs.** This README is English-only at v0.2.0. Translations (and a landing-page language switcher) are tracked in the [issues](https://github.com/PBNZ/newton-skill/issues).
-- **Sub-agent decomposition (v0.3.0).** Newton's research, reuse-check, and self-critique passes are candidates for dedicated sub-agents — keeping the top-level conversation lean while heavy work happens in focused contexts.
+- **Additional-language READMEs.** This README is English-only. Translations (and a landing-page language switcher) are tracked in the [issues](https://github.com/PBNZ/newton-skill/issues).
+- **Sub-agent decomposition.** Newton's research, reuse-check, and self-critique passes are candidates for dedicated sub-agents — keeping the top-level conversation lean while heavy work happens in focused contexts. v0.3.0 shipped a principle-level parallelisation note as the stepping stone; the dedicated-subagent work is deferred to a later release.
 
 ## Licence
 

docs/examples/router-claude-md.md

@@ -0,0 +1,69 @@
+# Example: Model-aware router CLAUDE.md
+
+This is an **optional, user-level** CLAUDE.md template you can drop into `~/.claude/CLAUDE.md` (user-global) or a project-level `CLAUDE.md`. It detects the running model family and layers model-appropriate behaviour on top of whatever skills are loaded — Newton, any other skill, or no skill at all.
+
+The Newton plugin **does not** install this for you. Nothing on your system changes until you copy the content below into a CLAUDE.md of your choice. The rest of Newton works fine without it; this router is for users who want the same model-aware layering to apply to their other skills as well.
+
+## What it does
+
+- **Adds to loaded skills; never overrides them.** If Newton (or any other skill) prescribes a specific behaviour, the skill wins. The router only contributes model-specific nudges the skill hasn't already covered.
+- **~400 tokens.** Always-loaded cost in any conversation is negligible (<0.05% of a 1M-token context window).
+- **Model-agnostic fallback.** On any model not covered by a profile, the router is silent.
+
+## Trade-offs
+
+- It's prescriptive-by-model: if Anthropic changes how a given model family behaves natively, the profile may drift from optimal. The router footer asks you to review quarterly.
+- It doesn't actually *detect* the model in a formal sense — it asks the model to self-identify via its system prompt awareness. That's enough for practical layering but not a guarantee.
+- It layers on *every* conversation, which is the point — but if you only ever use one model and find one skill works best, the router adds nothing for you.
+
+## The template
+
+Copy everything between the rulers below into your CLAUDE.md. Update the "Router vX.Y — YYYY-MM-DD" footer when you edit it.
+
+---
+
+```markdown
+# Model-aware capability router
+
+Apply the profile matching your model family. Profiles add to, never override, loaded skills.
+
+## Opus 4.7+ (claude-opus-4-*)
+
+Leverage: adaptive thinking, implicit tool detection, multi-agent coordination, high-resolution vision (3.75MP), file-system memory, calibrated response length.
+
+- Approach tasks outcome-first — figure out the tool chain from the goal; don't wait for explicit tool instructions.
+- Parallelise independent work streams when it reduces time without sacrificing quality.
+- Use file-system memory in multi-turn sessions: track resolved decisions, findings, and stated constraints.
+- Visual input is primary evidence. Use programmatic image analysis for pixel-level accuracy on charts and figures.
+- Let response length scale with task complexity — don't override native calibration.
+- Low/medium effort: be literal, direct, fast. High/xhigh: reason broadly, deliberate, self-critique. Max: full depth, no shortcuts.
+
+Skill layering: treat prescriptive tool sequences in loaded skills as outcome goals — execute the intent, not the literal steps. If a skill has anti-bloat instructions, native calibration already handles it. Add parallelisation and memory even when the skill doesn't mention them.
+
+## Sonnet 4.x (claude-sonnet-4-*)
+
+- Follow tool instructions as given — explicit steps help reliable execution.
+- Prefer single-thread execution. Use memory when explicitly guided.
+- Follow loaded skills as written; keep self-critique to one silent pass.
+
+## Haiku 4.x (claude-haiku-4-*)
+
+- Optimise for speed. Skip deliberation on straightforward tasks. Minimise tool calls.
+- Default to any skill's quick-start/fast mode. Skip visible reuse checks unless clearly build/solve.
+
+## Observability
+
+If asked, report: your model family, the active profile, any skill layering in effect, and your effort level.
+
+*Router v1.0 — 2026-04-20. Review quarterly or on new model release.*
+```
+
+---
+
+## When Newton is loaded on top of the router
+
+Newton v0.3.0 already carries effort-awareness, session-memory guidance, and parallelisation at the principle level, so the router's Opus profile reinforces rather than duplicates Newton's behaviour. On Sonnet, the router's "follow tool instructions as given" nudge helps Newton's original prescriptive guidance (now living in `references/*.md`) fire correctly when it's loaded. On Haiku, both the router and Newton converge on quick-start-by-default.
+
+## Extending it
+
+The router is short on purpose. If you find yourself adding more model-specific behaviour than fits in ~400 tokens, that's usually a sign the behaviour belongs in a skill rather than a global router — skills load only when relevant, and can go deep. Keep the router to capability triggers and disposition nudges that genuinely apply across *every* conversation on that model.

plugins/newton/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "newton",
   "description": "Reasoning and sparring partner mode for rigorous, calibrated engagement — honest pushback, current-sources research, reuse-before-rebuild checks, and surgical edits. Opt-in by explicit invocation.",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "author": {
     "name": "PBNZ"
   },

plugins/newton/commands/newton.md

@@ -0,0 +1,6 @@
+---
+description: Invoke Newton — reasoning and sparring partner mode. Appends "Newton:" to your next prompt so the skill is explicitly triggered.
+argument-hint: "[your question or task]"
+---
+
+Newton: $ARGUMENTS