@zalom/plastic 1.0.0-beta.35 → 1.0.0-beta.36

package/scripts/lib/bridge.rb

@@ -921,6 +921,49 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Solo-mode detection (intent 128) ---------------------------------------
+  #
+  # Positive-only confirmation that exactly one session is delivering, from the
+  # durable delivery.lock files (never the /tmp bridge cache, D2). Used to relax
+  # the two ARBITRATION gates (lock_gate_decision, worktree_gate_decision) from
+  # a hard deny to an advisory allow when there is nothing to arbitrate.
+  #
+  # SOLO iff exactly ONE fresh delivery.lock exists across scan_roots, that
+  # lock's owner_session equals the resolved session, and its delegates array
+  # is empty. Any ambiguity (more than one fresh lock, including several under
+  # the SAME owner_session, which reads as parallel-in-play), a foreign owner,
+  # a non-empty delegates array, a blank/unresolvable session, or any error
+  # during the scan all return false (fail-closed direction preserved).
+  def self.solo_delivery?(scan_roots:, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    return false if blank?(session)
+
+    lock_dirs = Array(scan_roots).compact.flat_map { |root|
+      Dir.glob(File.join(File.expand_path(root), "*", "delivery.lock"))
+    }.uniq.map { |lock_file| File.dirname(lock_file) }
+
+    fresh_dirs = lock_dirs.select { |dir| Lock.fresh?(dir, ttl: ttl, now: now) }
+    fresh_locks = fresh_dirs.map { |dir| Lock.read(dir) }
+
+    # A fresh-but-unreadable (corrupt) lock is real ambiguity, not an absence:
+    # dropping it via filter_map could leave exactly one READABLE lock and
+    # misconfirm solo while a second, unreadable-but-live lock is in play.
+    # Any unreadable fresh lock keeps this fail-closed (review finding 2).
+    return false if fresh_locks.any?(&:nil?)
+    return false unless fresh_locks.length == 1
+
+    lock = fresh_locks.first
+    lock["owner_session"].to_s == session.to_s && Array(lock["delegates"]).empty?
+  rescue StandardError
+    false
+  end
+
+  # One terse advisory line (no em-dashes), then ALLOW (nil). Shared by both
+  # arbitration gates so a relaxed deny always logs the same shape.
+  def self.solo_allow(id, reason)
+    $stderr.puts "plastic: solo delivery confirmed for intent #{id} (#{reason}); allowing"
+    nil
+  end
+
   # --- Fail-closed lock gate (intent 96) -------------------------------------
 
   # Returns a reason String to BLOCK, or nil to ALLOW. Decides from the
@@ -931,7 +974,7 @@ module Bridge
   # target's lock names as owner or delegate (even when stale: a stale lock is
   # still its owner's until an explicit takeover).
   def self.lock_gate_decision(bridge_data, file_path, session: nil,
-                              ttl: Lock::TTL_SECONDS, now: Time.now)
+                              ttl: Lock::TTL_SECONDS, now: Time.now, home: Dir.home)
     return nil if blank?(file_path)
 
     target_dir = intent_dir_for(file_path)
@@ -943,23 +986,34 @@ module Bridge
     sess = session
     sess = bridge_data["session"] if blank?(sess) && bridge_data.is_a?(Hash)
 
+    # Solo-mode detection (intent 128): scan this intent's store plus the
+    # global store under `home` for fresh delivery locks. Computed once; used
+    # at every arbitration deny below to relax a hard deny to an advisory
+    # allow when solo delivery is positively confirmed.
+    scan_roots = [store, File.join(File.expand_path(home), ".plastic", "store")]
+    solo = solo_delivery?(scan_roots: scan_roots, session: sess, ttl: ttl, now: now)
+
     lock = Lock.read(target_dir)
     if lock
       return nil if Lock.authorized?(lock, sess)
       if Lock.fresh?(target_dir, ttl: ttl, now: now)
+        return solo_allow(id, "fresh delivery lock") if solo
         return "intent #{id} delivery lock is held by session " \
                "#{lock['owner_session']}. Back off; if you are the owner's " \
                "subagent, the owner must run: plastic-lock delegate " \
                "--intent-dir #{target_dir} --session <your-session-id>. " \
                "Inspect with /plastic-lock status"
       end
