@zalom/plastic 1.0.0-beta.34 → 1.0.0-beta.36

package/skills/versions/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-versions
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
 ---
 
-# Plastic Versions — local version time-machine
+# Plastic Versions: local version time-machine
 
 ## When to Use
 - "show plastic versions", "version history", "what versions have I run"
@@ -11,11 +11,18 @@ description: Use when the user wants to see their Plastic version history or rol
 - A new version broke something and the user wants their last known-good build
 
 For upgrading to a **new** release, use `plastic-update`. This skill only navigates
-versions you have **already installed** — the ones recorded in the ledger.
+versions you have **already installed**, the ones recorded in the ledger.
+
+## Channel rule
+
+`versions` restores whichever build you pick from the ledger, it does not take a channel
+flag for the target. The pinned `<channel>` below is only the npx invocation itself:
+derive it from `~/.plastic/VERSION` the same way as the other lifecycle skills,
+`-alpha` -> `@alpha`, `-beta` -> `@beta`, otherwise `@latest`.
 
 ## The ledger
 
-`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+`~/.plastic/versions.json` is an **append-only JSONL** ledger, one line per version
 change, never modified or deleted:
 
 ```json
@@ -23,15 +30,16 @@ change, never modified or deleted:
 {"version":"1.0.0-alpha.18","action":"update","at":"..."}
 ```
 
-`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
-channel is derived from the version string, never stored). It is a troubleshooting record.
+`action` is one of `install`, `reinstall`, `update`, `downgrade` (derived from version
+direction; the channel is derived from the version string, never stored). It is a
+troubleshooting record.
 
 ## Procedure
 
 ### Show history
 
 ```bash
-npx @zalom/plastic versions
+npx -y @zalom/plastic@<channel> versions
 ```
 
 Prints the table with the currently-installed version marked. If the most recent action was
@@ -40,8 +48,8 @@ a `downgrade`, it asks whether to keep rolling back.
 ### Roll back
 
 ```bash
-npx @zalom/plastic versions --downgrade                    # one step back
-npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+npx -y @zalom/plastic@<channel> versions --downgrade                    # one step back
+npx -y @zalom/plastic@<channel> versions --downgrade --version 1.0.0-alpha.15   # to a specific run
 ```
 
 Rollback targets are restricted to versions in the ledger (only builds you have actually
@@ -51,15 +59,22 @@ re-fetched from npm and re-synced; your intent store, config, and the ledger are
 ### Step forward (after a rollback)
 
 ```bash
-npx @zalom/plastic versions --upgrade                      # one step forward in your history
+npx -y @zalom/plastic@<channel> versions --upgrade                      # one step forward in your history
 ```
 
 ### After any change
 
-Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
-swapped conventions.
+Run `plastic-doctor` to confirm health, then emit the reporting block and suggest
+`/clear` so the session picks up the swapped conventions:
+
+```
+Plastic versions (<channel>)
+Command:  npx -y @zalom/plastic@<channel> versions <flags>
+Version:  <before> -> <after>
+Doctor:   <summary or "all clear">
+```
 
 ## Notes
-- The ledger is **never** edited or pruned — it is the audit trail.
+- The ledger is **never** edited or pruned, it is the audit trail.
 - Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
   the user rather than forcing the rollback.

package/skills/writing-plans/SKILL.md

@@ -48,70 +48,13 @@ This structure informs the task decomposition. Each task should produce self-con
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
-## Plan Document Header
+## Plan Format
 
-**Every plan MUST start with this header:**
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
-
-**Goal:** [One sentence describing what this builds]
-
-**Architecture:** [2-3 sentences about approach]
-
-**Tech Stack:** [Key technologies/libraries]
-
-**Intent:** {id} — {name}
-
----
-```
-
-## Task Structure
-
-````markdown
-### Task N: [Component Name]
-
-**Files:**
-- Create: `exact/path/to/file.rb`
-- Modify: `exact/path/to/existing.rb:123-145`
-- Test: `test/exact/path/to/test.rb`
-
-- [ ] **Step 1: Write the failing test**
-
-```ruby
-def test_specific_behavior
-  result = function(input)
-  assert_equal expected, result
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: FAIL with "undefined method"
-
-- [ ] **Step 3: Write minimal implementation**
-
-```ruby
-def function(input)
-  expected
-end
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add test/path/test.rb lib/path/file.rb
-git commit -m "feat: add specific feature"
-```
-````
+For the exact plan/task/checklist/action format (the Plan Document Header
+template, the full Task Structure worked example, and the checklist.md /
+actions/ACTION_N.md templates), read `references/plan-format.md` before
+writing plan.md. Every plan starts with the header template and decomposes
+into tasks matching the Task Structure shape.
 
 ## No Placeholders
 
@@ -144,31 +87,10 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 ## Plastic Artifacts
 
 After writing `plan.md`, create two additional artifacts in the intent directory:
-
-### checklist.md
-
-Execution registry with one checkbox per task. Format:
-
-```markdown
-# Checklist — Intent {id}: {name}
-
-- [ ] Task 1: {task title}
-- [ ] Task 2: {task title}
-- [ ] Task 3: {task title}
-...
-```
-
-### actions/ACTION_N.md
-
-One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
-
-```markdown
-# Action {N}: {task title}
-
-{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
-```
-
-Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`
+`checklist.md` (execution registry with one checkbox per task) and
+`actions/ACTION_N.md` (one self-contained file per task, in an `actions/`
+directory inside the intent directory). For the exact format of both, read
+`references/plan-format.md`.
 
 ## Git Commit
 

package/skills/writing-plans/references/plan-format.md

@@ -0,0 +1,102 @@
+# Plan, Checklist, and Action Format
+
+The exact templates for `plan.md`'s header and task structure, and for the
+`checklist.md` and `actions/ACTION_N.md` artifacts. Read this before writing
+plan.md so the shape matches on the first pass.
+
+## Table of Contents
+
+- [Plan Document Header](#plan-document-header)
+- [Task Structure (worked example)](#task-structure-worked-example)
+- [checklist.md format](#checklistmd-format)
+- [actions/ACTION_N.md format](#actionsaction_nmd-format)
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Intent:** {id} — {name}
+
+---
+```
+
+## Task Structure (worked example)
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.rb`
+- Modify: `exact/path/to/existing.rb:123-145`
+- Test: `test/exact/path/to/test.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+def test_specific_behavior
+  result = function(input)
+  assert_equal expected, result
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: FAIL with "undefined method"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ruby
+def function(input)
+  expected
+end
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/path/test.rb lib/path/file.rb
+git commit -m "feat: add specific feature"
+```
+````
+
+## checklist.md format
+
+Execution registry with one checkbox per task. Format:
+
+```markdown
+# Checklist — Intent {id}: {name}
+
+- [ ] Task 1: {task title}
+- [ ] Task 2: {task title}
+- [ ] Task 3: {task title}
+...
+```
+
+## actions/ACTION_N.md format
+
+One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
+
+```markdown
+# Action {N}: {task title}
+
+{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
+```
+
+Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`