@zalom/plastic 1.8.0 → 1.10.0

package/skills/intent-planning/SKILL.md

@@ -12,8 +12,6 @@ Write comprehensive implementation plans assuming the engineer has zero context
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
-**Announce at start:** "I'm using the writing-plans skill to plan intent {id}: {name}."
-
 ## Active Intent Gate
 
 Before proceeding, resolve the active intent:
@@ -31,6 +29,10 @@ If the spec covers multiple independent subsystems, it should have been broken i
 
 ## Tier shapes
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind this section. This path resolves relative to this skill's own
+installed directory.
+
 Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the action shape it calls for. Every tier produces at least one REAL action file in `actions/`; the tier only changes how many:
 
 - **S or M (default):** write ONE consolidated `actions/ACTION_1.md` that carries the whole ordered delivery (the steps plus the exact changes). `plan.md` still holds the overall map and `checklist.md` still mirrors the task list. You may split into a few action files when that reads cleaner, but one real action file is the floor.
@@ -51,13 +53,19 @@ This structure informs the task decomposition. Each task should produce self-con
 
 ## Bite-Sized Task Granularity
 
-**Each step is one action (2-5 minutes):**
+Granularity follows the `Tier:` line the spec stamped.
+
+**At M or L, each step is one action (2-5 minutes):**
 - "Write the failing test" - step
 - "Run it to make sure it fails" - step
 - "Implement the minimal code to make the test pass" - step
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
+**At S, size each step to the work.** Do not slice a small delivery into fixed 2-5 minute steps. Keep steps coarse enough to read in one pass, and let the one consolidated `actions/ACTION_1.md` carry the whole delivery. Each step still names its exact file paths, its exact changes, and how it is verified. Only the slicing relaxes.
+
+This changes granularity, nothing else. Every tier still produces at least one real `actions/ACTION_N.md`, and an empty or `.gitkeep`-only `actions/` still fails the How gate (see `## Tier shapes` above).
+
 ## Plan Format
 
 For the exact plan/task/checklist/action format (the Plan Document Header
@@ -121,6 +129,9 @@ When collecting owner rulings for `[ORCHESTRATOR]` hard-gate items, read
 - **Produces:** `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md` (every tier; one consolidated file at S/M, one per task at L).
 - **Next:** /plastic-intent-executing.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on.
+
 ## Git Commit
 
 After writing all artifacts (plan.md, checklist.md, and the actions/ACTION_N.md files), commit to the store:

package/skills/intent-researching/SKILL.md

@@ -8,8 +8,6 @@ user-invocable: true
 
 Investigate a topic related to the active intent. Choose the right depth, produce a cited report.
 
-**Announce at start:** "I'm researching [topic] for intent {id} — {name}."
-
 ## Active Intent Gate
 
 Before proceeding, resolve the active intent:

package/skills/intent-savepoint/SKILL.md

@@ -22,6 +22,10 @@ It is **sugar on top of the conventions**, not a source of truth. The gate hook
 nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
 a resuming agent read the cycle's succession from one glance (last line = where we are).
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract that this ledger feeds. This path resolves relative to this skill's own
+installed directory.
+
 ## When to Use
 - A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
 - Resuming an intent: read the ledger to learn the cycle's succession quickly.

package/skills/intent-speccing/SKILL.md

@@ -47,6 +47,10 @@ not the Transition Gates table row). Writing `plan.md` is what opens the code ga
 writing `plan.md` is not this skill's job, that is `plastic-intent-planning`. State this to the user
 at step 6 so the handoff at step 8 is expected, not a surprise.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract behind this handoff. This path resolves relative to this skill's own
+installed directory.
+
 ## Tier stamp (step 3, convention only)
 
 Write `Tier: S|M|L` as the literal first line of the file, above the `# Spec:` heading. This line

package/skills/intent-starting/SKILL.md

@@ -10,8 +10,6 @@ user-invocable: true
 
 # Intent Starting — board a session onto an intent
 
-Announce: "Boarding intent [ID] — [name]."
-
 `plastic-intent-starting` is the Start procedure. It boards a session onto one intent: take
 the lock FIRST, confirm the delivery state, ask **auto or guided ONCE**, board at the latest
 delivered station, then run the cycle to Done. The What → Why → How → Exec stations are the
