@zalom/plastic 1.0.0-beta.4 → 1.0.0-beta.5

package/agents/plastic-intent-curator.md

@@ -26,15 +26,17 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 
 ## How You Work
 
+0. QMD-first (when available): when you need to locate a specific intent (to reclassify, link, or cluster it) rather than rebuild the whole landscape, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate or related intents, then open the authoritative intent file for any hit you act on. The command is a no-op when QMD is absent, so fall back to the full scan below. (This is discovery; the reindex step at completion is separate.)
 1. Scan `~/.plastic/store/*/ID--slug.md` (or project store) to understand the full intent landscape
 2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
 3. Compare: are there intents not in any cluster? Missing from Active/Completed? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
-5. Report what you changed
+5. On completion: whenever you move an intent to Completed, refresh the QMD index for that store so the new outcome is searchable. This is mandatory on completion and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
+6. Report what you changed
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
 - You never create new intents — that's the creating-intent skill's job
 - You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
-- You use Read and grep/find for discovery, Edit for targeted changes
+- For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

package/package.json

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

package/scripts/lib/power_tools.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "qmd_sync"
+
+# PowerTools — detect-then-degrade harness for Plastic's optional power-tools
+# (intent 66b). It owns deterministic detection of each tool and builds an
+# obligation ("mandate") string for whichever tools are present, so the agent is
+# obliged (not merely reminded) to use them: QMD for finding intents, Serena for
+# code navigation.
+#
+# Strictly detect-then-degrade: a tool that is absent contributes nothing, and
+# `mandate` returns nil when no tool is present. Nothing here installs anything.
+#
+# Pure and dependency-injected: every detection runs through an injected callable
+# or keyword probe (PATH scan / `.serena` marker walk), so the whole module is
+# unit-testable with no real binaries, no network, and no global/ENV state.
+module PowerTools
+  module_function
+
+  # True when QMD is present. Reuses QmdSync.detect (PATH probe), injectable.
+  def qmd?(detector: QmdSync.method(:detect))
+    !!detector.call
+  end
+
+  # True when Serena is present: a `.serena` directory exists in cwd or any
+  # ancestor, OR `serena` is resolvable on PATH. Both probes are injectable so
+  # tests do not depend on the host having Serena installed.
+  def serena?(cwd:, path_probe: method(:which_serena), marker_finder: method(:serena_marker?))
+    return true if marker_finder.call(cwd)
+    !!path_probe.call
+  end
+
+  # True when `serena` is an executable on PATH. Mirrors QmdSync.which_qmd.
+  def which_serena
+    ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+      candidate = File.join(dir, "serena")
+      File.file?(candidate) && File.executable?(candidate)
+    end
+  end
+
+  # Walk up from cwd to the filesystem root, returning true if any level holds a
+  # `.serena` directory.
+  def serena_marker?(cwd)
+    dir = File.expand_path(cwd)
+    loop do
+      return true if Dir.exist?(File.join(dir, ".serena"))
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    false
+  end
+
+  # Obligation text for whichever tools are present, joined by newlines, or nil
+  # when none are. One MANDATORY line per present tool.
+  def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
+    lines = []
+
+    if qmd?(detector: qmd_detector)
+      lines << "MANDATORY: you MUST use QMD (`qmd search` / `qmd query` over the " \
+               "`plastic-*` collections) to check for an existing or related intent " \
+               "before treating this as new work; do not grep/Read the store first."
+    end
+
+    serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
+    if serena_present
+      lines << "MANDATORY: you MUST use Serena's symbolic tools (find_symbol / " \
+               "get_symbols_overview / find_referencing_symbols) for code navigation " \
+               "before grep/Read."
+    end
+
+    return nil if lines.empty?
+    lines.join("\n")
+  end
+end

package/scripts/lib/qmd_hook.rb

@@ -2,43 +2,56 @@
 # frozen_string_literal: true
 
 require_relative "qmd_sync"
+require_relative "power_tools"
 
-# QmdHook — decision logic for the qmd-first UserPromptSubmit hook (intent 66).
-# Pure and dependency-injected: returns the additionalContext string to emit, or
-# nil to emit nothing. The executable hook wires real deps and prints; this is
-# unit-tested with a fake runner/detector (no real qmd, no network).
+# QmdHook — decision logic for the power-tools UserPromptSubmit hook (intents 66,
+# 66b). Pure and dependency-injected: returns the additionalContext string to
+# emit, or nil to emit nothing. The executable hook wires real deps and prints;
+# this is unit-tested with a fake runner/detector (no real qmd, no network).
+#
+# When qmd is present it still injects scored qmd hits (intent 66), then appends
+# the PowerTools mandate (a MUST obligation per present tool: qmd for finding
+# intents, serena for code navigation) instead of the old soft reminder.
 module QmdHook
   module_function
 
   MIN_PROMPT_LENGTH = 10