+      return solo_allow(id, "stale delivery lock") if solo
       return "intent #{id} has a stale delivery lock (owner " \
              "#{lock['owner_session']}); run /plastic-lock reclaim to take " \
              "it over, or /plastic-lock fix"
     end
     if Lock.corrupt?(target_dir)
+      return solo_allow(id, "unreadable delivery.lock") if solo
       return "delivery.lock for intent #{id} is unreadable; run /plastic-lock fix"
     end
+    return solo_allow(id, "no delivery lock") if solo
     "no delivery lock held for intent #{id}; run /plastic-intent-starting " \
       "to lock and begin"
   end
@@ -1012,6 +1066,19 @@ module Bridge
     under_own_intent = intent_dir_abs &&
                        (file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/"))
 
+    # Solo-mode detection (intent 128): current session first, else the
+    # bridge's own session; scan roots are this intent's store, the global
+    # store under `home`, AND the EDIT TARGET's own store (when the target
+    # lives inside a store dir), so a live foreign lock on the intent being
+    # edited is never invisible to the scan just because it belongs to a
+    # different project than the acting bridge's own store (review finding 1;
+    # duplicate roots are harmless, solo_delivery? dedupes). Computed once;
+    # used by both rules below.
+    sess = blank?(current_session) ? bridge_data["session"] : current_session
+    target_store = parse_store_target(file_abs, plastic_home)&.fetch(:store, nil)
+    scan_roots = [store, File.join(plastic_home, "store"), target_store]
+    solo = solo_delivery?(scan_roots: scan_roots, session: sess)
+
     # Rule 1 (fixed in intent 108, D7): confinement applies ONLY to paths
     # inside the project repo. The repo root is derived from the provisioned
     # code worktree path, which is <repo>/.claude/worktrees/{id}--{slug} by
@@ -1029,6 +1096,7 @@ module Bridge
         inside_code = file_abs == code_abs || file_abs.start_with?("#{code_abs}/")
         if inside_repo && !inside_code
           id = intent_info["id"]
+          return solo_allow(id, "worktree confinement") if solo
           return "intent #{id} is isolated to its worktree - edit project code " \
                  "inside #{code_abs}, not the shared checkout. (blocked edit: #{file_abs})"
         end
@@ -1040,7 +1108,10 @@ module Bridge
       reason = non_owner_store_edit_reason(file_abs, plastic_home, intent_dir_abs,
                                            home: home, current_session: current_session,
                                            own_session: bridge_data["session"])
-      return reason if reason
+      if reason
+        return solo_allow(intent_info["id"], "non-owner store edit") if solo
+        return reason
+      end
     end
 
     nil

package/scripts/lib/installer_core.rb

@@ -228,6 +228,7 @@ class InstallerCore
   def core_files
     {
       "PLASTIC.md" => "PLASTIC.md",
+      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
       "scripts/read-config" => "scripts/read-config",

package/scripts/lib/power_tools.rb

@@ -52,24 +52,26 @@ module PowerTools
     false
   end
 
-  # Recommendation text for whichever tools are present, joined by newlines, or
-  # nil when none are. One recommendation line per present tool.
-  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
-    lines = []
-
-    if qmd?(detector: qmd_detector)
-      lines << "QMD is available: prefer `qmd search` / `qmd query` over the " \
-               "`plastic-*` collections to check for existing or related intents " \
-               "before treating work as new."
-    end
+  QMD_OBLIGATION = "prefer `qmd search` / `qmd query` over the `plastic-*` " \
+                   "collections to check for existing or related intents before " \
+                   "treating work as new"
+  SERENA_OBLIGATION = "prefer its symbolic tools (find_symbol / get_symbols_overview / " \
+                       "find_referencing_symbols) for code navigation"
 
+  # Recommendation text for whichever tools are present, or nil when none are.
+  # Both present collapse to ONE combined line naming both obligations (no
+  # embedded newline); one present returns that tool's own line; neither
+  # returns nil.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    qmd_present = qmd?(detector: qmd_detector)
     serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
-    if serena_present
-      lines << "Serena is available: prefer its symbolic tools (find_symbol / " \
-               "get_symbols_overview / find_referencing_symbols) for code navigation."
-    end
 
-    return nil if lines.empty?
-    lines.join("\n")
+    if qmd_present && serena_present
+      "QMD and Serena are available: #{QMD_OBLIGATION}, and #{SERENA_OBLIGATION}."
+    elsif qmd_present
+      "QMD is available: #{QMD_OBLIGATION}."
+    elsif serena_present
+      "Serena is available: #{SERENA_OBLIGATION}."
+    end
   end
 end

package/skills/auto/SKILL.md

@@ -76,17 +76,10 @@ ruby -r ~/.plastic/scripts/lib/bridge -e \
 Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
 `<dir>` (the `ID--slug` directory), and `<name>`. The first argument is the session id you
 want the bridge keyed by: pass the hook stdin `session_id` when you have it, otherwise
-`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. `arm_auto` calls `resolve_session`, which
-picks the first non-empty of: the explicit id you pass -> `CLAUDE_CODE_SESSION_ID` -> a
-deterministic derived key (a hash of the store and intent id).
-It never returns nil, so the gate engages even when every session env var is empty; the call
-never needs a non-empty session env var to function. Arming prints a one-line notice to
-stderr when it falls through to the derived key.
-
-Arming acquires the durable `delivery.lock` in the intent dir, keyed by that resolved
-session. Ownership is session-keyed, not process-keyed, so the arm one-liner exiting
-immediately is fine by construction: the lock stays yours for every later tool call in this
-session. A failed arm raises with a message naming the resolving `plastic-lock` verb.
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. Arming always succeeds and acquires the
+durable `delivery.lock` in the intent dir. For the `resolve_session` fallback chain
+(why arming never needs a non-empty session env var, and what the lock ownership model
+implies for later tool calls) read `references/end-tail.md`.
 
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
@@ -165,6 +158,10 @@ Filesystem fallback (ledger missing only):
 
 Announce which stage you're entering and why.
 
+Notify user (What briefing): brief per `references/human-report-contract.md`
+(State: the work picked up and why it matters now; Risk: scope uncertainty; Call: confirm
+this is worth doing, or proceed).
+
 ## Why Completion (Autonomous)
 
 When entering at Why stage:
@@ -179,6 +176,9 @@ When entering at Why stage:
 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
+8. Notify user (Why briefing): brief per `references/human-report-contract.md`
+   (State: the approach chosen, one line; Risk: the main trade-off; Call: the one decision
+   needed, approve or pick an option).
 
 Then proceed to How.
 
@@ -193,6 +193,9 @@ only (S/M leave the directory empty).
 2. Otherwise, write `plan.md` directly — implementation plan with numbered tasks
 3. Write `ACTION_N.md` files into the existing `actions/` directory (one per task, self-contained) — L only
 4. Write `checklist.md` — execution registry with checkboxes covering all actions
+5. Notify user (How briefing): brief per `references/human-report-contract.md`
+   (State: the plan shape, task count and what it builds; Risk: the riskiest task or
+   dependency; Call: approve the plan to build).
 
 Then proceed to Exec.
 
@@ -216,6 +219,9 @@ If the plan calls for creating a new project (the intent is an implementation in
 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)
+7. Notify user (Exec briefing): brief per `references/human-report-contract.md`
+   (State: what got built and the test result; Risk: residual failures or deviations;
+   Call: go to review, or done).
 
 ## Permission Model — Safe-by-Default
 
@@ -281,36 +287,27 @@ During initial project creation, all decisions are non-destructive by definition
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>")'
    ```
-   Disarm runs the ordered End tail: it releases the worktrees first, then clears the
-   intent's `delivery.lock` (and the bridge's lock cache), and only then is the bridge
-   purge-eligible. Disarming also purges stale bridge files from the temp directory
-   automatically (it keeps the current bridge, any live run, and any bridge whose intent
-   still holds a delivery lock), so no manual `/tmp` cleanup is needed.
-
-   **Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
-   `disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
-   worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
-   `<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
-   from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
-   only when no release merges the branch (the branch survives and can be reclaimed).
-
-   When the work is being shipped through a release, do NOT rely on this plain remove. The
-   release path (step 4 above, via `plastic-releasing`) is responsible for merging the intent's
-   code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the worktree is
-   removed, so the integrated work is not lost. It does this with `Worktree.finish(bridge_data,
-   merge: true)` (merge-then-remove). Never leave an orphaned worktree, and run `git worktree
-   prune` if you hit a stale reference.
-9. QMD reindex LAST (canonical End tail). AFTER disarm has released the worktrees, cleared the
-   `delivery.lock`, and purged the bridge, refresh the QMD search index for this store (no-op when
-   QMD is absent). It runs in the background so it never blocks the turn:
+   Disarm runs the ordered End tail (release worktrees, then clear the `delivery.lock`,
+   then the bridge becomes purge-eligible) and performs the mandatory worktree cleanup
+   (intent 73c3): both per-intent worktrees are removed and both repos pruned. This is
+   the plain remove path (no merge); when the work ships through a release, the release
+   path merges the branch BEFORE the worktree is removed instead of relying on this step.
+   Never leave an orphaned worktree, and run `git worktree prune` if you hit a stale
+   reference. For the full ordering rationale and the release-vs-plain-disarm
+   distinction, read `references/end-tail.md`.
+9. QMD reindex LAST (canonical End tail), run only after disarm has released the
+   worktrees, cleared the `delivery.lock`, and purged the bridge. It runs in the
+   background so it never blocks the turn:
    ```bash
    ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the store
-   that holds this intent (the global store or the project store). The reindex is the LAST End-tail
-   step, run after purge, so the index never references a bridge or lock that is about to disappear
-   (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
-10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
+   `<store-root>` is the store that holds this intent (the global store or the project
+   store); the command is a no-op when QMD is absent. For why the reindex must be last
+   (so the index never references a bridge or lock about to disappear), read
+   `references/end-tail.md`.
+10. Notify user (Done briefing): brief per `references/human-report-contract.md`
+    (State: the delivered impact; Risk: residual risk; Call: the decision left to you, merge,
+    release, or accept). See `outcome.md` for details.
 
 ## Error Handling
 
@@ -324,3 +321,8 @@ If the agent gets stuck (can't resolve a gap, dependency is missing, tests fail
 
 - 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
 - Read `references/tiers.md` for the extended per-tier walkthrough (S/M/L worked examples, the collapsed one-thinker flow, the QMD-skip case for S) and rationale
+- Read `references/human-report-contract.md` for the human-facing per-stage briefing (the
+  State/Risk/Call skeleton used at each "Notify user" step above, and how it differs from the
+  internal `agent-report-contract.md`)
+- Read `references/end-tail.md` for the `resolve_session` fallback chain and the disarm
+  ordering / worktree cleanup / QMD reindex rationale referenced above

package/skills/auto/references/end-tail.md

@@ -0,0 +1,56 @@
+# End-Tail Mechanics: resolve_session and Disarm Ordering
+
+Deep WHY/mechanics detail behind two spots in `SKILL.md`: how `arm_auto` resolves a
+session id when arming the gate, and why the End-tail steps in Completion (release
+worktrees, clear the lock, purge the bridge, reindex) run in that exact order.
+
+## Table of Contents
+
+- [resolve_session fallback internals](#resolve_session-fallback-internals)
+- [Disarm ordering and worktree cleanup rationale](#disarm-ordering-and-worktree-cleanup-rationale)
+- [QMD reindex ordering rationale](#qmd-reindex-ordering-rationale)
+
+## resolve_session fallback internals
+
+`arm_auto` calls `resolve_session`, which picks the first non-empty of: the explicit
+id you pass -> `CLAUDE_CODE_SESSION_ID` -> a deterministic derived key (a hash of the
+store and intent id). It never returns nil, so the gate engages even when every
+session env var is empty; the call never needs a non-empty session env var to
+function. Arming prints a one-line notice to stderr when it falls through to the
+derived key.
+
+Arming acquires the durable `delivery.lock` in the intent dir, keyed by that resolved
+session. Ownership is session-keyed, not process-keyed, so the arm one-liner exiting
+immediately is fine by construction: the lock stays yours for every later tool call in
+this session. A failed arm raises with a message naming the resolving `plastic-lock`
+verb.
+
+## Disarm ordering and worktree cleanup rationale
+
+Disarm runs the ordered End tail: it releases the worktrees first, then clears the
+intent's `delivery.lock` (and the bridge's lock cache), and only then is the bridge
+purge-eligible. Disarming also purges stale bridge files from the temp directory
+automatically (it keeps the current bridge, any live run, and any bridge whose intent
+still holds a delivery lock), so no manual `/tmp` cleanup is needed.
+
+**Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
+`disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
+worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
+`<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
+from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
+only when no release merges the branch (the branch survives and can be reclaimed).
+
+When the work is being shipped through a release, do NOT rely on this plain remove. The
+release path (Completion step 4, via `plastic-releasing`) is responsible for merging the
+intent's code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the
+worktree is removed, so the integrated work is not lost. It does this with
+`Worktree.finish(bridge_data, merge: true)` (merge-then-remove). Never leave an orphaned
+worktree, and run `git worktree prune` if you hit a stale reference.
+
+## QMD reindex ordering rationale
+
+Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is
+the store that holds this intent (the global store or the project store). The reindex is
+the LAST End-tail step, run after purge, so the index never references a bridge or lock
+that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner
+Lock`).

