@zalom/plastic 1.0.0-alpha.11 → 1.0.0-alpha.12

package/README.md

@@ -1,87 +1,70 @@
 # 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
+## Install
 
-In Claude Code, run:
-```
-/plugin add plastic@plastic
-```
+Plastic requires Ruby (pre-installed on macOS/Linux) and Node.js 18+.
 
-### 3. Initialize in your project
+```bash
+# Alpha (current — active development)
+npx @zalom/plastic@alpha --claude
 
-In Claude Code, run:
-```
-/plastic:install
+# Beta (when available — API-stable, bug hunting)
+npx @zalom/plastic@beta --claude
+
+# Stable (when available — general use)
+npx @zalom/plastic --claude
 ```
 
-## Global vs Local
+Replace `--claude` with `--codex` for Codex CLI, `--hermes` for Hermes, or
+`--all` for all supported agents.
 
-**Global (recommended):** Plastic stores all intents at `~/.plastic/`. Projects spawned by implementation intents get their own `.plastic/store/` for tactical intents.
+### Updating
 
-```
-/plastic:install
-```
-
-**Local (testing):** Intents stored per-project in `.plastic/`. Useful for trying Plastic in a single project.
+From within your agent, say "update plastic" or run:
 
-```
-/plastic:install --local
+```bash
+npx @zalom/plastic@alpha --claude
 ```
 
-## Prerequisites
+The `plastic:update` command shows available versions across all channels and
+lets you choose which to install.
 
-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/.
+## Quick Start
 
-## Directory Structure
-
-```
-.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)
-```
+After installation, run `/clear` to load Plastic conventions, then:
 
-## Skills
+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
 
-| 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 |
+Or say "auto" to let the agent handle the full lifecycle autonomously.
 
-## 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/deprecations.yml

@@ -13,10 +13,10 @@
 
 deprecations:
   - id: cc-plugin-to-npx
-    severity: info
+    severity: warning
     summary: "Plastic distribution is moving from Claude Code plugin to npx install"
     migration_steps:
-      - "Install new distribution: npx @zalom/plastic@latest"
+      - "Install new distribution: npx @zalom/plastic@alpha --claude"
       - "Verify: check that ~/.plastic/ is intact and hooks work"
       - "Remove old plugin: /plugin remove plastic"
     introduced: "1.0.0"

package/package.json

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

package/scripts/install.rb

@@ -3,7 +3,7 @@
 # frozen_string_literal: true
 
 # Plastic installer — runs via npx shim or directly.
-# Usage: ruby scripts/install.rb [--claude] [--codex] [--hermes] [--all] [--uninstall] [--force] [--help]
+# Usage: ruby scripts/install.rb [--claude] [--codex] [--hermes] [--all] [--alpha] [--beta] [--latest] [--uninstall] [--force] [--help]
 
 require "json"
 require "yaml"
@@ -71,7 +71,7 @@ end
 # --- Flag parsing ---
 
 def parse_flags(argv)
-  flags = { agents: [], force: false, uninstall: false, help: false }
+  flags = { agents: [], force: false, uninstall: false, help: false, channel: "latest" }
 
   argv.each do |arg|
     case arg
@@ -79,6 +79,9 @@ def parse_flags(argv)
     when "--force" then flags[:force] = true
     when "--uninstall" then flags[:uninstall] = true
     when "--help", "-h" then flags[:help] = true
+    when "--alpha" then flags[:channel] = "alpha"
+    when "--beta" then flags[:channel] = "beta"
+    when "--latest" then flags[:channel] = "latest"
     else
       agent = AGENTS.find { |a| a[:flag] == arg }
       flags[:agents] << agent[:key] if agent
@@ -115,22 +118,30 @@ def show_help
     plastic - Intent-driven idea development system
 
     Usage:
-      npx @zalom/plastic@latest [options]
+      npx @zalom/plastic [options]
 
-    Options:
+    Agent options:
       --claude      Install for Claude Code
       --codex       Install for Codex CLI
       --hermes      Install for Hermes
       --all         Install for all supported agents