@@ -32,6 +30,10 @@ The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock
 enforces it: without a held lock, mutating writes to this active intent's dir are denied with
 "run /plastic-intent-starting to lock and begin".
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger behind everything below.
+This path resolves relative to this skill's own installed directory.
+
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
@@ -66,6 +68,16 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
    lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
    discovery yields nothing, proceed to Why normally.
 
+   **Skip the dispatch only at Tier S, when there is nothing to discover.** The skip fires
+   only when BOTH hold: a size of S is already on record for this intent, and the activating
+   intent's `chain` and `sources` frontmatter fields are both empty. On record means a
+   stamped `Tier: S` line at the top of `spec.md`. Sizing happens at Why, which is after this
+   step, so a first activation usually has no size yet: run the pass. The skip mainly earns
+   its keep on a re-activated intent that is already sized S. Never guess a size here to
+   unlock the skip. When both conditions hold, write the single line
+   `no chain/sources, discovery skipped` to `resources/discovery--<slug>.md` in its place,
+   then go to Why.
+
 **Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
 id the bridge is keyed by: pass the hook stdin `session_id` when you have it; in the executable
 snippets, a nonblank `CODEX_THREAD_ID` identifies Codex, otherwise a nonblank
@@ -106,12 +118,18 @@ Never re-ask at a later station.
 - **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
   only remaining job is the handoff; `plastic-auto` runs the cycle from here.
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind the auto branch above.
+
 ## Board at the latest delivered station
 
 The station is derived from `savepoint.md` last line + real artifacts on disk. See
 `references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
 continue with) and the per-station notes. Summary of what "continue" means per station:
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging that govern moving between the stations below.
+
 - **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
 - **Why** → continue brainstorming → `spec.md`.
 - **How** → continue `plan.md` + `actions/` + `checklist.md`.

package/skills/project-creating/SKILL.md

@@ -10,8 +10,6 @@ user-invocable: true
 
 # Creating a Project
 
-Announce: "Creating project `<slug>` from intent [ID] — [name]."
-
 ## Precondition
 
 An active intent must exist with enough context to define a project — at minimum: name/slug, path, and key decisions from `## Context > ### Decisions`.

package/skills/project-creating/references/project-scaffolding.md

@@ -17,8 +17,8 @@ Create `AGENTS.md` in the project root with:
 ```markdown
 # <Project Name> — Agent Instructions
 
-Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
-Follow it exactly.
+Read `PLASTIC.md` in `~/.plastic/` for the core conventions; deeper doctrine lives in
+the `plastic-conventions` skill's chapters. Follow it exactly.
 
 This file is the operating contract for this project. Any agent entering
 this project reads this file first.
@@ -74,7 +74,7 @@ Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
 # Index
 
 ## Active
-- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
+- [1 — <intent name>](store/1--<slug>/1--<slug>.md) — implementation, from: global:<ID>
 ```
 
 **For multi-intent spawning (Hub):**

package/skills/releasing/SKILL.md

@@ -332,7 +332,7 @@ the intent-41 re-land playbook.
 
 - Read `references/release-lines.md` for the two release lanes, the stable-line guarantees,
   the version-line map, and the intent-41 re-land playbook before starting any release
-- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+- When promoting a pre-release across channels (alpha to beta, beta to stable) or
   tagging a historical release retroactively, read `references/promotion-and-tagging.md`
   for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/promotion-and-tagging.md

@@ -33,21 +33,27 @@ cleared is a no-op.
 
 ## Promotion
 
