@zalom/plastic 1.0.0-alpha.1

package/scripts/read-config

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+# Usage: read-config <key> [--default VALUE] [--project PATH]
+# Resolves a config value: project -> global -> built-in defaults.
+# Nested keys use dot notation: agent.type, architect.style
+# Returns scalar values as strings, hash/array values as JSON.
+#
+# Environment:
+#   PLASTIC_GLOBAL_ROOT -- override ~/.plastic (for testing)
+
+require "yaml"
+require "json"
+
+DEFAULTS = {
+  "version" => 3,
+  "stale_threshold_days" => 3,
+  "execution_mode" => "subagent-driven",
+  "hash_length" => 6,
+  "hash_algorithm" => "sha256-base36",
+  "max_slug_words" => 5,
+  "project_roots" => ["~/.plastic/projects"],
+  "deprecations_dismissed" => [],
+  "agent" => {
+    "type" => "claude-code",
+    "parallel_mode" => "linear"
+  },
+  "architect" => {
+    "style" => nil
+  }
+}.freeze
+
+def parse_args(argv)
+  key = nil
+  default_val = nil
+  project_dir = nil
+
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--default"
+      abort "Error: --default requires a value" unless argv[i + 1]
+      default_val = argv[i + 1]
+      i += 2
+    when "--project"
+      abort "Error: --project requires a value" unless argv[i + 1]
+      project_dir = argv[i + 1]
+      i += 2
+    else
+      key = argv[i]
+      i += 1
+    end
+  end
+
+  [key, default_val, project_dir]
+end
+
+def load_yaml(path)
+  return {} unless File.exist?(path)
+  YAML.safe_load(File.read(path)) || {}
+rescue => e
+  $stderr.puts "Warning: failed to parse #{path}: #{e.message}"
+  {}
+end
+
+def dig_key(hash, dotted_key)
+  keys = dotted_key.split(".")
+  value = hash
+  keys.each do |k|
+    return nil unless value.is_a?(Hash) && value.key?(k)
+    value = value[k]
+  end
+  value
+end
+
+def format_value(value)
+  case value
+  when Hash, Array
+    JSON.generate(value)
+  when nil
+    ""
+  else
+    value.to_s
+  end
+end
+
+# Handle --migrate mode
+if ARGV.include?("--migrate")
+  global_root = ENV.fetch("PLASTIC_GLOBAL_ROOT", File.expand_path("~/.plastic"))
+  config_path = File.join(global_root, "config.yml")
+  config = load_yaml(config_path)
+
+  if config["version"].to_i >= 3
+    puts "Config already at version #{config["version"]}."
+    exit 0
+  end
+
+  config["version"] = 3
+  config["agent"] ||= {}
+  config["agent"]["type"] ||= "claude-code"
+  config["agent"]["parallel_mode"] ||= "linear"
+  config["architect"] ||= {}
+  config["architect"]["style"] ||= nil
+
+  File.write(config_path, YAML.dump(config))
+  puts "Migrated config.yml to version 3."
+  exit 0
+end
+
+key, explicit_default, project_dir = parse_args(ARGV)
+
+if key.nil? || key.empty?
+  $stderr.puts "Usage: read-config <key> [--default VALUE] [--project PATH]"
+  exit 1
+end
+
+global_root = ENV.fetch("PLASTIC_GLOBAL_ROOT", File.expand_path("~/.plastic"))
+global_config = load_yaml(File.join(global_root, "config.yml"))
+
+project_config = {}
+if project_dir
+  project_config_path = File.join(project_dir, ".plastic_store", "config.yml")
+  project_config = load_yaml(project_config_path)
+end
+
+value = dig_key(project_config, key)
+value = dig_key(global_config, key) if value.nil?
+value = explicit_default if value.nil? && explicit_default
+value = dig_key(DEFAULTS, key) if value.nil?
+
+puts format_value(value)

