@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/{skills/auto/references → docs/help}/human-report-contract.md

@@ -29,27 +29,25 @@ written by eye:
 
 ## Binding table (intent 331f)
 
-Every skill that shows state names its own report verb, one row per skill and trigger. Each
-bound skill's file carries the SAME rule next to its verb: print the screen as the first
+Every command or lead role that shows state names its own report verb, one row per binding
+and trigger. Each one carries the SAME rule next to its verb: print the screen as the first
 characters of the reply, nothing before it, no fence, or the hook cannot paint it.
 
-| Skill | Trigger | Verb |
+| Command or lead | Trigger | Verb |
 |---|---|---|
-| `plastic-intent-continuing` | project route (continue, load project) | `dashboard.rb ... --screen` |
-| `plastic-intent-continuing` | a named intent | `report-screen state` |
-| `plastic-intent-continuing` | "where are we" (a status ask) | `report-screen session` |
-| `plastic-intent-continuing` | "why so long" | `report-screen delay` |
-| `plastic-intent-continuing` | a roadmap route | `report-screen roadmap ... state` |
-| `plastic-auto` | the How boundary, before the executor | `report-screen plan` |
-| `plastic-auto` | each of the five triggers | `report-screen state` |
-| `plastic-auto` | close | `report-screen delivered` |
-| `plastic-intent-ending` | the close | `report-screen delivered` |
-| `plastic-intent-speccing` | the action files are written | `report-screen plan` |
-| `plastic-roadmap` | create | `report-screen roadmap ... plan` |
-| `plastic-roadmap` | read | `report-screen roadmap ... state` |
-| `plastic-roadmap` | close | `report-screen roadmap ... delivered` |
-| `plastic-dashboard` | any invocation | `dashboard.rb ... --screen` |
-| `plastic-intent-executing` | after the red commit, and after the suite | `report-screen state` |
+| `plastic continue` | project route (continue, load project) | `dashboard.rb ... --screen` |
+| `plastic continue` | a named intent | `report-screen state` |
+| `plastic continue` | "where are we" (a status ask) | `report-screen session` |
+| `plastic continue` | "why so long" | `report-screen delay` |
+| `plastic continue` | a roadmap route | `report-screen roadmap ... state` |
+| the auto team's lead | the How boundary, before the executor | `report-screen plan` |
+| the auto team's lead | each of the five triggers | `report-screen state` |
+| the auto team's lead | close | `report-screen delivered` |
+| `plastic intent end` | the close | `report-screen delivered` |
+| `plastic intent spec` | the action files are written | `report-screen plan` |
+| `plastic roadmap show` | any invocation | `report-screen roadmap ... state` |
+| `plastic status` | any invocation | in-process (`Scope#stores`) |
+| `plastic intent step` | after the red commit, and after the suite | `report-screen state` |
 
 ## A roadmap's own three reports (intent 331c)
 
@@ -104,7 +102,7 @@ A delivery still ends with `outcome.md` plus one `delivered` screen.
 
 A delivery produces exactly two artifacts: `outcome.md` (generated by `scripts/end-intent`
 from `graph.md`, `nodes/`, and the ledger when the intent has one, intent 339; hand-authored
-by `plastic-intent-ending` otherwise) and one `delivered` screen at the End stage. No stage or skill restates a delivery already
+by `plastic intent end` otherwise) and one `delivered` screen at the End stage. No stage or skill restates a delivery already
 written to `outcome.md`; point at it instead. Skills do not open with a banner that names the
 skill or restates the intent id and name the owner just typed. Announce only what the reader
 cannot already know: an error, a result, a choice with its reason, or a handoff.

package/{skills/conventions/references → docs/help}/roadmaps.md

@@ -6,8 +6,8 @@ This chapter holds the full roadmap file format and its relationship to INDEX.md
 
 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.
+release (completion-side, tracked in `CHANGELOG.md`). Create one by hand from the template, then
+use `plastic roadmap show`, `next`, `log`, and `check` to read, drive, and audit it.
 
 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

package/{skills/tutorial/references → docs/help}/track-1-guided.md

@@ -9,7 +9,7 @@ end to end: a piece of work moved through What, Why, How, and Exec, with a finis
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+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
@@ -22,7 +22,7 @@ directory instead (see station 6). Either way, nothing in this track touches a r
 
 ### 1. Create the intent
 
-Type `/plastic-intent-creating` and describe the work in plain words, for example "add a
+Run `plastic intent new` 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
@@ -35,7 +35,7 @@ tool, never written by hand.
 
 ### 2. Board the intent
 
-Type `/plastic-intent-continuing` and name the intent.
+Run `plastic continue` and name the intent.
 
 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
@@ -46,13 +46,13 @@ sessions from editing the same intent at the same time.
 
 ### 3. Why, rulings one at a time
 
