@zalom/plastic 1.0.0-beta.35 → 1.0.0-beta.37

package/PLASTIC-reference.md

@@ -0,0 +1,133 @@
+# Plastic - Reference
+
+> **This file is maintained by Plastic.** It will be overwritten when the
+> plugin is updated. It holds reference material: read it on demand, it is
+> not injected at session start.
+
+### Structural maintenance and revisions.md
+
+When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
+frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
+`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
+(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
+with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
+content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
+its full content embedded and the original is deleted.
+
+Violation tags (starter set, free-text tags allowed):
+- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
+- `phantom-section`: a section referenced but not present or not sanctioned
+- `stray-file`: a file that does not belong in the intent directory
+- `dangling-ref`: a link or reference to something that no longer exists
+- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
+- `broken-source`: a sources frontmatter edge to an intent that no longer exists
+- `misplaced-content`: content that belongs in a different artifact or section
+
+## Two Processes
+
+| Process | Scope | Type | Actor |
+|---|---|---|---|
+| **Build → Observe → Repeat** | The system | Continuous loop | Coordinator |
+| **What → Why → How → Exec** | One intent | Finite lifecycle | Agent |
+
+B→O→R is the Coordinator's heartbeat. W→W→H→E is what happens inside each intent.
+The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
+
+## Defaults-First
+
+Plastic stands on its own. Skills and agents use Plastic's own defaults; an
+external skill (for example `superpowers:*`) is opt-in, never load-bearing.
+
+- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
+  the default. Delegate to an external skill only when (a) it is available in the
+  harness, or (b) the user explicitly asks for it. A user without that plugin must
+  still get the core behavior.
+- **Phrase external skills as enhancements.** Write "use Plastic's native X by
+  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
+  to it" never "delegate to `superpowers:<skill>`" as the only path.
+- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
+  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
+  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
+  the same detect-then-skip pattern, so a missing tool never crashes a session.
+- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
+  the cost of running Plastic, not silent coupling. The principle targets accidental
+  dependence on external skills doing work Plastic should do itself.
+
+## Roadmaps
+
+Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
+is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
+release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
+close, and consume one.
+
+File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
+inside `store/` (store holds intent directories, not project artifacts). For a project that is its
+root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
+`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
+in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
+a sibling subdirectory scaffolded once with a `.gitkeep`.
+
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
+append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
+an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
+waves run sequentially, top to bottom.
+
+Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
+on any conflict INDEX wins and the roadmap entry is corrected to match.
+
+**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
+checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
+line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
+engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
+or codenames, ending with a link
+to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
+opening the file with no other context can tell what shipped, what is running now, and what is
+next in under a minute.
+
+**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
+loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
+Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
+running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
+after a stop. This section only states the relationship and points to intent 69 as the future
+consumer; it does not change intent 69's own design.
+
+## Context-economy measurement buckets (84a)
+
+Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
+
+- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
+- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
+  in the transcript.
+- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
+
+## Deprecation Process
+
+Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
+pre-1.0, a satisfied deprecation (its migration is already done on installed machines) may be
+removed immediately instead of waiting for its declared `removal` version. From `1.0.0` on,
+the steady-state grace rule applies (removal at least two minors ahead). For the full process,
+severity levels, and the pre-1.0 exception, see the `plastic-releasing` skill.
+
+## Skills Reference
+
+Detailed conventions live inside the skills that use them, not in this file.
+
+| Topic | Skill | References in skill |
+|-------|-------|-------------------|
+| Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
+| Brainstorming, spec writing | `plastic-brainstorming` | — |
+| Planning, actions | `plastic-writing-plans` | — |
+| Execution, delivery | `plastic-executing-plan` | — |
+| Autonomous delivery | `plastic-auto` | agent architecture |
+| Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
+| Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
+| Projects, hubs | `plastic-creating-project` | hubs, project stores |
+| Provision a project store | `plastic-add-project-store` | project stores |
+| Index maintenance | `plastic-managing-index` | — |
+| Releases, deprecations | `plastic-releasing` | deprecation process |
+| Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
+| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
+| Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
+| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |
+