package/skills/auto/references/human-report-contract.md

@@ -0,0 +1,55 @@
+# Human Report Contract (per-stage EM-to-CTO briefing)
+
+This doc defines how the orchestrator briefs the human at each of the five stage boundaries
+(What, Why, How, Exec, Done) in auto mode. It is the outward, human-facing counterpart to the
+internal report contract in `references/agent-report-contract.md`. Voice: an engineering
+manager briefing a CTO. Lead with impact, name the risk, leave the decision.
+
+## The skeleton
+
+One fixed 3-line shape, reused at every stage:
+
+1. **State**: what happened and what it means, impact first, one line.
+2. **Risk**: the one thing that could bite, or "nothing flagged."
+3. **Call**: the decision left to you, or the go-ahead I am taking.
+
+This is a shape, not a rigid template. Keep the order (State, then Risk, then Call) and keep it
+short. The words can flex to fit the stage.
+
+## Per-stage content
+
+- **What**: State = the work I picked up and why it matters now. Risk = scope uncertainty.
+  Call = confirm this is worth doing, or I proceed.
+- **Why**: State = the approach I chose, one line. Risk = the main trade-off. Call = the one
+  decision I need (approve, or pick an option).
+- **How**: State = the plan shape (task count and what it builds). Risk = the riskiest task or
+  dependency. Call = approve the plan to build.
+- **Exec**: State = what got built and the test result. Risk = residual failures or deviations.
+  Call = go to review, or done.
+- **Done**: State = the delivered impact. Risk = residual risk. Call = the decision left to you
+  (merge, release, accept).
+
+## Boundary vs intent 74
+
+Intent 74's report contract (`references/agent-report-contract.md`) is the INTERNAL,
+machine-checked handoff from a dispatched specialist back to the orchestrator: a structured
+envelope plus a per-role payload. This contract is the OUTWARD human briefing, orchestrator to
+user, in prose. Different direction, different audience, different form. The orchestrator
+CONSUMES the intent 74 report to WRITE the human briefing defined here. The two never merge.
+
+## Brevity: point, don't repeat
+
+Surface rules (no em-dashes, plain words, no filler openers, and so on) are owned by the
+shipped `plastic-humanizer` skill and the always-on plain-language layer. This contract does not
+re-list that catalog. It restates only the hard bans as one line: no em-dashes, no "not X but Y",
+no rule of three, no hype words, no sycophancy, no over-bolding. Apply `plastic-humanizer` and the
+always-on layer for everything else.
+
+## Emission: guided vs auto
+
+In guided mode, the briefing lands at each stage boundary and the human acts on the Call line
+before the next stage starts.
+
+In auto mode, the orchestrator still emits the briefing at each boundary, as a running EM-to-CTO
+account. The Call line becomes the go-ahead the orchestrator takes itself and moves on, except at
+the existing hard stops (destructive action without a safe alternative, project-path confirm).

