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

package/skills/creating-intent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:creating-intent
+name: plastic-creating-intent
 description: Use when new work begins, the user expresses a new goal, says "new intent", or no active intent exists for the current task. Creates intents in the global store (~/.plastic/store/) or in a project's store (~/.plastic/projects/{slug}/store/) depending on context.
 ---
 
@@ -60,6 +60,16 @@ IDs are scoped to the store they live in. Use the correct store path:
 "${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "<STORE>" "<parent_id>"
 ```
 
+**Branch vs root — decide before assigning the ID.** Having a "parent" in mind does
+NOT automatically mean branch. Choose by meaning:
+
+- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation. It only
+  makes sense as part of the parent's work.
+- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
+  Capture the inspiration in `sources` (e.g., `sources: ["14"]`), not in the ID.
+- **Rule of thumb:** if the intent could exist without its parent, make it a root and
+  set `sources`. Only branch when it genuinely cannot stand alone.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:
@@ -79,7 +89,17 @@ mkdir -p <STORE>/ID--slug
 
 Write `{ID}--{slug}.md` using the intent template. For project intents, add the governing intent's ID to `sources` and add `[[global:ID]]` backlink in `## Links`.
 
-### 5. If Implementation Intent Spawns a Project
+### 5. Self-Verify the Written Intent
+
+Before announcing or committing, verify the just-written intent is born complete:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/validate-intent" "<STORE>/ID--slug"
+```
+
+If it exits non-zero, read the stderr report, inject the missing field(s) into the `{ID}--{slug}.md` frontmatter (for example add `chain: []`) WITHOUT disturbing other frontmatter keys, and re-run `validate-intent` until it exits 0. Only then proceed to the remaining steps (project spawn, INDEX.md, commit, announce).
+
+### 6. If Implementation Intent Spawns a Project
 
 When the user says "start building" or the plan calls for a new project:
 
@@ -89,8 +109,6 @@ When the user says "start building" or the plan calls for a new project:
    mkdir -p <project_root>/<slug>
    cd <project_root>/<slug>
    git init
-   mkdir -p ~/.plastic/projects/{slug}/store
-   touch ~/.plastic/projects/{slug}/store/.gitkeep
    ```
 3. Copy `AGENTS.md` template from `${CLAUDE_PLUGIN_ROOT}/templates/agents.md`
 4. Register in `~/.plastic/projects.yml`:
@@ -101,22 +119,33 @@ When the user says "start building" or the plan calls for a new project:
      registered: <today>
      status: active
    ```
-5. Add `project-<slug>` to the intent's `tags` array
-6. Auto-commit in both `~/.plastic/` and the new project
+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
 
-### 6. Update INDEX.md
+### 7. Update INDEX.md
 
 - **Global intents:** update `~/.plastic/INDEX.md`
 - **Project intents:** no global INDEX.md change (tactical intents are project-scoped)
 
 Add to `## Active` (or `## Future`) and appropriate cluster.
 
-### 7. Auto-commit
+### 8. Auto-commit
 
 ```bash
 cd <store-root> && git add . && git commit -m "feat: create intent ID — [name]"
 ```
 
-### 8. Announce
+### 9. Announce
 
 "Created intent ID — [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
+
+## References
+
+- Read `references/lifecycle.md` for the full What→Why→How→Exec stage detail, filesystem-as-schema conventions, and creating-intent step-by-step
+- Read `references/wikilinks.md` for the wikilink syntax table when adding `## Links` to intents

package/skills/creating-intent/references/lifecycle.md

