@zalom/plastic 1.0.0-alpha.2 → 1.0.0-alpha.21

package/README.md

@@ -1,87 +1,119 @@
 # Plastic
 
-> Intent-driven state management for AI coding sessions.
-> Named after **neuroplasticity** — adaptive, malleable, dynamic, resilient.
+> **Alpha software.** Expect breaking changes between releases.
+> Install: `npx @zalom/plastic@alpha --claude`
 
-## What Is This?
+Intent-driven idea development system for AI coding agents. Named after
+**neuroplasticity**: adaptive, malleable, dynamic, resilient.
 
-Plastic implements two nested processes: **Build → Observe → Repeat** (Coordinator's continuous loop) and **What → Why → How → Next** (intent's finite lifecycle). Zettelkasten-inspired linking connects intents. All project state lives in `.plastic/`. Everything is an intent.
+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.
 
-## Installation
+## The Two Cycles
 
-### 1. Register the marketplace
+**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.
 
-In Claude Code, run:
-```
-/plugin marketplace add zalom/plastic
-```
+**Intent lifecycle (W→W→H→E):** Why → What → How → Execute. Each intent moves
+from motivation through specification, planning, to delivery. Intents produce
+artifacts: `spec.md`, `plan.md`, `checklist.md`, `outcome.md`.
 
-### 2. Install the plugin
+## How Plastic Works
 
-In Claude Code, run:
-```
-/plugin add plastic@plastic
-```
+Plastic is a **thinking system**, a blueprint for taking a desire from intent to
+delivery. It splits the work in two:
 
-### 3. Initialize in your project
+- **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.
 
-In Claude Code, run:
-```
-/plastic:install
-```
+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.
 
-## Global vs Local
+**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.
 
-**Global (recommended):** Plastic stores all intents at `~/.plastic/`. Projects spawned by implementation intents get their own `.plastic/store/` for tactical intents.
+**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.
 
-```
-/plastic:install
-```
+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.
 
-**Local (testing):** Intents stored per-project in `.plastic/`. Useful for trying Plastic in a single project.
+## Install
 
-```
-/plastic:install --local
+Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
+
+```bash
+# Alpha (current, active development)
+npx @zalom/plastic@alpha --claude
+
+# Beta (when available, API-stable, bug hunting)
+npx @zalom/plastic@beta --claude
+
+# Stable (when available, general use)
+npx @zalom/plastic --claude
 ```
 
-## Prerequisites
+Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
+`--all` for all supported agents.
 
-Plastic hooks use Ruby for intent ID generation. Ruby is pre-installed on macOS/Linux. On Windows, use WSL or install Ruby from https://rubyinstaller.org/.
+Bun users can substitute `bunx` for `npx` (e.g. `bunx @zalom/plastic@alpha --claude`).
+Bun is never required.
 
-## Directory Structure
+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.
 
+### Updating
+
+From within your agent, say "update plastic" or run:
+
+```bash
+npx @zalom/plastic@alpha --claude
 ```
-.plastic/
-├── AGENTS.md           # Conventions contract for all agents
-├── config.yml          # Plugin configuration
-├── INDEX.md            # Brain's entry point
-└── store/
-    └── ID--three-to-five-words/
-        ├── {ID}--{slug}.md         # Always present (e.g., 1a1--design-plastic.md)
-        ├── spec.md         # Optional (brainstorming output)
-        ├── plan.md         # Optional (implementation plan)
-        ├── checklist.md    # Optional (progress tracking)
-        └── savepoint.md    # Optional (session state)
-```
 
-## Skills
+The `plastic-update` command shows available versions across all channels and
+lets you choose which to install.
+
+## Quick Start
+
+After installation, run `/clear` to load Plastic conventions, then:
+
+1. Say "new intent" or run `/plastic-creating-intent` to create your first intent
+2. Describe what you want to accomplish
+3. Use `/plastic-brainstorming` to explore the design
+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.
+
+## Documentation
 
