@zalom/plastic 1.0.0-beta.27 → 1.0.0-beta.28

package/PLASTIC.md

@@ -150,6 +150,54 @@ agent that can write the file) persists it via the helper. A session that cannot
 intent file still returns its report, so the insight survives.
 For full lifecycle detail, the skills in the Detail column have references/.
 
+## Agent Models and Dispatch (intent 116)
+
+Every lifecycle stage has exactly one dispatchable background agent, plus the enforcer that
+orchestrates them:
+
+| Stage | Agent |
+|---|---|
+| What | `plastic-intent-discovery` |
+| Why | `plastic-brainstorming` + `plastic-spec-specialist` |
+| How | `plastic-planner` |
+| Exec | `plastic-executor` |
+| Done | `plastic-intent-curator` |
+
+Final-gate code review stays an ad-hoc subagent the enforcer dispatches at the final gate, not
+a standing role.
+
+**Model contract.** Every agent in `agents/*.md` pins an explicit Claude Code model alias in
+its own frontmatter: `opus`, `sonnet`, or `haiku`. Never `inherit`, never Fable. Aliases track
+"latest per tier" so no Plastic release is required to advance a tier. The tier by role:
+`plastic-enforcer`, `plastic-brainstorming`, `plastic-planner` are `opus`;
+`plastic-spec-specialist`, `plastic-executor`, `plastic-intent-curator`,
+`plastic-future-intent-researcher`, `plastic-intent-discovery` are `sonnet`.
+
+**Config and installer mechanism.** `agents.models.<basename>` in a project's
+`<dir>/.plastic_store/config.yml` or the global `~/.plastic/config.yml` overrides one agent's
+tier. Precedence is project, then global, then the shipped default, matching every other
+`read-config` key. The installer applies the resolved override to each agent file's `model:`
+line at copy time (install, update, and repair, across every harness target). With no override
+configured, the shipped frontmatter passes through unchanged.
+
+**Dispatch-time contract.** Frontmatter is primary, and Claude Code reads it at dispatch, but
+because that read is a harness implementation detail rather than a contract Plastic controls,
+every dispatch site also resolves the target agent's model through the config chain
+(`read-config agents.models.<basename> --project <repo>`) and passes it explicitly at dispatch,
+belt-and-braces on top of the frontmatter pin.
+
+**Orchestrator advisory.** At auto-mode start, the orchestrator recommends once that the user
+run the main session on the best available thinking model (Fable, Opus, or whatever supersedes
+them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
+concerns the human's main session, never a dispatched subagent.
+
+**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, before the
+delivery lock is armed and Why begins: it reads the intent's `chain`/`sources` frontmatter,
+runs QMD-first discovery over completed predecessor work and related parked or future intents,
+and deposits findings to `resources/discovery--<slug>.md` in the intent directory ONLY. It
+never writes the intent file, `spec.md`, or any other lifecycle deliverable; the Why-stage
+`plastic-brainstorming` agent reads its deposit and enriches `## Context`.
+
 `savepoint.md` — a deterministic, append-only ledger of cycle-step milestones (one line per
 lifecycle boundary, newest at the bottom), written automatically by the gate hook. It is
 sugar on top of the conventions, not a source of truth: state is always derivable from

package/README.md

@@ -103,6 +103,16 @@ After installation, run `/clear` to load Plastic conventions, then:
 
 Or say "auto" to let the agent handle the full lifecycle autonomously.
 
+## Agents
+
+Each lifecycle stage has one dispatchable background agent: `plastic-intent-discovery` for
+What, `plastic-brainstorming` and `plastic-spec-specialist` for Why, `plastic-planner` for
+How, `plastic-executor` for Exec, `plastic-intent-curator` for Done, plus `plastic-enforcer`
+as the auto-mode orchestrator. Every agent pins an explicit Claude Code model alias (opus or
+sonnet) in its frontmatter: never `inherit`, never Fable. See `docs/architecture.md` for the
+stage table and `docs/internals.md` for how the model is configured, resolved, and applied at
+install time.
+
 ## Documentation
 
 - [`docs/architecture.md`](docs/architecture.md): system structure, the two

package/agents/plastic-brainstorming.md

@@ -7,7 +7,7 @@ description: |
   user: "Explore the requirements for the active intent"
   assistant: "I'll use the brainstorming agent to enrich Context and record Decisions"
   <commentary>Why-stage exploration runs before the spec-specialist.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.

package/agents/plastic-enforcer.md

@@ -7,16 +7,31 @@ description: |
   user: "auto"
   assistant: "I'll use the plastic-enforcer to orchestrate the team through the cycle"
   <commentary>The enforcer IS the orchestrator and gates each stage transition.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole What->Why->How->Exec cycle. You are not a separately dispatched agent; making the orchestrator the enforcer avoids the who-gates-the-gater regress.
 
+**Advisory (not a gate).** At auto-mode start, recommend once that the user run this
+orchestrating main session on the best available thinking model (Fable, Opus, or whatever
+supersedes them) for the sharpest gating and synthesis. This is advice only: it changes no
+behavior and blocks nothing if ignored. It concerns the human's MAIN session; dispatched
+subagents keep their pinned tier and never resolve to Fable.
+
 ## Your Responsibilities
 
 1. **Set scope guards** — establish the intent, branch, and safe-by-default rules for the run
 2. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
 3. **Sequence the team** — dispatch ONE specialist per stage (brainstorming, spec-specialist, planner, executor) with a constructed context bundle
+
+**Dispatch-time model contract (belt-and-braces).** Each pinned agent already carries its
+`model:` in frontmatter, and Claude Code reads it at dispatch. Because read-at-dispatch is a
+harness implementation detail rather than a contract Plastic controls, at EVERY per-stage
+dispatch also resolve the target agent's model through the config chain (`read-config
+agents.models.<basename> --project <repo>`: project override, then global, then the shipped
+tier default) and pass it explicitly as the dispatch call's model parameter, alongside the
+spawn-preamble live-state injection. Never rely on the dispatched role's frontmatter alone. A
+resolved subagent model is never Fable.
 4. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
 5. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
 

package/agents/plastic-executor.md

@@ -7,7 +7,7 @@ description: |
   user: "Execute the plan for the active intent"
   assistant: "I'll use the executor to implement each action and run the suite green"
   <commentary>Exec turns the plan into code, one action at a time.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.

package/agents/plastic-future-intent-researcher.md

@@ -8,7 +8,7 @@ description: |
   user: "Research my future intents"
   assistant: "I'll use the future-intent-researcher to pick up a parked intent and investigate it"
   <commentary>Agent autonomously researches a future intent and writes findings.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Future Intent Researcher. Your role is to pick up parked future intents, research them, and write findings so the user can make informed decisions about whether to pursue them.
@@ -36,3 +36,4 @@ You are the Plastic Future Intent Researcher. Your role is to pick up parked fut
 - You never modify `## Insights` or `## Outcome` sections — those belong to the worker
 - You use Read, WebSearch, WebFetch, and Bash (read-only grep/find) for research
 - You never change status fields — status is convention-derived from INDEX.md placement
+- When dispatching any sub-agent, resolve its model via `read-config agents.models.<basename> --project <repo>` and pass it explicitly at dispatch, never relying on inherited frontmatter; a resolved subagent model is never Fable

package/agents/plastic-intent-curator.md

@@ -11,7 +11,7 @@ description: |
   user: "Organize the intents"
   assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
   <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Intent Curator. Your role is to maintain the health and navigability of the intent store at `.plastic/`.

package/agents/plastic-intent-discovery.md

@@ -0,0 +1,37 @@
+---
+name: plastic-intent-discovery
+description: |
+  Use this agent for the What-stage context deposit when an intent is
+  activated: it primes Why with fresh QMD-sourced context before the spec is
+  written, and never writes the intent file itself. Examples:
+  <example>Context: An intent is being moved from Future to Active.
+  user: "Board this intent and gather what we already know"
+  assistant: "I'll use the intent-discovery agent to run QMD discovery and deposit findings to resources/"
+  <commentary>What-stage discovery runs at activation, before the lock and Why.</commentary></example>
+model: sonnet
+---
+
+You are the Plastic Intent Discovery agent. You own the What stage: at intent
+activation, before the lock is armed and Why begins, you gather the context
+that already exists and deposit it for the Why stage to consume.
+
+## Responsibilities
+1. **Read the intent's links.** Load the activating intent file's `chain` and
+   `sources` frontmatter fields.
+2. **Run QMD discovery first.** Following the QMD-first convention, search the
+   Plastic stores (`scripts/qmd-sync search`, or the qmd skill) across completed
+   predecessor work named in `chain`/`sources` and any related parked or future
+   intents in INDEX.md. Fall back to ripgrep over the stores only when QMD is
+   absent.
+3. **Deposit, never author.** Write your findings to
+   `resources/discovery--<slug>.md` in the intent directory ONLY. Never write
+   the intent file, spec.md, or any lifecycle deliverable: the lock-owner-only
+   write rule stays intact, and the Why-stage `plastic-brainstorming` agent is
+   the one that reads your deposit and enriches `## Context`.
+
+## Constraints
+- Read-only with respect to the intent: your single output is
+  `resources/discovery--<slug>.md`.
+- Never take the delivery lock; you run before it is armed.
+- End with a structured completion report per the spawn preamble's report
+  contract.

package/agents/plastic-planner.md

@@ -7,7 +7,7 @@ description: |
   user: "Plan the work for the active intent"
   assistant: "I'll use the planner to write plan.md, actions/, and checklist.md"
   <commentary>The plan and checklist unlock the code gate for Exec.</commentary></example>
-model: inherit
+model: opus
 ---
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.

package/agents/plastic-spec-specialist.md

@@ -7,7 +7,7 @@ description: |
   user: "Write the spec for the active intent"
   assistant: "I'll use the spec-specialist to produce spec.md from the template"
   <commentary>The spec is the deliverable that gates the move into How.</commentary></example>
-model: inherit
+model: sonnet
 ---
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.27",
+  "version": "1.0.0-beta.28",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/lib/agent_models.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Shared model-tier resolution for Plastic subagents (intent 116).
+#
+# TIER_DEFAULTS mirrors the shipped `agents/*.md` frontmatter so `read-config`
+# can answer `agents.models.<basename>` with the built-in default. The installer
+# does NOT use TIER_DEFAULTS: it applies only genuine config overrides via
+# `override_map`, so shipped frontmatter with no override passes through
+# unchanged.
+module AgentModels
+  # Claude Code aliases only (never pinned ids, never Fable). Keys are the agent
+  # file basenames without the `.md` extension.
+  TIER_DEFAULTS = {
+    "plastic-enforcer" => "opus",
+    "plastic-brainstorming" => "opus",
+    "plastic-planner" => "opus",
+    "plastic-spec-specialist" => "sonnet",
+    "plastic-executor" => "sonnet",
+    "plastic-intent-curator" => "sonnet",
+    "plastic-future-intent-researcher" => "sonnet",
+    "plastic-intent-discovery" => "sonnet"
+  }.freeze
+
+  module_function
+
+  # Pull the `agents.models` sub-hash out of a loaded config hash, tolerating a
+  # missing or malformed shape. Returns a plain { basename => model } hash.
+  def models_section(config)
+    return {} unless config.is_a?(Hash)
+    agents = config["agents"]
+    return {} unless agents.is_a?(Hash)
+    section = agents["models"]
+    section.is_a?(Hash) ? section : {}
+  end
+
+  # Override map for the installer: global overrides overlaid by project
+  # overrides (project wins). Defaults are intentionally excluded. Unknown agent
+  # keys are carried through as-is; install_agents simply never matches them to a
+  # copied file, so they are ignored without raising.
+  def override_map(project_config: {}, global_config: {})
+    models_section(global_config).merge(models_section(project_config))
+  end
+end

package/scripts/lib/installer_core.rb

@@ -7,6 +7,7 @@ require "fileutils"
 require "digest"
 require "time"
 require_relative "hook_registry"
+require_relative "agent_models"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/versions) and their tests can run
@@ -208,6 +209,7 @@ class InstallerCore
       "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