package/skills/auto/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: plastic:auto
+description: >-
+  Autonomous intent delivery — agent takes over How and Exec. Use when user says
+  "auto", "take it from here", "deliver this", or when brainstorming-grill-me concludes
+  and user confirms autonomous execution. Requires an active intent in INDEX.md.
+---
+
+# Auto — Autonomous Intent Delivery
+
+Announce: "Taking over intent [ID] — [name] for autonomous delivery."
+
+## Precondition
+
+An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found. Create one first with /plastic:creating-intent."
+
+If multiple active intents exist, ask the user which one to deliver (this is the only question auto asks).
+
+## Flags
+
+- `--skip-permissions` — bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
+
+## Stage-Aware Entry
+
+Read the active intent's directory. Determine current lifecycle stage from filesystem state:
+
+| Check (in order) | Stage |
+|---|---|
+| `checklist.md` exists with some items checked | Resume Exec from last unchecked item |
+| `plan.md` + `checklist.md` exist (no items checked) | Enter Exec |
+| `spec.md` exists, no `plan.md` | Enter How |
+| `## Context` has content in intent file, no `spec.md` | Complete Why (fill gaps, write spec.md) |
+| Only `## Intent` exists | Start Why from scratch |
+
+Announce which stage you're entering and why.
+
+## Why Completion (Autonomous)
+
+When entering at Why stage:
+
+1. Read existing `## Context` and `### Decisions` from the intent file
+2. Assess gaps — what decisions are missing? What context is incomplete?
+3. Self-directed research — read code, search docs, explore related intents (via wikilinks in `## Links`), web search if needed. NO questions to human.
+4. Adaptive budget — assess complexity and set your own research budget:
+   - Simple (config change, small feature): 2-3 research steps
+   - Medium (new feature, integration): 5-8 research steps
+   - Complex (new project, architecture): 10-15 research steps
+5. Make decisions — pick best option, document in `## Context > ### Decisions` with rationale
+6. Log all autonomous decisions in `## Insights` with `(autonomous)` marker: "Decision: chose X because Y (autonomous)"
+7. Write `spec.md` — consolidated specification
+
+Then proceed to How.
+
+## How Phase
+
+1. If `superpowers:writing-plans` is available as a skill, delegate plan creation to it. Tell it the plan saves to the active intent's directory (not `docs/superpowers/plans/`).
+2. Otherwise, write `plan.md` directly — implementation plan with numbered tasks
+3. Create `actions/` directory with `ACTION_N.md` files (one per task, self-contained)
+4. Write `checklist.md` — execution registry with checkboxes covering all actions
+
+Then proceed to Exec.
+
+## Project Creation Gate
+
+If the plan calls for creating a new project (the intent is an implementation intent that needs a new codebase):
+
+1. Determine project path from `~/.plastic/config.yml` `project_roots` or from intent context
+2. **Confirm path with user** — this is the ONE human interaction during auto delivery:
+   > "Creating project `<slug>` at `<path>`. Confirm path, or provide alternative."
+3. Invoke `plastic:creating-project` skill
+4. The global intent is now Completed (creating-project handles this)
+5. The tactical mirror in the project store becomes the active intent
+6. Continue execution from the project directory using the tactical intent
+
+## Exec Phase
+
+1. If `superpowers:subagent-driven-development` or `superpowers:executing-plans` is available, delegate execution to it
+2. Otherwise invoke `plastic:executing-plan`
+3. Execute actions from checklist sequentially
+4. Check off items in `checklist.md` as completed
+5. Append observations to `## Insights` with `(autonomous)` marker
+6. Sub-agents can be spawned for parallel actions (one agent per action)
+
+## Permission Model — Safe-by-Default
+
+The agent MUST prefer non-destructive routes:
+
+| Instead of... | Do this... |
+|---|---|
+| Drop table | Rename to `_deprecated_<table>`, flag for cleanup |
+| Delete files | Move to `.archive/` or backup branch |
+| Alter column | Additive migration — new column + backfill |
+| Remove feature | Feature flag off, code stays until human confirms |
+| Database migration | Backup before migration, keep rollback path |
+
+### Hard Stop (without `--skip-permissions`)
+
+When a genuinely destructive action on an existing project has NO safe alternative:
+1. Log the proposed action in `## Insights`
+2. Notify user: "Blocked on destructive action: [description]. Approve to continue, or provide alternative direction."
+3. **STOP and wait for human response.** Do not proceed.
+
+With `--skip-permissions`, the agent logs the action in Insights but proceeds without stopping.
+
+### Greenfield Exception
+
+During initial project creation, all decisions are non-destructive by definition (there's nothing to destroy). The agent has full autonomy for greenfield choices — DB engine, framework, gems, architecture.
+
+## Completion
+
+1. Verify all checklist items are checked
+2. Write `outcome.md` with detailed results
+3. Write `## Outcome` summary in the intent file (1-2 sentences)
+4. Review `## Insights` for observations that should spawn future intents. If any:
+   - Create them (using `plastic:creating-intent` conventions)
+   - Update `chain` in the current intent's frontmatter
+5. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+6. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
+7. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+
+## Error Handling
+
+If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail persistently):
+1. Log the blocker in `## Insights`
+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.

