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

package/agents/plastic-brainstorming.md

@@ -0,0 +1,35 @@
+---
+name: plastic-brainstorming
+description: |
+  Use this agent for the Why-stage exploration of an active intent in auto mode:
+  it enriches context and records decisions before a spec is written. Examples:
+  <example>Context: An intent has a What but a thin Why.
+  user: "Explore the requirements for the active intent"
+  assistant: "I'll use the brainstorming agent to enrich Context and record Decisions"
+  <commentary>Why-stage exploration runs before the spec-specialist.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
+
+## Your Responsibilities
+
+1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code
+2. **Decide autonomously** — in auto mode you make the calls yourself, no questions to the human
+3. **Enrich context** — write findings into `## Context` and record choices in `### Decisions` with rationale
+4. **Hand off** — leave the Why stage ready for the spec-specialist to consolidate into a spec
+
+## How You Work
+
+1. Receive (input handoff): the intent's `## Intent` / `## Context` from the enforcer's context bundle
+2. Read the intent file, its `## Links`, and related code or docs
+3. Research with the adaptive budget the enforcer set (simple 2-3, medium 5-8, complex 10-15 steps)
+4. Produce (output handoff): an enriched `## Context` plus `### Decisions` with rationale
+5. Log autonomous calls in `## Insights` with the `(autonomous)` marker, then report for gating
+
+## Constraints
+
+- You are dispatched by the plastic-enforcer and your deliverable is gated before How begins
+- You only write intent-store files (the intent's `## Context`, `### Decisions`, `## Insights`)
+- You never write `spec.md`, `plan.md`, or project code; those belong to later stages
+- You explore and decide without asking the human (auto mode); record every decision

package/agents/plastic-enforcer.md

@@ -0,0 +1,36 @@
+---
+name: plastic-enforcer
+description: |
+  Use this agent as the auto-mode orchestrator: it spins up the team, sequences the
+  specialists, owns every gate, and runs the final review. Examples:
+  <example>Context: User triggers auto on an active intent.
+  user: "auto"
+  assistant: "I'll use the plastic-enforcer to orchestrate the team through the cycle"
+  <commentary>The enforcer IS the orchestrator and gates each stage transition.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole What->Why->How->Exec cycle. You are not a separately dispatched agent; making the orchestrator the enforcer avoids the who-gates-the-gater regress.
+
+## Your Responsibilities
+
+1. **Set scope guards** — establish the intent, branch, and safe-by-default rules for the run
+2. **Arm and verify the gate** — arm the lifecycle gate and confirm it is live before any code edit
+3. **Sequence the team** — dispatch ONE specialist per stage (brainstorming, spec-specialist, planner, executor) with a constructed context bundle
+4. **Gate each handoff** — check each stage deliverable against its exit criteria before handing to the next stage
+5. **Run the final review** — at the final gate, dispatch an INDEPENDENT reviewer subagent (not a sixth standing role)
+
+## How You Work
+
+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`
+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

package/agents/plastic-executor.md

@@ -0,0 +1,35 @@
+---
+name: plastic-executor
+description: |
+  Use this agent for the Exec stage in auto mode: it implements the actions, checks
+  off the checklist, and drives the test suite green. Examples:
+  <example>Context: plan.md and checklist.md exist for the active intent.
+  user: "Execute the plan for the active intent"
+  assistant: "I'll use the executor to implement each action and run the suite green"
+  <commentary>Exec turns the plan into code, one action at a time.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
+
+## Your Responsibilities
+
+1. **Implement the actions** — make the code changes for each action in order
+2. **Track progress** — check off `checklist.md` items as they complete
+3. **Record insights** — append observations to `## Insights` with the `(autonomous)` marker
+4. **Prove it green** — run the full test suite and reach zero failures before reporting done
+
+## How You Work
+
+1. Receive (input handoff): `plan.md`, `checklist.md`, and `actions/` from the planner
+2. Work one action at a time, preferring safe, non-destructive routes
+3. Edit project code (the gate is open now that plan and checklist exist)
+4. Run the full suite, iterate to zero failures and zero errors
+5. Produce (output handoff): the code changes, a checked-off `checklist.md`, and `## Insights`
+
+## Constraints
+
+- You are dispatched by the plastic-enforcer and your work is gated at the final review
+- Safe-by-default: rename instead of drop, additive migrations, backups before destructive steps
+- One action at a time; do not batch unrelated changes into one step
+- Do not claim done until the full suite is green; show the final summary

package/agents/plastic-planner.md

@@ -0,0 +1,35 @@
+---
+name: plastic-planner
+description: |
+  Use this agent for the How stage in auto mode: it turns a spec.md into a plan,
+  self-contained action files, and a checklist. Examples:
+  <example>Context: spec.md exists and the intent is ready to plan.
+  user: "Plan the work for the active intent"
+  assistant: "I'll use the planner to write plan.md, actions/, and checklist.md"
+  <commentary>The plan and checklist unlock the code gate for Exec.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
+
+## Your Responsibilities
+
+1. **Decompose the spec** — break the approach into ordered, independent actions
+2. **Write the plan** — produce `plan.md` with numbered tasks and verification
+3. **Write self-contained actions** — one `actions/ACTION_N.md` per task, each runnable on its own
+4. **Write the checklist** — `checklist.md` as the execution registry covering every action
+
+## How You Work
+
+1. Receive (input handoff): `spec.md` from the spec-specialist
+2. Read `spec.md` and the plan/checklist templates; match their FORM
+3. Write `plan.md`, the `actions/` directory, and `checklist.md` into the intent directory
+4. Produce (output handoff): `plan.md` plus `actions/` plus `checklist.md`
+5. Report for gating; the enforcer verifies plan and checklist exist before Exec is allowed
+
+## Constraints
+
+- You are dispatched by the plastic-enforcer and your deliverable is gated before Exec begins
+- You write only intent-store files (`plan.md`, `actions/`, `checklist.md`); no project code
+- The code gate stays closed until `plan.md` and `checklist.md` exist, so produce both
+- Keep each action self-contained so the executor can run them one at a time

package/agents/plastic-spec-specialist.md

@@ -0,0 +1,35 @@
+---
+name: plastic-spec-specialist
+description: |
+  Use this agent at the Why-to-How boundary in auto mode: it consolidates an
+  enriched Why into a spec.md from the spec template. Examples:
+  <example>Context: Why exploration is complete and decisions are recorded.
+  user: "Write the spec for the active intent"
+  assistant: "I'll use the spec-specialist to produce spec.md from the template"
+  <commentary>The spec is the deliverable that gates the move into How.</commentary></example>
+model: inherit
+---
+
+You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
+
+## Your Responsibilities
+
+1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec
+2. **Follow the template** — produce `spec.md` with Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria
+3. **Make it the contract** — the spec is what the planner and executor build against
+4. **Hand off** — leave a complete `spec.md` ready for the planner
+
+## How You Work
+
+1. Receive (input handoff): the enriched `## Context` plus `### Decisions` from the brainstorming stage
+2. Read the spec template (`templates/spec.md`) and match its FORM exactly
+3. Write `spec.md` into the intent directory, resolving the decisions into a coherent approach
+4. Produce (output handoff): a complete `spec.md`
+5. Report for gating; the enforcer checks the spec against its exit criteria before How begins
+
+## Constraints
+
+- You are dispatched by the plastic-enforcer and your deliverable is gated before How begins
+- You write `spec.md` only; you do not write `plan.md`, `actions/`, or project code
+- You write only intent-store files, never project code
+- You do not re-open exploration; if decisions are missing, flag the gap rather than inventing scope

package/package.json

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

package/scripts/doctor.rb

@@ -549,6 +549,9 @@ class Doctor
     # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
     checks << flat_skills_check(agent_dir, "--claude")
 
+    # agents_exist — auto-mode role files (plastic-*.md) synced into <dir>/agents
+    checks << flat_agents_check(agent_dir, "--claude")
+
     checks
   end
 
@@ -572,12 +575,33 @@ class Doctor
     end
   end
 
+  # Auto-mode role agents install as <dir>/agents/plastic-*.md. Pass if at least
+  # one such role file is present (the installer syncs agents/ on every install).
+  def flat_agents_check(agent_dir, installer_flag)
+    agents_root = File.join(agent_dir, "agents")
+    found = Dir.glob(File.join(agents_root, "plastic-*.md"))
+
+    if !found.empty?
+      check(
+        category: "agent_registration", name: "agents_exist", status: "pass",
+        message: "#{found.size} plastic-* agent(s) installed in #{tilde(agents_root)}"
+      )
+    else
+      check(
+        category: "agent_registration", name: "agents_exist", status: "fail",
+        message: "No plastic-* agents found in #{tilde(agents_root)}",
+        fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest #{installer_flag}"
+      )
+    end
+  end
+
   def check_generic_agent_registration(agent_key, agent_dir)
     checks = []
     config = agents[agent_key]
 
     # For codex/hermes: just check skills exist (no settings.json hooks)
     checks << flat_skills_check(agent_dir, "--#{agent_key}")
+    checks << flat_agents_check(agent_dir, "--#{agent_key}")
 
     checks
   end

package/scripts/lib/installer_core.rb

@@ -355,6 +355,9 @@ class InstallerCore
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, skills_root) if File.directory?(skills_source)
 
