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

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 (4) hide show
  1. package/README.md +122 -92
  2. package/package.json +1 -1
  3. package/scripts/install.rb +2 -1
  4. package/skills/install/SKILL.md +1 -1
package/README.md CHANGED
@@ -1,135 +1,165 @@
1
1
  # Plastic
2
2
 
3
- > **Alpha software.** Expect breaking changes between releases.
4
- > Install: `npx @zalom/plastic@alpha --claude`
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)
5
7
 
6
- Intent-driven idea development system for AI coding agents. Named after
7
- **neuroplasticity**: adaptive, malleable, dynamic, resilient.
8
+ **Where you were, where you are, where you are heading.**
8
9
 
9
- Plastic thinks in **intents**, not tasks. An intent is a desire, something
10
- you want to accomplish, explore, or understand. Intents are atomic thoughts
11
- that get developed through two nested processes.
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).
12
14
 
13
- ## The Two Cycles
15
+ Paste this to your coding agent to start:
14
16
 
15
- **Coordinator loop (B→O→R):** Brainstorm → Organize → Review. The human and
16
- agent explore ideas, structure them into intents, and validate the results.
17
- This loop runs continuously across sessions.
18
-
19
- **Intent lifecycle (W→W→H→E):** Why → What → How → Execute. Each intent moves
20
- from motivation through specification, planning, to delivery. Intents produce
21
- artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
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
+ ```
22
23
 
23
- ## How Plastic Works
24
+ ## Install
24
25
 
25
- Plastic is a **thinking system**, a blueprint for taking a desire from intent to
26
- delivery. It splits the work in two:
26
+ Plastic needs Ruby (already on macOS and Linux) and Node.js 18 or later.
27
27
 
28
- - **The blueprint (deterministic).** The conventions, templates, directory structure,
29
- lifecycle, and linking rules. This is *how to fill in the work*, and it comes out
30
- identically no matter who or what is working.
31
- - **The brain (non-deterministic).** The human or LLM that does the actual thinking.
32
- Plastic never replaces it. It only **steers and validates** it.
28
+ Plastic is in beta. Install with:
33
29
 
34
- Determinism lives in the **form** of the work (section sets, ordering, schemas, naming,
35
- IDs, file layout), never in the brain's reasoning. The framework stays constant while the
36
- thinking varies. Run Plastic on Claude Code, Codex, Hermes, OpenClaw, or by hand on paper
37
- in Obsidian or Word, and the only thing that changes is the *quality of thought*. The
38
- proof is the paper test: if a person with no tooling and no AI can reproduce a
39
- correctly-shaped intent, the determinism is in the form, not the agent.
30
+ ```bash
31
+ npx @zalom/plastic@beta --claude
32
+ ```
40
33
 
41
- **Deterministic by design, free by intent.** The rigid part is rigid on purpose. It is
42
- what makes work portable, reviewable, and resumable across any agent. The free part is
43
- free on purpose. It is where the brain's creativity lives. Plastic draws the line between
44
- the two and holds it.
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.
45
37
 
46
- **Harnesses are how it holds the line.** Shared harnesses (conventions, templates, and
47
- directory structure) constrain humans and agents alike. Agent-extra harnesses (evals that
48
- check a skill's output, plus hooks and instructions that steer reasoning) give an agent
49
- the instincts a careful person already has: stop and save state, leave a note when the
50
- context runs out, never plan before specifying.
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.
51
40
 
52
- This is **intent-driven delivery**, a new shape for the software lifecycle in the age of
53
- agentic engineering. The unit of work is an *intent*, not a ticket, and every intent
54
- carries its own spec, plan, checklist, and outcome as it moves through Why, What, How, and
55
- Execute. What you get is agent-agnostic, auditable, and additive: a knowledge graph of
56
- *why* things were built, not just what.
41
+ ```bash
42
+ npx @zalom/plastic --claude
43
+ ```
57
44
 
58
- ## Install
45
+ Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
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.
59
49
 
60
- Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
50
+ ## The lost thread
61
51
 
62
- ```bash
63
- # Alpha (current, active development)
64
- npx @zalom/plastic@alpha --claude
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.
65
56
 
66
- # Beta (when available, API-stable, bug hunting)
67
- npx @zalom/plastic@beta --claude
57
+ Come back after a day and ask where you were:
68
58
 
69
- # Stable (when available, general use)
70
- npx @zalom/plastic --claude
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?
71
64
  ```
72
65
 
73
- Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
74
- `--all` for all supported agents.
66
+ Memory is the result of working this way, not a feature bolted onto an agent
67
+ afterward.
75
68
 
76
- Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --claude`).
77
- Bun is never required.
69
+ ## Quick Start
78
70
 
