@zalom/plastic 1.0.0-beta.9 → 1.0.1

package/README.md

@@ -1,124 +1,140 @@
 # Plastic
 
-> **Alpha software.** Expect breaking changes between releases.
-> Install: `npx @zalom/plastic@alpha --claude`
+[![npm version](https://img.shields.io/npm/v/@zalom/plastic)](https://www.npmjs.com/package/@zalom/plastic)
+[![npm downloads](https://img.shields.io/npm/dm/@zalom/plastic)](https://www.npmjs.com/package/@zalom/plastic)
+[![license](https://img.shields.io/npm/l/@zalom/plastic)](LICENSE)
+[![CI](https://github.com/zalom/plastic/actions/workflows/test.yml/badge.svg)](https://github.com/zalom/plastic/actions/workflows/test.yml)
 
-Intent-driven idea development system for AI coding agents. Named after
-**neuroplasticity**: adaptive, malleable, dynamic, resilient.
+## Intent-based idea development system for AI-assisted work.
 
-Plastic thinks in **intents**, not tasks. An intent is a desire, something
-you want to accomplish, explore, or understand. Intents are atomic thoughts
-that get developed through two nested processes.
+> Plastic is a system that turns an intent, a vague goal or idea into a durable, linked record of discovery, decisions, delivery, and outcomes - it serves as a physical brain for your intents.
 
-## The Two Cycles
+[[Install]](#start-in-60-seconds) [[See it work]](#built-with-plastic) [[Read the manifesto]](MANIFESTO.md)
 
-**Coordinator loop (B→O→R):** Brainstorm → Organize → Review. The human and
-agent explore ideas, structure them into intents, and validate the results.
-This loop runs continuously across sessions.
 
-**Intent lifecycle (W→W→H→E):** Why → What → How → Execute. Each intent moves
-from motivation through specification, planning, to delivery. Intents produce
-artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
+## Why Plastic?
 
-## How Plastic Works
+You do not always start with a task.
 
-Plastic is a **thinking system**, a blueprint for taking a desire from intent to
-delivery. It splits the work in two:
+You start with an intent, something like:
 
-- **The blueprint (deterministic).** The conventions, templates, directory structure,
-  lifecycle, and linking rules. This is *how to fill in the work*, and it comes out
-  identically no matter who or what is working.
-- **The brain (non-deterministic).** The human or LLM that does the actual thinking.
-  Plastic never replaces it. It only **steers and validates** it.
+> “I want users who are locked out to recover access safely.”
 
-Determinism lives in the **form** of the work (section sets, ordering, schemas, naming,
-IDs, file layout), never in the brain's reasoning. The framework stays constant while the
-thinking varies. Run Plastic on Claude Code, Codex, Hermes, OpenClaw, or by hand on paper
-in Obsidian or Word, and the only thing that changes is the *quality of thought*. The
-proof is the paper test: if a person with no tooling and no AI can reproduce a
-correctly-shaped intent, the determinism is in the form, not the agent.
+Plastic delivers this intent in successive stages: What -> Why -> How -> Exec.
 
-**Deterministic by design, free by intent.** The rigid part is rigid on purpose. It is
-what makes work portable, reviewable, and resumable across any agent. The free part is
-free on purpose. It is where the brain's creativity lives. Plastic draws the line between
-the two and holds it.
+The result is a readable, linked record of how an idea became real.
 
-**Harnesses are how it holds the line.** Shared harnesses (conventions, templates, and
-directory structure) constrain humans and agents alike. Agent-extra harnesses (evals that
-check a skill's output, plus hooks and instructions that steer reasoning) give an agent
-the instincts a careful person already has: stop and save state, leave a note when the
-context runs out, never plan before specifying.
+**Plastic gives changing minds a durable way to develop ideas into work.**
 
-This is **intent-driven delivery**, a new shape for the software lifecycle in the age of
-agentic engineering. The unit of work is an *intent*, not a ticket, and every intent
-carries its own spec, plan, checklist, and outcome as it moves through Why, What, How, and
-Execute. What you get is agent-agnostic, auditable, and additive: a knowledge graph of
-*why* things were built, not just what.
+Plastic is named after neuroplasticity: the brain's amazing ability to change and adapt. It rewires itself as you learn new things, form memories, or heal from injuries. Instead of being fixed like a computer, your brain is more like clay. It constantly reshapes itself based on your experiences.
 
-## Install
+### What Plastic does?
 
-Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
+Plastic keeps the shape of the work stable - **deterministic** work system:
+- one durable intent
+- one visible lifecycle
+- one place for context, decisions, plans, and outcomes
+- links between the ideas that shaped the work and the ideas it creates
 
-```bash
-# Alpha (current, active development)
-npx @zalom/plastic@alpha --claude
+Plastic leaves the human or AI model free to think - **non-deterministic** thinking system.
 
-# Beta (when available, API-stable, bug hunting)
-npx @zalom/plastic@beta --claude
+Plastic makes that thinking legible, resumable, and useful later.
 
-# Stable (when available, general use)
-npx @zalom/plastic --claude
-```
+## Who is Plastic for?
 
-Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
-`--all` for all supported agents.
+**Plastic is built for an AI-native developer, technical founder, or
+independent builder who works across multiple sessions, has ideas before
+they have tickets, and feels the cost of losing reasoning between agents,
+contexts, and days.**
 
-Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --claude`).
-Bun is never required.
+## What it solves?
 
-Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
-`plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a Claude Code
-plugin; re-running the installer auto-removes any legacy plugin registration.
+It solves problems that builder already feels:
 
-### Updating
+- "I want to keep a record of my work - what I worked on, why I worked on it, how it was built"
+- "I do not need another TODO list."
+- "I do not want my work trapped inside a chat."
+- "I want to explore without losing the decision trail."
+- "I want a better model or new agent to inherit the work, not restart it."
+- "I want my ideas to compound."
 
-From within your agent, say "update plastic" or run:
+## Start in 60 seconds
+
+One command installs Plastic for your agent:
 
 ```bash
-npx @zalom/plastic@alpha --claude
+npx @zalom/plastic --claude
 ```
 
-The `plastic-update` command shows available versions across all channels and
-lets you choose which to install.
+Then load the conventions and begin:
+
+```bash
+/clear
+
+I would like to learn more about Plastic and how it works.
+```
+
+Describe what you want in plain words, like "add a `--version` flag." Plastic
+scaffolds the intent and walks it through What, Why, How, and Exec. For the
+full path, read [your first intent in 10 minutes](docs/guides/your-first-intent-in-10-minutes.md).
+
+## How Plastic works?
+
+A task assumes you already know the work.
+
+An intent begins earlier:
+something you want to accomplish, explore, or understand.
+
+Plastic helps you develop it until it becomes a decision,
+a plan, a delivery, and a reusable piece of project history.
+
+### Register What and start with Why
+
+Plastic delivers all work through successive stages ->
+
+| Stage | Meaning                                         | Developed concept  | On-disk artifact (evidence)                    |
+| ----- | ----------------------------------------------- | ------------------ | ---------------------------------------------- |
+| What  | What is the intention?                          | Intent             | {id}--slug.md                                  |
+| Why   | What context, evidence, and decisions shape it? | Specification      | spec.md                                        |
+| How   | What is the plan?                               | Plan and checklist | plan.md, checklist.md, actions/ACTION_1.md ... ACTION_N.md |
+| Exec  | What was actually delivered?                    | Outcome            | outcome.md                                     |
+
+
+## Compatibility and ownership
+
+- Native installers for Claude (Codex, Hermes, and and others coming soon).
+- Plain Markdown plus Git. The work stays in files you own.
+- Personal stores by default.
+- Guided delivery with a human at every gate, or autonomous delivery when you
+  ask for it.
+
+Plastic needs Ruby (already on macOS and Linux) and Node.js 18 or later. Bun
+users can run `bunx` in place of `npx`; Bun is never required.
 
-## Quick Start
+## Built with Plastic
 
-After installation, run `/clear` to load Plastic conventions, then:
+Plastic is developed through Plastic.
 
-1. Say "new intent" or run `/plastic-creating-intent` to create your first intent
-2. Describe what you want to accomplish
-3. Use `/plastic-brainstorming` to explore the design
-4. Use `/plastic-writing-plans` to create an implementation plan
-5. Use `/plastic-executing-plan` to deliver it
+The roadmap, intent history, plans, decisions, and outcomes
+behind releases are part of the repository, not a hidden process.
 
-Or say "auto" to let the agent handle the full lifecycle autonomously.
+See the current [roadmap](ROADMAP.md) and [changelog](CHANGELOG.md).
 
 ## Documentation
 
 - [`docs/architecture.md`](docs/architecture.md): system structure, the two
-  processes, the store layout, and the component map.
-- [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic, the
-  determinism breakdown, and the harness system.
+  processes, the store layout, and the full stage table.
+- [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic
+  and how the harness works.
+- [`docs/guides/`](docs/guides/index.md): task-oriented guides, from your
+  first intent in 10 minutes to picking a delivery mode.
 
 ## Conventions
 
-All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`
-during installation. Run `plastic-doctor` to check installation health.
-`plastic-doctor --core` runs a binary install-integrity check (compares files
-against the install manifests; pass or error). `plastic-doctor --store` checks
-store state (intents, INDEX sections, conventions) and can be scoped to
-`global` or a project slug. The full `plastic-doctor` runs all checks and is
-run automatically after every update.
+Plastic conventions live in `PLASTIC.md`, distributed to `~/.plastic/PLASTIC.md`
+and overwritten on every update. Project-specific rules live in `AGENTS.md`.
+Run `plastic-doctor` to check installation health; it compares files against
+the manifests, checks store state, and runs automatically after every update.
 
 ## License
 

package/agents/plastic-brainstorming.md

@@ -1,13 +1,9 @@
 ---
 name: plastic-brainstorming
 description: |
-  Use this agent for the Why-stage exploration of an active intent in auto mode:
-  it enriches context and records decisions before a spec is written. Examples:
-  <example>Context: An intent has a What but a thin Why.
-  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
+  Use for the Why-stage exploration of an active intent in auto mode: enrich the
+  intent's Context and record its Decisions before the spec is written.
+model: opus
 ---
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
@@ -19,7 +15,13 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code
 2. **Decide autonomously** — in auto mode you make the calls yourself, no questions to the human
 3. **Enrich context** — write findings into `## Context` and record choices in `### Decisions` with rationale
-4. **Hand off** — leave the Why stage ready for the spec-specialist to consolidate into a spec
+4. **Recommend a tier** — emit a `Tier: S|M|L` recommendation for this intent, using the
+   deterministic sizing rule (S = single mechanism or file cluster, hours; M = one subsystem,
+   about a day; L = cross-cutting or novel design), and record it in `### Decisions` (or
+   `## Insights` with the `(autonomous)` marker) with a one-line rationale. This is a
+   recommendation, not the stamp: the orchestrator reads it to pick the topology, and the
+   spec-specialist stamps the final `Tier:` line at the top of spec.md.
+5. **Hand off** — leave the Why stage ready for the spec-specialist to consolidate into a spec
 
 ## How You Work
 
@@ -31,11 +33,12 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the brainstorming payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the brainstorming payload:
 
 - Decisions recorded in `### Decisions`, each with its one-line rationale
 - Context enriched: what was researched and the key findings
 - Open questions resolved, and any deliberately left for the spec
+- Tier recommendation (`S|M|L`) and its one-line rationale
 
 ## Constraints
 

package/agents/plastic-enforcer.md

@@ -1,24 +1,55 @@
 ---
 name: plastic-enforcer
 description: |
-  Use this agent as the auto-mode orchestrator: it spins up the team, sequences the
-  specialists, owns every gate, and runs the final review. Examples:
-  <example>Context: User triggers auto on an active intent.
-  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
+  Use as the auto-mode orchestrator: it spins up the team, sequences the
+  specialists, owns every gate, and runs the final review.
+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
-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)
+2. **Size the intent at Why** — deterministically size S/M/L (S = single mechanism or file
+   cluster, hours; M = one subsystem, about a day; L = cross-cutting or novel design), then
+   pick the per-tier topology BEFORE How begins. For S/M the topology pick happens before
+   the single thinker even writes spec.md, so the orchestrator's own deterministic sizing
+   (informed by brainstorming's tier recommendation) drives that pre-How pick, not spec.md.
+   The `Tier: S|M|L` line stamped at the top of spec.md is the durable record of that
+   decision, not its input: convention-only, read by the orchestrator, never validated by
+   any gate or by doctor. Deterministic sizing keeps the two in agreement.
+3. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
+4. **Sequence the team** — dispatch specialists per the chosen topology with a constructed
+   context bundle:
+   - S/M: ONE thinker agent, one boot, two stations — it writes spec.md, then plan.md +
+     checklist.md, in a single context. Sections may be one line each; plan.md carries the
+     checklist rationale inline; `actions/` files appear only for L. S may skip the QMD
+     discovery deposit when chain and sources are both empty. A sonnet executor implements.
+   - L: today's full team, one specialist per stage (brainstorming, spec-specialist, planner,
+     executor), each in a fresh context.
+
+**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.
+5. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
+6. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
+
+Never-cut list at any tier: the independent reviewer (a separate agent, fresh context, never
+the maker), `outcome.md` as truth of delivery, the delivery lock, worktree isolation, intent
+creation via skill, INDEX as status truth, the QMD reindex at End. Lightness collapses
+ceremony, never these guarantees.
 
 ## How You Work
 
@@ -28,9 +59,18 @@ You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole
 4. Dispatch and review by default through Plastic's native engine, `plastic-executing-plan` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
 5. At the final gate, dispatch an independent reviewer subagent, then complete the intent
 
+## Human-facing stage reporting
+
+At each gate, the orchestrator briefs the human in EM-to-CTO voice: impact first, the one risk
+that matters, then the decision left to them. The shape and per-stage content live in
+`skills/auto/references/human-report-contract.md`; follow it rather than improvising a report.
+This is separate from the intent 74 report contract (`skills/auto/references/agent-report-contract.md`),
+which is the internal, structured handoff a dispatched specialist sends back to the orchestrator.
+The orchestrator consumes that internal report to write the human briefing; the two never merge.
+
 ## Constraints
 
-- Enforce gates manually; do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in headless or background runs
+- Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs
 - You never delegate gate ownership; the orchestrator is always the gate-keeper
 - Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
 - Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle

package/agents/plastic-executor.md

@@ -1,13 +1,9 @@
 ---
 name: plastic-executor
 description: |
-  Use this agent for the Exec stage in auto mode: it implements the actions, checks
-  off the checklist, and drives the test suite green. Examples:
-  <example>Context: plan.md and checklist.md exist for the active intent.
-  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
+  Use for the Exec stage in auto mode: implement the actions, check off the
+  checklist, and drive the test suite green.
+model: sonnet
 ---
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
@@ -18,12 +14,16 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Implement the actions** — make the code changes for each action in order
 2. **Track progress** — check off `checklist.md` items as they complete
-3. **Record insights** — append observations to `## Insights` with the `(autonomous)` marker
+3. **Record insights** — capture durable discoveries and report them in the `insights:` field; persist each to `## Insights` via the `insight-append` helper (`scripts/insight-append <intent_dir> <text> --stage Exec --author "plastic-executor (autonomous)"`), the blessed write path that stamps the `{utc-iso8601} · {stage} · {author}` prefix
 4. **Prove it green** — run the full test suite and reach zero failures before reporting done
 
 ## How You Work
 
-1. Receive (input handoff): `plan.md`, `checklist.md`, and `actions/` from the planner
+1. Receive (input handoff): `plan.md` and `checklist.md` from the planner (plus
+   `ACTION_N.md` files inside `actions/` at L; at S/M the `actions/` directory exists but
+   stays empty, so read the tier fork from the inline plan-as-checklist in plan.md
+   instead). For S/M intents you run on the sonnet default, the collapsed topology's
+   implementer; behavior is otherwise unchanged.
 2. Work one action at a time, preferring safe, non-destructive routes
 3. Edit project code (the gate is open now that plan and checklist exist)
 4. Run the full suite, iterate to zero failures and zero errors
@@ -32,7 +32,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the executor payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the executor payload:
 
 - Actions implemented this turn, mapped to checklist items checked off (checked / total)
 - A summary of the code changed (files and the shape of the change)

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

@@ -1,14 +1,9 @@
 ---
 name: plastic-future-intent-researcher
 description: |
-  Use this agent to research future intents autonomously. Picks up parked
-  intents from INDEX.md, investigates them via web search and codebase analysis,
-  and writes findings into the intent. Examples:
-  <example>Context: There are future intents parked in the index.
-  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
+  Use to research a parked future intent autonomously via web search and codebase
+  analysis, writing the findings into the intent.
+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 +31,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

@@ -1,17 +1,9 @@
 ---
 name: plastic-intent-curator
 description: |
-  Use this agent when completing or reviewing intents, reorganizing the index,
-  or when the intent store needs maintenance. Examples:
-  <example>Context: User has finished implementing a feature.
-  user: "This intent is done, clean up the index"
-  assistant: "I'll use the intent-curator agent to update the intent status and reorganize INDEX.md"
-  <commentary>Intent lifecycle change triggers curator for index maintenance.</commentary></example>
-  <example>Context: The intent store has grown and clusters need review.
-  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
+  Use when completing or reviewing intents, reorganizing INDEX.md, or maintaining
+  the intent store.
+model: sonnet
 ---
 
 You are the Plastic Intent Curator. Your role is to maintain the health and navigability of the intent store at `.plastic/`.
@@ -23,6 +15,7 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 3. **Link discovery** — suggest connections between intents that share topics but aren't linked
 4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
 5. **Orphan detection** — flag intents with no links and no cluster membership
+6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
 
 ## How You Work
 
@@ -31,12 +24,17 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
 3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
-5. On a terminal-state transition: whenever you move an intent to Completed OR Abandoned, refresh the QMD index for that store so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
-6. Report what you changed
+5. On a terminal-state transition (Completed OR Abandoned), run the closing acts in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
+   a. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
+   b. Stamp the terminal savepoint bookend (intent 81) recording the disposition. Idempotent.
+   c. Refresh the QMD index for that store LAST, after the terminal move, outcome.md, and savepoint, so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
+6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
+7. Report what you changed
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
 - You never create new intents — that's the creating-intent skill's job
-- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
+- For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
 - For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

package/agents/plastic-intent-discovery.md

@@ -0,0 +1,35 @@
+---
+name: plastic-intent-discovery
+description: |
+  Use for the What-stage context deposit when an intent is activated: run QMD
+  discovery and write findings to resources/, never the intent file itself.
+model: sonnet
+---
+
+You are the Plastic Intent Discovery agent. You own the What stage: at intent
+activation, after the lock is armed and before Why begins, under the lock as
+the owner session, 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`.
+- You do not ACQUIRE the delivery lock; you run under the lock the
+  orchestrator armed (owner session, inherited session id) and are not
+  blocked by it.
+- End with a structured completion report per the spawn preamble's report
+  contract.

package/agents/plastic-planner.md

@@ -1,13 +1,9 @@
 ---
 name: plastic-planner
 description: |
-  Use this agent for the How stage in auto mode: it turns a spec.md into a plan,
-  self-contained action files, and a checklist. Examples:
-  <example>Context: spec.md exists and the intent is ready to plan.
-  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
+  Use for the How stage in auto mode: turn spec.md into plan.md, self-contained
+  action files, and checklist.md.
+model: opus
 ---
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
@@ -18,8 +14,14 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Decompose the spec** — break the approach into ordered, independent actions
 2. **Write the plan** — produce `plan.md` with numbered tasks and verification
-3. **Write self-contained actions** — one `actions/ACTION_N.md` per task, each runnable on its own
-4. **Write the checklist** — `checklist.md` as the execution registry covering every action
+3. **Write self-contained actions, tier-forked**:
+   - S/M: `plan.md` carries the checklist rationale INLINE; do NOT write
+     `actions/ACTION_N.md` files. Sections may be one line each.
+   - L: keep today's shape — one self-contained `actions/ACTION_N.md` per task.
+4. **Write the checklist** — `checklist.md` as the execution registry covering every action.
+   `checklist.md` exists at every tier: the file set does not change by tier, only depth
+   (inline vs action files) and agent topology do. plan.md + checklist.md are the two files
+   that open the code gate at every tier.
 
 ## How You Work
 
@@ -31,11 +33,12 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the planner payload, which EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the planner payload, which EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR:
 
 - The ordered actions, one line each: what the action does and how it is verified
 - Decomposition rationale: why this order, and why the actions are independent
 - Checklist coverage: the item count, and that every action plus suite-green is covered
+- Which tier shape was produced: inline plan-as-checklist (S/M) or full `actions/` (L)
 
 The plan is an argument; the orchestrator gates on whether that argument is sound before any code is written, so make the report make that case.
 
@@ -45,3 +48,5 @@ The plan is an argument; the orchestrator gates on whether that argument is soun
 - You write only intent-store files (`plan.md`, `actions/`, `checklist.md`); no project code
 - The code gate stays closed until `plan.md` and `checklist.md` exist, so produce both
 - Keep each action self-contained so the executor can run them one at a time
+- The `actions/` empty-directory git-tracking edge (present only within one same-session
+  local delivery) is out of scope; do not add a `.gitkeep` or a guard for it here

package/agents/plastic-spec-specialist.md

@@ -1,13 +1,9 @@
 ---
 name: plastic-spec-specialist
 description: |
-  Use this agent at the Why-to-How boundary in auto mode: it consolidates an
-  enriched Why into a spec.md from the spec template. Examples:
-  <example>Context: Why exploration is complete and decisions are recorded.
-  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
+  Use at the Why-to-How boundary in auto mode: consolidate the enriched Why into
+  spec.md from the spec template.
+model: sonnet
 ---
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
@@ -18,8 +14,16 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec
 2. **Follow the template** — produce `spec.md` with Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria
-3. **Make it the contract** — the spec is what the planner and executor build against
-4. **Hand off** — leave a complete `spec.md` ready for the planner
+3. **Stamp the tier** — write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
+   Spec:` heading, taking the value from the orchestrator's sizing / the brainstorming
+   recommendation. This line is convention-only: read by the orchestrator, never validated by
+   any gate or by doctor. It is an extra top line, not a template field, so no template changes.
+4. **Accept collapsed sections at S/M** — a spec.md whose Problem, Goals, Non-Goals, Approach,
+   Decisions, or Acceptance Criteria sections are a single line each is still a complete
+   spec.md under the same-structure invariant; do not pad it. The gates check file existence
+   and realness, not artifact depth, so a collapsed-but-real spec passes.
+5. **Make it the contract** — the spec is what the planner and executor build against
+6. **Hand off** — leave a complete `spec.md` ready for the planner
 
 ## How You Work
 
@@ -31,11 +35,12 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## Completion Report
 
-END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the spec payload:
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers, insights) plus the spec payload:
 
 - The spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria)
 - How the recorded decisions resolved into the chosen approach
 - The acceptance-criteria count, so the planner knows the surface to cover
+- The stamped `Tier:` value
 
 ## Constraints