@zalom/plastic 1.0.0-beta.9 → 1.0.0

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/auto/references/tiers.md

@@ -0,0 +1,77 @@
+# Tiers — Extended Walkthrough
+
+This is the detail behind `## Tiers` in SKILL.md. The five points there (sizing rule, two
+levers, per-tier topology, never-cut list, tier record) are the authoritative contract;
+this file only expands on them with examples and rationale.
+
+## Why sizing exists
+
+Auto mode used to run every intent through the same full-ceremony team: brainstorming,
+spec-specialist, planner, executor, and an independent reviewer, each a separate agent
+booting a fresh context. For a large or novel intent that ceremony earns its cost. For a
+small intent (one file, one mechanism, an hour of real work) the ceremony dominates:
+overhead runs about 3 to 4 times the actual work time, roughly flat regardless of size, so
+it hurts small intents the most. Sizing at Why and matching the topology to that size drops
+small-intent ceremony toward about 1.5x work time, without touching structure, gates, or
+the savepoint ledger.
+
+## Sizing rule, worked examples
+
+- S: fixing one script's argument parsing, adding one skill section, a single bug fix
+  confined to one file. Hours of work.
+- M: adding a new agent role file end to end, a subsystem with a handful of touched files
+  and one clear seam. About a day.
+- L: cross-cutting prose or code that spans the skill contract plus multiple agent role
+  files (like this intent, 130), or any genuinely novel design with no established pattern
+  to follow.
+
+## S/M collapsed topology, in detail
+
+One thinker agent boots ONCE and stays in a single context for two stations:
+
+1. Station 1 — writes `spec.md` (collapsed sections allowed, one line each is valid).
+2. Station 2 — writes `plan.md` + `checklist.md` in the SAME context (no reboot). plan.md
+   carries the checklist rationale inline instead of separate `actions/ACTION_N.md` files.
+   `actions/` is not created for S/M.
+
+Then a sonnet executor (a fresh dispatch, this is the one topology split that always
+happens) implements from plan.md + checklist.md, checks off items, appends `## Insights`,
+and drives the suite green, exactly as it does for L.
+
+The independent reviewer still runs at the final gate for S/M, in its own fresh context,
+never the maker. This is on the never-cut list; it does not collapse.
+
+S may skip the QMD discovery deposit (normally a `plastic-intent-discovery` pass before
+Why) when the intent's `chain` and `sources` are both empty in frontmatter. With no graph
+edges there is nothing to discover, so the deposit is pure overhead; a one-line context
+note ("no chain/sources, discovery skipped") takes its place.
+
+## L topology, unchanged
+
+L keeps today's full multi-agent team as described in `## Team Spin-Up`: brainstorming,
+spec-specialist, planner, executor, each a separate agent in its own fresh context, plus
+the independent reviewer at the final gate. Cross-cutting or novel work benefits from the
+separate perspectives and the handoff discipline; the ceremony is not waste at this size.
+
+## Same-structure invariant, why it is non-negotiable
+
+The file set, stage order, gates, and savepoint ledger never change by tier. Renaming or
+skipping files to save time would require new gate logic per tier and would break state
+derivability (the gates and the savepoint rebuild depend on a fixed file set at fixed
+paths). So the only two levers are content depth and agent topology; structure is the
+constant that keeps every tier auditable the same way.
+
+## Tier record, mechanics
+
+The tier is recorded as a `Tier: S|M|L` line at the very top of spec.md, above the `#
+Spec:` heading. It is convention-only: the orchestrator reads it to pick topology, and
+nothing else depends on it. No frontmatter schema change, no new file, no doctor rule, no
+gate check. If a later intent wants doctor or a gate to validate the line, that is a
+separate, explicit follow-up; this system deliberately adds no new operational surface.
+
+## Never-cut list, the safety floor
+
+At any tier or mode: the independent reviewer (separate agent, fresh context, never the
+maker), `outcome.md` as the truth of delivery, the delivery lock, worktree isolation,
+intent creation via skill, INDEX as status truth, the QMD reindex at End. These are
+predictability and safety guarantees, not ceremony, and lightness never touches them.

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/continuing/SKILL.md

@@ -38,7 +38,11 @@ here — run the data payload and fill + present the matching template:
 - Otherwise → `ruby ~/.plastic/scripts/dashboard.rb continue --data`
 
 Fill the matching template from this skill's `templates/` and **present the filled Markdown
