@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/skills/humanizer/references/examples.md

@@ -0,0 +1,48 @@
+# Examples - before and after
+
+Each pair shows a tell or a slop pattern, then the fix.
+
+## 1. Em-dash
+Before: The release is ready - we just need sign-off.
+After: The release is ready. We just need sign-off.
+Why: Use a full stop or comma, not an em-dash.
+
+## 2. "Not X but Y"
+Before: This is not just a config change, it's a rethink of the flow.
+After: This change reworks the flow.
+Why: State the point directly.
+
+## 3. Rule of three
+Before: The tool is fast, robust, and powerful.
+After: The tool is fast.
+Why: Drop the list-for-rhythm; keep the claim you can back.
+
+## 4. Hype / AI word
+Before: We leverage a comprehensive caching layer to unlock performance.
+After: We cache results to make it faster.
+Why: Plain verbs and nouns.
+
+## 5. Filler opener / signposting
+Before: It's worth noting that the cache expires after five minutes.
+After: The cache expires after five minutes.
+Why: Say the thing; skip the runway.
+
+## 6. Hedging pile-up
+Before: This might possibly help reduce cost in some cases, generally.
+After: This reduces cost.
+Why: One clear claim. Add a caveat only if it is real.
+
+## 7. Sycophancy
+Before: Great question! That's a really insightful point. Here's the answer.
+After: Here's the answer.
+Why: Drop the praise; answer.
+
+## 8. Structural fix (the mush)
+Before: There are several important considerations to keep in mind when thinking about how best to approach the broad and multifaceted topic of caching, each of which carries its own trade-offs.
+After: Cache reads, not writes. Reads repeat; writes do not.
+Why: One load-bearing point. Cut the restatement and the abstract throat-clearing.
+
+## 9. Over-bolding
+Before: **Note:** the cache **expires** after **five minutes**, so **always** check it.
+After: The cache expires after five minutes, so check it first.
+Why: Bold nothing here; the sentence carries itself.

package/skills/intent-curator/SKILL.md

@@ -33,9 +33,14 @@ 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 — do two things as the closing act of the transfer:
+
+1. Stamp the terminal savepoint bookend (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+2. 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

@@ -6,34 +6,70 @@ description: Use when creating connections between intents, the user says "link"
 # Linking Intents
 
 ## When to Use
-- During intent creation (automatic — ask about related intents)
+- During intent creation (automatic: ask about related intents)
 - User says "link", "connect", "relates to"
 - Agent discovers a relationship between intents during work
 
-## Connection Types (Ranked by Strength)
+## Discovery and ranking are separate
 
-### 1. Direct Links (Strongest)
-Explicit wikilinks in the `## Links` section. Bidirectional — add to both intents.
+Two distinct steps, do not conflate them:
 
-```markdown
-## Links
-- [[1a]] — research this plan is based on
-```
+1. **Discovery** (finding candidate related intents) may use any tool: grep, find, ripgrep,
+   or QMD/Serena when present (QMD-first per the project rule). Discovery casts a wide net.
+2. **Ranking** the candidates is a CONTEXT-INFLUENCE judgement: read each candidate's `## Intent`
+   and `## Context` and ask whether that context actually informed this intent. Ranking is NOT a
+   structural metric (no shared-file or shared-symbol grading: on intent 90, matching whole files
+   flagged 35 intents because ~20 touch `bridge.rb`). It is NOT a similarity score either (QMD
+   relevance measures topic proximity, not influence). A script cannot make this call; an agent
+   does.
+
+## The three tiers (by context influence)
+
+- **sources:** the foundational context that shaped this intent's CREATION (a split, an idea born
+  during development, a merge). Earns an edge. Decided by origin, never inferred.
+- **chain:** the context that materially helps DELIVER this intent. HIGH bar: only the genuinely
+  delivery-moving intents, not everything in the same area. Earns an edge, reflected in `## Links`.
+  Worked example (intent 90): 79 created it so 79 is a source; 80 deferred the exact fix 90 makes,
+  so its context directly helps delivery and 80 is chain; 49/66/73 are same-area background, so
+  they get a shared tag and no link.
+- **tags:** loose theme grouping for search. NOT a link.
+
+**Timing.** The influence judgement happens at What/Why (and during upkeep), guided by this rule.
+It does not wait for code to exist; it is reasoning over the candidate's context, not over a diff.
+
+**Record the call.** For every edge an agent adds, store a rating (high / medium / low) plus a
+one-line reason in `link-decisions.md` in the intent dir. Keep it out of frontmatter (graph only)
+and out of the `## Links` label (which is projected), so the audit trail never breaks the
+projection identity.
+
+## `## Links` is derived (never author it by hand)
 