@@ -0,0 +1,74 @@
+# Building an Intent — Full Lifecycle Detail
+
+## What → `## Intent` section
+
+The desire. One paragraph. What the human or agent wants.
+This exists from the moment the intent is created.
+
+**Deliverable:** `{ID}--{slug}.md`
+
+## Why → `## Context` + `### Decisions` sections
+
+Why this intent exists. Grows over time through brainstorming and exploration.
+
+- **Context** — what we knew going in + what we decided along the way
+- **Decisions** — main premises derived from Context plus decisions from brainstorming/grilling
+- Decisions are Why-level: "status belongs on actions because multiple workstreams", not How-level: "use ACTION_N.md files"
+
+**Deliverable:** `spec.md` (consolidated specification from Context + Decisions + brainstorming)
+
+## How → Planning and preparation
+
+Research decisions, create the implementation plan, define actions.
+
+**Deliverable:** `plan.md` + `actions/` + `checklist.md` (execution registry with checkboxes covering all actions)
+
+## Exec → Execute actions
+
+Execute actions from the plan, track progress via checklist.
+
+**Deliverable:** `outcome.md` (detailed result). `## Outcome` in intent.md = short summary written as last step.
+
+## `## Insights` — Append-only work log
+
+Captured throughout ALL stages. One-liner bullet points.
+Never modified, only appended.
+
+Tracks: stage transitions, decisions, shifts, blocks, cancellations, material for future intents.
+This is how execution is tracked. When this intent completes, Insights
+is where to look for what comes next. New intents spawned from Insights
+appear in the `chain` field.
+
+## `## Links`
+
+Wikilinks for Obsidian graph navigation. Human-facing counterpart to the
+frontmatter knowledge graph.
+
+## Conventions — Filesystem as Schema
+
+State is derived from what exists, not from what's declared.
+
+| Convention | Signal |
+|---|---|
+| No `## Context` | Intent is fleeting (quick capture, non-actionable) |
+| `## Context` has content | Intent is permanent (developed, actionable) |
+| `## Outcome` has content | Intent is done |
+| `## Insights` has `(autonomous)` entries | Intent is/was being delivered autonomously |
+
+### Transitions
+
+- Fleeting → permanent: add `## Context` (one-way, also makes it actionable)
+- There is no separate "non-actionable → actionable" transition — permanence implies actionability
+- Even research intents are actionable: the research itself is the action, the conclusion is the outcome
+
+## Creating an Intent — Full Steps
+
+1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
+2. Determine the Folgezettel ID: If root (no parent), find highest root number +1. If branch, run `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
+3. Create the intent directory in the chosen store (e.g., `ID--three-to-five-words`)
+4. Create `{ID}--{slug}.md` with frontmatter (id, intent, sources, chain, created, author, tags)
+5. Write `## Intent` — the What
+6. Add remaining sections: `## Context`, `## Outcome`, `## Insights`, `## Links`
+7. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
+
+A fleeting intent can skip `## Context` — just `## Intent` and empty sections.

package/skills/creating-intent/references/wikilinks.md

@@ -0,0 +1,8 @@
+# Wikilink Conventions
+
+| Syntax | Meaning |
+|--------|---------|
+| `[[ID]]` | Link to intent in same store (e.g., `[[1a1]]`) |
+| `[[ID\|display text]]` | Link with human-readable label |
+| `[[global:ID]]` | Link to intent in `~/.plastic/store/` |
+| `[[project-slug:ID]]` | Link to intent in `~/.plastic/projects/{slug}/store/` |

package/skills/creating-project/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: plastic:creating-project
+name: plastic-creating-project
 description: >-
   Create a new project from an implementation intent. Sets up project directory,
-  git init, AGENTS.md with founding intent decisions, plastic:install --local,
+  git init, AGENTS.md with founding intent decisions, plastic-install --local,
   tactical mirror, projects.yml registration, and framework scaffolding.
   Use when an implementation intent spawns a project, or manually by user.
 ---
@@ -31,9 +31,9 @@ cd <project_root>/<slug>
 git init
 ```
 
-### 3. Run `plastic:install --local`
+### 3. Run `plastic-install --local`
 
-Invoke `plastic:install --local` in the project directory. This creates:
+Invoke `plastic-install --local` in the project directory. This creates:
 ```
 .plastic/
 ├── store/
@@ -127,7 +127,24 @@ Read `~/.plastic/projects.yml` and add:
 
 For Hub-spawned projects, `parent` references the primary founding intent.
 
-### 7. Mark Global Intent(s) Completed
+### 7. Provision the Project Store
+
+The `provision-project-store` verb is the single source of truth for store
+creation. Run it after the project is registered in step 6 (the provisioner
+requires registration), and before the QMD step:
+
+```bash
+ruby ~/.plastic/scripts/provision-project-store <slug>
+```
+
+This ensures `~/.plastic/projects/<slug>/store/` exists with `.gitkeep`, and
+writes `INDEX.md` and `project.yml` only if missing. It is idempotent, so it is
+safe even when the tactical mirror in step 5 already created the store directory.
+Do not create the store with an inline `mkdir`; the provisioner is the only place
+a store is made. For a project that is already registered but store-less, use the
+`plastic-add-project-store` skill instead.
+
+### 8. Mark Global Intent(s) Completed
 
 For each founding intent:
 