+    # Copy agent role files into <dir>/agents (manifest-tracked, pruned on update)
+    installed += install_agents(File.join(config[:dir], "agents"))
+
     # Write VERSION
     version_file = File.join(plastic_dir, "VERSION")
     File.write(version_file, "#{version}\n")
@@ -378,6 +381,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
+    installed += install_agents(File.join(config[:dir], "agents"))
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -387,6 +391,7 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     installed += install_skills_flat(skills_source, File.join(config[:dir], "skills")) if File.directory?(skills_source)
+    installed += install_agents(File.join(config[:dir], "agents"))
 
     write_manifest(installed, File.join(config[:dir], "plastic-manifest.json"))
     { agent: config[:name], success: true, files: installed.size }
@@ -414,6 +419,23 @@ class InstallerCore
     installed
   end
 
+  # Copy every repo agents/*.md into <agents_root> (flat, basename preserved), so
+  # the role files install as ~/.claude/agents/<name>.md (and the codex/hermes
+  # equivalents). Returns the installed destination paths so callers can append
+  # them to `installed` before write_manifest (manifest + prune are then automatic).
+  # No-op safe: returns [] when the package has no agents dir or it is empty.
+  def install_agents(agents_root)
+    sources = Dir.glob(File.join(package_root, "agents", "*.md"))
+    return [] if sources.empty?
+
+    FileUtils.mkdir_p(agents_root)
+    sources.map do |src|
+      dest = File.join(agents_root, File.basename(src))
+      FileUtils.cp(src, dest)
+      dest
+    end
+  end
+
   # --- Legacy plugin migration ---
 
   # Earlier versions registered Plastic as a local marketplace plugin

