@zalom/plastic 1.14.0 → 2.0.0-alpha.1

package/skills/skill-evaluating/SKILL.md

@@ -1,141 +0,0 @@
----
-name: plastic-skill-evaluating
-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".
-user-invocable: true
----
-
-# 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/skill-evaluating/assets/eval-template.json

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

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

@@ -1,75 +0,0 @@
-{
-  "skill_name": "plastic-skill-evaluating",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I want to evaluate whether my intent-creating 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 intent-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/skill-evaluating/references/convention-checks.md

@@ -1,76 +0,0 @@
-# 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/skill-evaluating/references/eval-methodology.md

@@ -1,154 +0,0 @@
-# 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/store-curating/SKILL.md

@@ -1,64 +0,0 @@
----
-name: plastic-store-curating
-description: |
-  Use when completing or reviewing intents, reorganizing the index,
-  or when the intent store needs maintenance. Examples:
-  <example>Context: User has finished implementing a feature.
-  user: "This intent is done, clean up the index"
-  assistant: "I'll use the intent-curator to update the intent status and reorganize INDEX.md"
-  <commentary>Intent lifecycle change triggers curator for index maintenance.</commentary></example>
-  <example>Context: The intent store has grown and clusters need review.
-  user: "Organize the intents"
-  assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
-  <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
-user-invocable: false
----
-
-# Intent Curator
-
-Dispatches to the `plastic-intent-curator` agent for intent store maintenance.
-
-## When to Use
-- Completing or reviewing intents
-- Reorganizing INDEX.md
-- Cluster maintenance, orphan detection, link discovery
-- Batch status updates
-
-## 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:
-
-1. **What to do** - complete intent, reorganize, triage stale, etc.
-2. **Which store** - global (`~/.plastic/`) or project (`.plastic/store/`)
-3. **Which intents** - by ID or "all active"
-
-The agent handles:
-- Intent lifecycle management (status transitions, Outcome sections)
-- INDEX.md maintenance (Active/Future/Clusters/Completed/Abandoned sections)
-- Link discovery between related intents
-- Cluster management (create, merge, rename)
-- Orphan detection
-
-Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
-influence, sources versus chain, and the `## Links` projection, before judging a link discovery or
-orphan finding. This path resolves relative to this skill's own installed directory.
-
-When an intent reaches a terminal state, moved to Completed OR Abandoned, do these things:
-
-1. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
-2. Call `plastic-intent-ending` for the terminal-transition close (INDEX move, savepoint `Done` bookend, store commit, disarm, and the QMD reindex last): `ruby ~/.plastic/scripts/end-intent --store <store> --id <id> --disposition delivered|abandoned`, then follow that skill's own disarm and reindex steps. Never restate those one-liners here.
-
-After the agent completes, report what changed.
-
-## Maintenance dispatch (intent 197)
-
-When invoked to fix a structural finding on an intent OTHER than one currently being delivered
-(for example, from `/plastic-doctor`'s fix-all routing), the `plastic-intent-curator` agent
-follows its own step 7: it detects (never acquires) the target's delivery lock, requires a
-clean working tree, and performs the fix on a fresh branch merged back to main as one closed
-operation, with an append-only `revisions.md` receipt in the same pass as the edit. See
-`agents/plastic-intent-curator.md` for the exact mechanics.
-
-Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
-MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog before
-running a maintenance dispatch like this one.

package/skills/store-curating/evals/evals.json

@@ -1,38 +0,0 @@
-{
-  "skill_name": "plastic-store-curating",
-  "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"
-        }
-      ]
-    },
-    {
-      "id": 2,
-      "scope": "behavior",
-      "set": "validation",
-      "prompt": "The user says: intent 26 (Completed) has a stale ## Links comment that contradicts its own real chain edge; fix it. Intent 26 is NOT the intent currently being delivered by this session.",
-      "expected_output": "Before editing intent 26, checks its delivery lock freshness (plastic-lock status --intent-dir, reading lock_fresh) and defers if fresh; requires a clean store working tree; creates a fresh maintenance branch off main; makes the scoped edit AND appends a revisions.md receipt in the same pass, refusing the edit if the receipt cannot be written; stages only the changed paths (never git add -A); merges the branch back to main and deletes it before reporting done.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "agent file states detect-only lock check, clean-tree precheck, branch-and-merge-back, and refuse-without-receipt as an unconditional sequence for maintenance on a non-current intent",
-          "observed": "agents/plastic-intent-curator.md step 7 covers all five sub-steps (a-f) exactly as asked",
-          "result": "pass"
-        }
-      ]
-    }
-  ]
-}