@@ -137,7 +154,7 @@ For each founding intent:
 3. Update `chain` to include `project-<slug>:1`
 4. Move from `## Active` to `## Completed` in `~/.plastic/INDEX.md` (with today's date)
 
-### 8. Framework Scaffolding
+### 9. Framework Scaffolding
 
 If decisions specify a framework, run the appropriate scaffolding command AFTER steps 3-4 (so scaffolding doesn't overwrite Plastic files or AGENTS.md):
 
@@ -150,17 +167,32 @@ If decisions specify a framework, run the appropriate scaffolding command AFTER
 
 After scaffolding, verify AGENTS.md and `.plastic/` still exist. If scaffolding overwrote them, restore.
 
-### 9. Auto-commit Both Stores
+### 10. Auto-commit Both Stores
 
 ```bash
 cd ~/.plastic && git add . && git commit -m "feat: spawn project <slug> from intent <ID>"
 cd <project> && git add . && git commit -m "feat: initialize project from intent <ID>"
 ```
 
-### 10. Announce
+### 11. Register the project store with QMD (optional)
+
+If QMD is installed, register the new project's store as a search collection:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
+```
+
+`qmd-sync` no-ops when QMD is absent, so run it unconditionally. This adds the
+`plastic-<slug>` collection and indexes it.
+
+### 12. Announce
 
 Log in `## Insights` of each founding intent:
 > "Project `<slug>` created at `<path>`. Tactical mirror: `project-<slug>:1` (autonomous)"
 
 Announce to user:
 > "Project `<slug>` created at `<path>`. AGENTS.md populated with [N] decisions from [founding intent IDs]. Tactical mirror `1` is now the active intent in the project store."
+
+## References
+
+- Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/creating-project/references/hubs-projects.md

@@ -0,0 +1,55 @@
+# Hubs and Projects
+
+## Hubs
+
+A Hub is a cloud of intents around related topics. Hubs emerge naturally from
+Folgezettel branching — intents that spawn in the same direction cluster.
+
+- A Hub can spawn a Project. The Hub holds the founding ideas.
+- A single intent can also spawn a Project.
+- Hub-spawned projects revolve around different ideas around related topics.
+- Intent-spawned projects revolve around the single founding intent.
+- A Project is the deliverable outcome of one or more intents.
+
+Hubs are represented as clusters in INDEX.md.
+
+## Projects — Full Detail
+
+A Project is a deliverable grouping of intents. Projects have two stores:
+
+- **Global store** (`~/.plastic/store/`): strategic intents
+- **Project store** (`~/.plastic/projects/{slug}/store/`): tactical intents
+
+`projects.yml` maps project slugs to codebase paths:
+```yaml
+projects:
+  plastic:
+    path: "/path/to/plastic"
+    remote: "git@github.com:org/plastic.git"
+    registered: '2026-05-26'
+    status: active
+```
+
+Config resolution: `~/.plastic/projects/{slug}/config.yml` overrides `~/.plastic/config.yml`.
+
+Cross-linking: project intents reference global intents via `[[global:ID]]`. Global intents reference project intents via `[[project-slug:ID]]`.
+
+## Privacy and Collaboration
+
+**Plastic is personal.** All intent data lives under `~/.plastic/` — one location,
+one git repo, never pushed. Each person has their own intent store.
+
+Collaboration happens through pull requests and project conventions, not shared intents.
+When an intent delivers something that changes how a project works, the decision gets
+written into the project's shared files (README, docs, config). The intents themselves
+are private working memory.
+
+## Project Creation Flow
+
+When an implementation intent spawns a project:
+1. Determine project path from config `project_roots` or intent context
+2. `gh repo create --private` (agent-created repos are always private by default)
+3. Set up project directory, git init, AGENTS.md with founding intent decisions
+4. Register in `projects.yml`
+5. Create tactical mirror in project store
+6. The global intent completes; the tactical mirror becomes the active intent

package/skills/dashboard/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: plastic-dashboard
+description: Use when the user wants an overview of intents, asks "where are we", "what's next", "what should I work on", "show the dashboard", or invokes /plastic-dashboard. Renders a deterministic Value×Effort work cockpit as Markdown across the global store and all projects, and emits a machine-readable queue that auto mode consumes.
+---
+
+# Dashboard — Plastic Work Cockpit
+
+A deterministic overview of the intent store(s). It answers three questions at a glance:
+**where we are** (recently worked), **where we go next** (a Value×Effort matrix), and
+**how to conduct it** (a disposition per intent). The human-facing surface is **Markdown**,
+because the user's UI renders Markdown natively but collapses raw tool-call stdout.
+
+The script does all the data work. The agent fills a Markdown template from the script's
+payload with near-zero reasoning and **presents the filled board in its reply**. Same store
+state → byte-identical payload, regardless of model. Do NOT hand-summarize intents.
+
+## When to Use
+
+- User invokes `/plastic-dashboard`
+- User asks "where are we", "what's next", "what should I work on", "show me the intents"
+- `plastic-continuing` lands on the board on resume
+- `plastic-auto` reads `--json` to choose the next dispatchable intent
+
+## Procedure (the Markdown board — default human surface)
+
+### Step 1 — Get the data payload
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>] --data
+```
+
+- `continue` (default) → the **global** board payload (`mode: "global"`).
+- `project <slug>` → that **project** board payload (`mode: "project"`).
+
+The payload is read-only JSON. Global-board fields: `date`, `store_health`, `recently_worked`,
+`matrix` (`quick_win`/`next_big`/`defer`/`triage`/`research`, each a list of `{line, bullet, ...}`),
+`counts`, `projects`, `project_totals`. Project-board fields: `slug`, `store_health`,
+`description`, `recently_worked`, `matrix`, `counts`, `active`, `future`.
+
+Each board load runs the scoped store check (`doctor --store <scope>`): the global board runs
+`--store global` and a project board runs `--store <slug>`. The result rides in the payload as
+`store_health` (`{scope, status, summary, failing_checks}`). Surface it as a one-line
+store-health note on the board (for example `store health: pass (3/3)` or
+`store health: warn (orphaned_intents)`). It is non-fatal: a warn or fail is shown as data and
+never blocks the board.
+
+### Step 2 — Fill the matching template
+
+Templates live in this skill's `templates/` directory:
+`~/.claude/skills/plastic-dashboard/templates/dashboard-global.md` and
+`dashboard-project.md`.
+
+Fill mechanically — no rewriting, no re-sorting:
+- `{{a.b.count}}` → the integer (e.g. `matrix.quick_win.count` = that list's length).
+- `{{...lines}}` → join the list's `.line` strings with **real newlines** (one per line).
+  These lines are already glyph-led (the glyph is the bullet — never add `-`, never emit
+  `<br>`). If a matrix quadrant list is empty, render `_(none)_`.
+- `projects.lines` → one line per project:
+  `- **{slug}** — {description} · active {active} · done {done} · future {future} · last accessed {last_accessed_at[0,10]}`.
+- Scalars (`{{date}}`, `{{slug}}`, `{{description}}`) → substitute verbatim.
+
+### Step 3 — Present it (mandatory, every invocation)
+
+**Paste the filled Markdown into your reply.** This is non-optional: the board only reaches
+the user when it is in the chat reply, not in tool-call stdout. Never describe the board
+instead of showing it.
+
+### Step 4 — Entry flow (the board is the menu)
+
+The board lists everything; the user navigates by free prose (no capped picker):
+- On the **global** board, the user replies with an **intent id** (work it), a **project
+  name** (re-run `project <slug> --data` and present that board), or **"new"** (start a new
+  intent in global via `plastic-creating-intent`).
+- On a **project** board, the user replies with an **intent id**, or **"global"** to return.
+
+## Auto-mode contract (`--json`)
+
+`plastic-auto` consumes a separate machine-readable manifest (unchanged):
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>|all] --json
+```
+
+```json
+{ "generated_for": "auto-mode", "scope": "<scope|all>",
+  "next_big_thing": "<id|null>",
+  "dispatchable_queue": [ {"id","scope","disposition","type","value","effort","flags","rank"} ],
+  "human_only": ["<id>", "..."] }
+```
+
+Work `dispatchable_queue` in `rank` order (`defer`/`research`); leave `human_only` for the user.
+
+## Text modes (terminal / legacy)
+
+`dashboard.rb [continue|project <slug>|all]` with no flag still prints the ASCII cockpit for
+a raw terminal. The Markdown board (`--data` + template) is the surface for the chat UI.
+
+## How classification works (deterministic)
+
+- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
+  (plan/checklist exists), or deep refinement branches; big otherwise.
+- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; an
+  intent with a non-empty `chain`; or an intent that is a `source` of ≥1 other intent. Else low.
+- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done;
+  `stale` only on future intents past the staleness threshold. Both kept low-noise by design.
+- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
+  model judgment at render time).
+
+## Eval
+
+The eval is the payload + golden snapshots: run the engine against the fixture store and
+assert the `--data` payload shape/sorting/classification and the byte-identical `--json` +
+text goldens in `test/fixtures/dashboard/`. See `test/dashboard_test.rb`. Drift without an
+intentional change means the skill is broken.
+
+## Notes
+
+- Quadrant lists are **not** Markdown `-` bullets — the glyph is the bullet (the boards are
+  UI-only and may evolve, so they need not be valid Markdown lists). Never emit `<br>`.
+- Clusters (Zettelkasten grouping in INDEX.md) are intentionally not rendered.
+- Additive: changes no core lifecycle, gate, or cycle logic.