-in your reply** (every time). See `plastic-dashboard` for the fill rules and entry flow.
+in your reply** (every time, non-optional). If the reply does not contain the filled Markdown,
+the user sees nothing — tool-call stdout and hook `additionalContext` are both invisible to
+them. `hook-continue` also emits a one-line `systemMessage` summary as a hook-owned fallback;
+treat it as a floor only, never as a substitute for presenting the full board here. See
+`plastic-dashboard` for the fill rules and entry flow.
 
 The board load runs the scoped store check on every load (`doctor --store <scope>`): the
 global board runs `--store global` and a project board runs `--store <slug>`. The result
@@ -63,13 +67,28 @@ command is a no-op when QMD is absent, so fall back to the existing INDEX.md / f
 
 For that intent's directory:
 
-1. **Read `savepoint.md`.** It is a deterministic, append-only stage ledger (one line per
-   milestone, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. The **last line =
-   current stage**.
-2. **Verify the stage file.** Confirm the file the ledger names exists and is non-empty
-   (ledger `How  plan.md created` → `plan.md` must be present and non-empty).
+1. **Read `savepoint.md` FIRST (intent 81).** It is a deterministic, append-only ledger
+   (one line per event, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. Classify
+   the state from the **last line** alone, then verify ONLY that line's artifact. The bookends
+   are fixed: first line `What  created`, last line either a cycle position or
+   `Done  delivered|abandoned`.
+
+   | Last line | State | Verify only |
+   |---|---|---|
+   | `What  {id}--{slug}.md` | born / parked | intent file exists |
+   | `Why  started` | Why entered, no spec yet | spec.md not yet real; continue Why |
+   | `Why  spec.md created` | Why done | spec.md present; continue to How |
+   | `How  started` / `How  plan.md created` | How in progress | plan.md; continue How |
+   | `How  checklist.md created` / `Exec  started` | ready for / in Exec | plan.md + checklist.md present; continue Exec |
+   | `Exec  outcome.md created` | Exec done | outcome.md present; ready to complete |
+   | `Done  delivered` / `Done  abandoned` | terminal | do NOT cycle-resume; INDEX is authoritative |
+
+2. **Verify the stage file.** Confirm only the last line's artifact exists and is non-empty
+   (ledger `How  plan.md created` → `plan.md` must be present and non-empty). Do not re-probe
+   every lifecycle file.
 3. **Drift handling.** If the ledger's last line disagrees with files-on-disk, rebuild the
-   ledger from filesystem state and note the correction:
+   ledger from filesystem state and note the correction. A rebuilt ledger is the file-landing
+   skeleton (no `started`/`Done` lines), which still pins cycle position:
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
    ```

package/skills/creating-intent/SKILL.md

@@ -62,12 +62,18 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
     direct-ascendant provenance (D1).
   - **Merely related to / inspired by another intent** (it did NOT come out of that
     intent's lifecycle): carry NO `--sources`. Record the relation on the PREDECESSOR's
-    `chain` instead, and mirror it as a `[[id]]` wikilink in `## Links` (the
-    related-but-not-spawned rule).
+    `chain` instead (the related-but-not-spawned rule); the `## Links` section follows
+    from that edge, you do not write it by hand.
 - **Rule of thumb:** if the intent could exist without its parent, make it a root; only set
   `--sources` when it was genuinely created from / emerged from that intent's lifecycle.
   Topic similarity alone is not a `sources` edge.
 
+`## Links` is a DERIVED view of `sources`/`chain`. Never hand-write a `## Links` line; add the
+frontmatter edge and reproject. Links are decided by context influence (a `chain` edge has a high
+bar: the candidate's context must materially help deliver this intent), not by shared files or a
+similarity score. To gather candidates with their context and record an edge, use the
+`plastic-linking-intents` skill and `scripts/link-suggest`.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:
@@ -118,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
 

package/skills/creating-project/SKILL.md

@@ -43,89 +43,25 @@ Invoke `plastic-install --local` in the project directory. This creates:
 
 ### 4. Populate AGENTS.md
 
-Create `AGENTS.md` in the project root with:
-
-```markdown
-# <Project Name> — Agent Instructions
-
-Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
-Follow it exactly.
-
-This file is the operating contract for this project. Any agent entering
-this project reads this file first.
-
-## Global Store
-
-Location: `~/.plastic/`
-Governing intent(s): <list of founding intent IDs with descriptions>
-
-## Decisions
-
-<Copy ALL decisions from founding intent(s)' `## Context > ### Decisions`>
-
-Each decision should include:
-- The decision itself
-- The rationale (why this choice)
-- Date decided
-
-## Project-Specific Rules
-
-<Any rules derived from the decisions — e.g., "Use Minitest, not RSpec",
-"37signals methodology", "sqlite-vec for vector storage">
-```
+Create `AGENTS.md` in the project root from the skeleton in
+`references/project-scaffolding.md` ("AGENTS.md skeleton"): read it now and fill in
+the project name, governing intent IDs, decisions, and project-specific rules.
 
 ### 5. Create Tactical Mirror
 
-Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`:
+Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`
+using the frontmatter, sections, and INDEX.md line in `references/project-scaffolding.md`
+("Tactical mirror intent"), including the Hub multi-intent variant if there is more
+than one founding intent.
 
 **Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
 **File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
 
-```yaml
----
-id: '1'
-intent: "<same description as founding intent>"
-sources: ["global:<founding_intent_ID>"]
-chain: []
-created: <today>
-author: <same as founding intent author>
-tags: [<relevant tags>]
----
-```
-
-Sections:
-- `## Intent` — same as founding intent
-- `## Context` — carry forward relevant Context and Decisions
-- `## Outcome` — (pending)
-- `## Insights` — empty
-- `## Links` — `[[global:<founding_intent_ID>|<founding intent name>]]`
-
-Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
-```markdown
-# Index
-
-## Active
-- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
-```
-
-**For multi-intent spawning (Hub):**
-- `sources`: `["global:<id1>", "global:<id2>", ...]` — all founding intents
-- All founding intents' decisions merge into AGENTS.md
-- Context carries forward from all founding intents
-
 ### 6. Register in projects.yml
 
-Read `~/.plastic/projects.yml` and add:
-
-```yaml
-<slug>:
-  path: <full-path>
-  parent: "<founding_intent_ID>"
-  registered: <today>
-  status: active
-```
-
-For Hub-spawned projects, `parent` references the primary founding intent.
+Read `~/.plastic/projects.yml` and add the entry shown in
+`references/project-scaffolding.md` ("projects.yml registration block"). For
+Hub-spawned projects, `parent` references the primary founding intent.
 
 ### 7. Provision the Project Store
 
@@ -195,4 +131,5 @@ Announce to user:
 
 ## References
 
+- Read `references/project-scaffolding.md` before steps 4-6, for the AGENTS.md skeleton, the tactical mirror intent format, and the projects.yml registration block
 - Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/creating-project/references/project-scaffolding.md

@@ -0,0 +1,97 @@
+# Project Scaffolding Templates
+
+Full templates for the artifacts created while spawning a project: the AGENTS.md
+skeleton (Workflow step 4), the tactical mirror intent (step 5), and the
+projects.yml registration block (step 6).
+
+## Table of Contents
+
+- [AGENTS.md skeleton (step 4)](#agentsmd-skeleton-step-4)
+- [Tactical mirror intent (step 5)](#tactical-mirror-intent-step-5)
+- [projects.yml registration block (step 6)](#projectsyml-registration-block-step-6)
+
+## AGENTS.md skeleton (step 4)
+
+Create `AGENTS.md` in the project root with:
+
+```markdown
+# <Project Name> — Agent Instructions
+
+Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
+Follow it exactly.
+
+This file is the operating contract for this project. Any agent entering
+this project reads this file first.
+
+## Global Store
+
+Location: `~/.plastic/`
+Governing intent(s): <list of founding intent IDs with descriptions>
+
+## Decisions
+
+<Copy ALL decisions from founding intent(s)' `## Context > ### Decisions`>
+
+Each decision should include:
+- The decision itself
+- The rationale (why this choice)
+- Date decided
+
+## Project-Specific Rules
+
+<Any rules derived from the decisions — e.g., "Use Minitest, not RSpec",
+"37signals methodology", "sqlite-vec for vector storage">
+```
+
+## Tactical mirror intent (step 5)
+
+Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`:
+
+**Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
+**File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
+
+```yaml
+---
+id: '1'
+intent: "<same description as founding intent>"
+sources: ["global:<founding_intent_ID>"]
+chain: []
+created: <today>
+author: <same as founding intent author>
+tags: [<relevant tags>]
+---
+```
+
+Sections:
+- `## Intent` — same as founding intent
+- `## Context` — carry forward relevant Context and Decisions
+- `## Outcome` — (pending)
+- `## Insights` — empty
+- `## Links` — `[[global:<founding_intent_ID>|<founding intent name>]]`
+
+Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
+```markdown
+# Index
+
+## Active
+- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
+```
+
+**For multi-intent spawning (Hub):**
+- `sources`: `["global:<id1>", "global:<id2>", ...]` — all founding intents
+- All founding intents' decisions merge into AGENTS.md
+- Context carries forward from all founding intents
+
+## projects.yml registration block (step 6)
+
+Read `~/.plastic/projects.yml` and add:
+
+```yaml
+<slug>:
+  path: <full-path>
+  parent: "<founding_intent_ID>"
+  registered: <today>
+  status: active
+```
+
+For Hub-spawned projects, `parent` references the primary founding intent.