package/skills/auto/SKILL.md

@@ -52,6 +52,26 @@ Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.
 
 - `--skip-permissions` — bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
 
+## Team Spin-Up
+
+Auto mode spins up exactly ONE enforcer-led team per intent. The plastic-enforcer IS this orchestrator (you), not a separately dispatched agent, which avoids the who-gates-the-gater regress.
+
+Roster (one role per cycle stage):
+
+- **plastic-brainstorming** (Why exploration): enriches `## Context` + `### Decisions`
+- **plastic-spec-specialist** (`spec.md`)
+- **plastic-planner** (`plan.md` + `actions/` + `checklist.md`)
+- **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.
+
+Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
+
+Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).
+
+Solo fallback: if the harness has no subagent dispatch, fall back to a single agent walking the full What, Why, How, Exec cycle yourself. This preserves current behavior.
+
 ## Stage-Aware Entry
 
 Read the active intent's directory. Determine current lifecycle stage from filesystem state:
@@ -184,4 +204,4 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 
 ## 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
+- Read `references/agent-architecture.md` for the full team model (the 5-role enforcer-led team, per-stage handoffs, gate ownership, headless note, solo fallback) and the orchestrator hierarchy (Main Orchestrator, Project Orchestrators, coordination loop) when spinning up the team or understanding autonomous delivery scope