-  REMINDER = "qmd is available: query it (`qmd search` / `qmd query` over the " \
-             "`plastic-*` collections) before grep/Read when gathering intent " \
-             "context (sources/chain) or checking whether this work already " \
-             "exists as an intent."
 
   def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
-          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5)
-    return nil unless detector.call
-    p = prompt.to_s.strip
-    return nil if p.length < MIN_PROMPT_LENGTH
-    return nil if p.downcase == "continue"
+          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5,
+          serena_detector: nil)
+    serena_detector ||= -> { PowerTools.serena?(cwd: cwd) }
+    qmd_present = !!detector.call
+    serena_present = !!serena_detector.call
+    return nil unless qmd_present || serena_present
 
-    collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
-    hits = QmdSync.search(p, collections: collections, limit: limit,
-                          min_score: min_score, runner: runner, detector: detector)
+    p = prompt.to_s.strip
+    # The hit SEARCH is the only expensive step and the only one gated by prompt
+    # triviality: skip it for short or bare-"continue" prompts (and when qmd is
+    # absent). The mandate itself is always-on for whichever tools are present.
+    search_ok = qmd_present && p.length >= MIN_PROMPT_LENGTH && p.downcase != "continue"
 
     parts = []
-    if hits.any?
-      parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
-               "check before treating this as new work:"
-      hits.each do |h|
-        loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
-        pct = (h[:score] * 100).round
-        parts << "- [#{pct}%] #{loc} — #{h[:title]}"
+    if search_ok
+      collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
+      hits = QmdSync.search(p, collections: collections, limit: limit,
+                            min_score: min_score, runner: runner, detector: detector)
+      if hits.any?
+        parts << "Related / prior Plastic intents (qmd BM25, includes completed) — " \
+                 "check before treating this as new work:"
+        hits.each do |h|
+          loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
+          pct = (h[:score] * 100).round
+          parts << "- [#{pct}%] #{loc} — #{h[:title]}"
+        end
+        parts << ""
       end
-      parts << ""
     end
-    parts << REMINDER
+
+    mandate = PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
+                                 serena_detector: -> { serena_present })
+    parts << mandate if mandate
+    return nil if parts.empty?
     parts.join("\n")
   end
 end

package/scripts/lib/qmd_sync.rb

@@ -99,6 +99,27 @@ module QmdSync
     { ran: true, ok: (ok1 && ok2) }
   end
 
+  # Non-blocking reindex for the completion path. QMD has no incremental reindex
+  # (`qmd update` is a full rescan, `qmd embed -c` re-embeds the whole collection,
+  # ~2 min), so running it inline would block the agent's turn; spawning detached
+  # returns immediately. No-op when qmd absent. Spawner/detector are injected so
+  # tests assert behavior with no real qmd and no real spawned process.
+  def reindex_async(collection:, detector: method(:detect), spawner: method(:default_async_spawner))
+    return skip_result unless detector.call
+    pid = spawner.call(collection)
+    { ran: true, async: true, pid: pid }
+  end
+
+  # Default spawner: launch `qmd update && qmd embed -c <collection>` detached and
+  # non-blocking, discarding output, then detach so it never blocks the turn.
+  def default_async_spawner(collection)
+    require "shellwords"
+    cmd = "qmd update && qmd embed -c #{Shellwords.escape(collection)}"
+    pid = Process.spawn(cmd, out: File::NULL, err: File::NULL, pgroup: true)
+    Process.detach(pid)
+    pid
+  end
+
   # Read-only status used by doctor and the session-start report line.
   # Returns a structured hash; never mutates the index.
   def status(plastic_home:, runner: default_runner, detector: method(:detect))

package/scripts/qmd-sync

@@ -13,7 +13,10 @@
 #   qmd-sync register --store <dir>     # register one store as a collection
 #   qmd-sync register --all             # register the global store + all projects
 #   qmd-sync reindex --store <dir>      # update + embed that store's collection
+#   qmd-sync reindex --store <dir> --async  # same, detached/non-blocking
 #   qmd-sync status [--format json]     # read-only status
+#   qmd-sync search "<terms>" [--store <dir>] [--limit N] [--min-score F]
+#                                       # ranked store search; scope by --store or CWD
 #
 # --home <path> overrides the Plastic home (default: ~/.plastic).
 