package/skills/brainstorming-grill-me/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: plastic:brainstorming-grill-me
+description: >-
+  Deep brainstorming that interviews the user relentlessly about a plan or design until reaching shared understanding.
+  Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+  Complements superpowers:brainstorming — use brainstorming for quick ideation, grill-me for thorough interrogation.
+---
+
+# Grill Me — Deep Brainstorming
+
+You are about to interview the user relentlessly. This is NOT a quick brainstorm — it is a thorough interrogation of every assumption, dependency, and design decision until you reach shared understanding.
+
+## Detect Mode
+
+**Coding mode** — the user is designing something that involves code (feature, architecture, refactor, system design):
+- You CAN and SHOULD explore the codebase to answer your own questions
+- Before asking "how does X work?", check if you can find out yourself
+- Ground your questions in what actually exists, not what you imagine
+
+**Non-coding mode** — the user is designing something conceptual (process, workflow, strategy, product):
+- No codebase to explore
+- Focus purely on the design tree
+
+## Workflow
+
+### 1. Identify the Root
+
+Ask: "What are we designing?" Get the one-sentence version. Restate it back to confirm.
+
+### 2. Walk the Decision Tree
+
+For each branch of the design:
+
+1. **State the branch** — "Let's talk about [aspect]."
+2. **Ask your question** — Be specific. "How will X handle Y when Z happens?"
+3. **Provide your recommended answer** — Always lead with what YOU think the answer should be, based on what you know. Let the user confirm, correct, or redirect.
+4. **Resolve before moving on** — Do not leave ambiguity. If the user says "I'm not sure", help them decide. Push.
+5. **Track dependencies** — If decision A affects decision B, say so. Resolve A first.
+
+### 3. Be Relentless
+
+- Do NOT accept vague answers. "It depends" requires "on what?"
+- Do NOT skip edge cases. "What happens when the list is empty?"
+- Do NOT assume. If you think you know, verify.
+- Do NOT be polite at the expense of thoroughness. Friendly but unrelenting.
+- DO challenge the user's assumptions. "Why not [alternative]?"
+- DO synthesize as you go. After every 3-4 questions, summarize what's been decided.
+
+### 4. Time Awareness
+
+This process is thorough. It typically takes 20-45 minutes for a complex design. At natural checkpoints (~every 10 questions), offer:
+
+> "We've covered [areas]. Still to explore: [areas]. Continue, or pause and capture what we have?"
+
+If the user wants to pause, capture all decisions made so far into the active intent's spec.md.
+
+### 5. Close Out
+
+When all branches are resolved:
+
+1. Write the complete spec to the active intent directory (`spec.md`)
+2. List all decisions made
+3. List any deferred items (things the user explicitly chose to decide later)
+4. Proceed to Autonomous Handoff Offer (step 6)
+
+### 6. Autonomous Handoff Offer
+
+After closing out (spec written, decisions listed), assess whether the agent has enough context to deliver the intent autonomously.
+
+**Self-assessment checklist:**
+- All key decisions resolved (no open "it depends" or "TBD")
+- Scope is clear and bounded
+- Dependencies are identified
+- Success criteria are defined
+
+If ALL items pass, offer autonomous delivery:
+
+> "I have enough context to take this from here. Here's my understanding:
+>
+> **Decisions:** [list key decisions]
+> **Scope:** [one-line scope summary]
+> **Approach:** [high-level approach]
+>
+> Want to grill more, or should I go autonomous?"
+
+- If human says go → invoke `plastic:auto`
+- If human says grill more → continue grilling (reset to step 2)
+- If human says neither (wants to drive manually) → proceed as before (offer planning)
+
+This offer replaces the final question in Close Out ("Ready to plan implementation, or do you want another pass?"). The new options are:
+1. Go autonomous (`plastic:auto`)
+2. Grill more (continue interrogation)
+3. Plan manually (invoke `superpowers:writing-plans` or proceed with human-driven planning)
+
+## Relationship to superpowers:brainstorming
+
+| | superpowers:brainstorming | plastic:brainstorming-grill-me |
+|---|---|---|
+| Speed | Quick (5-10 min) | Thorough (20-45 min) |
+| Depth | Surface-level exploration | Exhaustive decision tree |
+| When | Starting ideation, exploring options | Stress-testing a design, resolving ambiguity |
+| Output | Initial spec | Battle-tested spec with all branches resolved |
+| Style | Collaborative, exploratory | Interrogative, relentless |
+
+Use `superpowers:brainstorming` to generate ideas. Use `plastic:brainstorming-grill-me` to pressure-test them.