+
+    Channel options:
+      --latest      Install from stable channel (default)
+      --beta        Install from beta channel
+      --alpha       Install from alpha channel
+
+    Other options:
       --force       Overwrite existing files without prompting
       --uninstall   Remove Plastic from agent directories
       -h, --help    Show this help
 
     Examples:
-      npx @zalom/plastic@latest              Interactive agent selection
-      npx @zalom/plastic@latest --claude     Install for Claude Code only
-      npx @zalom/plastic@latest --all        Install for all agents
-      npx @zalom/plastic@latest --uninstall  Remove from agent directories
+      npx @zalom/plastic --claude            Install stable for Claude Code
+      npx @zalom/plastic@alpha --claude      Install alpha for Claude Code
+      npx @zalom/plastic@beta --claude       Install beta for Claude Code
+      npx @zalom/plastic --all               Install stable for all agents
+      npx @zalom/plastic --uninstall         Remove from agent directories
 
   HELP
 end

package/skills/doctor/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: doctor
+name: plastic:doctor
 description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
 ---
 

package/skills/install/SKILL.md

@@ -1,10 +1,34 @@
 ---
 name: plastic:install
-description: Use when initializing Plastic globally (~/.plastic/) or locally in a project. Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+description: Use when initializing Plastic globally (~/.plastic/) or locally in a project. Accepts channel flags (--alpha, --beta, --latest) to select release channel. Default is --latest (stable). Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
 ---
 
 # Install Plastic
 
+## Channel Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--latest` | Install from stable channel (default) |
+| `--beta` | Install from beta channel |
+| `--alpha` | Install from alpha channel |
+
+When invoked from within Claude Code (re-install or channel switch), the skill
+runs the appropriate npx command:
+
+```bash
+# Stable (default)
+npx @zalom/plastic --claude
+
+# Beta
+npx @zalom/plastic@beta --claude
+
+# Alpha
+npx @zalom/plastic@alpha --claude
+```
+
+The installed version and channel are recorded in `~/.plastic/VERSION`.
+
 ## Modes
 
 ### Global Install (default, recommended)

package/skills/releasing/SKILL.md

@@ -140,16 +140,24 @@ For the first release (no previous tag), write notes manually with `--notes "...
 
 #### `npm_publish`
 
-Publish the package to npm:
+Publish the package to npm with the appropriate dist-tag:
 
 ```bash
-# For pre-release versions (0.x.y, or version contains -alpha/-beta/-rc):
+# Alpha pre-release (version contains -alpha):
 npm publish --access public --tag alpha
 
-# For stable versions (>= 1.0.0, no pre-release suffix):
+# Beta pre-release (version contains -beta):
+npm publish --access public --tag beta
+
+# Stable release (no pre-release suffix, >= 1.0.0):
 npm publish --access public
 ```
 
+The dist-tag is derived from the version string in `package.json`:
+- Contains `-alpha` → `--tag alpha`
+- Contains `-beta` → `--tag beta`
+- No pre-release suffix → no `--tag` flag (publishes to `latest`)
+
 #### Other values
 
 If `on_green` contains an action not listed above, log it:
@@ -184,6 +192,24 @@ A release IS a delivery. The active intent that drove this work must be complete
 - **Version files** — driven by project.yml; all listed files must always match
 - **Branch cleanup** — delete merged feature branches: `git branch -d <branch>`
 
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic:releasing --promote beta    # promotes current alpha → beta
+plastic:releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
 ## Retroactive Tagging
 
 For repos without prior tags, tag historical releases:

package/skills/update/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: update
-description: Use when updating Plastic after a plugin update, or when the user says "update plastic". Runs the npx installer to sync core files and re-register agent adapters.
+name: plastic:update
+description: Use when updating Plastic. Queries npm for available versions across all channels, presents options interactively, or accepts --alpha/--beta/--latest flags for direct update.
 ---
 
 # Update Plastic
@@ -10,43 +10,98 @@ description: Use when updating Plastic after a plugin update, or when the user s
 - Statusline shows "Plastic update available"
 - After a version bump notification
 
+## Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--alpha` | Update to latest alpha, skip interactive prompt |
+| `--beta` | Update to latest beta, skip interactive prompt |
+| `--latest` | Update to latest stable, skip interactive prompt |
+
+No flag = interactive mode (show all available versions).
+
 ## Prerequisites
 
 Global install must exist (`~/.plastic/INDEX.md` present). If not, tell the