79
- Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
80
- `plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a Claude Code
81
- plugin; re-running the installer auto-removes any legacy plugin registration.
71
+ After installation, run `/clear` to load Plastic conventions, then:
82
72
 
83
- ### Updating
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
84
76
 
85
- From within your agent, say "update plastic" or run:
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.
86
80
 
87
- ```bash
88
- npx @zalom/plastic@alpha --claude
89
- ```
81
+ <details>
82
+ <summary>See the full 10-minute walkthrough</summary>
90
83
 
91
- The `plastic-update` command shows available versions across all channels and
92
- lets you choose which to install.
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.
93
91
 
94
- ## Quick Start
92
+ Full guide: [your first intent in 10 minutes](docs/guides/your-first-intent-in-10-minutes.md).
93
+ </details>
95
94
 
96
- After installation, run `/clear` to load Plastic conventions, then:
95
+ ## Two founding systems
96
+
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.
97
103
 
98
- 1. Say "new intent" or run `/plastic-creating-intent` to create your first intent
99
- 2. Describe what you want to accomplish
100
- 3. Use `/plastic-brainstorming` to explore the design
101
- 4. Use `/plastic-writing-plans` to create an implementation plan
102
- 5. Use `/plastic-executing-plan` to deliver it
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.
103
111
 
104
- Or say "auto" to let the agent handle the full lifecycle autonomously.
112
+ ## Plastic ships itself
105
113
 
106
- ## Agents
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:
107
118
 
108
- Each lifecycle stage has one dispatchable background agent: `plastic-intent-discovery` for
109
- What, `plastic-brainstorming` and `plastic-spec-specialist` for Why, `plastic-planner` for
110
- How, `plastic-executor` for Exec, `plastic-intent-curator` for Done, plus `plastic-enforcer`
111
- as the auto-mode orchestrator. Every agent pins an explicit Claude Code model alias (opus or
112
- sonnet) in its frontmatter: never `inherit`, never Fable. See `docs/architecture.md` for the
113
- stage table and `docs/internals.md` for how the model is configured, resolved, and applied at
114
- install time.
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.
115
141
 
116
142
  ## Documentation
117
143
 
144
+ Each lifecycle stage has one dispatchable background agent, from discovery
145
+ through delivery, plus `plastic-enforcer` as the auto-mode orchestrator.
146
+
118
147
  - [`docs/architecture.md`](docs/architecture.md): system structure, the two
119
- processes, the store layout, and the component map.
120
- - [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic, the
121
- 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.
151
+ - [`docs/guides/`](docs/guides/index.md): task-oriented guides, from your
152
+ first intent in 10 minutes to picking a delivery mode.
122
153
 
123
154
  ## Conventions
124
155
 
125
- All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`
126
- during installation. Run `plastic-doctor` to check installation health.
127
- `plastic-doctor --core` runs a binary install-integrity check (compares files
128
- against the install manifests; pass or error). `plastic-doctor --store` checks
129
- store state (intents, INDEX sections, conventions) and can be scoped to
130
- `global` or a project slug. The full `plastic-doctor` runs all checks and is
131
- run automatically after every update.
156
+ Plastic conventions live in `PLASTIC.md`, distributed to `~/.plastic/PLASTIC.md`
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.
132
160
 
133
161
  ## License
134
162
 
135
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.36",
3
+ "version": "1.0.0-beta.38",
4
4
  "description": "Intent-driven idea development system for AI coding agents",
5
5
  "type": "module",
6
6
  "bin": {
package/scripts/install.rb CHANGED
@@ -129,7 +129,8 @@ class Install < InstallerCore
129
129
  verb = mode == :reinstall ? "re-synced" : "installed"
130
130
  puts "\n\u{2705} Plastic v#{version} #{verb}."
131
131
  puts " Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
132
- puts " Run /clear (or restart your agent) to pick up new conventions.\n\n"
132
+ puts " Run /clear (or restart your agent) to pick up new conventions."
133
+ puts " Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
133
134
  end
134
135
 
135
136
  def show_help
package/skills/install/SKILL.md CHANGED
@@ -158,7 +158,7 @@ Version: none -> <installed>
158
158
  Doctor: <summary or "all clear">
159
159
  ```
160
160
 
161
- Then: "Create your first intent with `/plastic-creating-intent`."
161
+ Then: "Read `docs/guides/your-first-intent-in-10-minutes.md` for your first intent, start to finish."
162
162
 
163
163
  ### Local Install (testing/legacy)
164
164