package/skills/auto/evals/evals.json

@@ -1,91 +1,206 @@
 {
   "skill_name": "plastic-auto",
-  "notes": "Intent 27. Scopes: description triggering (1-8) and behavior/output quality (9). Assertions written after observing Step-3 runs (one clean subagent router per case).",
+  "notes": "Intent 27. Scopes: description triggering (1-8) and behavior/output quality (9). Assertions written after observing Step-3 runs (one clean subagent router per case). Intent 63 added cases 10-11 (auto-mode enforcer-led team spin-up and solo fallback).",
   "results": {
-    "triggering": { "cases": 8, "passed": 8, "pass_at_1": 1.0, "run": "2026-06-10, one subagent per case" },
-    "behavior": { "cases": 1, "passed": 1, "evidence": "dogfood: intent 27 itself delivered via auto produced spec->plan->checklist before any code edit; code-gate unit test proves pre-How project-code edits are blocked" }
+    "triggering": {
+      "cases": 8,
+      "passed": 8,
+      "pass_at_1": 1.0,
+      "run": "2026-06-10, one subagent per case"
+    },
+    "behavior": {
+      "cases": 1,
+      "passed": 1,
+      "evidence": "dogfood: intent 27 itself delivered via auto produced spec->plan->checklist before any code edit; code-gate unit test proves pre-How project-code edits are blocked"
+    }
   },
   "evals": [
     {
-      "id": 1, "scope": "triggering", "set": "train",
+      "id": 1,
+      "scope": "triggering",
+      "set": "train",
       "prompt": "auto",
       "expected_output": "Activates plastic-auto (the bare 'auto' keyword is the documented trigger).",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE == plastic-auto", "observed": "plastic-auto", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-auto",
+          "observed": "plastic-auto",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 2, "scope": "triggering", "set": "train",
+      "id": 2,
+      "scope": "triggering",
+      "set": "train",
       "prompt": "take it from here and deliver intent 27 end to end",
       "expected_output": "Activates plastic-auto (autonomous delivery of an active intent).",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE == plastic-auto", "observed": "plastic-auto", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-auto",
+          "observed": "plastic-auto",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 3, "scope": "triggering", "set": "validation",
+      "id": 3,
+      "scope": "triggering",
+      "set": "validation",
       "prompt": "go fully autonomous on the active intent, don't ask me questions",
       "expected_output": "Activates plastic-auto.",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE == plastic-auto", "observed": "plastic-auto", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-auto",
+          "observed": "plastic-auto",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 4, "scope": "triggering", "set": "train",
+      "id": 4,
+      "scope": "triggering",
+      "set": "train",
       "prompt": "deliver this intent for me",
       "expected_output": "Activates plastic-auto.",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE == plastic-auto", "observed": "plastic-auto", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE == plastic-auto",
+          "observed": "plastic-auto",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 5, "scope": "triggering", "set": "train",
+      "id": 5,
+      "scope": "triggering",
+      "set": "train",
       "prompt": "set up a hook to automatically format the file on every save",
       "expected_output": "Does NOT activate plastic-auto. Near-miss: shares 'auto*' but is a settings/hooks task (update-config).",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE != plastic-auto", "observed": "update-config", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-auto",
+          "observed": "update-config",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 6, "scope": "triggering", "set": "validation",
+      "id": 6,
+      "scope": "triggering",
+      "set": "validation",
       "prompt": "deliver the built package to the dist directory",
       "expected_output": "Does NOT activate plastic-auto. Near-miss: shares 'deliver' but is a build/file task.",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE != plastic-auto", "observed": "none", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-auto",
+          "observed": "none",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 7, "scope": "triggering", "set": "train",
+      "id": 7,
+      "scope": "triggering",
+      "set": "train",
       "prompt": "create a new intent for the dashboard idea",
       "expected_output": "Does NOT activate plastic-auto; activates plastic-creating-intent.",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE != plastic-auto", "observed": "plastic-creating-intent", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-auto",
+          "observed": "plastic-creating-intent",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 8, "scope": "triggering", "set": "validation",
+      "id": 8,
+      "scope": "triggering",
+      "set": "validation",
       "prompt": "what's the status of my active intents?",
       "expected_output": "Does NOT activate plastic-auto; this is a read/continuing/managing-index query.",
       "files": [],
       "assertions": [
-        { "type": "code", "check": "router CHOICE != plastic-auto", "observed": "plastic-managing-index", "result": "pass" }
+        {
+          "type": "code",
+          "check": "router CHOICE != plastic-auto",
+          "observed": "plastic-managing-index",
+          "result": "pass"
+        }
       ]
     },
     {
-      "id": 9, "scope": "behavior", "set": "train",
+      "id": 9,
+      "scope": "behavior",
+      "set": "train",
       "prompt": "Active intent X exists with only a '## Intent' section. Deliver it in auto mode.",
       "expected_output": "Arms the lifecycle gate first, then produces spec.md (Why), then plan.md + actions/ + checklist.md (How), and edits NO project code before plan.md + checklist.md exist. Disarms on completion.",
       "files": [],
       "assertions": [
-        { "type": "human", "check": "spec.md written before plan.md before any project-code edit", "observed": "dogfood run of intent 27 followed this order", "result": "pass" },
-        { "type": "code", "check": "code-gate blocks project-code Edit/Write while pre-How (test/code_gate_test.rb)", "observed": "test green", "result": "pass" }
+        {
+          "type": "human",
+          "check": "spec.md written before plan.md before any project-code edit",
+          "observed": "dogfood run of intent 27 followed this order",
+          "result": "pass"
+        },
+        {
+          "type": "code",
+          "check": "code-gate blocks project-code Edit/Write while pre-How (test/code_gate_test.rb)",
+          "observed": "test green",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 10,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Active intent X exists. Deliver it in auto mode on a harness that supports subagents.",
+      "expected_output": "Spins up one enforcer-led team per intent (brainstorming, spec-specialist, planner, executor, plastic-enforcer). The enforcer IS the orchestrator. Dispatches one specialist per stage sequentially on one branch, gating each deliverable (Context+Decisions, then spec.md, then plan.md+actions+checklist, then code) against the stage exit criteria before handoff, and dispatches an independent reviewer subagent at the final gate only.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "five-role roster spun up; specialists dispatched stage-sequentially with per-stage gating; independent reviewer only at final gate",
+          "observed": "dogfood: intents 60-62 delivered by exactly this enforcer-led team on a shared branch",
+          "result": "pass"
+        },
+        {
+          "type": "code",
+          "check": "agents/plastic-*.md role files ship and install into the harness agent dir, manifest-tracked (test/install_packaging_test.rb)",
+          "observed": "test green",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 11,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Active intent X exists. Deliver it in auto mode on a harness with no subagent dispatch.",
+      "expected_output": "Falls back to a single agent walking the full What, Why, How, Exec cycle itself, preserving current behavior. The enforcer gate discipline still applies (arm the gate first, no project-code edits before plan.md + checklist.md exist).",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "solo agent walks the full cycle when subagent dispatch is unavailable; gate discipline preserved",
+          "observed": "SKILL.md Team Spin-Up documents the solo fallback explicitly",
+          "result": "pass"
+        }
       ]
     }
   ]

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

@@ -6,55 +6,112 @@ 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)
+- 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
+- Spin up an enforcer-led team to deliver an intent
 - 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)
