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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +114 -107
  2. package/package.json +1 -1
  3. package/scripts/dashboard.rb +12 -2
package/README.md CHANGED
@@ -1,72 +1,29 @@
1
1
  # Plastic
2
2
 
3
- **Where you were, where you are, where you are heading.**
4
-
5
- The everyday problem: losing the thread of your own work. You step away for a
6
- day and come back to find the reasoning behind a decision is gone. A session
7
- ends and the next one starts from nothing. Plastic keeps a durable, growing
8
- record of your work as you do it, so that thread never breaks.
9
-
10
- ## Why Plastic
11
-
12
- You do not write documentation about your work after the fact. You do the
13
- work as an intent (a short file that states what you want, why, how you plan
14
- to get there, and what happened). Because intents stay after you finish them,
15
- and because they link to the intents that shaped them and the ones they led
16
- to, they build into a queryable trace of your project over time. You can ask
17
- what happened, why a choice was made, or where an idea came from, and get an
18
- answer grounded in your own history. Memory is the result of working this
19
- way, not a feature bolted onto an agent afterward.
20
-
21
- ## Two founding systems
3
+ [![npm version](https://img.shields.io/npm/v/@zalom/plastic/beta)](https://www.npmjs.com/package/@zalom/plastic)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@zalom/plastic)](https://www.npmjs.com/package/@zalom/plastic)
5
+ [![license](https://img.shields.io/npm/l/@zalom/plastic)](LICENSE)
6
+ [![CI](https://github.com/zalom/plastic/actions/workflows/test.yml/badge.svg)](https://github.com/zalom/plastic/actions/workflows/test.yml)
22
7
 
23
- **System for the Brain.** Plastic is built on the Zettelkasten method: small,
24
- linked notes that add up to more than their sum. The name borrows from
25
- neuroplasticity, the brain's own way of adapting and rewiring itself. An
26
- intent is one such note. Its `sources` and `chain` links connect it to the
27
- intents that shaped it and the ones it led to, so the store grows into a
28
- graph you can actually navigate, not a pile of files.
29
-
30
- **System for the Work.** Plastic separates the deterministic part of work
31
- from the creative part. The blueprint (conventions, templates, directory
32
- layout, and the lifecycle stages) is fixed: it comes out the same shape no
33
- matter who or what is doing the work. The thinking (the actual reasoning
34
- about what to build and how) stays free: a human or an agent does it, and
35
- Plastic never replaces that judgment, only steers and checks it. This is
36
- convention over configuration: one readable shape for every intent, so any
37
- person or agent can pick up where another left off.
38
-
39
- ## The Two Cycles
40
-
41
- **Coordinator loop (B→O→R):** Build → Observe → Repeat. The agent advances
42
- the active intent, observes what the work surfaced, and repeats with the
43
- next one. This loop runs continuously, across sessions.
8
+ **Where you were, where you are, where you are heading.**
44
9
 
45
- **Intent lifecycle (W→W→H→E):** What → Why → How → Exec. Each intent moves
46
- from capture through justification and planning to delivery. Intents produce
47
- artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
10
+ The everyday problem is losing the thread of your own work. You step away
11
+ for a day, come back, and the reasoning behind a decision is gone. Plastic
12
+ keeps a durable record of your work as you make it, so the thread never
13
+ breaks. Read [why I built it](MANIFESTO.md).
48
14
 
49
- ## How Plastic differs
15
+ Paste this to your coding agent to start:
50
16
 
51
- Plastic is not a memory service. Tools like mem0 give an agent a vector
52
- database to store and recall facts through an API; the memory lives in that
53
- service, apart from your project. Plastic instead keeps intents as plain,
54
- git-tracked Markdown files, moved through an enforced lifecycle (What, Why,
55
- How, Exec) that a person can read without any tooling. The result reads like
56
- the Zettelkasten linking model long used for personal notes, applied to
57
- software delivery.
58
-
59
- Projects like beads add persistent memory on top of an existing agent
60
- workflow. Plastic shares that goal, an agent should remember what it did and
61
- why, but gets there by making the intent itself, with its spec, plan, and
62
- delivered outcome, the actual unit of work. Plastic runs today with Claude
63
- Code, and works with Cursor and Cline through the same file-based
64
- conventions.
17
+ ```
18
+ Install Plastic: run `npx @zalom/plastic@beta --claude`.
19
+ Then run `/clear` and say "new intent" to begin.
20
+ Drive the work through What, Why, How, and Exec, and let Plastic
21
+ keep the record as we go.
22
+ ```
65
23
 
66
24
  ## Install
67
25
 
68
- Plastic requires Ruby (pre-installed on macOS and Linux) and Node.js 18 or
69
- later.
26
+ Plastic needs Ruby (already on macOS and Linux) and Node.js 18 or later.
70
27
 
71
28
  Plastic is in beta. Install with:
72
29
 
@@ -74,85 +31,135 @@ Plastic is in beta. Install with:
74
31
  npx @zalom/plastic@beta --claude
75
32
  ```
76
33
 
77
- Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
78
- `--all` for all supported agents.
34
+ Swap `--claude` for `--codex`, `--hermes`, or `--all` to match your agent.
35
+ Bun users can run `bunx` in place of `npx`; Bun is never required. To update
36
+ later, say "update plastic" or run the same `@beta` command again.
79
37
 
80
- A stable channel will follow later:
38
+ A stable channel will follow. The bare command below is not a working
39
+ install yet. It resolves to an early stub release, so keep `@beta` for now.
81
40
 
82
41
  ```bash
83
- # Stable (when available, general use)
84
42
  npx @zalom/plastic --claude
85
43
  ```
86
44
 
87
- The bare command above is not a working install yet. It currently resolves
88
- to an early stub release, so use `@beta` for now.
89
-
90
- Bun users can substitute `bunx` for `npx` (for example, `bunx
91
- @zalom/plastic@beta --claude`). Bun is never required.
92
-
93
45
  Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
94
- `plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a
95
- Claude Code plugin; re-running the installer automatically removes any
96
- legacy plugin registration.
46
+ `plastic-auto`, and so on). Invoke them with a hyphen. Plastic is not a
47
+ Claude Code plugin; re-running the installer removes any legacy plugin
48
+ registration.
97
49
 
98
- ### Updating
50
+ ## The lost thread
99
51
 
100
- From within your agent, say "update plastic" or run:
52
+ You do the work as an intent: a short file that states what you want, why,
53
+ how you plan to get there, and what happened. Intents stay after you finish,
54
+ and link to the ones that shaped them and the ones they led to, so your
55
+ project builds into a record you can ask questions against.
101
56
 
102
- ```bash
103
- npx @zalom/plastic@beta --claude
57
+ Come back after a day and ask where you were:
58
+
59
+ ```
60
+ You: Where was I?
61
+ Agent: Last intent: 140, "README round two". The plan is written and
62
+ approved. Next step is the ships-itself proof block. Want me to
63
+ pick it up in auto?
104
64
  ```
105
65
 
106
- The `plastic-update` command shows available versions across all channels
107
- and lets you choose which to install.
66
+ Memory is the result of working this way, not a feature bolted onto an agent
67
+ afterward.
108
68
 
109
69
  ## Quick Start
110
70
 
111
71
  After installation, run `/clear` to load Plastic conventions, then:
112
72
 
113
- 1. Say "new intent" or run `/plastic-creating-intent` to create your first intent
114
- 2. Describe what you want to accomplish
115
- 3. Use `/plastic-brainstorming` to explore the design
116
- 4. Use `/plastic-writing-plans` to create an implementation plan
117
- 5. Use `/plastic-executing-plan` to deliver it
73
+ 1. Say "new intent" to create your first piece of work
74
+ 2. Describe what you want, in plain words
75
+ 3. Explore the design, write a plan, then deliver it, one stage at a time
76
+
77
+ Guided delivery (a human at every gate) is the default. Say "auto" to let
78
+ the agent run the full lifecycle on its own. Run `/plastic-dashboard` any
79
+ time for a Value x Effort view of every intent and what to do next.
118
80
 
119
- Guided delivery (a human at every gate) is the default. Say "auto" if you
120
- want the agent to run the full lifecycle on its own instead.
81
+ <details>
82
+ <summary>See the full 10-minute walkthrough</summary>
121
83
 
122
- Run `/plastic-dashboard` any time for a Value x Effort view across every
123
- intent and what to work on next.
84
+ 1. Install once: `npx @zalom/plastic@beta --claude`.
85
+ 2. Describe a small first task, like "add a `--version` flag." Plastic
86
+ scaffolds the intent file for you; never write it by hand.
87
+ 3. Board it: say "continue." Plastic takes a lock, then asks "auto or guided?"
88
+ 4. Say "auto." The agent runs Why, then How, then Exec in one pass, then
89
+ writes `outcome.md` with exactly what was delivered and moves the intent
90
+ to Completed.
91
+
92
+ Full guide: [your first intent in 10 minutes](docs/guides/your-first-intent-in-10-minutes.md).
93
+ </details>
94
+
95
+ ## Two founding systems
124
96
 
125
- ## Agents
97
+ **System for the Brain.** Plastic is built on the Zettelkasten method:
98
+ small, linked notes that add up to more than their sum. The name borrows
99
+ from neuroplasticity, the brain's own way of rewiring itself. An intent is
100
+ one such note. Its `sources` and `chain` links connect it to the intents
101
+ that shaped it and the ones it led to, so the store grows into a graph you
102
+ can navigate, not a pile of files.
126
103
 
127
- Each lifecycle stage has one dispatchable background agent: `plastic-intent-discovery` for
128
- What, `plastic-brainstorming` and `plastic-spec-specialist` for Why, `plastic-planner` for
129
- How, `plastic-executor` for Exec, `plastic-intent-curator` for Done, plus `plastic-enforcer`
130
- as the auto-mode orchestrator. Every agent pins an explicit Claude Code model alias (opus or
131
- sonnet) in its frontmatter: never `inherit`, never Fable. See `docs/architecture.md` for the
132
- stage table and `docs/internals.md` for how the model is configured, resolved, and applied at
133
- install time.
104
+ **System for the Work.** Plastic separates the fixed part of work from the
105
+ creative part. The blueprint (conventions, templates, layout, and the
106
+ lifecycle stages) comes out the same shape no matter who does the work. The
107
+ thinking (what to build and how) stays free: a human or an agent does it,
108
+ and Plastic steers and checks that judgment without replacing it. One
109
+ readable shape for every intent, so any person or agent can pick up where
110
+ another left off.
111
+
112
+ ## Plastic ships itself
113
+
114
+ Every release of Plastic is a set of intents that Plastic itself tracked,
115
+ planned, and delivered. Over 2026-07-06 and 2026-07-07, the stable-1.0
116
+ roadmap run cut six beta releases, beta.32 through beta.37, collecting 19
117
+ intents. The evidence is public in `CHANGELOG.md` and the roadmap:
118
+
119
+ ```
120
+ - `1.0.0-beta.19` - shipped 2026-06-25; collected 92 (plastic-humanizer skill: clean authored prose, remove AI tells and slop from docs/specs/outcomes/READMEs).
121
+ - `1.0.0-beta.3` - shipped; collected 74 (mandatory structured agent completion reports + deterministic fallback).
122
+ - [x] 129 First-run user guides — delivered
123
+ - [x] 109 Audit README against the PLASTIC implementation — delivered
124
+ - [x] 97 Implement the first-sight positioning (README + repo) — delivered
125
+ ```
126
+
127
+ No other memory tool can paste this, because none is built with itself.
128
+
129
+ ## How Plastic differs
130
+
131
+ Plastic is not a memory service. Tools like mem0 give an agent a vector
132
+ database to store and recall facts through an API, and that memory lives in
133
+ the service, apart from your project. Plastic keeps intents as plain,
134
+ git-tracked Markdown files, moved through an enforced lifecycle (What, Why,
135
+ How, Exec) that a person can read without any tooling.
136
+
137
+ Projects like beads add persistent memory on top of an existing agent
138
+ workflow. Plastic shares that goal but makes the intent itself, with its
139
+ spec, plan, and delivered outcome, the unit of work. It runs today with
140
+ Claude Code, and works with Cursor and Cline through the same conventions.
134
141
 
135
142
  ## Documentation
136
143
 
144
+ Each lifecycle stage has one dispatchable background agent, from discovery
145
+ through delivery, plus `plastic-enforcer` as the auto-mode orchestrator.
146
+
137
147
  - [`docs/architecture.md`](docs/architecture.md): system structure, the two
138
- processes, the store layout, and the component map.
139
- - [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic, the
140
- determinism breakdown, and the harness system.
148
+ processes, the store layout, the component map, and the full stage table.
149
+ - [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic
150
+ and how the harness works.
141
151
  - [`docs/guides/`](docs/guides/index.md): task-oriented guides, from your
142
152
  first intent in 10 minutes to picking a delivery mode.
143
153
 
144
154
  ## Conventions
145
155
 
146
156
  Plastic conventions live in `PLASTIC.md`, distributed to `~/.plastic/PLASTIC.md`
147
- and overwritten on every update. Project-specific rules live in `AGENTS.md`,
148
- scaffolded once at `~/.plastic/AGENTS.md`. Run `plastic-doctor` to check
149
- installation health.
150
- `plastic-doctor --core` runs a binary install-integrity check (compares files
151
- against the install manifests; pass or error). `plastic-doctor --store` checks
152
- store state (intents, INDEX sections, conventions) and can be scoped to
153
- `global` or a project slug. The full `plastic-doctor` runs all checks and is
154
- run automatically after every update.
157
+ and overwritten on every update. Project-specific rules live in `AGENTS.md`.
158
+ Run `plastic-doctor` to check installation health; it compares files against
159
+ the manifests, checks store state, and runs automatically after every update.
155
160
 
156
161
  ## License
157
162
 
158
163
  MIT
164
+
165
+ Claude Code is powerful. Plastic makes it remember.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zalom/plastic",
3
- "version": "1.0.0-beta.37",
3
+ "version": "1.0.0-beta.39",
4
4
  "description": "Intent-driven idea development system for AI coding agents",
5
5
  "type": "module",
6
6
  "bin": {
package/scripts/dashboard.rb CHANGED
@@ -704,6 +704,16 @@ end
704
704
  # CLI
705
705
  # ---------------------------------------------------------------------------
706
706
 
707
+ # JSON.pretty_generate renders empty arrays/objects as multi-line ("[\n\n ]") on
708
+ # some json gem versions and single-line ("[]") on others, so the same payload
709
+ # serializes differently across environments. Collapse both to the single-line
710
+ # form so dashboard JSON output is byte-identical everywhere. The \n requirement
711
+ # in each pattern is what makes this safe: a raw newline is illegal inside a JSON
712
+ # string, so neither pattern can ever match inside string content.
713
+ def canonical_pretty_json(payload)
714
+ JSON.pretty_generate(payload).gsub(/\[\s*\n\s*\]/, "[]").gsub(/\{\s*\n\s*\}/, "{}")
715
+ end
716
+
707
717
  def main(argv)
708
718
  json = argv.delete("--json")
709
719
  data = argv.delete("--data")
@@ -715,7 +725,7 @@ def main(argv)
715
725
 
716
726
  if data
717
727
  payload = mode == "project" ? render_data_project(records, slug) : render_data_global(records)
718
- puts JSON.pretty_generate(payload)
728
+ puts canonical_pretty_json(payload)
719
729
  return 0
720
730
  end
721
731
 
@@ -729,7 +739,7 @@ def main(argv)
729
739
  # per-scope boards (keeping the all-scopes auto-mode contract stable).
730
740
  payload[:store_health] = store_health(slug) if mode == "project"
731
741
  payload[:store_health] = store_health(:global) if mode == "continue"
732
- puts JSON.pretty_generate(payload)
742
+ puts canonical_pretty_json(payload)
733
743
  return 0
734
744
  end
735
745