package/skills/continuing/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: plastic:continuing
+description: Use when the user says "continue" after a /clear, or when resuming work in a new session. Reads intent state from global store (~/.plastic/) or local store, offers active intents first, then future intents, and surfaces stale intents for triage.
+---
+
+# Continuing
+
+## When to Use
+- UserPromptSubmit hook detects "continue" (automatic)
+- User says "continue", "resume", or "pick up where we left off"
+- Starting a new session with existing active intents
+
+## Determine Store
+
+1. Check `~/.plastic/INDEX.md` → global mode
+2. 
+3. If neither exists → announce "No Plastic store found. Run /plastic:install."
+
+## Workflow
+
+### 1. Read INDEX.md
+Read the INDEX.md from the active store. Extract intents under `## Active` and `## Future`.
+
+### 2. Detect Current Project (global mode only)
+Read `~/.plastic/projects.yml`, match CWD against registered project paths. If in a project:
+- Load the governing intent (from `parent` in projects.yml)
+- Load tactical intents from `~/.plastic/projects/{slug}/store/`
+
+### 3. If Active Intents Exist → Resume
+
+For each active intent in the store:
+
+**a. Read `{ID}--{slug}.md`:**
+- What we're doing (`## Intent`)
+- Why (`## Context`)
+- What insights have emerged (`## Insights`)
+
+**b. Read savepoint.md** (if exists):
+- What was in progress, what's next, blockers
+
+**c. Read checklist.md** (if exists):
+- What's completed, what's next
+
+**d. Announce:**
+```
+Resuming intent [ID] — [name]
+Store: [global | project:<slug> | local]
+Status: active
+Last session: [date from savepoint]
+In progress: [from savepoint]
+Next step: [from checklist or savepoint]
+Blockers: [from savepoint, or "none"]
+```
+
+**e. Resume** — proceed with the next step.
+
+### 3b. Detect Autonomous Resume
+
+When resuming an active intent, check `## Insights` for entries containing `(autonomous)`.
+
+If found — this intent was being delivered autonomously:
+
+**Announce:**
+```
+Resuming autonomous delivery of intent [ID] — [name]
+Store: [global | project:<slug> | local]
+Last autonomous action: [last (autonomous) insight entry]
+Next step: [from checklist or savepoint]
+```
+
+**Then:** Continue autonomous execution by invoking `plastic:auto`. The auto skill will pick up from the current lifecycle stage (it reads filesystem state to determine where to resume).
+
+If NOT found — resume normally as described in step 3.
+
+### 4. If No Active Intents → Offer Future Intents
+
+Present future intents as options. When user picks one, move to Active in INDEX.md. Auto-commit.
+
+### 5. Surface Stale Future Intents
+
+If any future intent has `created` date older than the configured `stale_threshold_days` (default 3):
+
+```
+Stale future intents (no action taken):
+
+- [ID — name] (X days old)
+  Options:
+  a) Activate — start working on it now
+  b) Abandon — mark as abandoned
+  c) Defer to agent:
+     - implement: agent builds it
+     - research: agent investigates feasibility
+     - ideate: agent explores the problem space
+  d) Auto — go fully autonomous (invokes plastic:auto — agent delivers the intent end-to-end)
+```
+
+Auto-commit all triage changes.
+
+### 6. Priority Order
+
+1. **Active intents first** — resume work in progress
+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

