@zalom/plastic 1.0.0-alpha.1

package/agents/intent-curator.md

@@ -0,0 +1,40 @@
+---
+name: plastic:intent-curator
+description: |
+  Use this agent when completing or reviewing intents, reorganizing the index,
+  or when the intent store needs maintenance. Examples:
+  <example>Context: User has finished implementing a feature.
+  user: "This intent is done, clean up the index"
+  assistant: "I'll use the intent-curator agent to update the intent status and reorganize INDEX.md"
+  <commentary>Intent lifecycle change triggers curator for index maintenance.</commentary></example>
+  <example>Context: The intent store has grown and clusters need review.
+  user: "Organize the intents"
+  assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
+  <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Intent Curator. Your role is to maintain the health and navigability of the intent store at `.plastic/`.
+
+## Your Responsibilities
+
+1. **Intent lifecycle management** — move intents between Active/Future/Completed in INDEX.md, fill in `## Outcome` sections
+2. **INDEX.md maintenance** — keep Active/Future/Clusters/Completed sections accurate and well-organized
+3. **Link discovery** — suggest connections between intents that share topics but aren't linked
+4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
+5. **Orphan detection** — flag intents with no links and no cluster membership
+
+## How You Work
+
+1. Scan `~/.plastic/store/*/ID--slug.md` (or project store) to understand the full intent landscape
+2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
+3. Compare: are there intents not in any cluster? Missing from Active/Completed? Status mismatches?
+4. Make targeted edits to INDEX.md and intent frontmatter/links
+5. Report what you changed
+
+## Constraints
+
+- You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
+- You never create new intents — that's the creating-intent skill's job
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
+- You use Read and grep/find for discovery, Edit for targeted changes

package/bin/install.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+// Thin shim — npx entry point that delegates to the Ruby installer.
+// All logic lives in scripts/install.rb. JS is only the distribution mechanism.
+
+import { execFileSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+
+const packageRoot = new URL('..', import.meta.url).pathname
+const installer = resolve(packageRoot, 'scripts', 'install.rb')
+
+if (!existsSync(installer)) {
+  console.error('Error: scripts/install.rb not found in package.')
+  process.exit(1)
+}
+
+try {
+  execFileSync('ruby', [installer, ...process.argv.slice(2)], {
+    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 install Plastic.')
+  console.error('  macOS: Ruby is pre-installed')
+  console.error('  Linux: sudo apt install ruby / dnf install ruby')
+  process.exit(1)
+}

package/deprecations.yml

@@ -0,0 +1,23 @@
+# Plastic deprecation notices
+# Each entry is shown to the user during SessionStart.
+# See PLASTIC.md "Deprecation Process" for the full convention.
+#
+# Schema:
+#   id: unique-slug (used for dismissal tracking)
+#   severity: info | warning | critical
+#   summary: one-line human description
+#   migration_steps: ordered list of what user must do
+#   introduced: semver where notice was added
+#   removal: semver where feature is removed
+#   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"
+    migration_steps:
+      - "Install new distribution: npx @zalom/plastic@latest"
+      - "Verify: check that ~/.plastic/ is intact and hooks work"
+      - "Remove old plugin: /plugin remove plastic"
+    introduced: "1.0.0"
+    removal: "2.0.0"

package/hooks/check-update

@@ -0,0 +1,42 @@
+#!/bin/bash
+# plastic-hook-version: 1.0.0
+# Runs on SessionStart — checks npm for newer version, writes cache
+
+PLASTIC_HOME="$HOME/.plastic"
+CACHE_DIR="$PLASTIC_HOME/.cache"
+CACHE_FILE="$CACHE_DIR/update-check.json"
+VERSION_FILE="$PLASTIC_HOME/VERSION"
+
+mkdir -p "$CACHE_DIR"
+
+if [ ! -f "$VERSION_FILE" ]; then
+  exit 0
+fi
+
+CURRENT=$(cat "$VERSION_FILE" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$')
+
+if [ -z "$CURRENT" ]; then
+  exit 0
+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.]+)?$')
+
+  if [ -z "$LATEST" ]; then
+    exit 0
+  fi
+
+  CHECKED=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  if [ "$LATEST" != "$CURRENT" ]; then
+    printf '{"current":"%s","latest":"%s","checked":"%s","updateAvailable":true}\n' \
+      "$CURRENT" "$LATEST" "$CHECKED" > "$CACHE_FILE"
+  else
+    printf '{"current":"%s","latest":"%s","checked":"%s","updateAvailable":false}\n' \
+      "$CURRENT" "$LATEST" "$CHECKED" > "$CACHE_FILE"
+  fi
+) &
+
+exit 0

package/hooks/continue

@@ -0,0 +1,31 @@
+#!/bin/bash
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["user_prompt"]' 2>/dev/null || echo "")
+
+if echo "$MESSAGE" | grep -iq '\bcontinue\b'; then
+  GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+
+  if [ ! -f "$GLOBAL_INDEX" ]; then
+    exit 0
+  fi
+
+  INDEX="$GLOBAL_INDEX"
+  STORE_ROOT="$HOME/.plastic"
+  MODE="global"
+
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  OUTPUT=$(ruby "$SCRIPT_DIR/../scripts/hook-continue" "$INDEX" "$STORE_ROOT" "$MODE" 2>/dev/null)
+
+  if [ -n "$OUTPUT" ]; then
+    echo "$OUTPUT"
+  else
+    cat <<'HOOKJSON'
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "PLASTIC CONTINUE — The user wants to resume previous work.\n\nRead ~/.plastic/INDEX.md and follow the continuing skill workflow."
+  }
+}
+HOOKJSON
+  fi
+fi