+## The Auto-Mode Team
+
+Auto mode spins up exactly ONE enforcer-led team per intent. The plastic-enforcer
+IS the auto orchestrator itself, not a separately dispatched agent. Making the
+orchestrator the enforcer avoids the who-gates-the-gater regress (the gate-keeper
+can never be ungated).
+
+The team has five roles, one per place in the What, Why, How, Exec cycle:
+
+- **plastic-brainstorming** (Why exploration): enriches `## Context` and records
+  `### Decisions` with rationale.
+- **plastic-spec-specialist** (Why-to-How boundary): consolidates the Why into
+  `spec.md` (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria).
+- **plastic-planner** (How): produces `plan.md`, `actions/ACTION_N.md`, and
+  `checklist.md`.
+- **plastic-executor** (Exec): writes the code, checks off `checklist.md`, appends
+  `## Insights`, and drives the suite green.
+- **plastic-enforcer** (spans the whole cycle): orchestrates and gates.
+
+### Handoff Contracts
+
+Each specialist receives the prior stage's deliverable and produces the next stage's
+input. The enforcer dispatches one specialist per stage with a constructed context
+bundle, gates that deliverable against the stage's exit criteria, and only then hands
+off to the next stage. Dispatch is sequential on a single branch, because the stage
+deliverables share files (a parked spec, plan, and checklist all live in the same
+intent directory).
+
+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`.
+
+### Gate Ownership
+
+The enforcer arms and verifies the lifecycle gate, then gates every stage transition.
+It never delegates gate ownership. At the final gate only, it dispatches an
+INDEPENDENT reviewer subagent to review the delivered work. That reviewer is not a
+permanent sixth role, it exists only for the final review.
+
+### Headless Manual Gate
+
+When running headless or in the background, the enforcer enforces gates manually and
+does not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in those runs (the
+gate-check and savepoint hooks no-op without it). The enforcer arms via the bridge's
+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.
+
+### Dogfood Proof
+
+Intents 60, 61, and 62 were delivered by exactly this enforcer-led team on a shared
+branch, which is the dogfooded proof that the model works end to end.
 
 ## 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.
+- **Human-driven:** Human chats with the Main Orchestrator, creates intents,
+  brainstorms, then the Main Orchestrator dispatches Project Orchestrators and teams
+  for execution.
+- **Autonomous:** Human gives the Main Orchestrator a starting intent with defined
+  outcomes. The enforcer-led team runs the full cycle (the specialists do the
+  lifecycle, the enforcer reviews Insights and gates), then the orchestrator spawns
+  next intents and 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.
+Human owns What and Why for human-initiated intents. The team assists (research,
+exploration) but the human drives until handoff. When Why is complete, or the human
+triggers `plastic-auto`, the enforcer-led team takes over How and Exec autonomously.
 
-- **Safe-by-default:** Agent always prefers non-destructive routes (rename vs
+- **Safe-by-default:** the executor 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.
+  unresolvable error). No progress reports, `## Insights` tracks everything.
+- **Greenfield autonomy:** during initial project creation, all decisions are
+  non-destructive (nothing to destroy), so the team has full autonomy for greenfield
+  choices.
+- **Autonomous decisions** are logged in `## Insights` with the `(autonomous)` marker.
 
 ## Coordinator Loop
 
 When "work on Project X":