package/skills/brainstorming/SKILL.md

@@ -44,30 +44,8 @@ You MUST create a task for each of these items and complete them in order:
 
 ## Process Flow
 
-```dot
-digraph brainstorming {
-    "Explore project context" [shape=box];
-    "Ask clarifying questions" [shape=box];
-    "Propose 2-3 approaches" [shape=box];
-    "Present design sections" [shape=box];
-    "User approves design?" [shape=diamond];
-    "Write spec" [shape=box];
-    "Spec self-review\n(fix inline)" [shape=box];
-    "User reviews spec?" [shape=diamond];
-    "Invoke plastic-writing-plans" [shape=doublecircle];
-
-    "Explore project context" -> "Ask clarifying questions";
-    "Ask clarifying questions" -> "Propose 2-3 approaches";
-    "Propose 2-3 approaches" -> "Present design sections";
-    "Present design sections" -> "User approves design?";
-    "User approves design?" -> "Present design sections" [label="no, revise"];
-    "User approves design?" -> "Write spec" [label="yes"];
-    "Write spec" -> "Spec self-review\n(fix inline)";
-    "Spec self-review\n(fix inline)" -> "User reviews spec?";
-    "User reviews spec?" -> "Write spec" [label="changes requested"];
-    "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
-}
-```
+The Checklist above states the ordered flow (steps 1-8). For the same flow as a
+diagram, read `references/design-principles.md`.
 
 **The terminal state is invoking `plastic-writing-plans`.** Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is `plastic-writing-plans`.
 