-Type `/plastic-intent-speccing` (say "grill me" for a harder, interview-style pass over
+Run `plastic intent spec` (say "grill me" 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`
+later. This station's product is the enriched Why; it hands off to `plastic intent spec`
 next, it does not write `spec.md` itself.
 
 Checkpoint: after two or three answers, look at the intent file. Every ruling given out loud
@@ -60,7 +60,7 @@ is already sitting in `### Decisions` and in `## Insights`, in writing.
 
 ### 4. How, write the graph
 
-Ask the same conversation (`/plastic-intent-speccing`) to turn the rulings into the graph.
+Ask the same conversation (`plastic intent spec`) to turn the rulings into the graph.
 
 Artifact: `graph.md` (nodes, edges, dispatch policy) and one `nodes/N.md` file per node this
 small delivery needs. A delivery this size is one node; many independent tasks instead get
@@ -70,7 +70,7 @@ Checkpoint: open `graph.md` and point at the one node this worked example needs.
 
 ### 5. Exec, drive the runner loop
 
-Type `/plastic-intent-executing`.
+Run `plastic intent step`.
 
 Teach the loop: `ruby scripts/runner step <intent_dir>` computes which nodes are ready and
 prints a spawn block to dispatch, `ruby scripts/runner status <intent_dir>` reads the
@@ -87,7 +87,7 @@ moving to station 6.
 
 ### 6. End
 
-Type `/plastic-intent-ending`.
+Run `plastic intent end`.
 
 Artifact: a real `outcome.md` (Summary, Delivered, Verification, Follow-ups) generated by
 `scripts/outcome-report` from `graph.md` and the ledger, the intent moved from `## Active`

package/{skills/tutorial/references → docs/help}/track-2-auto.md

@@ -9,7 +9,7 @@ agent end to end, and pausing and resuming that delivery will feel familiar.
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+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
@@ -19,8 +19,8 @@ track touches a real project.
 
 ### 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`.
+Start from an active intent (create one first with `plastic intent new` if none
+exists, the same way as track 1 station 1). Run `plastic auto take ID`.
 
 Artifact: the delivery lock arms, and the agent announces it is taking over the intent for
 autonomous delivery.
@@ -45,7 +45,7 @@ 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
+("run plastic intent spec"), 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.
 
@@ -74,7 +74,7 @@ line.
 
 ### 5. Continue and where-was-I after time away
 
-Type `/plastic-intent-continuing`.
+Run `plastic continue`.
 
 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

package/{skills/tutorial/references → docs/help}/track-3-projects-and-roadmaps.md

@@ -9,7 +9,7 @@ will exist with more than one intent inside it and a roadmap file describing the
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+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
@@ -20,11 +20,11 @@ one this tutorial keeps or ships.
 
 ### 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-continuing`. Describe something meant to grow into a small real project,
+Create and board an intent the same way as track 1, stations 1 and 2: `plastic intent new`,
+then `plastic continue`. Describe something meant to grow into a small real project,
 for example "build a personal todo app."
 
-Then type `/plastic-intent-speccing` and record a couple of real rulings on this founding
+Then type `plastic intent spec` 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.
 
@@ -33,17 +33,21 @@ into a whole new project.
 
 ### 2. Grow it into a project
 
-Type `/plastic-project-creating`.
+Make the project directory yourself and write its `AGENTS.md`, carrying forward at least one
+decision from the founding intent. Plastic does not create the directory or fill that file;
+that is ordinary agent work, done once, before the project exists. Once the directory exists,
+run `plastic project new SLUG --path PATH` to register it in `projects.yml` and provision and
+validate its store.
 
-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.
+Artifact: a new project directory with its `AGENTS.md`, 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
+Run `plastic intent new` 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
@@ -54,13 +58,16 @@ in the global store.
 
 ### 4. Plan a delivery batch
 
-Type `/plastic-roadmap`.
+Copy `templates/roadmap.md` to `roadmaps/<slug>.md`, next to the project's `INDEX.md`, and fill
+it by hand: a title and short meta header, a `## Goal` section in prose describing what "done"
+looks like for the whole batch, a `## Batches` section (an ordered list of groups of intents;
+intents inside one batch are safe to run in parallel, batches 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. List the two or more intents from station 3
+across one or more batches.
 
-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 `## Batches` section (an
-ordered list of groups of intents; intents inside one batch are safe to run in parallel,
-batches 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.
+Run `plastic roadmap check <slug>` to confirm the file parses, then `plastic roadmap show
+<slug>` to see it rendered as a report.
 
 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 batches.
@@ -93,8 +100,8 @@ sections you turned into the condition above.
 
 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.
+is a push to `alpha`, `beta`, or `main`: the version files are bumped in that push, and CI
+tags, publishes, 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.
@@ -108,4 +115,4 @@ This is the same What, Why, How, Exec cycle from tracks 1 and 2, repeated across
 and gathered by a roadmap. Read
 [`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.
+walkthrough covers, [`docs/help/roadmaps.md`](roadmaps.md) is the reference.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.26",
+  "version": "2.0.0-alpha.28",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {
-    "plastic": "bin/plastic.js"
+    "plastic": "bin/plastic"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -34,6 +34,7 @@
     "bin/",
     "scripts/",
     "skills/",
+    "docs/help/",
     "hooks/",
     "agents/",
     "templates/",

package/scripts/append-ledger

@@ -30,6 +30,7 @@
 #   2 - usage error, or promote/tick found nothing to address (no write happens)
 #   3 - promote/tick could not take an exclusive lock (filesystem without flock support)
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
 
@@ -162,7 +163,7 @@ def main(argv)
   usage_abort("verb must be one of #{VERBS.join(", ")}, got #{opts[:verb].inspect}") unless VERBS.include?(opts[:verb])
 
   plastic_home = expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-  store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+  store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(plastic_home)
   templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
   usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
   opts[:templates] = templates

package/scripts/dashboard.rb

@@ -21,6 +21,7 @@
 #
 # Read-only. Never modifies files.
 
+require_relative "lib/store_layout"
 require "json"
 require "yaml"
 require "date"
@@ -143,13 +144,13 @@ def completion_dates(index_path)
 end
 
 # All stores: global + every registered project. -> [{scope, store, index}]
-def stores
+def stores(home = PLASTIC_HOME)
   list = []
-  global = File.join(PLASTIC_HOME, "store")
-  list << { scope: "global", store: global, index: File.join(PLASTIC_HOME, "INDEX.md") } if File.directory?(global)
-  projects_root = File.join(PLASTIC_HOME, "projects")
+  global = Plastic::StoreLayout.global_store(home)
+  list << { scope: "global", store: global, index: File.join(Plastic::StoreLayout.global_root(home), "INDEX.md") } if File.directory?(global)
+  projects_root = Plastic::StoreLayout.projects_root(home)
   if File.directory?(projects_root)
-    Dir.children(projects_root).sort.each do |proj|
+    Plastic::StoreLayout.project_slugs(home).each do |proj|
       store = File.join(projects_root, proj, "store")
       next unless File.directory?(store)
       list << { scope: "project:#{proj}", store: store, index: File.join(projects_root, proj, "INDEX.md") }
@@ -592,7 +593,7 @@ def render_continue(records)
   out.concat(matrix(open, scope_tag: true))
   out << ""
   out << LEGEND
-  out << "ask    for the <slug> project board  ·  plastic-auto  (works the dispatchable queue)"
+  out << "ask    for the <slug> project board  ·  plastic auto take ID  (works the dispatchable queue)"
   out.join("\n") + "\n"
 end
 
@@ -855,7 +856,7 @@ end
 def short_description(scope)
   return "" unless scope.start_with?("project:")
   slug = scope.sub("project:", "")
-  agents = File.join(PLASTIC_HOME, "projects", slug, "AGENTS.md")
+  agents = File.join(Plastic::StoreLayout.project_root(PLASTIC_HOME, slug), "AGENTS.md")
   if File.exist?(agents)
     File.readlines(agents).each do |l|
       t = l.strip
@@ -1022,7 +1023,7 @@ end
 # directly under PLASTIC_HOME, with no intervening "store" segment.
 def screen_tier_root(plastic_home, scope)
   return plastic_home if scope == "global"
-  File.join(plastic_home, "projects", screen_scope_slug(scope))
+  Plastic::StoreLayout.project_root(plastic_home, screen_scope_slug(scope))
 end
 
 # "global" spans every store (the same aggregate render_continue and --json's
@@ -1085,7 +1086,7 @@ end
 # PLASTIC_HOME/store tmp root, and `session: nil` (A6) so the calling
 # session's own live heartbeat counts rather than being excluded as "self".
 def screen_sessions_count(plastic_home, now:)
-  store = File.join(plastic_home, "store")
+  store = Plastic::StoreLayout.global_store(plastic_home)
   DaySummary.active_sessions(store, nil, now: now, ttl: DaySummary::HEARTBEAT_TTL).size
 end
 

package/scripts/day-summary

@@ -14,6 +14,7 @@
 #
 # Exit codes: 0 done; 2 usage error.
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/day_summary"
 
@@ -43,7 +44,7 @@ end
 
 opts = parse_args(ARGV)
 home = opts[:home] ? expand(opts[:home]) : expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-store = opts[:store] ? expand(opts[:store]) : File.join(home, "store")
+store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(home)
 day = opts[:day] || SessionLedger.day_id
 usage_abort("--day must be eight digits parsing as a real date, got #{day.inspect}") unless SessionLedger.valid_day_id?(day)
 session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])