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

package/README.md

@@ -1,95 +1,110 @@
 # Plastic
 
-> **Alpha software.** Expect breaking changes between releases.
-> Install: `npx @zalom/plastic@alpha --claude`
-
-Intent-driven idea development system for AI coding agents. Named after
-**neuroplasticity**: adaptive, malleable, dynamic, resilient.
-
-Plastic thinks in **intents**, not tasks. An intent is a desire, something
-you want to accomplish, explore, or understand. Intents are atomic thoughts
-that get developed through two nested processes.
+**Where you were, where you are, where you are heading.**
+
+The everyday problem: losing the thread of your own work. You step away for a
+day and come back to find the reasoning behind a decision is gone. A session
+ends and the next one starts from nothing. Plastic keeps a durable, growing
+record of your work as you do it, so that thread never breaks.
+
+## Why Plastic
+
+You do not write documentation about your work after the fact. You do the
+work as an intent (a short file that states what you want, why, how you plan
+to get there, and what happened). Because intents stay after you finish them,
+and because they link to the intents that shaped them and the ones they led
+to, they build into a queryable trace of your project over time. You can ask
+what happened, why a choice was made, or where an idea came from, and get an
+answer grounded in your own history. Memory is the result of working this
+way, not a feature bolted onto an agent afterward.
+
+## Two founding systems
+
+**System for the Brain.** Plastic is built on the Zettelkasten method: small,
+linked notes that add up to more than their sum. The name borrows from
+neuroplasticity, the brain's own way of adapting and rewiring itself. An
+intent is one such note. Its `sources` and `chain` links connect it to the
+intents that shaped it and the ones it led to, so the store grows into a
+graph you can actually navigate, not a pile of files.
+
+**System for the Work.** Plastic separates the deterministic part of work
+from the creative part. The blueprint (conventions, templates, directory
+layout, and the lifecycle stages) is fixed: it comes out the same shape no
+matter who or what is doing the work. The thinking (the actual reasoning
+about what to build and how) stays free: a human or an agent does it, and
+Plastic never replaces that judgment, only steers and checks it. This is
+convention over configuration: one readable shape for every intent, so any
+person or agent can pick up where another left off.
 
 ## The Two Cycles
 
-**Coordinator loop (B→O→R):** Brainstorm → Organize → Review. The human and
-agent explore ideas, structure them into intents, and validate the results.
-This loop runs continuously across sessions.
+**Coordinator loop (B→O→R):** Build → Observe → Repeat. The agent advances
+the active intent, observes what the work surfaced, and repeats with the
+next one. This loop runs continuously, across sessions.
 
-**Intent lifecycle (W→W→H→E):** Why → What → How → Execute. Each intent moves
-from motivation through specification, planning, to delivery. Intents produce
+**Intent lifecycle (W→W→H→E):** What → Why → How → Exec. Each intent moves
+from capture through justification and planning to delivery. Intents produce
 artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
 
-## How Plastic Works
-
-Plastic is a **thinking system**, a blueprint for taking a desire from intent to
-delivery. It splits the work in two:
-
-- **The blueprint (deterministic).** The conventions, templates, directory structure,
-  lifecycle, and linking rules. This is *how to fill in the work*, and it comes out
-  identically no matter who or what is working.
-- **The brain (non-deterministic).** The human or LLM that does the actual thinking.
-  Plastic never replaces it. It only **steers and validates** it.
-
-Determinism lives in the **form** of the work (section sets, ordering, schemas, naming,
-IDs, file layout), never in the brain's reasoning. The framework stays constant while the
-thinking varies. Run Plastic on Claude Code, Codex, Hermes, OpenClaw, or by hand on paper
-in Obsidian or Word, and the only thing that changes is the *quality of thought*. The
-proof is the paper test: if a person with no tooling and no AI can reproduce a
-correctly-shaped intent, the determinism is in the form, not the agent.
-
-**Deterministic by design, free by intent.** The rigid part is rigid on purpose. It is
-what makes work portable, reviewable, and resumable across any agent. The free part is
-free on purpose. It is where the brain's creativity lives. Plastic draws the line between
-the two and holds it.
-
-**Harnesses are how it holds the line.** Shared harnesses (conventions, templates, and
-directory structure) constrain humans and agents alike. Agent-extra harnesses (evals that
-check a skill's output, plus hooks and instructions that steer reasoning) give an agent
-the instincts a careful person already has: stop and save state, leave a note when the
-context runs out, never plan before specifying.
-
-This is **intent-driven delivery**, a new shape for the software lifecycle in the age of
-agentic engineering. The unit of work is an *intent*, not a ticket, and every intent
-carries its own spec, plan, checklist, and outcome as it moves through Why, What, How, and
-Execute. What you get is agent-agnostic, auditable, and additive: a knowledge graph of
-*why* things were built, not just what.
+## How Plastic differs
+
+Plastic is not a memory service. Tools like mem0 give an agent a vector
+database to store and recall facts through an API; the memory lives in that
+service, apart from your project. Plastic instead keeps intents as plain,
+git-tracked Markdown files, moved through an enforced lifecycle (What, Why,
+How, Exec) that a person can read without any tooling. The result reads like
+the Zettelkasten linking model long used for personal notes, applied to
+software delivery.
+
+Projects like beads add persistent memory on top of an existing agent
+workflow. Plastic shares that goal, an agent should remember what it did and
+why, but gets there by making the intent itself, with its spec, plan, and
+delivered outcome, the actual unit of work. Plastic runs today with Claude
+Code, and works with Cursor and Cline through the same file-based
+conventions.
 
 ## Install
 
-Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
+Plastic requires Ruby (pre-installed on macOS and Linux) and Node.js 18 or
+later.
 
-```bash
-# Alpha (current, active development)
-npx @zalom/plastic@alpha --claude
+Plastic is in beta. Install with:
 
-# Beta (when available, API-stable, bug hunting)
+```bash
 npx @zalom/plastic@beta --claude
+```
+
+Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
+`--all` for all supported agents.
 
+A stable channel will follow later:
+
+```bash
 # Stable (when available, general use)
 npx @zalom/plastic --claude
 ```
 
-Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
-`--all` for all supported agents.
+The bare command above is not a working install yet. It currently resolves
+to an early stub release, so use `@beta` for now.
 
-Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --claude`).
-Bun is never required.
+Bun users can substitute `bunx` for `npx` (for example, `bunx
+@zalom/plastic@beta --claude`). Bun is never required.
 
 Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