-### 2. Sources (Backward)
+`## Links` is a DERIVED view of `sources` then `chain`, not a place to write links. Never
+hand-write a `## Links` line, and never auto-delete one. To add a link, add the frontmatter
+edge (below), then let the projection regenerate the section (`scripts/project-links`).
+
+Run `scripts/link-suggest <id>` to gather candidate intents WITH each one's Intent and Context (the
+evidence you judge influence on) and to flag drift (a `## Links` line with no frontmatter edge
+behind it). To record a confirmed edge plus its rating and reason, run it with
+`--record <id> --edge <sources|chain> --rating <high|medium|low> --reason "..." --confirm`. It never
+grades influence itself, never writes an edge without `--confirm`, and never deletes.
+
+## Connection Types (the frontmatter edges)
+
+### 1. Sources (Backward)
 The `sources` array in frontmatter. The direct ascendant(s) this intent was created from / emerged from the lifecycle of (formation, not topic similarity), backward links to the work it was built out of:
 ```yaml
 sources: ["1a", "1a2"]
 ```
 
-### 3. Chain (Forward)
+### 2. Chain (Forward)
 The `chain` array in frontmatter. What this intent spawned AND related-but-not-spawned successors it leads to, forward links to children, follow-on, and related work:
 ```yaml
 chain: ["1b1", "1b2"]
 ```
 
-### 4. Tags (Weakest)
-Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership.
+### 3. Tags (for discovery, not links)
+Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership. A shared tag is a loose theme grouping: it earns NO edge.
 ```yaml
 tags: [plastic, project-reddit-kb]
 ```
@@ -41,6 +77,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/linking-intents/references/zettelkasten.md

@@ -10,6 +10,13 @@ Plastic implements three Zettelkasten structures:
 
 INDEX.md is a structure note (hub), not a table of contents.
 
+`## Links` mirrors the frontmatter graph exactly. Each entry is
+`- [[id--slug|<target's full intent: text>]]` (cross-store: `- [[store:id--slug|...]]`),
+a clickable `id--slug` target with the target's full `intent:` text as the label.
+Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
+preserved within each group. Sources never appear at the end. No source/chain tags, no
+sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+
 ## Folgezettel IDs
 
 IDs encode lineage using Luhmann's alternating convention:

package/skills/managing-index/SKILL.md

@@ -41,8 +41,16 @@ Topic-based groupings. Manually curated. Create a new cluster when 3+ intents sh
 ### Completed
 All completed intents with dates. Links preserved, never deleted.
 