package/hooks/future-intent-check

@@ -0,0 +1,25 @@
+#!/bin/bash
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["user_prompt"].downcase' 2>/dev/null || echo "")
+
+if [ ${#MESSAGE} -lt 10 ]; then
+  exit 0
+fi
+
+if echo "$MESSAGE" | grep -qx '\s*continue\s*'; then
+  exit 0
+fi
+
+GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+LOCAL_INDEX=".plastic/INDEX.md"
+
+if [ -f "$GLOBAL_INDEX" ]; then
+  STORE_ROOT="$HOME/.plastic"
+elif [ -f "$LOCAL_INDEX" ]; then
+  STORE_ROOT=".plastic"
+else
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-future-intent-check" "$STORE_ROOT" "$MESSAGE"

package/hooks/gate-check

@@ -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-gate-check" "$FILE_PATH"

package/hooks/hooks.json

@@ -0,0 +1,78 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" session-start",
+            "statusMessage": "Loading Plastic context..."
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/check-update\"",
+            "statusMessage": ""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" savepoint",
+            "statusMessage": "Saving Plastic intent state..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" gate-check",
+            "statusMessage": "Checking lifecycle gates..."
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" continue",
+            "statusMessage": "Checking for continue..."
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/future-intent-check\"",
+            "statusMessage": "Checking future intents..."
+          }
+        ]
+      }
+    ],
+    "statusLine": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/statusline\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook

@@ -0,0 +1,7 @@
+#!/bin/bash
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK_NAME="$1"
+shift
+if [ -f "$HOOK_DIR/$HOOK_NAME" ]; then
+  exec "$HOOK_DIR/$HOOK_NAME" "$@"
+fi

package/hooks/savepoint