package/PLASTIC.md

@@ -1,31 +1,33 @@
-# Plastic — Conventions
+# Plastic: Conventions
 
 > **This file is maintained by Plastic.** It will be overwritten when the
-> plugin is updated. Do not modify — your changes will be lost.
+> plugin is updated. Do not modify it: your changes will be lost.
 > For project-specific rules, use `AGENTS.md` instead.
 
+See `PLASTIC-reference.md` for reference material: read it on demand, it is not injected at session start.
+
 ## What is an Intent
 
 A directory in the store containing `{ID}--{slug}.md` and optional supporting files.
-It represents a desire — something a human or agent wants to accomplish, explore, or understand.
+It represents a desire: something a human or agent wants to accomplish, explore, or understand.
 
 ```
 store/
   ID--three-to-five-words/
-    {ID}--{slug}.md       # required — the intent itself
-    spec.md               # optional — specification (Why deliverable)
-    plan.md               # optional — implementation plan (How deliverable)
-    checklist.md          # optional — execution registry (How deliverable)
-    outcome.md            # optional — detailed result (Exec deliverable)
-    actions/              # optional — individual work items
-    resources/            # optional — research, references, screenshots, diagrams
-    savepoint.md          # optional — deterministic cycle-step ledger (auto-written)
+    {ID}--{slug}.md       # required - the intent itself
+    spec.md               # optional - specification (Why deliverable)
+    plan.md               # optional - implementation plan (How deliverable)
+    checklist.md          # optional - execution registry (How deliverable)
+    outcome.md            # optional - detailed result (Exec deliverable)
+    actions/              # optional - individual work items
+    resources/            # optional - research, references, screenshots, diagrams
+    savepoint.md          # optional - deterministic cycle-step ledger (auto-written)
     revisions.md          # optional - append-only structural-maintenance audit trail
 ```
 
 Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
-roles. Supporting artifacts that aren't lifecycle deliverables — research reports,
-reference docs, external API snapshots, screenshots, diagrams — go in `resources/`.
+roles. Supporting artifacts that aren't lifecycle deliverables (research reports,
+reference docs, external API snapshots, screenshots, diagrams) go in `resources/`.
 Name files inside as `{type}--{description}.md` (e.g., `deep-research--gsd-core.md`).
 
 `revisions.md` is an optional, append-only structural-maintenance audit trail. It is not a
@@ -36,25 +38,6 @@ inside `revisions.md` (newest entry at the bottom, one entry per relocated item)
 lost and the delivered meaning is never altered. Changing what an intent delivered is a new intent,
 not a revision.
 
-### Structural maintenance and revisions.md
-
-When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
-frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
-`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
-(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
-with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
-content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
-its full content embedded and the original is deleted.
-
-Violation tags (starter set, free-text tags allowed):
-- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
-- `phantom-section`: a section referenced but not present or not sanctioned
-- `stray-file`: a file that does not belong in the intent directory
-- `dangling-ref`: a link or reference to something that no longer exists
-- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
-- `broken-source`: a sources frontmatter edge to an intent that no longer exists
-- `misplaced-content`: content that belongs in a different artifact or section
-
 ## Frontmatter
 
 Identity and knowledge graph only. Nothing operational.
@@ -106,16 +89,6 @@ tags: [plastic, architecture]
 - IDs use Luhmann's alternating convention: `1` → `1a` → `1a1` → `1a1a`
 - Multiple branches increment: `1a`, `1b`, `1c`
 
-## Two Processes
-
-| Process | Scope | Type | Actor |
-|---|---|---|---|
-| **Build → Observe → Repeat** | The system | Continuous loop | Coordinator |
-| **What → Why → How → Exec** | One intent | Finite lifecycle | Agent |
-
-B→O→R is the Coordinator's heartbeat. W→W→H→E is what happens inside each intent.
-The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
-
 ## Lifecycle Stages
 
 | Stage | Section | Deliverable | Detail |
@@ -222,7 +195,7 @@ the intent directory ONLY. It never writes the intent file, `spec.md`, or any ot
 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
+`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
 files-on-disk, and the ledger is rebuildable. It exists so a resuming agent reads the cycle's
