@zalom/plastic 1.0.0-alpha.33 → 1.0.0-alpha.35

package/PLASTIC.md

@@ -97,6 +97,26 @@ succession at a glance (last line = where we are).
   brainstorming, writing-plans, etc., Plastic's directory rules override
   their default output paths.
 
+## Defaults-First
+
+Plastic stands on its own. Skills and agents use Plastic's own defaults; an
+external skill (for example `superpowers:*`) is opt-in, never load-bearing.
+
+- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
+  the default. Delegate to an external skill only when (a) it is available in the
+  harness, or (b) the user explicitly asks for it. A user without that plugin must
+  still get the core behavior.
+- **Phrase external skills as enhancements.** Write "use Plastic's native X by
+  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
+  to it" never "delegate to `superpowers:<skill>`" as the only path.
+- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
+  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
+  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
+  the same detect-then-skip pattern, so a missing tool never crashes a session.
+- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
+  the cost of running Plastic, not silent coupling. The principle targets accidental
+  dependence on external skills doing work Plastic should do itself.
+
 ## State System
 
 ```

package/agents/plastic-brainstorming.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code

package/agents/plastic-enforcer.md

@@ -25,12 +25,12 @@ You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole
 1. Arm the gate, then dispatch the brainstorming specialist; gate its `## Context` + `### Decisions`
 2. Dispatch the spec-specialist; gate `spec.md`. Then the planner; gate `plan.md` + `checklist.md`
 3. Dispatch the executor; require a green suite. Sequential, one team per intent, on one branch when files are shared
-4. Delegate real parallelism and dispatch to `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents`
+4. Dispatch and review by default through Plastic's native engine, `plastic-executing-plan` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
 5. At the final gate, dispatch an independent reviewer subagent, then complete the intent
 
 ## Constraints
 
 - Enforce gates manually; do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in headless or background runs
 - You never delegate gate ownership; the orchestrator is always the gate-keeper
-- Roles are thin handoff contracts, not an execution engine; delegate dispatch to the superpowers skills
-- If the harness has no subagent dispatch, fall back to a single agent walking the full cycle
+- Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
+- Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle

package/agents/plastic-executor.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Implement the actions** — make the code changes for each action in order

package/agents/plastic-planner.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Decompose the spec** — break the approach into ordered, independent actions

package/agents/plastic-spec-specialist.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec

package/package.json

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

package/scripts/hook-gate-check

@@ -8,6 +8,7 @@
 
 require "json"
 require_relative "lib/bridge"
+require_relative "lib/intent_validator"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
@@ -28,6 +29,24 @@ if intent_dir_abs
   end
 end
 
+# --- Artifact-validity backstop (intent 4a1c1) ---
+# When the written file IS the intent file itself (the `<id>--<slug>.md` directly
+# inside `store/<id>--<slug>/`), run IntentValidator on it. This is headless-safe:
+# it depends only on the file path and disk, never on a bridge or session. In the
+# PostToolUse model the write has already happened, so we cannot prevent it; the
+# loud non-zero exit + stderr is the rejection signal. NOT for spec.md/plan.md/
+# checklist.md/outcome.md/savepoint.md — those are validated by the stage gates.
+if intent_dir_abs && File.basename(file_path_abs) == File.basename(Bridge.intent_file(intent_dir_abs))
+  result = IntentValidator.validate(intent_dir_abs)
+  unless result[:ok]
+    warn "PLASTIC ARTIFACT INVALID — #{File.basename(file_path_abs)} is not born complete:"
+    result[:missing].each { |field| warn "  missing required field: #{field}" }
+    result[:errors].each { |error| warn "  #{error}" }
+    warn "Fix the frontmatter; the intent is not valid until every required field is present and sources/chain are well-formed."
+    exit 1
+  end
+end
+
 # --- Find bridge file ---
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 

package/scripts/lib/installer_core.rb

@@ -208,6 +208,7 @@ class InstallerCore
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/validate-intent" => "scripts/validate-intent",
+      "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",

