@zalom/plastic 1.0.0-alpha.18 → 1.0.0-alpha.19

package/README.md

@@ -4,9 +4,9 @@
 > Install: `npx @zalom/plastic@alpha --claude`
 
 Intent-driven idea development system for AI coding agents. Named after
-**neuroplasticity** — adaptive, malleable, dynamic, resilient.
+**neuroplasticity**: adaptive, malleable, dynamic, resilient.
 
-Plastic thinks in **intents**, not tasks. An intent is a desire — something
+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.
 
@@ -20,18 +20,53 @@ This loop runs continuously across sessions.
 from motivation through specification, 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.
+
 ## Install
 
 Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
 
 ```bash
-# Alpha (current — active development)
+# Alpha (current, active development)
 npx @zalom/plastic@alpha --claude
 
-# Beta (when available — API-stable, bug hunting)
+# Beta (when available, API-stable, bug hunting)
 npx @zalom/plastic@beta --claude
 
-# Stable (when available — general use)
+# Stable (when available, general use)
 npx @zalom/plastic --claude
 ```
 
@@ -42,7 +77,7 @@ Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --cla
 Bun is never required.
 
 Skills install as flat, hyphen-namespaced personal skills (`plastic-doctor`,
-`plastic-auto`, …) — invoke them with a hyphen. Plastic is **not** a Claude Code
+`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.
 
 ### Updating
@@ -68,6 +103,13 @@ After installation, run `/clear` to load Plastic conventions, then:
 
 Or say "auto" to let the agent handle the full lifecycle autonomously.
 
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md): system structure, the two
+  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.
+
 ## Conventions
 
 All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`

package/bin/plastic.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+// Thin shim — npx entry point that dispatches a subcommand to the matching Ruby verb script.
+// All logic lives in scripts/<verb>.rb. JS is only the distribution + dispatch mechanism.
+//
+//   npx @zalom/plastic install   [flags]
+//   npx @zalom/plastic update    [flags]
+//   npx @zalom/plastic uninstall [flags]
+//   npx @zalom/plastic versions  [flags]
+//
+// Back-compat: a bare `--uninstall` (no subcommand) routes to uninstall with a deprecation
+// warning; no subcommand at all defaults to install (legacy behaviour, one release).
+
+import { execFileSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+
+const VERBS = ['install', 'update', 'uninstall', 'versions']
+const packageRoot = new URL('..', import.meta.url).pathname
+const argv = process.argv.slice(2)
+
+let verb
+let rest
+
+if (VERBS.includes(argv[0])) {
+  verb = argv[0]
+  rest = argv.slice(1)
+} else if (argv.includes('--uninstall')) {
+  // Deprecated: `--uninstall` as a flag instead of the `uninstall` subcommand.
+  console.error('! plastic: `--uninstall` is deprecated — use `npx @zalom/plastic uninstall`. (works for now)')
+  verb = 'uninstall'
+  rest = argv.filter((a) => a !== '--uninstall')
+} else {
+  // No subcommand: legacy default to install (one release of grace).
+  verb = 'install'
+  rest = argv
+}
+
+const script = resolve(packageRoot, 'scripts', `${verb}.rb`)
+
+if (!existsSync(script)) {
+  console.error(`Error: scripts/${verb}.rb not found in package.`)
+  process.exit(1)
+}
+
+try {
+  execFileSync('ruby', [script, ...rest], {
+    stdio: 'inherit',
+    env: { ...process.env, PLASTIC_PACKAGE_ROOT: packageRoot },
+  })
+} catch (err) {
+  if (err.status) process.exit(err.status)
+  console.error('Error: Ruby is required to run Plastic.')
+  console.error('  macOS: Ruby is pre-installed')
+  console.error('  Linux: sudo apt install ruby / dnf install ruby')
+  process.exit(1)
+}

package/bin/test

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Runs the FULL Minitest suite in a single process.
+#
+# `release.verify` used to be `ruby -Itest test/*_test.rb`, but Ruby runs only
+# the first glob-expanded file as the program — the rest land in ARGV and are
+# never required. The release gate exercised one test file, reported green, and
+# let releases ship over real failures (intent 30). Pointing verify at this
+# script keeps the runner in version control and guarantees every test file is
+# loaded.
+
+root = File.expand_path("..", __dir__)
+
+files = Dir.glob(File.join(root, "test", "**", "*_test.rb")).sort
+abort "No test files found under #{File.join(root, "test")}" if files.empty?
+
+# `bin/test --list` prints the discovered files without running them, so the
+# discovery logic can be tested cheaply (no full-suite execution).
+if ARGV.delete("--list")
+  puts files.map { |f| f.sub("#{root}/", "") }
+  exit 0
+end
+
+$LOAD_PATH.unshift File.join(root, "test")
+require "minitest/autorun"
+files.each { |f| require f }

package/hooks/bash-gate

@@ -0,0 +1,3 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-bash-gate"

package/hooks/hooks.json

@@ -39,6 +39,16 @@
             "statusMessage": "Checking lifecycle gate..."
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" bash-gate",
+            "statusMessage": "Checking lifecycle gate..."
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-alpha.18",
+  "version": "1.0.0-alpha.19",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {
-    "plastic": "bin/install.js"
+    "plastic": "bin/plastic.js"
   },
   "engines": {
     "node": ">=18.0.0"