@@ -0,0 +1,6 @@
+#!/bin/bash
+cat <<'HOOKJSON'
+{
+  "systemMessage": "PLASTIC SAVEPOINT — Context is being compacted.\n\nYou MUST perform the savepoint procedure NOW:\n1. Read .plastic/INDEX.md to find active intent(s)\n2. For each active intent in .plastic/store/ID--slug/:\n   a. Update checklist.md (check off completed items)\n   b. Create/update savepoint.md (in-progress work, next steps, blockers, discoveries)\n   c. Update intent.md Build/Observe sections with session work\n3. Update .plastic/INDEX.md active section\n4. Commit: git add .plastic/ && git commit -m 'chore: savepoint — [intent name]'\n5. Tell the user: 'Context is getting large. I have saved progress to the active intent. Please run /clear and say continue to resume.'\n\nDO NOT skip this. The user's work depends on it."
+}
+HOOKJSON

package/hooks/session-start

@@ -0,0 +1,9 @@
+#!/bin/bash
+GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+
+if [ ! -f "$GLOBAL_INDEX" ]; then
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ruby "$SCRIPT_DIR/../scripts/hook-session-start" "$GLOBAL_INDEX" "$HOME/.plastic" "global" "${CLAUDE_PLUGIN_ROOT:-}"

package/hooks/statusline

@@ -0,0 +1,16 @@
+#!/bin/bash
+# plastic-hook-version: 1.0.0
+# StatusLine hook — shows update available warning
+
+CACHE_FILE="$HOME/.plastic/.cache/update-check.json"
+
+if [ ! -f "$CACHE_FILE" ]; then
+  exit 0
+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"
+fi

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zalom/plastic",
+  "version": "1.0.0-alpha.1",
+  "description": "Intent-driven idea development system for AI coding agents",
+  "type": "module",
+  "bin": {
+    "plastic": "bin/install.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "intent-driven",
+    "idea-development",
+    "zettelkasten",
+    "ai-agent",
+    "multi-agent",
+    "neuroplasticity",
+    "claude-code",
+    "codex-cli",
+    "hermes"
+  ],
+  "author": {
+    "name": "Zlatko Alomerovic",
+    "email": "zlatko.alomerovic@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zalom/plastic"
+  },
+  "homepage": "https://github.com/zalom/plastic",
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "hooks/",
+    "agents/",
+    "templates/",
+    "PLASTIC.md",
+    "deprecations.yml"
+  ]
+}

package/scripts/folgezettel-id

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# Generate the next available Folgezettel ID for a new intent.
+#
+# Usage:
+#   folgezettel-id <store_path>                    # next root ID
+#   folgezettel-id <store_path> <parent_id>        # next child of parent
+
+store_path = ARGV[0]
+parent_id = ARGV[1] # nil for root
+
+unless store_path && Dir.exist?(store_path)
+  $stderr.puts "Usage: folgezettel-id <store_path> [parent_id]"
+  exit 1
+end
+
+existing_dirs = Dir.glob("#{store_path}/*--*").map { |d| File.basename(d).split("--").first }
+
+if parent_id.nil? || parent_id.empty?
+  roots = existing_dirs.select { |id| id.match?(/\A\d+\z/) }.map(&:to_i)
+  next_root = roots.empty? ? 1 : roots.max + 1
+  puts next_root.to_s
+else
+  depth = parent_id.length
+  use_letter = parent_id[-1].match?(/\d/)
+
+  children = existing_dirs.select do |id|
+    id.start_with?(parent_id) && id.length == depth + 1
+  end
+
+  suffixes = children.map { |id| id[-1] }
+
+  if use_letter
+    last = suffixes.select { |s| s.match?(/[a-z]/) }.max || "`"
+    puts "#{parent_id}#{last.succ}"
+  else
+    last = suffixes.select { |s| s.match?(/\d/) }.map(&:to_i).max || 0
+    puts "#{parent_id}#{last + 1}"
+  end
+end