-To promote a release across channels, use `--promote`:
+Promotion is not a CLI flag; there is no `--promote` command. It is a set of steps the
+agent performs during the releasing workflow, reusing the normal release mechanics
+(version bump, tag, `npm publish` with the channel's dist-tag, GitHub release):
 
 ```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
+# Promote alpha → beta: set version files from -alpha.N to -beta.1, commit, tag, then
+npm publish --access public --tag beta
+
+# Promote beta → stable: strip the pre-release suffix (e.g., 1.0.0-beta.3 → 1.0.0),
+# commit, tag, then
+npm publish --access public          # no --tag flag publishes to latest
 ```
 
 **Promotion rules:**
 - Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
 - Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
+- An annotated tag is created for the promoted version, and the GitHub release is cut
+  as in the normal workflow (`gh release create ... --latest` for stable).
+- To point a channel at an already-published version without republishing, move the
+  dist-tag directly: `npm dist-tag add @zalom/plastic@<version> <channel>`. To move the
+  GitHub "Latest" badge: `gh release edit <tag> --latest`.
 
 ## Retroactive Tagging
 

package/skills/releasing/references/release-lines.md

@@ -20,7 +20,7 @@ green Minitest run can fully vouch for.
 
 **Beta-verified lane.** Branch, merge to the `beta` branch, publish to the npm `beta` dist-tag,
 verify in real use, then merge `beta` into `main` and cut stable. It sits on top of the existing
-promotion mechanics (`--promote beta` / `--promote stable`, linear only, see
+promotion mechanics (agent-performed channel promotion, linear only, see
 `promotion-and-tagging.md`); it names when to use them, not new machinery.
 
 ## Routing rule

package/skills/roadmap/SKILL.md

@@ -43,6 +43,10 @@ See `references/file-format.md` for the exact entry-line shape, status vocabular
 format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
 verb above.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule that this skill's own file-format reference builds on. This
+path resolves relative to this skill's own installed directory.
+
 ## Notes
 
 - File location and the four-section shape are identical across tiers; do not invent a different

package/skills/roadmap-continuing/SKILL.md

@@ -45,6 +45,10 @@ roadmap handoff had to be resumed by hand, carried as a free-prose note in `171`
 4. A genuine tie (two candidates equally live) is presented to the user and resolved by the
    single ask below, not silently picked.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule behind the candidates gathered above. This path resolves
+relative to this skill's own installed directory.
+
 ## Present state
 
 Present the chosen roadmap's `## Goal`, the current batch with each entry's mirrored status, the

package/skills/skill-creating/SKILL.md

@@ -35,8 +35,11 @@ routes each authoring task to the reference that holds the depth.
 - Build at least three evals before writing extensive docs.
 - Match determinism to fragility: a deterministic script for fragile or
   repeated mechanical steps, prose for judgment calls.
-- Imperative voice, no second person. No em-dashes or en-dashes in any shipped
-  skill or doc (use commas, periods, parentheses, colons).
+- Imperative voice, no second person. User-facing docs (README, docs/, AGENTS.md,
+  CLAUDE.md) never use em-dashes or en-dashes, and newly authored skill text avoids
+  them (use commas, periods, parentheses, colons). Existing internal files and the
+  sanctioned template emissions (templates/index.md's INDEX line shape) are not
+  violations.
 
 ## Route the authoring task to its reference
 
@@ -49,6 +52,9 @@ routes each authoring task to the reference that holds the depth.
 | Deciding script versus prose, or writing a script | `references/scripts.md` |
 | Building evals for a skill | `references/evals.md` |
 
+Read `references/defaults-first.md` before naming an external skill as a default, for the
+Plastic-first, delegate-by-exception rule.
+
 ## Shrink context, or let a skill self-improve
 
 - When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for

package/skills/skill-creating/references/defaults-first.md

@@ -0,0 +1,23 @@
+# Defaults First
+
+This chapter holds the Plastic-first, delegate-by-exception rule for naming an external skill as a default.
+
+### 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.

package/skills/skill-creating/references/hooks.md

@@ -77,7 +77,10 @@ Notes that change the choice of event: [E2]
 - PreCompact fires before the runtime compacts the conversation. Use it to write a savepoint
   while the full context still exists.
 
-Plastic ships working instances of each: `scripts/hook-code-gate` (PreToolUse gate),
+Plastic ships working instances of each: `hooks/edit-gates` -> `scripts/hook-edit-gates`
+(PreToolUse, the merged dispatcher that runs code-gate, lock-gate, savepoint-pre, links-gate,
+and create-gate in one process; each gate's own logic lives in `scripts/lib/edit_gates.rb`
+and is also reachable through the standalone `scripts/hook-code-gate` CLI wrapper),
 `scripts/hook-session-start` (SessionStart boot and inject), `scripts/hook-savepoint-pre`
 (PreCompact savepoint). Read one before authoring a new hook of the same shape.
 

package/skills/store-curating/SKILL.md

@@ -39,6 +39,10 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection, before judging a link discovery or
+orphan finding. This path resolves relative to this skill's own installed directory.
+
 When an intent reaches a terminal state, moved to Completed OR Abandoned, do these things:
 
 1. 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).
@@ -54,3 +58,7 @@ follows its own step 7: it detects (never acquires) the target's delivery lock,
 clean working tree, and performs the fix on a fresh branch merged back to main as one closed
 operation, with an append-only `revisions.md` receipt in the same pass as the edit. See
 `agents/plastic-intent-curator.md` for the exact mechanics.
+
+Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
+MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog before
+running a maintenance dispatch like this one.

package/skills/store-indexing/SKILL.md

@@ -14,20 +14,20 @@ user-invocable: false
 
 ## INDEX.md Structure
 
-INDEX.md is a Zettelkasten main structure note - the brain's entry point. It has four sections:
+INDEX.md is a Zettelkasten main structure note - the brain's entry point. It has five sections:
 
 ### Active
 Intents currently being worked on. Max 1-2 for focus.
 ```markdown
 ## Active
-- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2.md) — decision, human
+- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2--design-plastic-state-system.md) — decision, human
 ```
 
 ### Future
 Intents parked for later. May be picked up by agents.
 ```markdown
 ## Future
-- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1.md) — implementation, human
+- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1--build-reddit-knowledge-base.md) — implementation, human
 ```
 
 ### Clusters
@@ -35,10 +35,13 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ```markdown
 ## Clusters
 ### Reddit Knowledge Base
-- [1a — Research](store/1a--research-reddit-saved-posts/1a.md)
-- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1.md)
+- [1a — Research](store/1a--research-reddit-saved-posts/1a--research-reddit-saved-posts.md)
+- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1--plan-reddit-knowledge-base.md)
 ```
 
+### Abandoned
+Intents ended without delivery. Links preserved, never deleted.
+
 ### Completed
 All completed intents with dates. Links preserved, never deleted.
 
@@ -75,8 +78,16 @@ When 3+ intents share tags but aren't in a cluster, suggest a new cluster headin
 ### Flag Orphans
 Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
 
+Before reclassifying a structural finding outside routine indexing, read
+`../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus MAINTENANCE, the
+`revisions.md` move-and-record contract, and the violation-tag catalog.
+
 REQUIRED BACKGROUND: intent-linking (for understanding connection types and Zettelkasten theory)
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection. This path resolves relative to
+this skill's own installed directory.
+
 ## References
 
 - Read `references/zettelkasten-linking.md` for the three structural layers (Folgezettel, directed graph, tags) and how they map to INDEX.md organization

package/skills/store-indexing/references/zettelkasten-linking.md

@@ -14,7 +14,7 @@
    `intent:` text. Ordering is mandatory: all `sources` first (top), then all `chain`,
    frontmatter order preserved within each group. Sources never appear at the end. No
    source/chain tags, no sub-grouping.
-2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See `docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
+2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See [`how-plastic-sources-and-chains-intents.md`](https://github.com/zalom/plastic/blob/main/docs/concepts/how-plastic-sources-and-chains-intents.md) for the full model.
 3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
 
 ## When to Create a Cluster

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

@@ -120,6 +120,6 @@ 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
+[`your-first-intent-in-10-minutes.md`](https://github.com/zalom/plastic/blob/main/docs/guides/your-first-intent-in-10-minutes.md) for the same path condensed to a single
+read, and [`what-the-gates-are-telling-you.md`](https://github.com/zalom/plastic/blob/main/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

@@ -55,18 +55,20 @@ Checkpoint: name one thing auto will always stop and ask about, rather than deci
 
 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.
+the create gate (intents only come from the tool that makes them, never hand-authored), the
+links gate (a `## Links` section changes only to match the file's own frontmatter), and the
+bash gate (a shell command cannot write project code the code gate would have blocked).
 
-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.
+Checkpoint: read one gate message from the run so far and name which of the five gates it
+came from.
 
 ### 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).
+agent is taking on its own). That is the depth for a medium or large intent. A small intent
+gets one briefing, at How, folding in what the earlier stages would have said.
 
 Checkpoint: in the most recent report, point at the State line, the Risk line, and the Call
 line.
@@ -85,10 +87,10 @@ 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
+Read [`pick-your-mode.md`](https://github.com/zalom/plastic/blob/main/docs/guides/pick-your-mode.md) for the honest trade-off between guided and auto, and
+[`using-plastic-with-claude-code.md`](https://github.com/zalom/plastic/blob/main/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`.
+[`what-the-gates-are-telling-you.md`](https://github.com/zalom/plastic/blob/main/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

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

@@ -106,6 +106,6 @@ waiting on a release to exist first.
 
 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,
+[`using-plastic-with-claude-code.md`](https://github.com/zalom/plastic/blob/main/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

@@ -1,6 +1,6 @@
 ---
 name: plastic-uninstall
-description: Use when the user wants to remove Plastic from an agent. Runs the manifest-driven uninstaller (removes skills, hooks, statusline, and any legacy plugin layout), reports exactly what was removed and what was left behind, then gives verification steps. Optionally deletes the intent store.
+description: Use when the user wants to remove Plastic from an agent. Runs the manifest-driven uninstaller (removes skills, hooks, statusline, and any legacy plugin layout), reports exactly what was removed and what was left behind, then gives verification steps. The intent store always stays.
 user-invocable: true
 ---
 
@@ -51,7 +51,7 @@ ls ~/.claude/hooks  | grep '^plastic-'    # -> no output
 grep -n plastic ~/.claude/settings.json   # -> no plastic hook/plugin refs
 ```
 
-### Step 4: Report + offer the data decision
+### Step 4: Report
 
 Emit the reporting block, using the Step 3 checks for the verification line:
 
@@ -67,12 +67,9 @@ Then:
 ```
 Plastic is uninstalled from [agent].
 Your intent store at ~/.plastic/ is untouched.
-
-Delete it too?
-  a) Keep everything (recommended): re-install anytime with npx
-  b) Delete everything now: removes ~/.plastic/ entirely (irreversible)
 ```
 
-- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with
-  `npx -y @zalom/plastic@latest install --claude` (or your channel)."
-- **Delete:** run `rm -rf ~/.plastic/` and confirm.
+Uninstall removes installed harness files only. The store at `~/.plastic/` (intents,
+history, projects, config, version ledger) always stays; no uninstall path deletes it.
+Tell the user: "Your data is at ~/.plastic/. Re-install anytime with
+`npx -y @zalom/plastic@latest install --claude` (or your channel)."

package/templates/agents.md

@@ -23,31 +23,30 @@ means preferring a detected tool's own search or navigation over a generic file
 4. **Use [[global:ID]]** to link back to the governing strategic intent
 5. **Auto-commit** all intent changes in this project's git repo
 
-## Intent Lifecycle — What→Why→How→Next
+## Intent Lifecycle — What→Why→How→Exec
 
 State is derived from filesystem conventions, not frontmatter fields:
 
 | Convention | Signal |
 |---|---|
-| `## Context` has content | Intent is permanent (not fleeting) |
-| `actions/` directory exists | Intent is actionable |
+| `## Context` has content | Intent is permanent (developed, actionable) |
 | `## Outcome` has content | Intent is done |
 
 Sections map to the lifecycle:
 - **## Intent** — What (the desire)
 - **## Context** — Why (background + ### Decisions)
-- **## Outcome** — How (the result, deliverables)
-- **## Insights** — Next (observations, raw material for future intents)
+- **## Outcome** — Exec (the result; How's deliverables are the `plan.md`, `actions/`, and `checklist.md` files)
+- **## Insights** — observations across all stages, raw material for future intents
 
 Active/Future/Completed placement is managed in INDEX.md, not in frontmatter.
 
 ## Creating Tactical Intents
 
-1. Scan `.plastic/store/` for the next sequential ID
-2. Generate ID: `~/.plastic/scripts/folgezettel-id`
-3. Create `.plastic/store/ID--slug/ID--slug.md`
-4. Set frontmatter: `id`, `intent`, `sources` (array — link to governing intent), `chain` (starts empty), `created`, `author`, `tags`
-5. Add `[[global:ID]]` backlink in `## Links`
+Create through the `plastic-intent-creating` skill, which scaffolds with one call:
+`ruby ~/.plastic/scripts/new-intent --store .plastic/store --intent "<one-line>" --slug <slug> [--sources <governing-id>]`.
+It allocates the Folgezettel ID, creates `.plastic/store/ID--slug/ID--slug.md` born
+complete, and wires the links. Never hand-author the files: the write-time create gate
+rejects an incomplete or malformed intent file.
 
 ## Lifecycle Skills
 
@@ -56,12 +55,13 @@ Plastic has its own lifecycle skills. When a Plastic skill exists for the curren
 | Phase | Skill | Produces |
 |-------|-------|----------|
 | What | `plastic-intent-creating` | Intent file |
-| Why | `plastic-intent-brainstorming` | `spec.md` |
+| Why | `plastic-intent-brainstorming` | Enriched `## Context` + `### Decisions` |
+| Why | `plastic-intent-speccing` | `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 |
+| Done | `plastic-intent-ending` | 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

@@ -8,7 +8,8 @@ hash_algorithm: sha256-base36
 max_slug_words: 5
 agent:
   type: claude-code
-  parallel_mode: linear
+  # read-config falls back to linear when this key is absent
+  parallel_mode: agent-teams
 architect:
   style:
 
@@ -27,14 +28,14 @@ architect:
 #       plastic-executor: sonnet
 #       plastic-enforcer: opus
 #     codex:
-#       plastic-executor: gpt-5.1-codex
+#       plastic-executor: gpt-5.6-terra
 
 # The advisor (intent 185): two consultation agents, plastic-advisor (the real
 # advisor, expensive, model fable by default) and plastic-faux-advisor (the
 # cheaper imitation, model opus by default, carrying the same reasoning
 # discipline inline). advisor.enabled defaults to enabled; missing or
-# unreadable counts as enabled (fail-open). The claude.default/primary/
-# secondary values are AGENT NAMES, never model names, so a slot can point at
+# unreadable counts as enabled (fail-open). The claude.default value is an
+# AGENT NAME, never a model name, so it can point at
 # a locally registered agent instead. Set at install time via --no-advisor /
 # --advisor, or uncomment here directly. Each agent's actual model is a plain
 # agents.models.claude.<name> override, same mechanism as any other agent.
@@ -42,6 +43,4 @@ architect:
 #   enabled: false               # skip installing both advisor agents and the
 #                                 # agent-advisor skill entirely
 #   claude:
-#     default: plastic-faux-advisor    # which agent the advisor skill routes to
-#     primary: plastic-advisor         # the real advisor slot
-#     secondary: plastic-faux-advisor  # the cheaper advisor slot
+#     default: plastic-advisor         # which agent the advisor skill routes to

package/templates/index.md

@@ -1,9 +1,9 @@
 # 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). -->
+<!-- Line shape: `- [ID — Title](path)`. Writes emit the em-dash (U+2014) between
+     id and title; readers (Bridge.index_entry_match) accept the em-dash or a plain
+     hyphen, so either form parses (see https://github.com/zalom/plastic/blob/main/docs/internals.md). -->
 (no active intents)
 
 ## Future
@@ -12,5 +12,8 @@
 ## Clusters
 (clusters emerge as intents accumulate; add headings when 3+ intents share a topic)
 
+## Abandoned
+(links preserved, never deleted)
+
 ## Completed
 (links preserved, never deleted)

package/templates/spec.md

@@ -13,7 +13,7 @@
 (the chosen approach, in prose)
 
 ## Alternatives Considered
-- <alternative> — not chosen because ...
+- <alternative>: not chosen because ...
 
 ## Decisions
 - ...