-user to run `npx @zalom/plastic@latest` first.
+user to run `npx @zalom/plastic@alpha --claude` first.
 
 ## Procedure
 
-### Step 1: Verify global install exists
+### Step 1: Read current version
+
+```bash
+cat ~/.plastic/VERSION
+```
+
+Parse the version string to determine the current channel:
+- Contains `-alpha` → alpha channel
+- Contains `-beta` → beta channel
+- No pre-release suffix → stable/latest channel
+
+### Step 2: Query npm for available versions
 
 ```bash
-if [ ! -f ~/.plastic/INDEX.md ]; then
-  echo "No global install found. Run: npx @zalom/plastic@latest"
-  exit
-fi
+npm view @zalom/plastic dist-tags --json
+```
+
+This returns a JSON object like:
+```json
+{
+  "latest": "0.0.1",
+  "alpha": "1.0.0-alpha.14",
+  "beta": "1.0.0-beta.2"
+}
+```
+
+A missing dist-tag means no release exists on that channel.
+
+### Step 3: Present options or act on flag
+
+**If a channel flag was provided** (`--alpha`, `--beta`, `--latest`):
+
+Skip the interactive prompt. Install the flagged channel directly. Go to Step 4.
+
+**If no flag (interactive mode):**
+
+Present the available updates to the user:
+
 ```
+Currently installed: 1.0.0-alpha.11 (alpha channel)
 
-### Step 2: Run the installer
+Available updates:
+  alpha:  1.0.0-alpha.14  ← your channel
+  beta:   1.0.0-beta.2
+  stable: (no stable release yet)
+
+Which channel do you want to install?
+```
+
+Use AskUserQuestion with the available channels as options. Mark the user's
+current channel with "← your channel". If a dist-tag points to the same
+version as currently installed, show "(up to date)" instead of the version.
+If a dist-tag doesn't exist, show "(no release yet)".
+
+Wait for user selection.
+
+### Step 4: Run the installer
 
 ```bash
-npx @zalom/plastic@latest --claude
+npx @zalom/plastic@{selected-tag} --claude
 ```
 
-This re-runs the installer which:
-- Downloads the latest version from npm
-- Syncs core files (PLASTIC.md, scripts, hooks) to ~/.plastic/
-- Re-registers hooks and skills into Claude Code's ~/.claude/
-- Preserves all user data (INDEX.md, config.yml, projects.yml, store/)
+Replace `{selected-tag}` with `alpha`, `beta`, or `latest` based on the
+user's selection or the flag provided. Replace `--claude` with the appropriate
+agent flag(s) — detect current agents from `~/.claude/`, `~/.agents/`,
+`~/.hermes/` directories.
 
-### Step 3: Announce key changes
+### Step 5: Announce key changes
 
 After the installer completes, read `~/.plastic/PLASTIC.md` and announce any
-convention changes that affect the current session. This corrects the agent's
-in-context understanding without needing /clear.
+convention changes that affect the current session.
 
 Format:
 ```
-Plastic updated to vX.Y.Z.
+Plastic updated to vX.Y.Z (channel).
 
 Key changes in this version:
 - [list notable convention changes if any]
@@ -54,24 +109,22 @@ Key changes in this version:
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Run health check
+### Step 6: Run health check
 
 Invoke `plastic:doctor` to verify the installation is healthy after the update.
 
 If all checks pass, show: **"Health check: all clear."**
 
-If issues are found, show the full doctor report and offer to fix any fixable items.
+If issues are found, show the full doctor report and offer to fix.
 
-### Step 5: Commit
+### Step 7: Commit
 
 ```bash
-cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
+cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic to $(cat ~/.plastic/VERSION)" --allow-empty
 ```
 
-### Step 6: Clear update cache
+### Step 8: Clear update cache
 
 ```bash
 rm -f ~/.plastic/.cache/update-check.json
 ```
-
-This removes the statusline warning since the update is now applied.