-1. Read `projects.yml` → find project path
+1. Read `projects.yml`, find the 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
+4. Load global INDEX.md, find hub intents tagged `project-<name>`
+5. Load project INDEX.md, find tactical intents
+6. The coordinator has the full picture, spins up an enforcer-led team per intent

package/skills/releasing/SKILL.md

@@ -6,7 +6,7 @@ description: Use when merging a feature branch to main and tagging a release, bu
 # Releasing
 
 Merge, bump, tag, push. Annotated tags with changelogs. Semantic versioning.
-Project configuration drives the workflow — no hardcoded assumptions.
+Project configuration drives the workflow - no hardcoded assumptions.
 
 ## Checklist
 
@@ -18,6 +18,7 @@ Project configuration drives the workflow — no hardcoded assumptions.
 - [ ] Create annotated tag
 - [ ] Push to remote with tags
 - [ ] Run post-push actions (GitHub release, npm publish, etc.)
+- [ ] Verify release sync (npm dist-tag, GitHub "Latest", git tag all show the new version)
 - [ ] Complete active intent
 
 ## Workflow
@@ -26,9 +27,9 @@ Project configuration drives the workflow — no hardcoded assumptions.
 
 Before anything else, determine which project we are releasing and load its config.
 
-1. Read `~/.plastic/projects.yml` — find the project whose `path` matches the current working directory.
+1. Read `~/.plastic/projects.yml` - find the project whose `path` matches the current working directory.
 2. Extract the project slug (the key under `projects:`).