package/scripts/spawn-preamble

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# spawn-preamble — deterministic live-state injection for spawned agents
+# (intent 4a1c1, agent harness foundation).
+#
+# Emits a preamble block built ONLY from filesystem state for a single intent
+# directory. It is a PURE function of the intent dir: no network, no randomness,
+# no wall-clock reads. Two runs over the same on-disk state produce byte-identical
+# output. This is the authoritative L2 (live-state) mechanism for harnesses whose
+# spawned sub-agents do not inherit a top-level session event (see
+# docs/reference/harness-adapters.md).
+#
+# Usage:
+#   spawn-preamble <intent_dir> [--role ROLE] [--step STEP]
+#
+# The preamble reports the active intent (id + intent line from frontmatter), the
+# current lifecycle stage (last savepoint line if present, else derived from which
+# lifecycle files exist), the cycle role/step (from --role/--step, else the
+# derived stage), and an imperative honoring instruction.
+#
+# Exit codes: 0 (preamble emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+# Verbatim honoring instruction. Kept as one constant so the contract doc and the
+# test assert against the exact same string.
+HONOR_INSTRUCTION =
+  "You are operating inside Plastic. Use it as your operating scaffold. " \
+  "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
+  "Your output is a deliverable, not a message."
+
+def parse_args(argv)
+  role = nil
+  step = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    when "--step"
+      step = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role, step]
+end
+
+# Read the intent file frontmatter via the same parser the validator uses, so the
+# id/intent we report match what the rest of Plastic sees. Returns a Hash (possibly
+# empty) — never raises.
+def frontmatter_for(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return {} unless File.exist?(ifile)
+
+  content = File.read(ifile)
+  return {} unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return {} if parts.length < 3
+
+  require "yaml"
+  require "date"
+  require "time"
+  YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+rescue StandardError
+  {}
+end
+
+# Current stage label. Prefer the last non-empty line of savepoint.md (the ledger
+# already encodes the furthest-reached milestone). Fall back to the file-derived
+# stage when there is no ledger.
+STAGE_LABELS = {
+  "what" => "What", "why" => "Why", "how" => "How",
+  "exec" => "Exec", "done" => "Done"
+}.freeze
+
+def current_stage(intent_dir)
+  ledger = File.join(intent_dir, Bridge::SAVEPOINT_FILE)
+  if File.exist?(ledger)
+    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
+    return last if last
+  end
+  STAGE_LABELS.fetch(Bridge.derive_stage(intent_dir), Bridge.derive_stage(intent_dir))
+end
+
+intent_dir_arg, role, step = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: spawn-preamble <intent_dir> [--role ROLE] [--step STEP]"
+  exit 2
+end
+
+intent_dir = File.expand_path(intent_dir_arg)
+
+fm = frontmatter_for(intent_dir)
+id = fm["id"].to_s.strip
+intent_name = fm["intent"].to_s.strip
+id = "(unknown)" if id.empty?
+intent_name = "(unknown)" if intent_name.empty?
+
+stage = current_stage(intent_dir)
+cycle = role || step || stage
+
+lines = []
+lines << "=== Plastic spawn preamble ==="
+lines << "Store: #{intent_dir}"
+lines << "Active intent: #{id} - #{intent_name}"
+lines << "Current stage: #{stage}"
+lines << "Cycle step / role: #{cycle}"
+lines << ""
+lines << HONOR_INSTRUCTION
+lines << "=== end preamble ==="
+
+puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -64,7 +64,9 @@ Roster (one role per cycle stage):
 - **plastic-executor** (code + checklist + `## Insights`)
 - **plastic-enforcer** (orchestrates + gates; that is YOU)
 
-Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. Delegate the actual How and Exec dispatch to `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` (see the How and Exec phases below); do not restate them.
+Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
+
+Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
 
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 

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

@@ -48,6 +48,19 @@ The chain: intent `## Intent` / `## Context`, then enriched `## Context` plus
 `### Decisions`, then `spec.md`, then `plan.md` plus `actions/` plus `checklist.md`,
 then the code changes plus a checked-off checklist plus `## Insights`.
 
+### Spawn Preamble (L2 live-state injection)
+
+Every dispatched specialist is booted with a spawn preamble: the enforcer runs
+`scripts/spawn-preamble <intent_dir> --role <role>` and prepends its output to the
+specialist's prompt. The preamble is a pure function of the intent directory on disk
+(no network, no clock, no randomness), so it is deterministic and rebuildable. It
+carries the active intent id and intent line, the current lifecycle stage (the last
+savepoint line, else stage derived from which lifecycle files exist), the cycle
+role, and the honoring instruction that the agent must emit valid lifecycle artifacts
+and not hallucinate intents or stages. This is the standard L2 live-state mechanism
+for harnesses whose spawned sub-agents do not inherit the top-level session event. See
+`docs/reference/harness-adapters.md` for how it slots into the per-harness contract.
+
 ### Gate Ownership
 
 The enforcer arms and verifies the lifecycle gate, then gates every stage transition.
@@ -64,16 +77,21 @@ derived-key fallback and verifies state itself.
 
 ### Delegation
 
-The roles are thin handoff contracts, not a spawning engine. Real parallelism and
-dispatch are delegated to `superpowers:subagent-driven-development` and
-`superpowers:dispatching-parallel-agents`. The team model defines who hands what to
-whom and where the gates sit, the superpowers skills do the actual dispatching.
-
-### Solo Fallback
-
-If the harness has no subagent dispatch, auto mode falls back to a single agent
-walking the full What, Why, How, Exec cycle itself. This preserves the original
-behavior on harnesses without teams. The enforcer's gate discipline still applies.
+The roles are thin handoff contracts, not a spawning engine. Dispatch and review run
+by default through Plastic's own engine, `plastic-executing-plan` (implementer plus
+two-stage review, no external plugin). When `superpowers:subagent-driven-development`
+and `superpowers:dispatching-parallel-agents` are available, or the user asks for them,
+they delegate to those as an enhancement. The team model defines who hands what to whom
+and where the gates sit; the dispatch engine, native or superpowers, does the actual
+spawning.
+
+### Fallback by Case
+
+The default is always Plastic's native engine, so a user without superpowers still gets
+the full behavior. If the harness supports subagents but superpowers is absent, auto
+mode dispatches through `plastic-executing-plan`. If the harness has no subagent dispatch
+at all, auto mode falls back to a single agent walking the full What, Why, How, Exec
+cycle itself. The enforcer's gate discipline still applies in every case.
 
 ### Dogfood Proof
 

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

@@ -3,7 +3,7 @@ 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.
+  Pair with plastic-brainstorming for quick ideation and use grill-me for thorough interrogation. If superpowers:brainstorming is installed it complements this skill, but it is not required.
 ---
 
 # Grill Me — Deep Brainstorming