@zalom/plastic 1.0.3 → 1.1.1

package/skills/tutorial/references/track-1-guided.md

@@ -0,0 +1,123 @@
+# Track 1: Guided, your first intent
+
+## Who it is for and what you will have done
+
+For a new user who wants to feel the whole cycle once, one stage at a time, approving each
+step before the next one starts. After this track, one small, real change will be delivered
+end to end: a piece of work moved through What, Why, How, and Exec, with a finished
+`outcome.md` to show for it.
+
+## Before you start
+
+Run `/plastic-update` first, so the commands below match what is actually installed.
+
+Work in a sandbox: this track always creates a global-store intent; the throwaway repo below
+is never registered as a Plastic project. Pick a throwaway git repository if you have one
+handy, since the worked example edits its README: station 6's deliverable is that file edit.
+No repo handy? Station 6's deliverable becomes a short written note saved in the intent's own
+directory instead (see station 6). Either way, nothing in this track touches a real project.
+
+## Stations
+
+### 1. Create the intent
+
+Type `/plastic-intent-creating` and describe the work in plain words, for example "add a
+short Usage section to this project's README."
+
+Artifact: a new intent directory, `{id}--slug.md`, plus the sentinel placeholder lifecycle
+files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) and empty `actions/` and
+`resources/` folders.
+
+Checkpoint: open the new file. It already has a real id and a one-line description; nothing
+was hand-typed into it directly. That is the point: intents are always scaffolded by the
+tool, never written by hand.
+
+### 2. Board the intent
+
+Type `/plastic-intent-starting`.
+
+Artifact: a delivery lock (a `delivery.lock` file in the intent directory) naming this
+session as the one owner, and a line in `savepoint.md` recording the stage. The agent then
+asks exactly one question: "auto or guided?"
+
+Checkpoint: answer "guided." Explain in one sentence why the lock matters: it stops two
+sessions from editing the same intent at the same time.
+
+### 3. Why, rulings one at a time
+
+Type `/plastic-intent-brainstorming` (or `/plastic-intent-grilling` for a harder,
+interview-style pass over the same ground). It asks conversational prose questions, one at a
+time, never a multiple-choice menu, and answers them one at a time in return.
+
+Artifact: `## Context` and `### Decisions` in the intent file fill in as each answer lands, and
+each ruling also lands as its own `## Insights` entry the moment it is made, never batched for
+later. This station's product is the enriched Why; it hands off to `/plastic-intent-speccing`
+next, it does not write `spec.md` itself.
+
+Checkpoint: after two or three answers, look at the intent file. Every ruling given out loud
+is already sitting in `### Decisions` and in `## Insights`, in writing.
+
+### 4. Consolidate the spec
+
+Type `/plastic-intent-speccing`.
+
+Artifact: `spec.md`, stamped with a tier (`S`, for this small worked example) and its eight
+sections filled from the rulings recorded in station 3.
+
+Checkpoint: name the stamped tier and point at one sentence in `spec.md` that traces back to
+an answer given in station 3.
+
+### 5. Plan
+
+Type `/plastic-intent-planning`.
+
+Artifact: `plan.md` and `checklist.md`. At the S tier used here, `actions/` stays empty and
+the task rationale lives inline in `plan.md` instead of separate action files; only the L
+tier (many independent tasks, dispatched in parallel) gets one `actions/ACTION_N.md` file
+per task. `checklist.md` follows a fixed form: tasks start under `## In Progress`, move to
+`## Completed` as they land, and a `## Session Log` table records what happened each session.
+A task that depends on an owner decision landing first (a destructive step, a structural
+ruling) gets an `[ORCHESTRATOR]` prefix and blocks every other item until that decision is
+made; this worked example has none.
+
+Checkpoint: open `checklist.md`. Every task in `plan.md` has a matching checkbox under
+`## In Progress`; that checklist, not `plan.md` itself, is what gets ticked off and moved to
+`## Completed` during Exec.
+
+### 6. Exec, verify before the gate
+
+Type `/plastic-intent-executing`.
+
+Teach the order: first the agent syncs its working copy with the main line, so no edit lands
+on a path a merged change upstream has already touched or removed. Then it makes the change,
+runs whatever verifies it (a test suite, or a manual check for a docs change like this one),
+and only then ticks the checklist box, moving the task from `## In Progress` to
+`## Completed` and adding a `## Session Log` row, before moving to the next task. Verifying
+always comes before checking a box, never after, and each task is ticked the moment it lands,
+never batched for later.
+
+Artifact: the actual change on disk (the new README Usage section, or, in the global-store
+fallback, a short written note saved as the intent's deliverable) and a fully ticked
+`checklist.md`.
+
+Checkpoint: find the new Usage section in the README (or the written note) and confirm every
+box in `checklist.md` is checked and moved to `## Completed`, with a `## Session Log` row for
+this session, before moving to station 7.
+
+### 7. Done
+
+Type `/plastic-intent-ending`.
+
+Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups), the intent
+moved from `## Active` to `## Completed` in `INDEX.md`, and a closing `Done` line in
+`savepoint.md`.
+
+Checkpoint: open `outcome.md` and read its Summary. It should describe, in a sentence or
+two, exactly the README section (or note) just delivered.
+
+## Wrap and where to go next
+
+That is the full cycle once: create, board, decide, spec, plan, build, done. Read
+`docs/guides/your-first-intent-in-10-minutes.md` for the same path condensed to a single
+read, and `docs/guides/what-the-gates-are-telling-you.md` for what to do if a station denies
+an action instead of completing it.