-3. Read `~/.plastic/projects/{slug}/project.yml` — this contains the `release:` section.
+3. Read `~/.plastic/projects/{slug}/project.yml` - this contains the `release:` section.
 
 Expected `release:` keys in project.yml:
 
@@ -37,8 +38,9 @@ release:
   verify: "bin/rails test"              # command to run before release
   version_file: package.json            # single file containing the version
   version_files:                        # multiple files (overrides version_file)
-    - package.json
-    - .claude-plugin/plugin.json
+    - package.json                      # list EVERY file carrying the version;
+    - .claude-plugin/plugin.json        # they must all be bumped together or they drift
+    - .claude-plugin/marketplace.json
   tag_format: "v{{version}}"            # tag naming pattern ({{version}} is replaced)
   on_green:                             # actions to run after push succeeds
     - github_release
@@ -47,7 +49,7 @@ release:
   on_red: stop                          # what to do if verification fails
 ```
 
-**Fallback:** If no project.yml exists or it has no `release:` section, fall back to asking the user for each step — verify command, version files, tag format, and post-push actions.
+**Fallback:** If no project.yml exists or it has no `release:` section, fall back to asking the user for each step - verify command, version files, tag format, and post-push actions.
 
 ### 1. Verify Tests Pass
 
@@ -77,7 +79,7 @@ Pre-1.0: minor bumps for features, patch for fixes. No major until stable.
 
 ```bash
 git checkout main
-git merge <branch-name> --no-ff -m "feat: merge intent [ID] — [description]"
+git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 ```
 
 Always `--no-ff` to preserve branch history in the merge commit.
@@ -94,7 +96,7 @@ Update the version string in each file, then commit:
 
 ```bash
 git add <version-files>
-git commit -m "chore: bump version to X.Y.Z — [one-line summary]"
+git commit -m "chore: bump version to X.Y.Z - [one-line summary]"
 ```
 
 ### 5. Create Annotated Tag
@@ -113,7 +115,7 @@ git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges | grep -E
 Create the tag with a multi-line message:
 
 ```bash
-git tag -a <tag-name> -m "<tag-name> — [release name]
+git tag -a <tag-name> -m "<tag-name> - [release name]
 
 - [changelog bullet points from feat/fix/refactor commits]"
 ```
@@ -133,9 +135,15 @@ Read `release.on_green` from project.yml. This is a list of actions to run after
 Create a GitHub release from the tag:
 
 ```bash