package/scripts/hash-intent

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Generate a 6-char deterministic hash for an intent name.
+# Auto-detects Ruby or Node.js. Exits with error if neither available.
+#
+# Usage: hash-intent "intent name words"
+
+INTENT_NAME="$1"
+
+if [ -z "$INTENT_NAME" ]; then
+  echo "Usage: hash-intent \"intent name\"" >&2
+  exit 1
+fi
+
+# Try Ruby first (macOS/Linux default)
+if command -v ruby &>/dev/null; then
+  ruby -r digest -e 'puts Digest::SHA256.hexdigest(ARGV[0]).to_i(16).to_s(36)[0,6]' "$INTENT_NAME"
+  exit 0
+fi
+
+# Fallback to Node.js (common on Windows)
+if command -v node &>/dev/null; then
+  node -e "const c=require('crypto');console.log(BigInt('0x'+c.createHash('sha256').update(process.argv[1]).digest('hex')).toString(36).slice(0,6))" "$INTENT_NAME"
+  exit 0
+fi
+
+echo "Error: Neither ruby nor node found. Install one of them." >&2
+echo "  macOS/Linux: Ruby is usually pre-installed" >&2
+echo "  Windows: Install Node.js or use WSL" >&2
+exit 1

package/scripts/hook-continue

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# Usage: hook-continue <index_path> <store_root> <mode>
+# Outputs hook JSON for the continue hook. Exits silently if nothing to show.
+
+require "json"
+require "date"
+require "yaml"
+
+index_path, store_root, mode = ARGV
+exit 0 unless index_path && store_root && mode
+
+# --- Parse INDEX.md ---
+
+lines = File.readlines(index_path)
+active = []
+future = []
+section = nil
+
+lines.each do |line|
+  if line.start_with?("## Active")
+    section = :active
+    next
+  elsif line.start_with?("## Future")
+    section = :future
+    next
+  elsif line.start_with?("## ")
+    section = nil
+    next
+  end
+
+  next unless section && line.strip.start_with?("- [")
+
+  if section == :active
+    active << line.strip
+  elsif section == :future
+    future << line.strip
+  end
+end
+
+# --- Detect stale future intents ---
+
+stale = []
+stale_days = 3
+config_path = "#{store_root}/config.yml"
+if File.exist?(config_path)
+  config = YAML.safe_load(File.read(config_path)) rescue {}
+  stale_days = config["stale_threshold_days"] || 3
+end
+
+future.each do |f|
+  if f =~ /store\/([\w-]+)\//
+    dir_name = $1
+    intent_file = "#{store_root}/store/#{dir_name}/#{dir_name}.md"
+    next unless File.exist?(intent_file)
+
+    content = File.read(intent_file)
+    if content =~ /^created:\s*['"]?(\d{4}-\d{2}-\d{2})/
+      age = (Date.today - Date.parse($1)).to_i
+      if age >= stale_days
+        name = f[/\[([^\]]+)\]/, 1] || "unknown"
+        stale << { name: name, age: age, entry: f }
+      end
+    end
+  end
+end
+
+# --- Detect current project ---
+
+current_project = nil
+if mode == "global"
+  projects_path = "#{store_root}/projects.yml"
+  if File.exist?(projects_path)
+    projects = YAML.safe_load(File.read(projects_path)) rescue {}
+    cwd = Dir.pwd
+    (projects["projects"] || {}).each do |slug, info|
+      project_path = File.expand_path(info["path"])
+      if cwd.start_with?(project_path)
+        current_project = { "slug" => slug, "parent" => info["parent"], "path" => project_path }
+        break
+      end
+    end
+  end
+end
+
+# --- Build context ---
+
+parts = []
+parts << "PLASTIC CONTINUE — The user wants to resume work.\n"
+
+if mode == "global" && current_project
+  parts << "Project: #{current_project["slug"]} (#{current_project["path"]})\n"
+  parts << "Governing intent: #{current_project["parent"]}\n" if current_project["parent"]
+end
+
+if active.any?
+  parts << "## Active Intents (work on these first)\n"
+  active.each { |a| parts << a }
+  parts << ""
+else
+  parts << "## No Active Intents\n"
+end
+
+if future.any?
+  parts << "## Future Intents (offer as next work)\n"
+  future.each { |f| parts << f }
+  parts << ""
+end
+
+if stale.any?
+  parts << "## Stale Future Intents\n"
+  parts << "These future intents have not been actioned. Ask the user what to do with each:\n"
+  stale.each do |s|
+    parts << "- #{s[:name]} (#{s[:age]} days old) — options: activate, abandon, or defer to agent (implement / research / ideate)"
+  end
+  parts << ""
+end
+
+parts << "Follow the plastic:continuing skill workflow.\n"
+parts << "1. If active intents exist: read their state and resume\n"
+parts << "2. If no active intents: present future intents as options\n"
+parts << "3. If stale intents exist: surface them and ask user to decide"
+
+payload = {
+  "hookSpecificOutput" => {
+    "hookEventName" => "UserPromptSubmit",
+    "additionalContext" => parts.join("\n")
+  }
+}
+puts JSON.generate(payload)