package/skills/tutorial/references/track-2-auto.md

@@ -0,0 +1,95 @@
+# Track 2: Auto, hand delivery to the agent
+
+## Who it is for and what you will have done
+
+For someone who has seen the stages once (track 1) and now wants to hand the work to the
+agent, watch it move through the gates and reports on its own, and learn how to check in on
+it and step back in later. After this track, one small intent will have been delivered by the
+agent end to end, and pausing and resuming that delivery will feel familiar.
+
+## Before you start
+
+Run `/plastic-update` first, so the commands below match what is actually installed.
+
+Work in a sandbox: a throwaway git repository, or a global-store intent. Nothing in this
+track touches a real project.
+
+## Stations
+
+### 1. Board a small intent and choose auto
+
+Start from an active intent (create one first with `/plastic-intent-creating` if none
+exists, the same way as track 1 station 1). Type `/plastic-auto`.
+
+Artifact: the delivery lock arms, and the agent announces it is taking over the intent for
+autonomous delivery.
+
+Checkpoint: name the one precondition auto needs before it will start: an active intent must
+already exist for the intent you name. (Say "auto" with nothing named, and it can pick a
+queued intent from the dashboard's queue itself.)
+
+### 2. What auto does, and what stays with the user
+
+No new command at this station. Watch how the work splits.
+
+Auto owns How (the plan, the checklist, the action files) and Exec (the code, the tests, the
+mechanical close) from here on. Inside Exec it follows a few fixed habits: it syncs its
+working copy with the main line before touching anything, ticks each task the moment it
+lands rather than batching several into one later edit, and independently verifies its own
+work (running the test suite, or checking the changed file) before presenting anything back
+to you. For a task shaped like an audit or a sweep, checking many files rather than building
+one artifact, it also drops a short methods report into `resources/` before the gate, so you
+can review how it checked, not just what it found.
+
+The user keeps two things: the rulings made along the way, and the review points, moments
+auto is built to pause for, such as confirming a project path or stopping before a
+destructive action with no safe way back. When auto tells you to run a command yourself
+("run /plastic-intent-speccing"), that is an instruction for you to type; it is a different
+thing from the prompts auto hands to its own dispatched subagents, and the two are never
+mixed up in what it tells you.
+
+Checkpoint: name one thing auto will always stop and ask about, rather than decide alone.
+
+### 3. Walking the gates
+
+No new command. Auto still honors every hard gate a guided session would hit: the delivery
+lock (one owner at a time), the code gate (shut until `plan.md` and `checklist.md` exist),
+and the create gate (intents only come from the tool that makes them, never hand-authored).
+One gate, retrieval, is advisory only and never blocks anything; it just adds a note.
+
+Checkpoint: read one gate message from the run so far and say whether it is one of the hard
+gates or the one advisory note.
+
+### 4. Reading the per-stage reports
+
+No new command. At each stage boundary (What, Why, How, Exec, Done) the agent briefs in a
+fixed three-line shape: State (what happened and why it matters), Risk (the one thing that
+could bite, or "nothing flagged"), and Call (the decision left to the user, or the call the
+agent is taking on its own).
+
+Checkpoint: in the most recent report, point at the State line, the Risk line, and the Call
+line.
+
+### 5. Continue and where-was-I after time away
+
+Type `/plastic-continuing`.
+
+Artifact: the current state, presented and then the session stops. If a specific intent is
+named, the agent reads its stage and savepoint and resumes exactly there, rather than
+starting over.
+
+Checkpoint: after stepping away and running this command, name the stage the intent resumed
+at and how that matched what was actually on disk.
+
+## Wrap and where to go next
+
+Auto keeps the same stages and the same gates as guided; the only difference is who steers.
+Read `docs/guides/pick-your-mode.md` for the honest trade-off between guided and auto, and
+`docs/guides/using-plastic-with-claude-code.md` for how that choice feels day to day and how
+it connects to roadmap-driven delivery. For denial messages met along the way, read
+`docs/guides/what-the-gates-are-telling-you.md`.
+
+Note on terms: "guided" means the user starts each stage with a command and the agent
+narrows the thinking inside it, the same shape track 1 walked. "Manual", editing project
+files outside the lifecycle entirely, is not a third mode; it is the anti-pattern both guided
+and auto exist to avoid.

package/skills/tutorial/references/track-3-projects-and-roadmaps.md

@@ -0,0 +1,110 @@
+# Track 3: Projects and roadmaps
+
+## Who it is for and what you will have done
+
+For someone ready to see a founding idea grow past a single intent: into a small real
+project, a handful of related intents, and a roadmap that plans and tracks them as one
+batch. After this track, a small project (a personal todo app, in the walkthrough below)
+will exist with more than one intent inside it and a roadmap file describing the batch.
+
+## Before you start
+
+Run `/plastic-update` first, so the commands below match what is actually installed.
+
+Work in a sandbox: this whole track is a walked example. It creates a real project directory
+and a real roadmap file on disk, but the project is a throwaway one made for learning, not
+one this tutorial keeps or ships.
+
+## Stations
+
+### 1. Start from a founding implementation intent
+
+Create and board an intent the same way as track 1, stations 1 and 2: `/plastic-intent-creating`,
+then `/plastic-intent-starting`. Describe something meant to grow into a small real project,
+for example "build a personal todo app."
+
+Then type `/plastic-intent-brainstorming` and record a couple of real rulings on this founding
+intent, for example the language or how tasks get stored. Keep it short: this intent only
+needs enough decisions for the new project to inherit, not a full design.
+
+Checkpoint: explain why this intent is "founding": its decisions are about to carry forward
+into a whole new project.
+
+### 2. Grow it into a project
+
+Type `/plastic-project-creating`.
+
+Artifact: a new project directory, an `AGENTS.md` file carrying the founding intent's
+decisions, the project's own intent store, and a new entry in `projects.yml` registering it.
+
+Checkpoint: open `AGENTS.md` and find at least one line that traces back to a decision
+recorded in the founding intent back in station 1.
+
+### 3. Add more intents inside the project
+
+Type `/plastic-intent-creating` at least twice, from inside the project, describing two
+pieces of real work, for example "add a task list model" and "add a due date field."
+
+Artifact: two or more intent directories inside the project's own store, separate from the
+global store the founding intent came from.
+
+Checkpoint: point at the project's store path and confirm both new intents live there, not
+in the global store.
+
+### 4. Plan a delivery batch
+
+Type `/plastic-roadmap`.
+
+Teach the roadmap file shape exactly: a title and short meta header, a `## Goal` section in
+prose describing what "done" looks like for the whole batch, a `## Waves` section (an
+ordered list of groups of intents; intents inside one wave are safe to run in parallel,
+waves themselves run one after another), and an append-only, dated `## Log`. `INDEX.md`
+stays the single source of truth for each intent's status; the roadmap only mirrors it.
+
+Artifact: a new `roadmaps/<slug>.md` file, sitting next to the project's `INDEX.md`, listing
+the two or more intents from station 3 across one or more waves.
+
+Checkpoint: name which of the two intents from station 3 share a wave (so they run in
+parallel) and which one, if any, sits in a later wave (so it waits).
+
+### 5. Drive delivery with /goal
+
+`/goal` is a Claude Code harness command, not a Plastic skill. It sets a completion condition
+and Claude keeps working, turn after turn, until a fast checker model confirms from what
+Claude has actually reported that the condition holds; `/goal` never reads files on its own,
+so the condition has to name a check Claude's own output can prove.
+
+Turn the roadmap's `## Goal` and current `## Waves` into that condition, for example:
+
+`/goal every intent in wave 1 of roadmaps/<slug>.md shows Completed in INDEX.md, and the test
+suite is green`
+
+Claude then works through the wave itself, one intent at a time, and stops on its own once the
+checker agrees the condition holds. Run `/goal` with no argument at any point to see how long
+it has run and how many turns it has spent; run `/goal clear` to stop it before that.
+
+On a harness without `/goal`, just tell the agent to deliver the roadmap in auto mode instead.
+
+Checkpoint: point at the exact file (`roadmaps/<slug>.md`) whose `## Goal` and `## Waves`
+sections you turned into the condition above.
+
+### 6. Merge discipline and releases
+
+No command run here; describe the step instead. Each delivered intent's code merges to main
+as it lands. When the batch (or a meaningful slice of it) is ready to ship, cutting a release
+runs through `/plastic-releasing`, which merges, bumps the version, tags, and completes the
+intents it collects.
+
+Releases and any npm publish step are described here, not run: this walkthrough stays in a
+sandbox and never touches a real package registry.
+
+Checkpoint: explain why a release completes the intents it collects, rather than an intent
+waiting on a release to exist first.
+
+## Wrap and where to go next
+
+This is the same What, Why, How, Exec cycle from tracks 1 and 2, repeated across a project
+and gathered by a roadmap. Read
+`docs/guides/using-plastic-with-claude-code.md` for roadmap-driven delivery in more depth,
+including a real worked roadmap. For the exact roadmap file format beyond what this
+walkthrough covers, the `plastic-roadmap` skill itself is the reference.

package/skills/uninstall/SKILL.md

@@ -14,7 +14,7 @@ underlying uninstaller and adds reporting + verification.
 
 If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
 `-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed,
-default to `@beta`. The user can always override with `--alpha` / `--beta` / `--latest`.
+default to `@latest`. The user can always override with `--alpha` / `--beta` / `--latest`.
 
 ## Procedure
 
@@ -74,5 +74,5 @@ Delete it too?
 ```
 
 - **Keep:** "Your data is at ~/.plastic/. Re-install anytime with
-  `npx -y @zalom/plastic@beta install --claude` (or your channel)."
+  `npx -y @zalom/plastic@latest install --claude` (or your channel)."
 - **Delete:** run `rm -rf ~/.plastic/` and confirm.

package/skills/update/SKILL.md

@@ -22,7 +22,7 @@ clean no-op. You do not compute the target yourself, the script does.
 
 If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
 `-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
-(first install), default to `@beta`. The user can always override with
+(first install), default to `@latest`. The user can always override with
 `--alpha` / `--beta` / `--latest`.
 
 ## Flags
@@ -35,12 +35,12 @@ If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version
 | `--alpha` | Switch to / advance the **alpha** channel (bleeding edge, confirmed if moving down in stability) |
 
 Switching toward a more stable channel is frictionless; switching toward bleeding edge is
-confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
+confirmed. To roll **back** to a previously-installed version, use `plastic-rollback`.
 
 ## Prerequisites
 
 Plastic must be installed (`~/.plastic/VERSION` present). If not, run `plastic-install`
-first (or `npx -y @zalom/plastic@beta install --claude` directly).
+first (or `npx -y @zalom/plastic@latest install --claude` directly).
 
 ## Procedure
 

package/templates/agents.md

@@ -47,13 +47,13 @@ Plastic has its own lifecycle skills. When a Plastic skill exists for the curren
 
 | Phase | Skill | Produces |
 |-------|-------|----------|
-| What | `plastic-creating-intent` | Intent file |
-| Why | `plastic-brainstorming` | `spec.md` |
-| Why | `plastic-research` | `resources/*.md` |
-| Why | `plastic-brainstorming-grill-me` | Deep interrogation |
-| How | `plastic-writing-plans` | `plan.md`, `checklist.md`, `actions/` |
-| Exec | `plastic-executing-plan` | Code + `outcome.md` |
-| Done | `plastic-intent-curator` | Lifecycle transition |
+| What | `plastic-intent-creating` | Intent file |
+| Why | `plastic-intent-brainstorming` | `spec.md` |
+| Why | `plastic-intent-researching` | `resources/*.md` |
+| Why | `plastic-intent-grilling` | Deep interrogation |
+| How | `plastic-intent-planning` | `plan.md`, `checklist.md`, `actions/` |
+| Exec | `plastic-intent-executing` | Code + `outcome.md` |
+| Done | `plastic-store-curating` | Lifecycle transition |
 
 **Artifact convention:** ALL lifecycle artifacts go to the active intent directory (`store/{id}--{slug}/`). Never write specs to `docs/superpowers/specs/` or plans to `docs/superpowers/plans/`.
 

package/templates/config.yml

@@ -14,7 +14,8 @@ architect:
 
 # 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.
+# no entry, the shipped default applies and never resolves to Fable; naming
+# Fable here is an explicit, sanctioned override, honored as written.
 # agents:
 #   models:
 #     plastic-executor: sonnet

package/templates/index.md

@@ -1,13 +1,16 @@
 # Index
 
 ## Active
+<!-- Line shape: `- [ID — Title](path)`. The em-dash (U+2014, not a plain hyphen)
+     between id and title is load-bearing: Bridge.intent_active? matches only that
+     shape, and a plain hyphen there fails the lock gate open (see docs/internals.md). -->
 (no active intents)
 
 ## Future
 (no future intents)
 
 ## Clusters
-(clusters emerge as intents accumulate — add headings when 3+ intents share a topic)
+(clusters emerge as intents accumulate; add headings when 3+ intents share a topic)
 
 ## Completed
 (links preserved, never deleted)

package/skills/brainstorming/evals/evals.json

@@ -1,22 +0,0 @@
-{
-  "skill_name": "plastic-brainstorming",
-  "notes": "Intent 66a. Spec for the QMD-first step in the Why/explore-context phase (surface prior decisions/specs/outcomes before grep/Read). Runner is intent 76; spec only.",
-  "evals": [
-    {
-      "id": 1,
-      "scope": "behavior",
-      "set": "validation",
-      "prompt": "QMD is present. Brainstorming the active intent during the Why phase, the agent needs prior decisions and specs on caching.",
-      "expected_output": "In the explore-project-context (Why) step, before scanning the store with grep/Read, runs `ruby ~/.plastic/scripts/qmd-sync search \"caching decisions\"` to surface prior decisions, specs, or outcomes, then opens the authoritative intent file for any hit it acts on. No-op fallback to INDEX.md / file scan when QMD is absent.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "qmd-sync search is run during Why before grep/Read; authoritative file opened for any hit",
-          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
-          "result": "pass"
-        }
-      ]
-    }
-  ]
-}

package/skills/savepoint/references/context-management.md

@@ -1,32 +0,0 @@
-# Context Management (Start-Save-Continue)
-
-## Save Point
-Triggered by PreCompact hook or manually:
-1. Find active intent(s) from `~/.plastic/INDEX.md`
-2. Update active intent's `checklist.md` (check off completed items)
-3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
-4. Add observations to `## Insights`
-5. Update INDEX.md
-6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
-7. Notify user to `/clear`
-
-## Continue
-Triggered by UserPromptSubmit hook when user says "continue". Priority order:
-
-**1. Active intents first (resume work):**
-1. Read INDEX.md → find active intent(s)
-2. Read active intent's `intent.md` → what and why
-3. Read active intent's `savepoint.md` → where we left off
-4. Read active intent's `checklist.md` → what's next
-5. Announce: intent name, current state, next step, blockers
-6. Resume
-
-**2. No active intents → offer future intents:**
-1. List all future intents from INDEX.md
-2. Present them as options
-3. When user picks one, move to Active in INDEX.md
-
-**3. Stale future intents (untouched 3+ days) → triage:**
-- **activate** — start working on it now
-- **abandon** — mark as abandoned
-- **defer to agent** — implement, research, or ideate