@@ -234,7 +207,7 @@ succession at a glance (last line = where we are).
   `docs/specs/`, `researches/`, or similar. All meta-artifacts go in
   `~/.plastic/store/ID--slug/` or the project store equivalent.
 - **Code goes in the project. Everything else goes in the intent.**
-  Plans, specs, checklists, savepoints — all in the intent directory.
+  Plans, specs, checklists, savepoints: all in the intent directory.
 - **The global store is never pushed.** `~/.plastic/` is git-tracked locally
   but contains sensitive data. Never push to a remote.
 - **Agent-created repos are private by default.** Use `gh repo create --private`.
@@ -247,26 +220,6 @@ succession at a glance (last line = where we are).
   brainstorming, writing-plans, etc., Plastic's directory rules override
   their default output paths.
 
-## Defaults-First
-
-Plastic stands on its own. Skills and agents use Plastic's own defaults; an
-external skill (for example `superpowers:*`) is opt-in, never load-bearing.
-
-- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
-  the default. Delegate to an external skill only when (a) it is available in the
-  harness, or (b) the user explicitly asks for it. A user without that plugin must
-  still get the core behavior.
-- **Phrase external skills as enhancements.** Write "use Plastic's native X by
-  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
-  to it" never "delegate to `superpowers:<skill>`" as the only path.
-- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
-  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
-  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
-  the same detect-then-skip pattern, so a missing tool never crashes a session.
-- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
-  the cost of running Plastic, not silent coupling. The principle targets accidental
-  dependence on external skills doing work Plastic should do itself.
-
 ## State System
 
 ```
@@ -300,10 +253,10 @@ Format: `ID--three-to-five-words` (all stores).
 - Intent file matches directory: `1a1--slug/1a1--slug.md`
 - Next ID: `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
 
-**Branch vs root — the semantic decision.** The numbering is mechanics; choosing
+**Branch vs root: the semantic decision.** The numbering is mechanics; choosing
 *whether* to branch is meaning:
 
-- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation of the
+- **Branch (`14a`, `14b`):** a sub-task, refinement, or direct continuation of the
   parent. It cannot stand on its own; it only makes sense as part of the parent's work.
 - **Root (`15`, `16`)**: an independent thought, even if inspired by another intent.
   Reserve `sources` for true created-from provenance (intents this was built out of). An
@@ -324,45 +277,6 @@ One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>]
 The title is the title, not a summary: aim for about 80 characters, no multi-sentence
 descriptions. This is a self-check, not a gate.
 
-## Roadmaps
-
-Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
-is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
-release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
-close, and consume one.
-
-File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
-inside `store/` (store holds intent directories, not project artifacts). For a project that is its
-root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
-`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
-in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
-a sibling subdirectory scaffolded once with a `.gitkeep`.
-
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
-append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
-waves run sequentially, top to bottom.
-
-Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
-that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
-on any conflict INDEX wins and the roadmap entry is corrected to match.
-
-**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
-checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
-line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
-engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
-or codenames, ending with a link
-to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
-opening the file with no other context can tell what shipped, what is running now, and what is
-next in under a minute.
-
-**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
-loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
-Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
-running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
-after a stop. This section only states the relationship and points to intent 69 as the future
-consumer; it does not change intent 69's own design.
-
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -404,25 +318,16 @@ one recommendation line per present tool. The legacy trailing `# qmd-ok` token i
 accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
 calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
-## Context-economy measurement buckets (84a)
-
-Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
-
-- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
-- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
-  in the transcript.
-- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
-
 ## Transition Gates
 
 | Transition | Trigger | Gate |
 |---|---|---|