@@ -71,8 +74,13 @@ when "register"
 when "reindex"
   dir = opt(ARGV, "--store") or (warn("reindex: pass --store <dir>"); exit 2)
   collection = QmdSync.collection_name(dir, plastic_home: home)
-  res = QmdSync.reindex(collection: collection)
-  puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  if ARGV.include?("--async")
+    QmdSync.reindex_async(collection: collection)
+    puts "reindex (async) #{collection} (started)"
+  else
+    res = QmdSync.reindex(collection: collection)
+    puts "reindexed #{collection} (#{res[:ok] ? "ok" : "warn"})"
+  end
   exit 0
 
 when "status"
@@ -86,7 +94,46 @@ when "status"
   end
   exit 0
 
+when "search"
+  # The query is the first bareword that is NOT the value of a known value-taking
+  # flag. Walk ARGV, skipping each such flag and the token right after it, then
+  # take the first remaining token that does not start with "--".
+  value_flags = %w[--store --limit --min-score --home]
+  query = nil
+  i = 0
+  while i < ARGV.length
+    tok = ARGV[i]
+    if value_flags.include?(tok)
+      i += 2
+      next
+    end
+    unless tok.start_with?("--")
+      query = tok
+      break
+    end
+    i += 1
+  end
+  collections =
+    if (dir = opt(ARGV, "--store"))
+      [QmdSync.collection_name(dir, plastic_home: home), "plastic-global"].uniq
+    else
+      QmdSync.collections_for_cwd(Dir.pwd, plastic_home: home)
+    end
+  limit = (opt(ARGV, "--limit") || "5").to_i
+  min_score = (opt(ARGV, "--min-score") || "0.5").to_f
+  hits = QmdSync.search(query, collections: collections, limit: limit, min_score: min_score)
+  if hits.empty?
+    puts "no qmd hits"
+  else
+    hits.each do |h|
+      pct = (h[:score] * 100).round
+      path = h[:file].to_s.sub(%r{\Aqmd://}, "")
+      puts "[#{pct}%] #{path} - #{h[:title]}"
+    end
+  end
+  exit 0
+
 else
-  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status."
+  warn "qmd-sync: unknown verb #{verb.inspect}. Use detect|register|reindex|status|search."
   exit 2
 end

package/skills/auto/SKILL.md

@@ -28,6 +28,13 @@ Work `dispatchable_queue` in `rank` order (these are `defer`/`research` disposit
 safe to deliver autonomously). Leave `human_only` and `next_big_thing` for the user — those
 are `drive`/`triage` items the human should lead. See the `plastic-dashboard` skill.
 
+QMD-first (when available): when the user describes the work to deliver rather than naming an
+intent, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
+intents, then open the authoritative intent file for the hit you take over. The command is a no-op
+when QMD is absent, so fall back to the existing INDEX.md / file scan. (This is discovery; the
+reindex step under Completion is separate.)
+
 ## Arm the Lifecycle Gate (do this FIRST)
 
 Immediately after selecting the intent — before any other work — arm auto mode. This
@@ -186,11 +193,12 @@ During initial project creation, all decisions are non-destructive by definition
    - Update `chain` in the current intent's frontmatter
 6. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. Refresh the QMD search index for this store (optional, no-op when QMD is absent):
+8. On completion, ALWAYS 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:
    ```bash
-   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
    ```
-   Delivery is the lifecycle event that keeps the search index fresh. `<store-root>` is the
+   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).
 9. Disarm the lifecycle gate (auto delivery is finished):
    ```bash

package/skills/auto/evals/evals.json

@@ -202,6 +202,54 @@
           "result": "pass"
         }
       ]
+    },
+    {
+      "id": 12,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "A power-tool is present (qmd on PATH, or a .serena marker / serena on PATH). A substantive prompt arrives in auto mode.",
+      "expected_output": "The UserPromptSubmit power-tools hook appends a MANDATORY obligation per present tool: a MUST-use-QMD line when qmd is present (to check for an existing or related intent before treating work as new), and a MUST-use-Serena line when serena is present (symbolic tools before grep/Read). QMD hits are still injected when above threshold.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns MUST/MANDATORY lines for each present tool; QmdHook.run appends the mandate",
+          "observed": "power_tools_test.rb + qmd_hook_test.rb assert MUST wording; serena line gated on the serena detector",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Neither qmd nor serena is present (no qmd on PATH, no .serena marker, no serena on PATH). A substantive prompt arrives.",
+      "expected_output": "Detect-then-degrade: the hook emits nothing (silent no-op, exit 0). No mandate text appears. Nothing is required to install.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns nil and QmdHook.run returns nil when neither tool is present",
+          "observed": "power_tools_test.rb test_mandate_neither_is_nil + qmd_hook_test.rb test_nil_when_neither_tool_present",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. In auto mode the user says: deliver the work on the uploader retry policy (no intent id given).",
+      "expected_output": "Before scanning the store with grep/Read to find the matching intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"uploader retry policy\"` to surface the candidate intent, then opens the authoritative intent file for the hit it takes over. This discovery step is distinct from the completion-time reindex step. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read 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"
+        }
+      ]
     }
   ]
 }