package/skills/dashboard/templates/dashboard-global.md

@@ -0,0 +1,31 @@
+# 🧩 Plastic · Global Board — {{date}}
+
+**Recently worked** · last 24h
+{{recently_worked.lines}}
+
+## Where we go next · Value × Effort  *(global intents only)*
+
+|  | Small effort | Big effort |
+|---|---|---|
+| **High value** | ⚡ **Quick win** · {{matrix.quick_win.count}} | ★ **Next big thing** · {{matrix.next_big.count}} |
+| **Low value** | → **Defer (agent)** · {{matrix.defer.count}} | ⚑ **Triage** · {{matrix.triage.count}} |
+
+**⚡ Quick win** — small effort, high value
+{{matrix.quick_win.lines}}
+
+**★ Next big thing** — big effort, high value
+{{matrix.next_big.lines}}
+
+**→ Defer (agent)** — small effort, low value
+{{matrix.defer.lines}}
+
+**⚑ Triage** — big effort, low value
+{{matrix.triage.lines}}
+
+🔬 **Research → agent**
+{{matrix.research.lines}}
+
+## Projects · active {{project_totals.active}} · done {{project_totals.done}} · future {{project_totals.future}}
+{{projects.lines}}
+
+**What would you like to work on next?** (type an **intent id**, a **project name**, or anything **new** you'd like to start)

package/skills/dashboard/templates/dashboard-project.md

@@ -0,0 +1,40 @@
+# 📦 {{slug}} · Project Board — {{date}}
+
+{{description}}
+
+**Recently worked** · last 24h
+{{recently_worked.lines}}
+
+## Where we go next · Value × Effort
+
+|  | Small effort | Big effort |
+|---|---|---|
+| **High value** | ⚡ **Quick win** · {{matrix.quick_win.count}} | ★ **Next big thing** · {{matrix.next_big.count}} |
+| **Low value** | → **Defer (agent)** · {{matrix.defer.count}} | ⚑ **Triage** · {{matrix.triage.count}} |
+
+**⚡ Quick win** — small effort, high value
+{{matrix.quick_win.lines}}
+
+**★ Next big thing** — big effort, high value
+{{matrix.next_big.lines}}
+
+**→ Defer (agent)** — small effort, low value
+{{matrix.defer.lines}}
+
+**⚑ Triage** — big effort, low value
+{{matrix.triage.lines}}
+
+🔬 **Research → agent**
+{{matrix.research.lines}}
+
+## Intents · active {{counts.active}} · done {{counts.done}} · future {{counts.future}}
+
+**Active**
+{{active.lines}}
+
+**Future**
+{{future.lines}}
+
+**Legend** · ○ What ◔ Why ◑ How ◕ Exec ● Done · ⚡ quick win ★ big → defer ⚑ triage 🔬 research
+
+**What would you like to work on next?** (type an **intent id**, or **global** to go back)

package/skills/doctor/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: plastic-doctor
+description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
+---
+
+# Doctor — Plastic Health Check
+
+## Scopes
+
+Doctor has three scopes. Pick the right one for the situation:
+
+| Scope | Flag | When it runs | States |
+|-------|------|--------------|--------|
+| Core check | `--core` | SessionStart hook (automatic), also available on demand | Binary: pass or error |
+| Store check | `--store [global\|<slug>]` | Dashboard load, `plastic-continuing` | Three-state: pass / warn / fail |
+| Full check | (no flag) | After every update (automatic), or `/plastic-doctor` | Three-state: pass / warn / fail |
+
+### `--core` (binary, manifest-backed)
+
+Verifies that every core file is present and content-matches what the installed
+version shipped. It checks two install manifests:
+
+- `~/.plastic/manifest.json` (global manifest, covers PLASTIC.md and global scripts)
+- `~/.claude/plastic/manifest.json` (agent-side manifest, covers agent scripts and hooks)
+
+Each manifest maps a file path to its SHA256. The core check also confirms hooks
+are registered, scripts are present and executable, and the installed version
+matches. Result is binary: exit 0 on pass, non-zero on error. It never produces
+warnings.
+
+### `--store [global|<slug>]`
+
+Checks store state: intents are well-formed, INDEX sections are present, conventions
+are followed, and links are valid. Scope options:
+
+- No argument: checks all stores (global and all projects)
+- `global`: checks only the global store
+- A project slug (e.g. `--store plastic`): checks only that project's store
+
+Produces three-state results (pass / warn / fail) and is run per-scope at dashboard
+load time: the global board uses `--store global`, a project board uses `--store <slug>`.
+
+### Full doctor (no flag)
+
+Runs core plus all store checks plus deprecation checks. This is what `/plastic-doctor`
+invokes. It also runs automatically after every `plastic-update` (informational,
+does not block or revert the update).
+
+## When to Use
+
+- User invokes `/plastic-doctor` (full check)
+- After `plastic-update` completes (automatically, full check)
+- When hooks aren't firing, skills aren't loading, or something seems broken
+- When the user says "check plastic", "diagnose", "what's wrong with plastic"
+
+## Procedure
+
+### Step 1: Run the diagnostic script
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Replace `claude` with the current agent type if known (`codex`, `hermes`).
+
+Parse the JSON output from stdout. The script is read-only and never modifies
+files. Errors go to stderr.
+
+Exit codes indicate check results, not script failure:
+- `0` — all checks passed
+- `1` — warnings found
+- `2` — failures found
+
+All three exit codes mean the script ran successfully. Do not treat non-zero
+as an error.
+
+### Step 2: Determine overall status
+
+Read the `status` field from the JSON root:
+
+| Status | Meaning |
+|--------|---------|
+| `pass` | Everything is healthy |
+| `warn` | Warnings found but Plastic works normally |
+| `fail` | Blocking issues that prevent Plastic from operating |
+
+### Step 3: Fill the report template
+
+Read `report.md` from the same directory as this SKILL.md
+(`~/.plastic/skills/doctor/report.md` at runtime, or the plugin source
+`skills/doctor/report.md` during development).
+
+Group checks by category. For each category, list the checks with their
+status icon and message. If a check has `details`, list them as sub-items.
+
+Present the filled template to the user.
+
+### Step 4: Offer fixes (if applicable)
+
+If any checks have `fixable: true` AND status is not `pass`:
+
+1. Group fixable items by category
+2. Show what each fix would do (from `fix_hint`)
+3. Ask the user: **"Fix all / Select individually / Skip"**
+
+If no fixable issues exist, skip this step.
+
+### Step 5: Apply fixes
+
+Use the `fix_hint` value to determine the correct action:
+
+| Fix hint pattern | Agent action |
+|---|---|
+| "chmod +x on the listed files" | Run `chmod +x` on each file listed in `details` |
+| "Create missing directory" | Run `mkdir -p` on the path |
+| "Create INDEX.md with required sections" | Write INDEX.md with the 5 sections: Active, Future, Clusters, Abandoned, Completed |
+| "Add missing entries to INDEX.md" | Add orphaned intents to the appropriate INDEX.md section |
+| "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
+| "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
+| "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
+| "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+
+For fixes the agent cannot handle automatically, explain what the user needs
+to do manually.
+
+### Step 6: Verify
+
+After applying fixes, re-run the diagnostic script:
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Show the updated results.
+
+- If all checks pass: announce success.
+- If issues remain: explain what is still wrong and what the user can do.
+
+## Post-Update Mode
+
+When invoked from `plastic-update` (not directly by the user):
+
+1. Run the diagnostic script as in Step 1.
+2. If all checks pass: show a single line — **"Health check: all clear."**
+3. If issues are found: show the full report (Steps 3-6).
+
+This keeps the update flow clean when nothing is wrong.
+
+## Important Notes
+
+- The script is **read-only**. It inspects but never modifies files.
+  All fixes are performed by the agent using standard tools.
+- The script outputs JSON to stdout. Any diagnostic errors go to stderr.
+- Non-zero exit codes mean "issues found", not "script crashed".
+  Always parse stdout regardless of exit code.
+
+## References
+
+- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and stuck detection thresholds when diagnosing gate failures or stuck agents