-| What → Why | `spec.md` written | — |
+| What → Why | `spec.md` written | (none) |
 | Why → How | `plan.md` + `actions/` + `checklist.md` | `spec.md` must exist |
 | How → Exec | Checklist has items | Plan triplet must exist |
 | Exec → Done | `outcome.md` written | All checklist items checked |
 
-Hard blocking — hooks exit code 2 on gate failure.
+Hard blocking: hooks exit code 2 on gate failure.
 
 ## Delivery Isolation and the Single-Owner Lock
 
@@ -547,32 +452,3 @@ liveness surface, the lock-issue message, orchestrator auto-repair, and the fail
 behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
 fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
 
-## Deprecation Process
-
-Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
-pre-1.0, a satisfied deprecation (its migration is already done on installed machines) may be
-removed immediately instead of waiting for its declared `removal` version. From `1.0.0` on,
-the steady-state grace rule applies (removal at least two minors ahead). For the full process,
-severity levels, and the pre-1.0 exception, see the `plastic-releasing` skill.
-
-## Skills Reference
-
-Detailed conventions live inside the skills that use them, not in this file.
-
-| Topic | Skill | References in skill |
-|-------|-------|-------------------|
-| Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
-| Brainstorming, spec writing | `plastic-brainstorming` | — |
-| Planning, actions | `plastic-writing-plans` | — |
-| Execution, delivery | `plastic-executing-plan` | — |
-| Autonomous delivery | `plastic-auto` | agent architecture |
-| Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
-| Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
-| Projects, hubs | `plastic-creating-project` | hubs, project stores |
-| Provision a project store | `plastic-add-project-store` | project stores |
-| Index maintenance | `plastic-managing-index` | — |
-| Releases, deprecations | `plastic-releasing` | deprecation process |
-| Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
-| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
-| Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
-| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |

package/README.md

@@ -1,95 +1,110 @@
 # Plastic
 
-> **Alpha software.** Expect breaking changes between releases.
-> Install: `npx @zalom/plastic@alpha --claude`
-
-Intent-driven idea development system for AI coding agents. Named after
-**neuroplasticity**: adaptive, malleable, dynamic, resilient.
-
-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.
+**Where you were, where you are, where you are heading.**
+
+The everyday problem: losing the thread of your own work. You step away for a
+day and come back to find the reasoning behind a decision is gone. A session
+ends and the next one starts from nothing. Plastic keeps a durable, growing
+record of your work as you do it, so that thread never breaks.
+
+## Why Plastic
+
+You do not write documentation about your work after the fact. You do the
+work as an intent (a short file that states what you want, why, how you plan
+to get there, and what happened). Because intents stay after you finish them,
+and because they link to the intents that shaped them and the ones they led
+to, they build into a queryable trace of your project over time. You can ask
+what happened, why a choice was made, or where an idea came from, and get an
+answer grounded in your own history. Memory is the result of working this
+way, not a feature bolted onto an agent afterward.
+
+## Two founding systems
+
+**System for the Brain.** Plastic is built on the Zettelkasten method: small,
+linked notes that add up to more than their sum. The name borrows from
+neuroplasticity, the brain's own way of adapting and rewiring itself. An
+intent is one such note. Its `sources` and `chain` links connect it to the
+intents that shaped it and the ones it led to, so the store grows into a
+graph you can actually navigate, not a pile of files.
+
+**System for the Work.** Plastic separates the deterministic part of work
+from the creative part. The blueprint (conventions, templates, directory
+layout, and the lifecycle stages) is fixed: it comes out the same shape no
+matter who or what is doing the work. The thinking (the actual reasoning
+about what to build and how) stays free: a human or an agent does it, and
+Plastic never replaces that judgment, only steers and checks it. This is
+convention over configuration: one readable shape for every intent, so any
+person or agent can pick up where another left off.
 
 ## The Two Cycles
 