-| Skill | Purpose |
-|-------|---------|
-| `install` | Initialize `.plastic/` in a new project |
-| `creating-intent` | Create a new intent with directory, hash, and INDEX.md entry |
-| `savepoint` | Save active intent state before context reset |
-| `continuing` | Resume from savepoint after `/clear` |
-| `linking-intents` | Connect intents via Zettelkasten links |
-| `managing-index` | Curate INDEX.md structure note |
-| `executing-plan` | Execute plans via subagent-driven (default) or inline mode |
+- [`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.
 
-## Agents
+## Conventions
 
-| Agent | Purpose |
-|-------|---------|
-| `intent-curator` | Maintains INDEX.md health, suggests links |
-| `future-intent-researcher` | Researches parked future intents |
+All conventions live in `AGENTS.md`, distributed to `~/.plastic/AGENTS.md`
+during installation. Run `plastic-doctor` to check installation health.
 
 ## License
 

package/agents/future-intent-researcher.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:future-intent-researcher
+name: plastic-future-intent-researcher
 description: |
   Use this agent to research future intents autonomously. Picks up parked
   intents from INDEX.md, investigates them via web search and codebase analysis,

package/agents/intent-curator.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:intent-curator
+name: plastic-intent-curator
 description: |
   Use this agent when completing or reviewing intents, reorganizing the index,
   or when the intent store needs maintenance. Examples:

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/deprecations.yml

@@ -12,12 +12,13 @@
 #   link: optional URL to migration guide
 
 deprecations:
-  - id: cc-plugin-to-npx
-    severity: info
-    summary: "Plastic distribution is moving from Claude Code plugin to npx install"
+  - id: cc-plugin-to-hyphen-skills
+    severity: warning
+    summary: "Plastic now ships as flat hyphen-named personal skills (plastic-doctor), not a Claude Code plugin. Invocation changed from plastic:<name> to plastic-<name>."
     migration_steps:
-      - "Install new distribution: npx @zalom/plastic@latest"
-      - "Verify: check that ~/.plastic/ is intact and hooks work"
-      - "Remove old plugin: /plugin remove plastic"
+      - "Re-run the installer: npx @zalom/plastic@latest --claude (bunx also works)"
+      - "It auto-removes the old plugin/marketplace registration — no /plugin step needed"
+      - "Invoke skills with a hyphen now: /plastic-doctor, /plastic-auto, etc."
+      - "Run /plastic-doctor to verify"
     introduced: "1.0.0"
     removal: "2.0.0"

package/hooks/auto-arm

@@ -0,0 +1,5 @@
+#!/bin/bash
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["user_prompt"].to_s' 2>/dev/null || echo "")
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-auto-arm" "$MESSAGE"

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/check-update

@@ -1,11 +1,15 @@
 #!/bin/bash
-# plastic-hook-version: 1.0.0
-# Runs on SessionStart — checks npm for newer version, writes cache
+# plastic-hook-version: 1.1.0
+# Runs on SessionStart — checks npm for a newer version on the installed
+# channel, writes cache. Channel-aware: queries dist-tags and picks the best
+# upgrade target instead of blindly trusting the `latest` tag.
 
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLASTIC_HOME="$HOME/.plastic"
 CACHE_DIR="$PLASTIC_HOME/.cache"
 CACHE_FILE="$CACHE_DIR/update-check.json"
 VERSION_FILE="$PLASTIC_HOME/VERSION"
+SELECTOR="$SCRIPT_DIR/../scripts/select-update-target"
 
 mkdir -p "$CACHE_DIR"
 
@@ -21,21 +25,21 @@ fi
 
 # Background check — don't block session start
 (
-  RAW=$(npm view @zalom/plastic version 2>/dev/null)
-  LATEST=$(echo "$RAW" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$')
+  TAGS=$(npm view @zalom/plastic dist-tags --json 2>/dev/null)
 
-  if [ -z "$LATEST" ]; then
+  if [ -z "$TAGS" ]; then
     exit 0
   fi
 
+  TARGET=$(printf '%s' "$TAGS" | ruby "$SELECTOR" "$CURRENT" 2>/dev/null)
   CHECKED=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
-  if [ "$LATEST" != "$CURRENT" ]; then
+  if [ -n "$TARGET" ]; then
     printf '{"current":"%s","latest":"%s","checked":"%s","updateAvailable":true}\n' \
-      "$CURRENT" "$LATEST" "$CHECKED" > "$CACHE_FILE"
+      "$CURRENT" "$TARGET" "$CHECKED" > "$CACHE_FILE"
   else
     printf '{"current":"%s","latest":"%s","checked":"%s","updateAvailable":false}\n' \
-      "$CURRENT" "$LATEST" "$CHECKED" > "$CACHE_FILE"
+      "$CURRENT" "$CURRENT" "$CHECKED" > "$CACHE_FILE"
   fi
 ) &
 

package/hooks/code-gate

@@ -0,0 +1,10 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("tool_params", "file_path") || data.dig("tool_input", "file_path") || ""' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-code-gate" "$FILE_PATH"

package/hooks/hooks.json

@@ -29,6 +29,28 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" code-gate",
+            "statusMessage": "Checking lifecycle gate..."
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" bash-gate",
+            "statusMessage": "Checking lifecycle gate..."
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
@@ -61,15 +83,14 @@
             "statusMessage": "Checking future intents..."
           }
         ]
-      }
-    ],
-    "statusLine": [
+      },
       {
         "matcher": "",
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/statusline\""
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/auto-arm\"",
+            "statusMessage": "Checking auto mode..."
           }
         ]
       }

package/hooks/statusline

@@ -1,16 +1,56 @@
 #!/bin/bash
-# plastic-hook-version: 1.0.0
-# StatusLine hook — shows update available warning
+# plastic-hook-version: 2.0.0
+# StatusLine hook — chains user's original statusline, adds Plastic info
 
-CACHE_FILE="$HOME/.plastic/.cache/update-check.json"
+INPUT=$(cat)
+
+# --- Chain original statusline ---
+ORIGINAL_CONFIG="$HOME/.plastic/.cache/original-statusline.json"
+ORIGINAL_OUTPUT=""
+if [ -f "$ORIGINAL_CONFIG" ]; then
+  ORIGINAL_CMD=$(grep -o '"command":"[^"]*"' "$ORIGINAL_CONFIG" 2>/dev/null | head -1 | cut -d'"' -f4)
+  if [ -z "$ORIGINAL_CMD" ]; then
+    ORIGINAL_CMD=$(grep -o '"command": "[^"]*"' "$ORIGINAL_CONFIG" 2>/dev/null | head -1 | sed 's/.*"command": "//;s/".*//')
+  fi
+  if [ -n "$ORIGINAL_CMD" ] && [ -x "$ORIGINAL_CMD" ]; then
+    ORIGINAL_OUTPUT=$(echo "$INPUT" | "$ORIGINAL_CMD" 2>/dev/null)
+  fi
+fi
+
+# --- Plastic status ---
+PLASTIC_PARTS=""
 
-if [ ! -f "$CACHE_FILE" ]; then
-  exit 0
+# Active intent from INDEX.md
+INDEX="$HOME/.plastic/INDEX.md"
+if [ -f "$INDEX" ]; then
+  ACTIVE=$(sed -n '/^## Active$/,/^## /{/^- \[/p;}' "$INDEX" | head -1)
+  if [ -n "$ACTIVE" ]; then
+    INTENT=$(echo "$ACTIVE" | sed 's/^- \[\([^]]*\)\].*/\1/')
+    PLASTIC_PARTS="plastic: ${INTENT}"
+  fi
+fi
+
+# Update notification
+CACHE_FILE="$HOME/.plastic/.cache/update-check.json"
+if [ -f "$CACHE_FILE" ]; then
+  UPDATE_AVAILABLE=$(grep -o '"updateAvailable":true' "$CACHE_FILE" 2>/dev/null)
+  if [ -n "$UPDATE_AVAILABLE" ]; then
+    LATEST=$(grep -o '"latest":"[^"]*"' "$CACHE_FILE" 2>/dev/null | head -1 | cut -d'"' -f4)
+    CURRENT=$(grep -o '"current":"[^"]*"' "$CACHE_FILE" 2>/dev/null | head -1 | cut -d'"' -f4)
+    UPDATE_MSG="plastic update: $CURRENT -> $LATEST"
+    if [ -n "$PLASTIC_PARTS" ]; then
+      PLASTIC_PARTS="$PLASTIC_PARTS | $UPDATE_MSG"
+    else
+      PLASTIC_PARTS="$UPDATE_MSG"
+    fi
+  fi
 fi
 
-UPDATE_AVAILABLE=$(grep -o '"updateAvailable":true' "$CACHE_FILE" 2>/dev/null)
-if [ -n "$UPDATE_AVAILABLE" ]; then
-  LATEST=$(grep -o '"latest":"[^"]*"' "$CACHE_FILE" | cut -d'"' -f4)
-  CURRENT=$(grep -o '"current":"[^"]*"' "$CACHE_FILE" | cut -d'"' -f4)
-  echo "Plastic update: $CURRENT → $LATEST — run /plastic:update"
+# --- Combine output ---
+if [ -n "$ORIGINAL_OUTPUT" ] && [ -n "$PLASTIC_PARTS" ]; then
+  echo "$ORIGINAL_OUTPUT | $PLASTIC_PARTS"
+elif [ -n "$ORIGINAL_OUTPUT" ]; then
+  echo "$ORIGINAL_OUTPUT"
+elif [ -n "$PLASTIC_PARTS" ]; then
+  echo "$PLASTIC_PARTS"
 fi

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.21",
   "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"