package/scripts/hook-future-intent-check

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# Usage: hook-future-intent-check <store_root> <message>
+# Outputs hook JSON when the user's message matches future intent keywords.
+# Exits silently if no matches.
+
+require "json"
+require "yaml"
+
+store_root, message = ARGV
+exit 0 unless store_root && message
+
+index_path = "#{store_root}/INDEX.md"
+exit 0 unless File.exist?(index_path)
+
+# --- Find future intent dirs ---
+
+lines = File.readlines(index_path)
+future_dirs = []
+section = nil
+
+lines.each do |line|
+  section = :future if line.start_with?("## Future")
+  section = nil if line.start_with?("## ") && !line.start_with?("## Future")
+  next unless section == :future && line.strip.start_with?("- [")
+
+  if line =~ /store\/([\w-]+)\//
+    future_dirs << $1
+  end
+end
+
+exit 0 if future_dirs.empty?
+
+# --- Match keywords against message ---
+
+matches = []
+message_words = message.split(/\W+/).reject { |w| w.length < 4 }
+
+future_dirs.each do |dir|
+  intent_path = "#{store_root}/store/#{dir}/#{dir}.md"
+  next unless File.exist?(intent_path)
+
+  content = File.read(intent_path)
+
+  tags = []
+  if content =~ /^tags:\s*\[([^\]]+)\]/
+    tags = $1.split(",").map(&:strip).map(&:downcase)
+  end
+
+  intent_name = ""
+  if content =~ /^intent:\s*["']?(.+?)["']?\s*$/
+    intent_name = $1.downcase
+  end
+
+  intent_id = ""
+  if content =~ /^id:\s*["']?([a-z0-9]+)["']?\s*$/
+    intent_id = $1
+  end
+
+  keywords = tags + intent_name.split(/\W+/).reject { |w| w.length < 4 }
+  keywords = keywords.map(&:downcase).uniq
+
+  matched_keywords = keywords.select { |kw| message.include?(kw) }
+  name_matches = message_words.select { |w| intent_name.include?(w) }
+  matched_keywords = (matched_keywords + name_matches).uniq
+
+  if matched_keywords.length >= 1
+    index_line = lines.find { |l| l.include?(dir) }&.strip || "#{intent_id} — #{intent_name}"
+    matches << { "index_line" => index_line, "keywords" => matched_keywords }
+  end
+end
+
+exit 0 if matches.empty?
+
+# --- Build context ---
+
+parts = []
+parts << "PLASTIC — Future intents related to this message:\n"
+matches.each do |m|
+  parts << "#{m["index_line"]} (matched: #{m["keywords"].join(", ")})"
+end
+parts << "\nConsider asking the user if they want to activate any of these, or note the connection."
+
+payload = {
+  "hookSpecificOutput" => {
+    "hookEventName" => "UserPromptSubmit",
+    "additionalContext" => parts.join("\n")
+  }
+}
+puts JSON.generate(payload)