-gh release create <tag-name> --title "<tag-name> — [release name]" --generate-notes --notes-start-tag <previous-tag>
+gh release create <tag-name> --title "<tag-name> - [release name]" --latest --generate-notes --notes-start-tag <previous-tag>
 ```
 
+`--latest` is REQUIRED. Pre-release (alpha/beta) tags are NOT auto-promoted to the "Latest"
+badge by GitHub, so without it the Releases page keeps showing an older version as Latest while
+the newest tag sits below it (a real sync drift we hit on the alpha line). Pass `--latest` on
+every release so the newest one always carries the badge. Do NOT pass `--prerelease` unless you
+specifically want the release hidden from Latest.
+
 For the first release (no previous tag), write notes manually with `--notes "..."` instead.
 
 #### `npm_publish`
@@ -168,6 +176,22 @@ If `on_green` contains an action not listed above, log it:
 
 If `on_green` is empty or absent: skip post-push actions entirely.
 
+#### Verify sync (always, after the post-push actions)
+
+A release is not done until all three surfaces show the SAME newest version. Confirm:
+
+```bash
+npm view <package> dist-tags                      # channel tag (alpha/beta/latest) -> new version
+gh release list --limit 1                         # newest release is the new tag AND marked "Latest"
+git ls-remote --tags origin | grep <tag-name>     # the tag reached the remote
+```
+
+If the GitHub "Latest" badge is on an older tag (the common drift), fix it without re-releasing:
+
+```bash
+gh release edit <tag-name> --latest
+```
+
 ### 8. Complete Active Intent
 
 A release IS a delivery. The active intent that drove this work must be completed as part of the release process. This is NOT optional.
@@ -179,18 +203,21 @@ A release IS a delivery. The active intent that drove this work must be complete
    c. Update `## Insights` with final observations
    d. Move from `## Active` to `## Completed` in INDEX.md (with today's date)
    e. Update clusters to show `_(completed)_`
-3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> — delivered in <tag-name>"`
+3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> - delivered in <tag-name>"`
 
-**If no active intent exists for this release**, that itself is a problem — work happened outside the intent system. Log it and move on, but flag it.
+**If no active intent exists for this release**, that itself is a problem - work happened outside the intent system. Log it and move on, but flag it.
 
 ## Conventions
 
-- **Annotated tags only** — `git tag -a`, never lightweight tags
-- **Tag format** — driven by `release.tag_format` in project.yml (default: `vX.Y.Z`)
-- **Tag message** — first line: `<tag> — [short name]`, then blank line, then bullet changelog
-- **Commit prefixes** — `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
-- **Version files** — driven by project.yml; all listed files must always match
-- **Branch cleanup** — delete merged feature branches: `git branch -d <branch>`
+- **Annotated tags only** - `git tag -a`, never lightweight tags
+- **Tag format** - driven by `release.tag_format` in project.yml (default: `vX.Y.Z`)
+- **Tag message** - first line: `<tag> - [short name]`, then blank line, then bullet changelog
+- **Commit prefixes** - `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
+- **Hyphens, never em-dashes** - in tag names, release titles, and commit messages, use a hyphen (`-`). Never an em-dash.
+- **Latest badge** - always `gh release create --latest`; the newest release must carry GitHub's "Latest" badge.
+- **Version files** - driven by project.yml; list and bump EVERY file carrying the version (they drift otherwise)
+- **Verify sync** - after pushing, confirm npm dist-tag, GitHub "Latest", and the git tag all show the new version
+- **Branch cleanup** - delete merged feature branches: `git branch -d <branch>`
 
 ## Promotion
 
@@ -215,7 +242,7 @@ plastic-releasing --promote stable  # promotes current beta → stable
 For repos without prior tags, tag historical releases:
 
 ```bash
-git tag -a v0.1.0 <commit-sha> -m "v0.1.0 — [description]"
+git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
 ```
 
 Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).