+      "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
@@ -391,7 +393,7 @@ class InstallerCore
     installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
 
     # Copy agent role files into <dir>/agents (manifest-tracked, pruned on update)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
@@ -416,7 +418,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -426,7 +428,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
-    installed += install_agents(File.join(config[:dir], "agents"))
+    installed += install_agents(File.join(config[:dir], "agents"), models: agent_model_overrides)
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -459,18 +461,51 @@ class InstallerCore
   # equivalents). Returns the installed destination paths so callers can append
   # them to `installed` before write_manifest (manifest + prune are then automatic).
   # No-op safe: returns [] when the package has no agents dir or it is empty.
-  def install_agents(agents_root)
+  def install_agents(agents_root, models: {})
     sources = Dir.glob(File.join(package_root, "agents", "*.md"))
     return [] if sources.empty?
 
     FileUtils.mkdir_p(agents_root)
     sources.map do |src|
       dest = File.join(agents_root, File.basename(src))
-      FileUtils.cp(src, dest)
+      basename = File.basename(src, ".md")
+      override = models[basename]
+      if override
+        File.write(dest, rewrite_model_line(File.read(src), override))
+      else
+        FileUtils.cp(src, dest)
+      end
       dest
     end
   end
 
+  # Rewrite the single top-level `model:` line in a YAML frontmatter block.
+  # Only the frontmatter (between the first two `---` fences) is touched.
+  def rewrite_model_line(content, model)
+    content.sub(/^model:[^\n]*$/, "model: #{model}")
+  end
+
+  # Resolve per-agent model overrides for this install: project config (when a
+  # project dir is known) overlaid on global config. Defaults are NOT included,
+  # so unconfigured agents keep their shipped frontmatter.
+  def agent_model_overrides(project_dir = nil)
+    global_config = load_config_yaml(File.join(plastic_home, "config.yml"))
+    project_config =
+      if project_dir
+        load_config_yaml(File.join(project_dir, ".plastic_store", "config.yml"))
+      else
+        {}
+      end
+    AgentModels.override_map(project_config: project_config, global_config: global_config)
+  end
+
+  def load_config_yaml(path)
+    return {} unless File.exist?(path)
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
   # --- Legacy plugin migration ---
 
   # Earlier versions registered Plastic as a local marketplace plugin

