@zalom/plastic 1.0.0-alpha.10 → 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.10",
+  "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/auto/SKILL.md

@@ -139,3 +139,7 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 2. Write `savepoint.md` with current state
 3. Notify user: "Blocked on intent [ID] — [name]: [description]. Savepoint written."
 4. **STOP.** Do not attempt workarounds that could leave the project in a broken state.
+
+## References
+
+- Read `references/agent-architecture.md` for the full agent hierarchy (Main Orchestrator, Project Orchestrators, coordination loop) when dispatching agents or understanding autonomous delivery scope

package/skills/auto/references/agent-architecture.md

@@ -0,0 +1,60 @@
+# Agent Architecture
+
+## Main Orchestrator
+
+The Main Orchestrator manages the global store (Main Knowledge Base). It:
+- Recognizes, creates, updates, and groups intents
+- Spawns Project Orchestrators for registered projects
+- Receives contributions back from Project Orchestrators
+- Is the only agent that runs in a loop (continuous Build→Observe→Repeat)
+
+## Project Orchestrators
+
+Project Orchestrators manage project stores (Project Knowledge Bases). They:
+- Care about intents and execution within their project
+- Spawn teams to develop and execute intents
+- Contribute back to the Main Orchestrator when new intents are born
+  that could enrich the Main Knowledge Base
+
+Rules:
+- 1 Main Orchestrator : 1 Global Store (`~/.plastic/`)
+- 1 Main Orchestrator : N Project Orchestrators
+- 1 Project Orchestrator : 1 Project Store
+- 1 Agent : 1 Intent (exclusive assignment)
+- 1 Agent : N Sub-agents (for parallel Actions within an intent)
+
+## Two Modes
+
+- **Human-driven:** Human chats with Main Orchestrator, creates intents,
+  brainstorms, then Main Orchestrator dispatches Project Orchestrators and
+  Agents for execution.
+- **Autonomous:** Human gives Main Orchestrator a starting intent with defined
+  outcomes. Main Orchestrator runs the full cycle — Agents do the lifecycle
+  (What→Why→How→Exec), Main Orchestrator reviews Insights, spawns next intents,
+  dispatches again.
+
+## Autonomous Delivery
+
+Human owns What and Why for human-initiated intents. Agent assists (research,
+exploration) but human drives until handoff. When Why is complete — or human
+triggers `plastic:auto` — the agent takes over How and Exec autonomously.
+
+- **Safe-by-default:** Agent always prefers non-destructive routes (rename vs
+  delete, additive migrations, backups before changes). Destructive actions on
+  existing projects require human approval unless `--skip-permissions` is set.
+- **One agent per intent.** Agent follows the full W→W→H→E lifecycle.
+- **Notification only on:** finish or hard stop (blocked on destructive action,
+  unresolvable error). No progress reports — `## Insights` tracks everything.
+- **Greenfield autonomy:** During initial project creation, all decisions are
+  non-destructive (nothing to destroy). Agent has full autonomy for greenfield choices.
+- **Autonomous decisions** are logged in `## Insights` with `(autonomous)` marker.
+
+## Coordinator Loop
+
+When "work on Project X":
+1. Read `projects.yml` → find project path
+2. Load global config (defaults)
+3. Load project config (overrides)
+4. Load global INDEX.md → find hub intents tagged `project-<name>`
+5. Load project INDEX.md → tactical intents
+6. Coordinator has full picture, dispatches Agent teams

package/skills/continuing/SKILL.md

@@ -102,3 +102,7 @@ Auto-commit all triage changes.
 2. **Project context** — if in a registered project, show governing intent + tactical intents
 3. **Stale future intents** — surface for triage
 4. **Fresh future intents** — offer as next work
+
+## References
+
+- Read `references/context-management.md` for the full save/continue protocol when resuming from a savepoint or when the resume flow needs debugging

package/skills/continuing/references/context-management.md

@@ -0,0 +1,32 @@
+# Context Management (Start-Save-Continue)
+
+## Save Point
+Triggered by PreCompact hook or manually:
+1. Find active intent(s) from `~/.plastic/INDEX.md`
+2. Update active intent's `checklist.md` (check off completed items)
+3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
+4. Add observations to `## Insights`
+5. Update INDEX.md
+6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
+7. Notify user to `/clear`
+
+## Continue
+Triggered by UserPromptSubmit hook when user says "continue". Priority order:
+
+**1. Active intents first (resume work):**
+1. Read INDEX.md → find active intent(s)
+2. Read active intent's `intent.md` → what and why
+3. Read active intent's `savepoint.md` → where we left off
+4. Read active intent's `checklist.md` → what's next
+5. Announce: intent name, current state, next step, blockers
+6. Resume
+
+**2. No active intents → offer future intents:**
+1. List all future intents from INDEX.md
+2. Present them as options
+3. When user picks one, move to Active in INDEX.md
+
+**3. Stale future intents (untouched 3+ days) → triage:**
+- **activate** — start working on it now
+- **abandon** — mark as abandoned
+- **defer to agent** — implement, research, or ideate