package/skills/brainstorming/SKILL.md

@@ -74,6 +74,7 @@ digraph brainstorming {
 ## The Process
 
 **Understanding the idea:**
+- QMD-first (when available): before scanning the store with grep/Read for prior decisions, specs, or outcomes, run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents, then open the authoritative intent file for any hit you act on. The command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
 - Check out the current project state first (files, docs, recent commits)
 - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
 - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.

package/skills/brainstorming/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-brainstorming",
+  "notes": "Intent 66a. Spec for the QMD-first step in the Why/explore-context phase (surface prior decisions/specs/outcomes before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. Brainstorming the active intent during the Why phase, the agent needs prior decisions and specs on caching.",
+      "expected_output": "In the explore-project-context (Why) step, before scanning the store with grep/Read, runs `ruby ~/.plastic/scripts/qmd-sync search \"caching decisions\"` to surface prior decisions, specs, or outcomes, then opens the authoritative intent file for any hit it acts on. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run during Why before grep/Read; authoritative file opened for any hit",
+          "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"
+        }
+      ]
+    }
+  ]
+}

package/skills/continuing/SKILL.md

@@ -54,7 +54,14 @@ intents. Do not start executing work. The branches below are the only follow-ups
 ## Conditional Ledger-Resume
 
 Fires ONLY when the user explicitly asks to continue a SPECIFIC intent, or an agent is
-instructed to continue one. It is not part of every boot. For that intent's directory:
+instructed to continue one. It is not part of every boot.
+
+QMD-first (when available): when the user names the intent by description rather than id, before
+scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to
+surface the candidate intent, then open the authoritative intent file for the hit you resume. The
+command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
+
+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 =

package/skills/continuing/evals/evals.json

@@ -131,6 +131,15 @@
       "assertions": [
         { "type": "convention", "check": "Determine Store step 2 documents local/project store detection via projects.yml + CWD match", "observed": "filled", "result": "pass" }
       ]
+    },
+    {
+      "id": 15, "scope": "behavior", "set": "validation",
+      "prompt": "QMD is present. The user says: continue the work on the statusline coloring (names the intent by description, not id).",
+      "expected_output": "Before scanning the store with grep/Read to locate the named intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"statusline coloring\"` to surface the candidate intent, then opens the authoritative intent file for the hit it resumes. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": ["skills/continuing/SKILL.md"],
+      "assertions": [
+        { "type": "human", "check": "qmd-sync search is run before grep/Read when the intent is named by description; authoritative file opened for the hit", "observed": "Conditional Ledger-Resume 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" }
+      ]
     }
   ]
 }

package/skills/creating-intent/SKILL.md

@@ -41,6 +41,14 @@ When creating a tactical intent in a project store:
 - **Global:** `~/.plastic/store/`
 - **Project:** `~/.plastic/projects/{slug}/store/`
 
+### 1b. Check for a Duplicate or Predecessor (QMD-first)
+
+QMD-first (when available): before scanning the store with grep/Read, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
+intents, then open the authoritative intent file for any hit you act on. The command is a no-op
+when QMD is absent, so fall back to the existing INDEX.md / file scan. Do this before allocating
+the id so a near-duplicate can be reused and a true predecessor can be set in `--sources`.
+
 ### 2. Decide Branch vs Root
 
 Decide this BEFORE scaffolding, because it sets whether you pass `--parent`.

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

@@ -51,6 +51,22 @@
           "result": "pass"
         }
       ]
+    },
+    {
+      "id": 3,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: create an intent to add retry to the uploader.",
+      "expected_output": "Before allocating the id / scaffolding, runs `ruby ~/.plastic/scripts/qmd-sync search \"add retry to the uploader\"` to surface a near-duplicate or true predecessor, then opens the authoritative intent file for any hit (reusing a near-duplicate or setting a real predecessor in --sources). No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before id allocation; authoritative file opened for any hit; informs reuse / --sources",
+          "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"
+        }
+      ]
     }
   ]
 }

package/skills/dashboard/SKILL.md

@@ -67,6 +67,11 @@ instead of showing it.
 
 ### Step 4 — Entry flow (the board is the menu)
 