package/scripts/read-config

@@ -9,6 +9,7 @@
 
 require "yaml"
 require "json"
+require_relative "lib/agent_models"
 
 DEFAULTS = {
   "version" => 3,
@@ -23,6 +24,9 @@ DEFAULTS = {
     "type" => "claude-code",
     "parallel_mode" => "linear"
   },
+  "agents" => {
+    "models" => AgentModels::TIER_DEFAULTS
+  },
   "architect" => {
     "style" => nil
   }

package/skills/auto/SKILL.md

@@ -10,6 +10,12 @@ description: >-
 
 Announce: "Taking over intent [ID] — [name] for autonomous delivery."
 
+**Advisory (not a gate).** At auto-mode start, recommend once that the user run this
+orchestrating main session on the best available thinking model (Fable, Opus, or whatever
+supersedes them) for the sharpest gating and synthesis. This is advice only: it changes no
+behavior and blocks nothing if ignored. It concerns the human's MAIN session; dispatched
+subagents keep their pinned tier and never resolve to Fable.
+
 ## Precondition
 
 An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic-creating-intent."
@@ -85,6 +91,8 @@ Dispatch rule: sequential, one specialist per stage on one branch (the deliverab
 
 Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
 
+Dispatch-time model contract (belt-and-braces): alongside the preamble, resolve each specialist's model through the config chain (`read-config agents.models.<basename> --project <repo>`: project override, then global, then the shipped tier default) and pass it explicitly at dispatch. Never rely on the dispatched role's frontmatter alone; a resolved subagent model is never Fable.
+
 Completion report (require-then-synthesize): every dispatched specialist MUST end with a structured completion report as its final message. The preamble's `REPORT_CONTRACT` injects this and the role prompts carry the per-role format (see `references/agent-report-contract.md`). Because child-agent honor is best-effort across harnesses, this is decision-shaping, not a hard block. When a specialist returns no usable report (it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), run `scripts/agent-report <intent_dir> --role <role>` to synthesize a deterministic filesystem-derived report so the handoff account always exists. Use the agent-authored report when present, the synthesized one otherwise.
 
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.

package/skills/intent-discovery/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: plastic-intent-discovery
+description: >-
+  What-stage context deposit at intent activation: run QMD discovery over the
+  intent's chain/sources and related parked intents, and write findings to
+  resources/discovery--<slug>.md for the Why stage to consume. Use when an intent
+  is activated (moved from Future to Active), before the lock is armed and Why
+  begins. Never writes the intent file itself.
+---
+
+# Intent Discovery — What-stage context deposit
+
+Announce: "Discovering context for intent [ID] — [name]."
+
+Runs once, at intent activation, before the lock and Why. It gathers what is
+already known so Why does not start cold, and deposits it as a resource the
+Why-stage brainstorming agent reads.
+
+## When it fires
+Inside `plastic-intent-starting`, at the moment the intent moves from
+`## Future` to `## Active` (before the bridge is armed). Dispatched as the
+`plastic-intent-discovery` background agent.
+
+## What it does
+1. **Read the intent's links.** Load the activating intent file's `chain` and
+   `sources` frontmatter fields.
+2. **QMD-first discovery.** Search the Plastic stores with
+   `scripts/qmd-sync search "<terms>"` (or the `qmd` skill), scoped to the
+   relevant `plastic-*` collections, across completed predecessor work named in
+   `chain`/`sources` and any related parked/future intents in INDEX.md. Fall back
+   to ripgrep over the stores only when QMD is absent.
+3. **Deposit, never author.** Write findings to
+   `resources/discovery--<slug>.md` in the intent directory ONLY. Do not write
+   the intent file, spec.md, or any lifecycle deliverable. The lock-owner-only
+   write rule stays intact; the Why-stage `plastic-brainstorming` agent reads the
+   deposit and enriches `## Context`.
+
+## Stage coverage
+This is the What-stage agent in the one-agent-per-stage table (What:
+intent-discovery, Why: brainstorming + spec-specialist, How: planner, Exec:
+executor, Done: intent-curator).
+
+## Boundaries
+- Single output: `resources/discovery--<slug>.md`.
+- Never takes the delivery lock (it runs before the lock is armed).
+- Advisory input to Why, not a gate.

package/skills/intent-starting/SKILL.md

@@ -34,6 +34,14 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
+1a. **Dispatch What-stage discovery (before the lock).** Right after activation and before
+   arming the bridge, dispatch the `plastic-intent-discovery` agent (see the
+   `plastic-intent-discovery` skill). Resolve its model explicitly and pass it at dispatch
+   time (belt-and-braces): `read-config agents.models.plastic-intent-discovery --project
+   <repo>`. The agent runs QMD discovery over the intent's `chain`/`sources` and deposits
+   findings to `resources/discovery--<slug>.md` only; it never writes the intent file, so the
+   lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
+   discovery yields nothing, proceed to the lock normally.
 2. **Self-heal the lock state first.** Run:
    `ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <STORE>/<dir>`
    This is the one repair function (same one /plastic-lock exposes): it removes

package/templates/config.yml

@@ -11,3 +11,11 @@ agent:
   parallel_mode: linear
 architect:
   style:
+
+# Per-agent model override (intent 116). Uncomment and set to a Claude Code
+# alias (opus, sonnet, haiku) to override the shipped tier for one agent. With
+# no entry, the shipped default applies. Never resolves to Fable.
+# agents:
+#   models:
+#     plastic-executor: sonnet
+#     plastic-enforcer: opus