+When you move an intent INTO Completed or Abandoned, stamp the terminal savepoint bookend as the closing act of the transfer (intent 81), so the ledger's last line records the disposition: `ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.append_terminal_savepoint("<intent_dir>", "delivered")'` (use `"abandoned"` for an abandoned intent). Idempotent.
+
 ## 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/managing-index/references/zettelkasten-linking.md

@@ -8,7 +8,12 @@
 
 ## Three Connection Types (Ranked)
 
-1. **Direct links** (strongest) — wikilinks in `## Links` section
+1. **Direct links** (strongest): wikilinks in the `## Links` section, the projection of the
+   frontmatter graph. Each entry is `- [[id--slug|<target's full intent: text>]]` (cross-store:
+   `- [[store:id--slug|...]]`), a clickable `id--slug` target labeled with the target's full
+   `intent:` text. Ordering is mandatory: all `sources` first (top), then all `chain`,
+   frontmatter order preserved within each group. Sources never appear at the end. No
+   source/chain tags, no sub-grouping.
 2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See `docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
 3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
 

package/skills/releasing/SKILL.md

@@ -20,6 +20,7 @@ Project configuration drives the workflow - no hardcoded assumptions.
 - [ ] Run post-push actions (GitHub release, npm publish, etc.)
 - [ ] Verify release sync (npm dist-tag, GitHub "Latest", git tag all show the new version)
 - [ ] Complete active intent
+- [ ] Clean up the intent's worktrees (merge-then-remove)
 
 ## Workflow
 
@@ -84,6 +85,15 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
 ### 4. Bump Version
 
 Determine which files to update from project.yml:
@@ -207,6 +217,28 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 **If no active intent exists for this release**, that itself is a problem - work happened outside the intent system. Log it and move on, but flag it.
 
+### 9. Clean Up the Intent's Worktrees (merge-then-remove)
+
+A release is the merge-then-remove path for the intent's worktrees (intent 73c3). This is the
+one place the merge-vs-remove policy lands on "merge": the intent's code branch
+(`plastic/{id}--{slug}`) is merged back into the repo's default branch BEFORE the worktree is
+removed, so the integrated work is never lost. (The disarm path in `plastic-auto`, by contrast,
+is a plain remove because no release is merging the branch.)
+
+Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
+removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
+from the bridge:
+
+```bash
+ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
+  'b = Bridge.read(ENV["CLAUDE_CODE_SESSION_ID"]); Worktree.finish(b, merge: true) if b'
+```
+
+`finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the worktree
+is still removed rather than stranded), and a second call with the block already cleared is a
+no-op. Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
+prune` in the affected repo if you hit a stale reference.
+
 ## Conventions
 
 - **Annotated tags only** - `git tag -a`, never lightweight tags

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"
+        }
+      ]
+    }
+  ]
+}

package/skills/writing-instructions/SKILL.md

@@ -1,159 +0,0 @@
----
-name: plastic-writing-instructions
-description: >
-  Write or restructure agent instructions, conventions files, and SKILL.md
-  content using progressive disclosure and the agentskills.io specification.
-  Use when creating PLASTIC.md, rewriting convention docs, authoring new
-  skills, restructuring large instruction files to fit context budgets,
-  or when instructions feel too long, too vague, or agents aren't following
-  them. Also use when the user says "progressive disclosure", "restructure
-  instructions", or "the instructions are too big".
----
-
-# Writing Agent Instructions
-
-Based on the [agentskills.io specification](https://agentskills.io).
-
-## Progressive Disclosure Architecture
-
-All agent instructions follow three loading stages. Design for this — it's the
-architecture, not a nice-to-have.
-
-| Stage | What loads | Budget | Design for |
-|-------|-----------|--------|------------|
-| **Discovery** | name + description | ~100 tokens | Trigger accuracy |
-| **Activation** | Full instruction body | <5000 tokens / <500 lines | Core procedures |
-| **Execution** | references/, scripts/, assets/ | As needed | Deep detail |
-
-**The description carries the entire burden of triggering.** If agents aren't
-activating your skill, the description is the problem.
-
-## Procedure
-
-### Step 1: Audit the content
-
-Before writing or restructuring, classify every piece of content:
-
-| Classification | Where it goes | Example |
-|---------------|---------------|---------|
-| **Trigger context** | description field | "Use when...", keywords |
-| **Core procedure** | SKILL.md body | Step-by-step workflows |
-| **Gotchas** | SKILL.md body (early) | Facts that defy assumptions |
-| **Deep reference** | references/ | API details, full schemas |
-| **Templates** | assets/ or inline | Output format examples |
-| **Executable logic** | scripts/ | Validation, data processing |
-
-Ask for each piece: "Would the agent get this wrong without this?"
-If no — cut it. If unsure — test it.
-
-### Step 2: Write the description
-
-The description must convey WHEN to use, not just WHAT it does.
-
-**Rules:**
-- Imperative phrasing: "Use this skill when..." not "This skill does..."
-- Focus on user intent, not implementation
-- Err on the side of being pushy — list contexts explicitly
-- Include cases where user doesn't name the domain directly
-- Under 1024 characters (hard limit)
-- Include specific trigger keywords
-
-**Template:**
-```yaml
-description: >
-  [One sentence: what it does]. Use when [primary trigger context],
-  [secondary trigger], or when [indirect trigger where user doesn't
-  name the domain]. Also use when [edge case trigger].
-```
-
-### Step 3: Write the body
-
-**Principles (in priority order):**
-
-1. **Procedures over declarations** — Teach HOW to approach a class of problems,
-   not WHAT to produce for a specific instance
-2. **Defaults, not menus** — Pick one approach, mention alternatives briefly.
-   "Use X. For Y cases, use Z instead." Never present options as equals.
-3. **Calibrate control to fragility** — Prescriptive for fragile/sequential tasks,
-   flexible when multiple approaches are valid. Most skills have a mix.
-4. **Reasoning over rigid directives** — "Do X because Y tends to cause Z" beats
-   "ALWAYS do X, NEVER do Y"
-5. **Add what the agent lacks, omit what it knows** — No explaining HTTP, PDFs,
-   or what a migration is. Jump to what's non-obvious.
-
-**Structure:**
-```markdown
-# Title
-
-[1-2 sentence purpose statement]
-
-## Gotchas
-- [Highest-value content first — facts that defy assumptions]
-- [Each gotcha is a concrete correction, not general advice]
-
-## Procedure
-### Step 1: ...
-### Step 2: ...
-
-## Patterns
-[Only if the skill covers multiple approaches to similar problems]
-```
-
-### Step 4: Extract to references/
-
-Anything over 500 lines or 5000 tokens goes to `references/`. But tell the
-agent WHEN to load each file — conditional references, not a generic "see
-references/ for details."
-
-**Good:** "Read `references/api-errors.md` if the API returns a non-200 status"
-**Bad:** "See references/ for more information"
-
-### Step 5: Validate
-
-Run through this checklist:
-
-- [ ] Description under 1024 chars
-- [ ] Body under 500 lines / 5000 tokens
-- [ ] Every instruction passes "would the agent get this wrong without it?"
-- [ ] Gotchas are concrete corrections, not general advice
-- [ ] Defaults chosen, not menus presented
-- [ ] Control calibrated: prescriptive where fragile, flexible where tolerant
-- [ ] References have conditional load triggers
-- [ ] No explaining what the agent already knows
-
-For structured evaluation beyond this checklist (paired evals, pass rate
-tracking, regression testing), use `plastic-evaluating-skills`.
-
-## Gotchas
-
-- Hook `additionalContext` truncates at **10,000 characters**. If instructions
-  must load via hooks (not skills), they must fit this budget.
-- `~/.claude/rules/*.md` files load fully with no truncation — use for
-  always-loaded conventions that don't fit in a skill.
-- CLAUDE.md supports `@path/to/file` imports (max depth 4) — another way
-  to load large instruction sets without truncation.
-- Agents only consult skills for tasks beyond what they can handle alone.
-  Simple one-step requests may not trigger even with a perfect description.
-- Content from real domain expertise (runbooks, incident reports, code review)
-  dramatically outperforms LLM-generated instructions without project context.
-- The most common cause of agents not following instructions: the instruction
-  was too vague, didn't apply to the current task, or presented too many
-  options without a clear default. Read execution traces to diagnose.
-
-## For Convention Files (PLASTIC.md, CLAUDE.md)
-
-Convention files aren't skills — they load differently. Apply progressive
-disclosure by splitting:
-
-| Layer | Mechanism | Budget | Content |
-|-------|-----------|--------|---------|
-| **Always-on** | `~/.claude/rules/` or hook | <10K chars | Core identity, gotchas, critical procedures |
-| **On-demand** | Skills (SKILL.md) | <5K tokens each | Specific workflows activated by task |
-| **Deep reference** | `references/` in skills | Unlimited | Full specs, schemas, examples |
-
-**The always-on layer should answer: "What does this agent need to know about
-every single task?"** Everything else activates on demand.
-
-## References
-
-- Read `references/agentskills-spec.md` for the complete agentskills.io specification including frontmatter fields, description optimization methodology, evaluation framework, and script design requirements