-**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.
+**Coordinator loop (B→O→R):** Build → Observe → Repeat. The agent advances
+the active intent, observes what the work surfaced, and repeats with the
+next one. 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
+**Intent lifecycle (W→W→H→E):** What → Why → How → Exec. Each intent moves
+from capture through justification and planning to delivery. Intents produce
 artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
 
-## How Plastic Works
-
-Plastic is a **thinking system**, a blueprint for taking a desire from intent to
-delivery. It splits the work in two:
-
-- **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.
-
-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.
-
-**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.
-
-**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.
-
-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.
+## How Plastic differs
+
+Plastic is not a memory service. Tools like mem0 give an agent a vector
+database to store and recall facts through an API; the memory lives in that
+service, apart from your project. Plastic instead keeps intents as plain,
+git-tracked Markdown files, moved through an enforced lifecycle (What, Why,
+How, Exec) that a person can read without any tooling. The result reads like
+the Zettelkasten linking model long used for personal notes, applied to
+software delivery.
+
+Projects like beads add persistent memory on top of an existing agent
+workflow. Plastic shares that goal, an agent should remember what it did and
+why, but gets there by making the intent itself, with its spec, plan, and
+delivered outcome, the actual unit of work. Plastic runs today with Claude
+Code, and works with Cursor and Cline through the same file-based
+conventions.
 
 ## Install
 
-Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
+Plastic requires Ruby (pre-installed on macOS and Linux) and Node.js 18 or
+later.
 
-```bash
-# Alpha (current, active development)
-npx @zalom/plastic@alpha --claude
+Plastic is in beta. Install with:
 
-# Beta (when available, API-stable, bug hunting)
+```bash
 npx @zalom/plastic@beta --claude
+```
+
+Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
+`--all` for all supported agents.
 
+A stable channel will follow later:
+
+```bash
 # Stable (when available, general use)
 npx @zalom/plastic --claude
 ```
 
-Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
-`--all` for all supported agents.
+The bare command above is not a working install yet. It currently resolves
+to an early stub release, so use `@beta` for now.
 
-Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --claude`).
-Bun is never required.
+Bun users can substitute `bunx` for `npx` (for example, `bunx
+@zalom/plastic@beta --claude`). Bun is never required.
 
 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.
+`plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a
+Claude Code plugin; re-running the installer automatically removes any
+legacy plugin registration.
 
 ### Updating
 
 From within your agent, say "update plastic" or run:
 
 ```bash
-npx @zalom/plastic@alpha --claude
+npx @zalom/plastic@beta --claude
 ```
 
-The `plastic-update` command shows available versions across all channels and
-lets you choose which to install.
+The `plastic-update` command shows available versions across all channels
+and lets you choose which to install.
 
 ## Quick Start
 
@@ -101,7 +116,11 @@ After installation, run `/clear` to load Plastic conventions, then:
 4. Use `/plastic-writing-plans` to create an implementation plan
 5. Use `/plastic-executing-plan` to deliver it
 
-Or say "auto" to let the agent handle the full lifecycle autonomously.
+Guided delivery (a human at every gate) is the default. Say "auto" if you
+want the agent to run the full lifecycle on its own instead.
+
+Run `/plastic-dashboard` any time for a Value x Effort view across every
+intent and what to work on next.
 
 ## Agents
 
@@ -119,11 +138,15 @@ install time.
   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.
+- [`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 conventions live in `PLASTIC.md`, distributed to `~/.plastic/PLASTIC.md`
+and overwritten on every update. Project-specific rules live in `AGENTS.md`,
+scaffolded once at `~/.plastic/AGENTS.md`. 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

package/agents/plastic-brainstorming.md

@@ -1,12 +1,8 @@
 ---
 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>
+  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
 ---
 

package/agents/plastic-enforcer.md

@@ -1,12 +1,8 @@
 ---
 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>
+  Use as the auto-mode orchestrator: it spins up the team, sequences the
+  specialists, owns every gate, and runs the final review.
 model: opus
 ---
 
@@ -63,6 +59,15 @@ ceremony, never these guarantees.
 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 the session id may be unset in headless or background runs