@@ -95,16 +73,11 @@ digraph brainstorming {
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify if something doesn't make sense
 
-**Design for isolation and clarity:**
-- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
-- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
-- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
-- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
-
-**Working in existing codebases:**
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+**Design for isolation and clarity, and working in existing codebases:** before
+proposing a design, read `references/design-principles.md` for unit-boundary
+guidance (what makes a good interface, when a file has grown too large) and
+existing-codebase guidance (follow established patterns, fold in targeted
+improvements without unrelated refactoring).
 
 ## After the Design
 **Documentation:**

package/skills/brainstorming/references/design-principles.md

@@ -0,0 +1,49 @@
+# Design Principles: Unit Boundaries and Existing Codebases
+
+General good-developer guidance behind two parts of the Process: how to design for
+isolation and clarity, and how to behave in an existing codebase. Also holds the
+Process Flow diagram (the same ordered flow the Checklist already states as numbered
+steps).
+
+## Design for isolation and clarity
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+## Working in existing codebases
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## Process Flow (diagram)
+
+The Checklist above already states this ordered flow as numbered steps 1-8; this
+diagram is the same flow in a visual form.
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write spec" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke plastic-writing-plans" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write spec" [label="yes"];
+    "Write spec" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write spec" [label="changes requested"];
+    "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
+}
+```

package/skills/creating-intent/SKILL.md

@@ -124,32 +124,11 @@ cleanly, and do not work around the failure by hand-writing the files.
 
 ### 6. 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
-   ```
-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. Provision the project store (the single source of truth for store creation;
-   runs after step 4 because the provisioner requires the project to be
-   registered):
-   ```bash
-   ruby ~/.plastic/scripts/provision-project-store <slug>
-   ```
-6. Add `project-<slug>` to the intent's `tags` array
-7. Auto-commit in both `~/.plastic/` and the new project
+When the user says "start building" or the plan calls for a new project, invoke the
+`plastic-creating-project` skill; it owns project directory creation, AGENTS.md
+population, projects.yml registration, store provisioning, and the auto-commit of
+both stores. Add `project-<slug>` to this intent's `tags` array either before
+invoking it or as part of that skill's handoff.
 
 ### 7. Update INDEX.md