package/skills/creating-intent/SKILL.md

@@ -120,3 +120,8 @@ cd <store-root> && git add . && git commit -m "feat: create intent ID — [name]
 ### 8. Announce
 
 "Created intent ID — [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
+
+## References
+
+- Read `references/lifecycle.md` for the full What→Why→How→Exec stage detail, filesystem-as-schema conventions, and creating-intent step-by-step
+- Read `references/wikilinks.md` for the wikilink syntax table when adding `## Links` to intents

package/skills/creating-intent/references/lifecycle.md

@@ -0,0 +1,74 @@
+# Building an Intent — Full Lifecycle Detail
+
+## What → `## Intent` section
+
+The desire. One paragraph. What the human or agent wants.
+This exists from the moment the intent is created.
+
+**Deliverable:** `{ID}--{slug}.md`
+
+## Why → `## Context` + `### Decisions` sections
+
+Why this intent exists. Grows over time through brainstorming and exploration.
+
+- **Context** — what we knew going in + what we decided along the way
+- **Decisions** — main premises derived from Context plus decisions from brainstorming/grilling
+- Decisions are Why-level: "status belongs on actions because multiple workstreams", not How-level: "use ACTION_N.md files"
+
+**Deliverable:** `spec.md` (consolidated specification from Context + Decisions + brainstorming)
+
+## How → Planning and preparation
+
+Research decisions, create the implementation plan, define actions.
+
+**Deliverable:** `plan.md` + `actions/` + `checklist.md` (execution registry with checkboxes covering all actions)
+
+## Exec → Execute actions
+
+Execute actions from the plan, track progress via checklist.
+
+**Deliverable:** `outcome.md` (detailed result). `## Outcome` in intent.md = short summary written as last step.
+
+## `## Insights` — Append-only work log
+
+Captured throughout ALL stages. One-liner bullet points.
+Never modified, only appended.
+
+Tracks: stage transitions, decisions, shifts, blocks, cancellations, material for future intents.
+This is how execution is tracked. When this intent completes, Insights
+is where to look for what comes next. New intents spawned from Insights
+appear in the `chain` field.
+
+## `## Links`
+
+Wikilinks for Obsidian graph navigation. Human-facing counterpart to the
+frontmatter knowledge graph.
+
+## Conventions — Filesystem as Schema
+
+State is derived from what exists, not from what's declared.
+
+| Convention | Signal |
+|---|---|
+| No `## Context` | Intent is fleeting (quick capture, non-actionable) |
+| `## Context` has content | Intent is permanent (developed, actionable) |
+| `## Outcome` has content | Intent is done |
+| `## Insights` has `(autonomous)` entries | Intent is/was being delivered autonomously |
+
+### Transitions
+
+- Fleeting → permanent: add `## Context` (one-way, also makes it actionable)
+- There is no separate "non-actionable → actionable" transition — permanence implies actionability
+- Even research intents are actionable: the research itself is the action, the conclusion is the outcome
+
+## Creating an Intent — Full Steps
+
+1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
+2. Determine the Folgezettel ID: If root (no parent), find highest root number +1. If branch, run `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
+3. Create the intent directory in the chosen store (e.g., `ID--three-to-five-words`)
+4. Create `{ID}--{slug}.md` with frontmatter (id, intent, sources, chain, created, author, tags)
+5. Write `## Intent` — the What
+6. Add remaining sections: `## Context`, `## Outcome`, `## Insights`, `## Links`
+7. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
+
+A fleeting intent can skip `## Context` — just `## Intent` and empty sections.

package/skills/creating-intent/references/wikilinks.md

@@ -0,0 +1,8 @@
+# Wikilink Conventions
+
+| Syntax | Meaning |
+|--------|---------|
+| `[[ID]]` | Link to intent in same store (e.g., `[[1a1]]`) |
+| `[[ID\|display text]]` | Link with human-readable label |
+| `[[global:ID]]` | Link to intent in `~/.plastic/store/` |
+| `[[project-slug:ID]]` | Link to intent in `~/.plastic/projects/{slug}/store/` |

package/skills/creating-project/SKILL.md