-`plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a Claude Code
-plugin; re-running the installer auto-removes any legacy plugin registration.
+`plastic-auto`, and so on). Invoke them with a hyphen. Plastic is **not** a
+Claude Code plugin; re-running the installer automatically removes any
+legacy plugin registration.
 
 ### Updating
 
 From within your agent, say "update plastic" or run:
 
 ```bash
-npx @zalom/plastic@alpha --claude
+npx @zalom/plastic@beta --claude
 ```
 
-The `plastic-update` command shows available versions across all channels and
-lets you choose which to install.
+The `plastic-update` command shows available versions across all channels
+and lets you choose which to install.
 
 ## Quick Start
 
@@ -101,7 +116,11 @@ After installation, run `/clear` to load Plastic conventions, then:
 4. Use `/plastic-writing-plans` to create an implementation plan
 5. Use `/plastic-executing-plan` to deliver it
 
-Or say "auto" to let the agent handle the full lifecycle autonomously.
+Guided delivery (a human at every gate) is the default. Say "auto" if you
+want the agent to run the full lifecycle on its own instead.
+
+Run `/plastic-dashboard` any time for a Value x Effort view across every
+intent and what to work on next.
 
 ## Agents
 
@@ -119,11 +138,15 @@ install time.
   processes, the store layout, and the component map.
 - [`docs/internals.md`](docs/internals.md): how Plastic stays deterministic, the
   determinism breakdown, and the harness system.
+- [`docs/guides/`](docs/guides/index.md): task-oriented guides, from your
+  first intent in 10 minutes to picking a delivery mode.
 
 ## Conventions
 
-All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`
-during installation. Run `plastic-doctor` to check installation health.
+Plastic conventions live in `PLASTIC.md`, distributed to `~/.plastic/PLASTIC.md`
+and overwritten on every update. Project-specific rules live in `AGENTS.md`,
+scaffolded once at `~/.plastic/AGENTS.md`. Run `plastic-doctor` to check
+installation health.
 `plastic-doctor --core` runs a binary install-integrity check (compares files
 against the install manifests; pass or error). `plastic-doctor --store` checks
 store state (intents, INDEX sections, conventions) and can be scoped to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.36",
+  "version": "1.0.0-beta.37",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/install.rb

@@ -129,7 +129,8 @@ class Install < InstallerCore
     verb = mode == :reinstall ? "re-synced" : "installed"
     puts "\n\u{2705} Plastic v#{version} #{verb}."
     puts "   Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
-    puts "   Run /clear (or restart your agent) to pick up new conventions.\n\n"
+    puts "   Run /clear (or restart your agent) to pick up new conventions."
+    puts "   Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
   end
 
   def show_help

package/skills/install/SKILL.md

@@ -158,7 +158,7 @@ Version:  none -> <installed>
 Doctor:   <summary or "all clear">
 ```
 
-Then: "Create your first intent with `/plastic-creating-intent`."
+Then: "Read `docs/guides/your-first-intent-in-10-minutes.md` for your first intent, start to finish."
 
 ### Local Install (testing/legacy)