package/skills/store-indexing/SKILL.md

@@ -1,93 +0,0 @@
----
-name: plastic-store-indexing
-description: Use after creating, completing, or abandoning intents, when the user says "index" or "organize", or when INDEX.md needs maintenance. Curates the INDEX.md structure note.
-user-invocable: false
----
-
-# Managing the Index
-
-## When to Use
-- After creating a new intent (automatic - part of intent-creating workflow)
-- After completing or abandoning an intent
-- User says "index", "organize", or "clean up"
-- Periodic maintenance when the store grows
-
-## INDEX.md Structure
-
-INDEX.md is a Zettelkasten main structure note - the brain's entry point. It has five sections:
-
-### Active
-Intents currently being worked on. Max 1-2 for focus.
-```markdown
-## Active
-- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2--design-plastic-state-system.md) — decision, human
-```
-
-### Future
-Intents parked for later. May be picked up by agents.
-```markdown
-## Future
-- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1--build-reddit-knowledge-base.md) — implementation, human
-```
-
-### Clusters
-Topic-based groupings. Manually curated. Create a new cluster when 3+ intents share a topic.
-```markdown
-## Clusters
-### Reddit Knowledge Base
-- [1a — Research](store/1a--research-reddit-saved-posts/1a--research-reddit-saved-posts.md)
-- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1--plan-reddit-knowledge-base.md)
-```
-
-### Abandoned
-Intents ended without delivery. Links preserved, never deleted.
-
-### Completed
-All completed intents with dates. Links preserved, never deleted.
-
-When you move an intent INTO Completed or Abandoned, do these things:
-
-1. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
-2. Call `plastic-intent-ending` for the terminal-transition close (INDEX move, savepoint `Done` bookend, store commit, disarm, and the QMD reindex last): `ruby ~/.plastic/scripts/end-intent --store <store> --id <id> --disposition delivered|abandoned`, then follow that skill's own disarm and reindex steps. Never restate those one-liners here.
-
-## 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:
-
-```bash
-for dir in $STORE_ROOT/store/*/; do
-  f=$(find "$dir" -maxdepth 1 -name "*.md" ! -name "spec.md" ! -name "plan.md" ! -name "checklist.md" ! -name "outcome.md" ! -name "savepoint.md" | head -1)
-  [ -n "$f" ] && dirname_slug=$(basename "$dir") && ruby -e '
-    data = File.read(ARGV[0]).split("---")[1]
-    parsed = YAML.safe_load(data)
-    puts "#{parsed["id"]}|#{parsed["intent"]}|#{ARGV[1]}"
-  ' "$f" "$dirname_slug" 2>/dev/null
-done | sort -t'|' -k1
-```
-
-### Suggest Clusters
-When 3+ intents share tags but aren't in a cluster, suggest a new cluster heading.
-
-### Flag Orphans
-Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
-
-Before reclassifying a structural finding outside routine indexing, read
-`../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus MAINTENANCE, the
-`revisions.md` move-and-record contract, and the violation-tag catalog.
-
-REQUIRED BACKGROUND: intent-linking (for understanding connection types and Zettelkasten theory)
-
-Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
-influence, sources versus chain, and the `## Links` projection. This path resolves relative to
-this skill's own installed directory.
-
-## References
-
-- Read `references/zettelkasten-linking.md` for the three structural layers (Folgezettel, directed graph, tags) and how they map to INDEX.md organization