@@ -164,3 +164,7 @@ Log in `## Insights` of each founding intent:
 
 Announce to user:
 > "Project `<slug>` created at `<path>`. AGENTS.md populated with [N] decisions from [founding intent IDs]. Tactical mirror `1` is now the active intent in the project store."
+
+## References
+
+- Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/creating-project/references/hubs-projects.md

@@ -0,0 +1,55 @@
+# Hubs and Projects
+
+## Hubs
+
+A Hub is a cloud of intents around related topics. Hubs emerge naturally from
+Folgezettel branching — intents that spawn in the same direction cluster.
+
+- A Hub can spawn a Project. The Hub holds the founding ideas.
+- A single intent can also spawn a Project.
+- Hub-spawned projects revolve around different ideas around related topics.
+- Intent-spawned projects revolve around the single founding intent.
+- A Project is the deliverable outcome of one or more intents.
+
+Hubs are represented as clusters in INDEX.md.
+
+## Projects — Full Detail
+
+A Project is a deliverable grouping of intents. Projects have two stores:
+
+- **Global store** (`~/.plastic/store/`): strategic intents
+- **Project store** (`~/.plastic/projects/{slug}/store/`): tactical intents
+
+`projects.yml` maps project slugs to codebase paths:
+```yaml
+projects:
+  plastic:
+    path: "/path/to/plastic"
+    remote: "git@github.com:org/plastic.git"
+    registered: '2026-05-26'
+    status: active
+```
+
+Config resolution: `~/.plastic/projects/{slug}/config.yml` overrides `~/.plastic/config.yml`.
+
+Cross-linking: project intents reference global intents via `[[global:ID]]`. Global intents reference project intents via `[[project-slug:ID]]`.
+
+## Privacy and Collaboration
+
+**Plastic is personal.** All intent data lives under `~/.plastic/` — one location,
+one git repo, never pushed. Each person has their own intent store.
+
+Collaboration happens through pull requests and project conventions, not shared intents.
+When an intent delivers something that changes how a project works, the decision gets
+written into the project's shared files (README, docs, config). The intents themselves
+are private working memory.
+
+## Project Creation Flow
+
+When an implementation intent spawns a project:
+1. Determine project path from config `project_roots` or intent context
+2. `gh repo create --private` (agent-created repos are always private by default)
+3. Set up project directory, git init, AGENTS.md with founding intent decisions
+4. Register in `projects.yml`
+5. Create tactical mirror in project store
+6. The global intent completes; the tactical mirror becomes the active intent

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.
 ---
 
@@ -110,3 +110,7 @@ This keeps the update flow clean when nothing is wrong.
 - The script outputs JSON to stdout. Any diagnostic errors go to stderr.
 - Non-zero exit codes mean "issues found", not "script crashed".
   Always parse stdout regardless of exit code.
+
+## References
+
+- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and stuck detection thresholds when diagnosing gate failures or stuck agents

package/skills/doctor/references/gates-stuck-detection.md

@@ -0,0 +1,38 @@
+# Gate Enforcement and Stuck Detection
+
+## Bridge File Pattern
+
+`/tmp/plastic-{session}.json` is the hot cache; the filesystem is the authority.
+SessionStart rebuilds the bridge file from the filesystem — the bridge is always disposable.
+
+## Gate Taxonomy
+
+| Gate type | Purpose |
+|---|---|
+| **Pre-flight** | Prerequisites exist? |
+| **Revision** | New info invalidated prior work? |
+| **Escalation** | Blocked items surface to user |
+| **Abort** | Inconsistent state detected |
+
+## Full Gate Enforcement
+
+| Gate | Blocked action | Required prerequisite |
+|---|---|---|
+| Pre-flight | Cannot write `plan.md` | `spec.md` must exist |
+| Pre-flight | Cannot create `actions/` | `spec.md` must exist |
+| Pre-flight | Cannot write `outcome.md` | `checklist.md` must exist with all items checked |
+| Revision | Cannot proceed to Exec | Context changed after spec.md — re-derive spec |
+| Abort | Cannot complete intent | `outcome.md` exists but checklist has unchecked items |
+
+Hard blocking — hooks exit with code 2 when gates fail.
+
+## Stuck Detection
+
+| Condition | Threshold | Action |
+|---|---|---|
+| Consecutive gate failures | 3+ | Warning |
+| Consecutive gate failures | 5+ | Force savepoint + escalate |
+| No activity | 5+ min | Warning |
+| No activity | 10+ min | Force savepoint + escalate |
+| Context pressure | 80% | Warning |
+| Context pressure | 90% | Force savepoint |