+QMD-first (when available): when the user navigates by describing an intent rather than giving its
+id, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"`
+to surface the candidate intent, then open the authoritative intent file for the hit. The command is
+a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
+
 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

package/skills/dashboard/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-dashboard",
+  "notes": "Intent 66a. Spec for the QMD-first step in the entry flow (resolve a free-prose intent reference before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. On the board, the user navigates by describing an intent (the search verb work) instead of giving its id.",
+      "expected_output": "Before scanning the store with grep/Read to resolve the free-prose reference, runs `ruby ~/.plastic/scripts/qmd-sync search \"search verb\"` to surface the candidate intent, then opens the authoritative intent file for the hit. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read when the user navigates by description; authoritative file opened for the hit",
+          "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"
+        }
+      ]
+    }
+  ]
+}

package/skills/executing-plan/SKILL.md

@@ -75,7 +75,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 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. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+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.
 
@@ -101,7 +101,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 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. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+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/intent-curator/SKILL.md

@@ -38,4 +38,6 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+When an intent is moved to Completed, 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"
+        }
+      ]
+    }
+  ]
+}

package/skills/linking-intents/SKILL.md

@@ -41,6 +41,12 @@ tags: [plastic, project-reddit-kb]
 ## Workflow
 
 ### 1. Identify Intents to Connect
+
+QMD-first (when available): before scanning the store with grep/Read, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related
+intents to propose as sources/chain, then open the authoritative intent file for any hit you act
+on. The command is a no-op when QMD is absent, so fall back to the directory scan below.
+
 Show existing intents by scanning the store's directory for intent files:
 ```bash
 for dir in $STORE_ROOT/store/*/; do

package/skills/linking-intents/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-linking-intents",
+  "notes": "Intent 66a. Spec for the QMD-first discovery step (surface candidate/related intents to propose as sources/chain before grep/Read). Runner is intent 76; this case is a spec, not executed.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: link this intent to the related upload-pipeline work.",
+      "expected_output": "Before scanning the store directory with grep/Read to identify related intents, runs `ruby ~/.plastic/scripts/qmd-sync search \"upload pipeline\"` to surface candidate or related intents to propose as sources/chain, then opens the authoritative intent file for any hit it links. No-op fallback to the directory scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before the directory scan; authoritative file opened for any hit before proposing sources/chain",
+          "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"
+        }
+      ]
+    }
+  ]
+}

package/skills/managing-index/SKILL.md

@@ -43,6 +43,12 @@ All completed intents with dates. Links preserved, never deleted.
 
 ## Workflow
 
+QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or
+cluster it) rather than rebuild every section, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate or related intents, then
+open the authoritative intent file for any hit you act on. The command is a no-op when QMD is
+absent, so fall back to the directory scan below.
+
 ### Rebuild Sections
 Scan the active store's `store/` directory for intent files and rebuild each section:
 

package/skills/managing-index/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-managing-index",
+  "notes": "Intent 66a. Spec for the QMD-first step when locating a specific intent to reclassify/flag/cluster before grep/Read. Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: move the intent about the statusline into the Completed section.",
+      "expected_output": "When locating one specific intent rather than rebuilding every section, before scanning the store with grep/Read runs `ruby ~/.plastic/scripts/qmd-sync search \"statusline\"` to surface the candidate intent, then opens the authoritative intent file for the hit it reclassifies. No-op fallback to the directory scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before the directory scan when locating a specific intent; authoritative file opened for the hit",
+          "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"
+        }
+      ]
+    }
+  ]
+}

package/skills/research/SKILL.md

@@ -17,6 +17,14 @@ Before proceeding, resolve the active intent:
 2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic-creating-intent"
 3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
 
+## Check Prior Work First
+
+QMD-first (when available): before scanning the store with grep/Read or searching the web, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents
+and existing research, then open the authoritative intent file for any hit you act on. Reusing a
+prior report beats re-deriving it. The command is a no-op when QMD is absent, so fall back to the
+existing INDEX.md / file scan.
+
 ## Depth Decision
 
 Before starting research, assess the question against these criteria:

package/skills/research/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-research",
+  "notes": "Intent 66a. Spec for the QMD-first step before researching (reuse prior intents/reports before grep/Read or web search). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user asks the agent to research installer patterns for the active intent.",
+      "expected_output": "Before scanning the store with grep/Read or searching the web, runs `ruby ~/.plastic/scripts/qmd-sync search \"installer patterns\"` to surface candidate, prior, or related intents and existing research, then opens the authoritative intent file for any hit it reuses. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read and web search; authoritative file opened for any prior report reused",
+          "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"
+        }
+      ]
+    }
+  ]
+}