@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.10

package/skills/evaluating-skills/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: plastic-evaluating-skills
+description: >
+  Evaluate Plastic skills for correctness, convention compliance, and
+  progressive disclosure. Use when testing whether a skill produces good
+  outputs, verifying convention compliance after changes, running evals
+  against skills or instructions, creating evals for a new or updated
+  skill, checking if a description triggers correctly, or assessing
+  whether a skill is still needed. Also use when the user says "evaluate",
+  "test the skill", "run evals", "check conventions", or "write evals".
+---
+
+# Evaluating Skills
+
+Eval methodology for Plastic skills, based on
+[agentskills.io](https://agentskills.io/skill-creation/evaluating-skills)
+and [Anthropic's eval guide](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents).
+
+## Gotchas
+
+- Assertions written before observing output are almost always wrong — run
+  the eval first, observe actual output, THEN write assertions
+- Near-miss negative test cases are the most valuable — prompts that share
+  keywords with should-trigger cases but need a different skill entirely
+- Select the best skill iteration by validation pass rate, not the last one
+- Grade outcomes, not execution paths — if the agent solved the task via an
+  unexpected route but produced correct output, that is a pass
+- Same skill can behave differently across agent frameworks — test on each
+  target agent (Claude Code, Hermes, OpenClaw, Codex)
+
+## Procedure
+
+### Step 1: Choose eval scope
+
+Determine what you are evaluating:
+
+- **Description triggering** — does the agent activate the right skill for
+  a given prompt? Tests the description field effectiveness.
+- **Output quality** — does the skill produce correct results when activated?
+  Tests the skill body and references.
+- **Convention compliance** — does the output follow Plastic conventions?
+  Read `references/convention-checks.md` for the full assertion library.
+
+Multiple scopes can apply to the same skill. Start with the scope that
+addresses your immediate concern, add others as needed.
+
+### Step 2: Design test cases
+
+Create `evals/evals.json` in the skill being evaluated. Copy the starter
+template from `assets/eval-template.json` in this skill.
+
+**For description triggering:**
+- Write ~20 queries: 8-10 should-trigger, 8-10 should-not-trigger
+- Split 60/40 into train and validation sets (proportional mix in each)
+- Include near-miss negatives that share keywords but need a different skill
+- In `expected_output`, describe whether the skill should or should not activate
+  and why
+
+**For output quality:**
+- Start with 2-3 test cases, expand after first results
+- Use realistic user prompts with varied phrasing, detail level, and formality
+- In `expected_output`, describe what correct output looks like — not exact text
+- Use `files` array for any input files the test needs
+
+**For convention compliance:**
+- Start with 2-3 test cases targeting specific convention areas
+- In `expected_output`, describe which conventions must be met
+- Read `references/convention-checks.md` for the full assertion library
+
+Leave `assertions` arrays empty. They are populated after Step 4.
+
+### Step 3: Run paired evals
+
+Dispatch a subagent per test case to ensure clean context — no leakage
+between test runs. Run each case twice:
+
+1. **With skill** — the skill is available and loaded
+2. **Without skill** — the skill is not available (baseline comparison)
+
+The delta between with-skill and without-skill measures what the skill adds.
+If the delta is negligible, the skill may not be adding value for that case.
+
+Grade outcomes, not paths. An unexpected tool-call sequence that produces
+correct output is still a pass.
+
+### Step 4: Write assertions after observing
+
+Review actual outputs from Step 3. Write specific, verifiable assertions
+based on what you observed — not what you expected beforehand.
+
+Choose the grader type that fits each assertion:
+- **Code-based** — structure, file existence, format validity, counts
+- **LLM-as-judge** — quality, completeness, tone, semantic correctness
+- **Human** — edge cases, calibration, judgment calls
+
+Read `references/eval-methodology.md` for the full grader taxonomy and
+LLM-judge calibration protocol.
+
+Good assertions are specific, verifiable, and countable:
+"Output includes at least 3 concrete recommendations."
+
+Weak assertions are vague: "Output is good."
+Brittle assertions use exact phrase matching.
+
+Require concrete evidence for PASS. No benefit of the doubt.
+
+### Step 5: Grade and iterate
+
+Compute pass rates per test case and aggregate across the eval suite.
+
+Track two metrics separately:
+- **pass@k** — succeeded at least once in k trials (capability)
+- **pass^k** — succeeded every time in k trials (reliability)
+
+Read `references/eval-methodology.md` for formulas and interpretation.
+
+Three signal sources for skill improvement:
+1. **Failed assertions** — specific gaps in the skill
+2. **Human feedback** — broader quality issues not captured by assertions
+3. **Execution transcripts** — reveals WHY things went wrong
+
+Feed all three plus the current SKILL.md to propose targeted changes.
+Iterate on the train set only. Check the validation set for generalization.
+5 iterations is usually enough. If not improving after 5, the test cases
+themselves may be the problem — revisit Step 2.
+
+### Step 6: Graduate and monitor
+
+Once a skill hits ~100% on capability evals (pass@k = 1.0 for 3+
+consecutive runs):
+
+1. **Graduate** capability evals into regression tests — run them on every
+   skill change to protect against backsliding
+2. **Monitor** the with/without delta over time — if it shrinks to zero
+   across 3+ runs, the model may have internalized the skill
+3. **Retire** cautiously — archive the skill, do not delete. Re-test after
+   model updates in case capabilities regress.
+
+Read `references/eval-methodology.md` for graduation criteria, retirement
+detection, and the three-layer eval taxonomy.

package/skills/evaluating-skills/assets/eval-template.json

@@ -0,0 +1,12 @@
+{
+  "skill_name": "",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "",
+      "expected_output": "",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}

package/skills/evaluating-skills/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill_name": "evaluating-skills",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to evaluate whether my creating-intent skill follows Plastic conventions",
+      "expected_output": "The skill should activate and guide the user through convention compliance evaluation: choose eval scope, design test cases using convention-checks reference, run paired evals, write assertions after observing.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run evals on the brainstorming skill to see if the description triggers correctly",
+      "expected_output": "The skill should activate and guide through description triggering evaluation: design ~20 queries with should-trigger and near-miss negatives, 60/40 train/validation split, compute trigger rates.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 3,
+      "prompt": "Create evals for a new skill I just wrote for database migrations",
+      "expected_output": "The skill should activate, help create evals/evals.json in the migration skill directory using the template, guide through choosing eval scope (likely output quality), and design initial test cases.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 4,
+      "prompt": "Check if my SKILL.md is under the token budget and follows progressive disclosure",
+      "expected_output": "The skill should activate and guide through convention compliance evaluation focused on progressive disclosure checks: body under 500 lines/5000 tokens, references have conditional triggers, description under 1024 chars.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 5,
+      "prompt": "My skill's description isn't triggering on the right prompts, how do I fix it?",
+      "expected_output": "The skill should activate and guide through description triggering evaluation: create should-trigger and should-not-trigger queries, run paired evals, measure trigger rate, iterate on description wording.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 6,
+      "prompt": "Write unit tests for my Ruby model that validates email addresses",
+      "expected_output": "The skill should NOT trigger. This is a code testing task, not a skill evaluation task. Near-miss negative — shares 'test' keyword but needs a different skill.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 7,
+      "prompt": "Fix the bug in my login controller where sessions aren't persisting",
+      "expected_output": "The skill should NOT trigger. This is a debugging task with no relation to skill evaluation.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 8,
+      "prompt": "Review this pull request for code quality issues",
+      "expected_output": "The skill should NOT trigger. Code review is different from skill evaluation. Near-miss negative — shares 'review/evaluate' concept.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 9,
+      "prompt": "I updated my skill and want to make sure it still works correctly",
+      "expected_output": "The skill should activate and guide through regression evaluation: run existing evals against the updated skill, compare pass rates with previous version, check for backsliding.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 10,
+      "prompt": "How do I know if a skill is still needed or if the model has learned the behavior?",
+      "expected_output": "The skill should activate and guide through skill retirement detection: monitor with/without delta over time, if delta approaches zero the model has internalized the skill.",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}

package/skills/evaluating-skills/references/convention-checks.md

@@ -0,0 +1,76 @@
+# Plastic Convention Checks
+
+Assertion library for convention compliance evals on Plastic skills.
+Load when running convention compliance evals on a Plastic skill.
+
+## Directory Structure
+
+| Check | Pass criteria |
+|-------|--------------|
+| SKILL.md exists | File present at skill root |
+| Name matches directory | `name` in frontmatter equals directory name |
+| Standard directories only | Only scripts/, references/, assets/, evals/ at root level (all optional) |
+| References one level deep | No nested directories inside references/ |
+| No orphan files | Every file in the skill dir is referenced from SKILL.md or another skill file |
+| evals/ has evals.json | If evals/ exists, it contains evals.json |
+
+## Frontmatter
+
+| Check | Pass criteria |
+|-------|--------------|
+| `name` present | Non-empty, 1-64 chars |
+| `name` format | Lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens |
+| `name` matches dir | Exact match with skill directory name |
+| `description` present | Non-empty, 1-1024 chars |
+| `description` phrasing | Starts with imperative verb or "Use when" pattern |
+| `description` triggers | Mentions at least one trigger context ("Use when...") |
+| `description` edge cases | Includes at least one indirect trigger (user doesn't name the domain) |
+| No unknown required fields | Only uses fields from agentskills.io spec: name, description, license, compatibility, metadata, allowed-tools |
+
+## Progressive Disclosure
+
+| Check | Pass criteria |
+|-------|--------------|
+| Body line count | SKILL.md body (excluding frontmatter) under 500 lines |
+| Body token count | SKILL.md body under 5000 tokens (estimate: lines * 10) |
+| Deep detail in references | Content exceeding activation budget lives in references/ |
+| Conditional reference triggers | Every reference file mentioned in SKILL.md has a "when" condition |
+| No generic references | No "see references/ for more" — each reference has specific load trigger |
+| Description token budget | Description stays under ~100 tokens for discovery stage |
+
+## Content Quality
+
+| Check | Pass criteria |
+|-------|--------------|
+| Gotchas are concrete | Each gotcha is a specific correction, not general advice |
+| Gotchas positioned early | Gotchas section appears before or near the top of procedures |
+| Defaults, not menus | Skill picks one approach; alternatives mentioned briefly if at all |
+| Procedures over declarations | Instructions teach HOW to approach, not WHAT to produce |
+| Reasoning over rigid directives | Uses "Do X because Y" pattern, not "ALWAYS/NEVER" without rationale |
+| No redundant knowledge | Every instruction passes "would the agent get this wrong without it?" |
+| No explaining basics | Does not explain HTTP, JSON, what a migration is, etc. |
+
+## Eval Quality (when evals/ exists)
+
+| Check | Pass criteria |
+|-------|--------------|
+| Standard format | evals.json follows agentskills.io eval structure |
+| Prompts are realistic | Each prompt reads like a real user message |
+| Varied phrasing | Prompts use different wording, detail levels, formality |
+| Near-miss negatives | At least 2 should-not-trigger cases that share keywords |
+| Expected output descriptive | expected_output describes success, not exact text |
+| Assertions (if populated) | Each assertion is specific, verifiable, and countable |
+
+## Intent Structure (when evaluating intent compliance)
+
+| Check | Pass criteria |
+|-------|--------------|
+| Intent file exists | `{ID}--{slug}.md` present in intent directory |
+| Frontmatter complete | id, intent, sources, chain, created, author, tags present |
+| ID format correct | Follows Luhmann alternating: digits and letters alternate |
+| Directory name matches | `{ID}--{slug}` format, 3-5 word slug |
+| Lifecycle artifacts | Present artifacts match the intent's lifecycle stage |
+| spec.md gate | plan.md only exists if spec.md exists |
+| plan.md gate | checklist.md only exists if plan.md exists |
+| outcome.md gate | outcome.md only exists if all checklist items checked |
+| Insights append-only | `## Insights` section only grows, never shrinks |

package/skills/evaluating-skills/references/eval-methodology.md

@@ -0,0 +1,154 @@
+# Evaluation Methodology
+
+Load when choosing a grader type, interpreting pass rate results, or deciding
+whether to graduate or retire evals.
+
+Sources: agentskills.io, Anthropic eval engineering, Tessl eval framework,
+Philipp Schmid skill testing guide.
+
+## Three-Tier Grader Taxonomy
+
+Layer graders like a Swiss cheese model — no single tier catches everything.
+Use the simplest grader that covers the assertion. Combine tiers for coverage.
+
+### Code-Based Graders
+
+Best for structural and mechanical checks:
+- File existence and correct path
+- JSON/YAML validity
+- Line count, character count, token budget
+- Regex pattern matching (frontmatter fields, required sections)
+- Exit codes from bundled scripts
+
+Use as the default tier. Fast, deterministic, reproducible.
+
+### LLM-as-Judge Graders
+
+Best for subjective quality and semantic checks:
+- "Does this description convey when to use the skill?"
+- "Are the gotchas concrete corrections, not general advice?"
+- "Does the output address the user's actual intent?"
+
+Calibration protocol:
+1. Write a natural-language rubric (not binary pass/fail)
+2. Run the judge on 10-15 cases where you already know the correct grade
+3. Compare judge grades to your grades — adjust rubric until >80% agreement
+4. Spot-check with human grading periodically (every 5th eval run)
+
+Rubric template:
+- PASS: [specific criteria with examples]
+- PARTIAL: [what partial credit looks like]
+- FAIL: [specific failure modes]
+
+### Human Graders
+
+Best for edge cases and final calibration:
+- Novel failure modes the other tiers miss
+- Calibration set for LLM judges
+- Final sign-off on graduating evals to regression
+
+Use sparingly — human grading doesn't scale. Reserve for calibration
+and cases where code + LLM judges disagree.
+
+## pass@k vs pass^k
+
+Two metrics that diverge dramatically. Always track both.
+
+### pass@k — Capability
+
+"Did it succeed at least once in k trials?"
+
+Formula: pass@k = 1 - (1 - p)^k where p = single-trial pass rate
+
+Measures: Can the skill/agent do this at all?
+
+Example at p=0.7, k=10: pass@k = 97.2%
+
+Use when: evaluating whether a skill enables a new capability,
+initial development, deciding whether to invest more iteration.
+
+### pass^k — Reliability
+
+"Did it succeed every time in k trials?"
+
+Formula: pass^k = p^k
+
+Measures: Will it always do this correctly?
+
+Example at p=0.7, k=10: pass^k = 2.8%
+
+Use when: evaluating production readiness, regression testing,
+deciding whether a skill is reliable enough to ship.
+
+### Interpreting the Gap
+
+| pass@k | pass^k | Interpretation |
+|--------|--------|----------------|
+| High | High | Reliable — ready for production |
+| High | Low | Capable but flaky — needs iteration on consistency |
+| Low | Low | Not yet capable — needs fundamental skill improvement |
+| Low | High | Impossible (pass^k <= pass@k always) |
+
+Run k=3 minimum for meaningful results. k=5 for production decisions.
+
+## Capability-to-Regression Graduation
+
+Track pass rates across iterations. When a capability eval consistently
+hits ~100% (pass@k=1.0 for 3+ consecutive runs):
+
+1. Graduate the eval from "capability" to "regression"
+2. Regression evals run on every skill change — they protect against backsliding
+3. If a regression eval starts failing, the recent change broke something
+4. Investigate the failing regression before iterating further
+
+Graduation is one-way. Once an eval is regression, it stays regression
+unless the underlying requirement changes.
+
+## Skill Retirement Detection
+
+Monitor the with/without skill delta over time:
+
+1. Run paired evals (with-skill vs without-skill) periodically
+2. Compute the delta in pass rates
+3. If delta shrinks to near-zero across 3+ consecutive runs:
+   - The model has likely internalized the skill's knowledge
+   - The skill may be ready for retirement
+4. Before retiring: run one final full eval suite to confirm
+5. Archive the skill (don't delete — may need to restore if model changes)
+
+Common cause of false retirement signals: model update changed capabilities.
+Re-test after model updates.
+
+## Tessl Three-Layer Eval Taxonomy
+
+Three layers of increasing realism. Each catches failures the others miss.
+
+### Layer 1: Skill Review (Structural Lint)
+
+Does the skill itself follow best practices?
+- SKILL.md structure (frontmatter, sections, length)
+- Description quality (imperative, user-intent, trigger keywords)
+- Reference organization (conditional triggers, one level deep)
+- Convention compliance (for Plastic skills, see convention-checks.md)
+
+Fast, cheap, runs without executing the skill.
+
+### Layer 2: Task Evals (Synthetic)
+
+Does the skill improve agent output on synthetic tasks?
+- Paired with/without comparison
+- Controlled prompts with known-good expected outputs
+- Measures the delta the skill adds
+
+This is the core eval loop (Steps 2-5 in the SKILL.md procedure).
+
+### Layer 3: Repo Evals (Real Codebase)
+
+Does the skill work correctly in a real project context?
+- Install the skill in a real repository
+- Run real tasks (not synthetic prompts)
+- Measure whether the agent uses the skill correctly in situ
+
+Most expensive, most realistic. Catches skills that pass synthetic tests
+but fail under real project complexity. Use for high-stakes skills
+or before shipping to users.

package/skills/executing-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:executing-plan
+name: plastic-executing-plan
 description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
 ---
 
@@ -70,11 +70,12 @@ After all tasks complete, dispatch a final reviewer for the entire implementatio
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -95,11 +96,12 @@ For each task:
 ### Step 3: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/install/SKILL.md

@@ -1,22 +1,64 @@
 ---
-name: plastic:install
-description: Use when initializing Plastic globally (~/.plastic/) or locally in a project. Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+name: plastic-install
+description: Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. Default is --latest (stable). Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
 ---
 
 # Install Plastic
 
+> **Recommended path:** for a first install, run `npx @zalom/plastic@latest install --claude`
+> in your shell (or `bunx @zalom/plastic@latest --claude` if you use Bun). This skill
+> exists to **re-install or repair** an existing setup from inside the agent, and to
+> drive interactive global configuration. Whenever this skill performs an install or
+> re-install, it **runs `/plastic-doctor` afterward** and reports the result.
+
+## Re-install / repair
+
+If Plastic is already installed but something is broken (skills missing, hooks not
+firing, leftover legacy plugin), re-run the installer — it is idempotent, prunes
+files that no longer ship, and removes any legacy plugin/marketplace layout:
+
+```bash
+npx @zalom/plastic@latest install --reinstall --claude   # or @beta / @alpha to match your channel
+```
+
+Then **run `/plastic-doctor`** and report what it found.
+
+## Channel Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--latest` | Install from stable channel (default) |
+| `--beta` | Install from beta channel |
+| `--alpha` | Install from alpha channel |
+
+When invoked from within Claude Code (re-install or channel switch), the skill
+runs the appropriate npx command:
+
+```bash
+# Stable (default)
+npx @zalom/plastic install --claude
+
+# Beta
+npx @zalom/plastic@beta install --claude
+
+# Alpha
+npx @zalom/plastic@alpha install --claude
+```
+
+The installed version and channel are recorded in `~/.plastic/VERSION`.
+
 ## Modes
 
 ### Global Install (default, recommended)
 
-Run `/plastic:install` with no arguments.
+Run `/plastic-install` with no arguments.
 
 #### Procedure
 
 **Step 1: Check for existing installation**
 
 Check if `~/.plastic/INDEX.md` exists.
-- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic:update` to sync core files."
+- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic-update` to sync core files."
 - If no: proceed with fresh install.
 
 **Step 2: Create ~/.plastic/ as a git repo**
@@ -106,13 +148,32 @@ Update `config.yml` with any additional roots.
 
 Auto-commit the config change.
 
-**Step 4: Announce**
+**Step 4: Verify with doctor**
+
+Run `/plastic-doctor` and report the result. Resolve any fixable findings before
+announcing success.
+
+**Step 5: Register stores with QMD (optional)**
+
+QMD is an optional search layer. If it is installed, register the Plastic stores so
+they are searchable:
+
+```bash
+ruby ~/.plastic/scripts/qmd-sync detect && ruby ~/.plastic/scripts/qmd-sync register --all
+```
+
+`qmd-sync` no-ops cleanly when QMD is absent, so this is safe to run unconditionally.
+It registers `plastic-global` and every project store from `projects.yml`, then indexes
+them. Report what was registered, or that QMD was not detected and the step was skipped.
+
+**Step 6: Announce**
 
-> "Plastic installed globally at ~/.plastic/. Create your first intent with `/plastic:creating-intent`."
+> "Plastic installed globally at ~/.plastic/. Health check: [doctor summary].
+> Create your first intent with `/plastic-creating-intent`."
 
 ### Local Install (testing/legacy)
 
-Run `/plastic:install --local`.
+Run `/plastic-install --local`.
 
 #### Procedure
 
@@ -131,4 +192,4 @@ Run `/plastic:install --local`.
 
 **Step 4:** Commit in project: `git add .plastic/ && git commit -m "chore: initialize Plastic local store"`
 
-**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic:install` for global mode."
+**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic-install` for global mode."

package/skills/intent-curator/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:intent-curator
+name: plastic-intent-curator
 description: |
   Use when completing or reviewing intents, reorganizing the index,
   or when the intent store needs maintenance. Examples:
@@ -15,7 +15,7 @@ description: |
 
 # Intent Curator
 
-Dispatches to the `plastic:intent-curator` agent for intent store maintenance.
+Dispatches to the `plastic-intent-curator` agent for intent store maintenance.
 
 ## When to Use
 - Completing or reviewing intents
@@ -25,7 +25,7 @@ Dispatches to the `plastic:intent-curator` agent for intent store maintenance.
 
 ## Workflow
 
-Invoke the `plastic:intent-curator` agent via the Agent tool with `subagent_type: "plastic:intent-curator"`. Pass the user's request as the prompt, including:
+Invoke the `plastic-intent-curator` agent via the Agent tool with `subagent_type: "plastic-intent-curator"`. Pass the user's request as the prompt, including:
 
 1. **What to do** — complete intent, reorganize, triage stale, etc.
 2. **Which store** — global (`~/.plastic/`) or project (`.plastic/store/`)
@@ -33,9 +33,11 @@ Invoke the `plastic:intent-curator` agent via the Agent tool with `subagent_type
 
 The agent handles:
 - Intent lifecycle management (status transitions, Outcome sections)
-- INDEX.md maintenance (Active/Future/Clusters/Completed sections)
+- INDEX.md maintenance (Active/Future/Clusters/Completed/Abandoned sections)
 - Link discovery between related intents
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+When an intent reaches a terminal state — moved to Completed OR Abandoned — refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+
 After the agent completes, report what changed.

package/skills/intent-curator/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-intent-curator",
+  "notes": "Intent 66a. Spec for the QMD-first discovery step in agents/plastic-intent-curator.md (locate a specific intent before grep/find; distinct from the completion-time reindex step). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: find and reclassify the intent about orphan detection.",
+      "expected_output": "During discovery (How You Work), before scanning the store with grep/find to locate the intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"orphan detection\"` to surface the candidate or related intents, then opens the authoritative intent file for the hit it acts on. This discovery step is distinct from the completion-time reindex step. No-op fallback to the full scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/find during discovery; authoritative file opened for the hit; reindex step stays separate",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}