package/skills/creating-intent/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: plastic:creating-intent
+description: Use when new work begins, the user expresses a new goal, says "new intent", or no active intent exists for the current task. Creates intents in the global store (~/.plastic/store/) or in a project's store (~/.plastic/projects/{slug}/store/) depending on context.
+---
+
+# Creating an Intent
+
+## When to Use
+- User starts new work ("build X", "fix Y", "research Z")
+- No active intent matches the current task
+- User explicitly says "new intent" or "create intent"
+- An agent discovers work needed during implementation
+
+## Determine Tier
+
+**Global intent** (strategic): created when working outside a registered project, or when the user expresses a high-level goal. Stored in `~/.plastic/store/`.
+
+**Project intent** (tactical): created when working inside a registered project directory. Stored in `~/.plastic/projects/{slug}/store/`. Automatically linked to the project's governing intent.
+
+### Detection logic:
+1. Read `~/.plastic/projects.yml`
+2. **CWD match:** Match CWD against registered project paths
+   - If CWD is inside a registered project → **project intent (tactical)**
+3. **Explicit mention:** User mentions an existing project by name ("add this to reddit-kb", "new intent for plastic")
+   - Look up project in `projects.yml` by slug
+   - If found → **project intent (tactical)** in that project's store at `~/.plastic/projects/{slug}/store/`
+   - Agent changes working directory to the project path for execution
+4. **No match:** CWD is not in a project AND no project mentioned
+   - → **global intent (strategic)** in `~/.plastic/store/`
+
+When creating a tactical intent in a project store:
+- Read the project's `AGENTS.md` for project context and decisions
+- Link back to the project's governing intent (from `projects.yml` `parent` field) via `sources`
+- Add `[[global:<parent_ID>]]` backlink in `## Links`
+- The intent's Folgezettel ID is scoped to the project store (run `folgezettel-id` against the project's store at `~/.plastic/projects/{slug}/store/`)
+
+## Workflow
+
+### 1. Determine Store Location
+
+- **Global:** `~/.plastic/store/`
+- **Project:** `~/.plastic/projects/{slug}/store/`
+
+### 2. Determine Folgezettel ID
+
+IDs are scoped to the store they live in. Use the correct store path:
+
+**Global store:**
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "~/.plastic/store"
+```
+
+**Project store:**
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "~/.plastic/projects/{slug}/store"
+```
+
+**Branch intent (has parent, either store):**
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "<STORE>" "<parent_id>"
+```
+
+### 3. Determine Intent Properties
+
+Ask or infer from context:
+- **intent**: one-line description
+- **author**: `human` | `claude-code` | other agent name
+- **sources**: array of Folgezettel IDs that influenced this intent (e.g., `["4a1"]`)
+- **chain**: starts empty `[]`, populated when this intent spawns others
+- **tags**: freeform list (use `project-<name>` for project membership)
+
+Place in `## Active` or `## Future` in INDEX.md (status is convention-derived, not a frontmatter field).
+
+### 4. Create Directory and Files
+
+```bash
+mkdir -p <STORE>/ID--slug
+```
+
+Write `{ID}--{slug}.md` using the intent template. For project intents, add the governing intent's ID to `sources` and add `[[global:ID]]` backlink in `## Links`.
+
+### 5. If Implementation Intent Spawns a Project
+
+When the user says "start building" or the plan calls for a new project:
+
+1. Determine project slug from intent name
+2. Create project directory in first `project_roots` path (from `~/.plastic/config.yml`):
+   ```bash
+   mkdir -p <project_root>/<slug>
+   cd <project_root>/<slug>
+   git init
+   mkdir -p ~/.plastic/projects/{slug}/store
+   touch ~/.plastic/projects/{slug}/store/.gitkeep
+   ```
+3. Copy `AGENTS.md` template from `${CLAUDE_PLUGIN_ROOT}/templates/agents.md`
+4. Register in `~/.plastic/projects.yml`:
+   ```yaml
+   <slug>:
+     path: <full-path>
+     parent: "ID"
+     registered: <today>
+     status: active
+   ```
+5. Add `project-<slug>` to the intent's `tags` array
+6. Auto-commit in both `~/.plastic/` and the new project
+
+### 6. Update INDEX.md
+
+- **Global intents:** update `~/.plastic/INDEX.md`
+- **Project intents:** no global INDEX.md change (tactical intents are project-scoped)
+
+Add to `## Active` (or `## Future`) and appropriate cluster.
+
+### 7. Auto-commit
+
+```bash
+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]."