@zalom/plastic 1.0.0-beta.3 → 1.0.0-beta.30

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/templates/config.yml

@@ -11,3 +11,11 @@ agent:
   parallel_mode: linear
 architect:
   style:
+
+# Per-agent model override (intent 116). Uncomment and set to a Claude Code
+# alias (opus, sonnet, haiku) to override the shipped tier for one agent. With
+# no entry, the shipped default applies. Never resolves to Fable.
+# agents:
+#   models:
+#     plastic-executor: sonnet
+#     plastic-enforcer: opus

package/templates/outcome.md

@@ -1,3 +1,6 @@
+---
+disposition: delivered|abandoned
+---
 # Outcome: <intent name>
 
 ## Summary

package/templates/revisions.md

@@ -0,0 +1,58 @@
+# revisions.md
+
+<!--
+FORM reference. A live revisions.md exists in an intent directory ONLY when structural
+maintenance actually happened. It is never scaffolded at intent birth, it carries no
+placeholder sentinel, and its mere presence signals that this intent underwent structural
+(not conceptual) change.
+
+Rules:
+- Append-only. Newest entry at the BOTTOM. Never edit or reorder past entries.
+- One entry per relocated item (one section, one file, or one ref per entry).
+- Move-and-record: remove the misplaced thing from its artifact and preserve it IN FULL
+  here. Never rewrite, summarize, or reinterpret delivered meaning. A change to delivered
+  meaning is a new intent, not a revision.
+- Header form: "## Revision vN - YYYY-MM-DD-HH:MM" (N increments by one per entry).
+
+Fields:
+- Why:            one sentence naming the broken rule, ending with "[rule: <tag>]".
+- Prior location: the artifact plus the section or path the content came from.
+- Content held:   the verbatim removed content, as an indented block (block form), OR
+- Change:         a one-line "removed X (before: ... -> after: ...)" for a frontmatter
+                  edit, used instead of a Content held block.
+
+Stray file: embed the file's full content as the Content held block and delete the
+original; Prior location names the filename. revisions.md is the single container.
+
+Violation-tag catalog (starter set; free-text tags are allowed):
+- unsanctioned-section : a top-level section the sanctioned-section rule now rejects
+- phantom-section      : a section referenced but not present or not sanctioned
+- stray-file           : a file that does not belong in the intent directory
+- dangling-ref         : a link or reference to something that no longer exists
+- broken-chain         : a chain frontmatter edge to an intent that no longer exists
+- broken-source        : a sources frontmatter edge to an intent that no longer exists
+- misplaced-content    : content that belongs in a different artifact or section
+
+The examples below show the three variants. Delete them when you write the first real
+entry; keep the "# revisions.md" title line above.
+-->
+
+## Revision v1 - 2026-06-30-14:35
+- Why: unsanctioned top-level section left over from an early draft [rule: unsanctioned-section]
+- Prior location: intent.md - ## Scope
+- Content held:
+
+  ## Scope
+  <the full content that was removed, verbatim>
+
+## Revision v2 - 2026-06-30-15:02
+- Why: chain edge to an intent that no longer exists [rule: broken-chain]
+- Prior location: intent.md frontmatter - chain
+- Change: removed "99x"  (before: ["4a1a", "99x"]  ->  after: ["4a1a"])
+
+## Revision v3 - 2026-06-30-15:20
+- Why: a stray notes file that does not belong in the intent directory [rule: stray-file]
+- Prior location: notes-old.md
+- Content held:
+
+  <the full content of notes-old.md, verbatim; the original file is then deleted>

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

package/skills/writing-instructions/references/agentskills-spec.md

@@ -1,135 +0,0 @@
-# agentskills.io Full Reference
-
-Source: https://agentskills.io (all sections, verified June 2026)
-
-## Specification Details
-
-### Frontmatter Fields
-
-| Field | Required | Constraints |
-|-------|----------|-------------|
-| name | Yes | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. Must match directory name. |
-| description | Yes | 1-1024 chars. Non-empty. What + when. |
-| license | No | Short — name or filename reference |
-| compatibility | No | 1-500 chars. Environment requirements only when needed. |
-| metadata | No | String→string map. Use unique key names. |
-| allowed-tools | No | Space-separated. Experimental. |
-
-### Progressive Disclosure Token Budgets
-
-- Discovery: ~100 tokens per skill (name + description only)
-- Activation: <5000 tokens / <500 lines recommended for SKILL.md body
-- Execution: Unbounded — files in scripts/, references/, assets/ load as needed
-
-### File References
-
-- Use relative paths from skill root
-- Keep one level deep from SKILL.md
-- Agent resolves paths automatically
-
-## Description Optimization
-
-### Evaluation Methodology
-
-1. Create ~20 eval queries (8-10 should-trigger, 8-10 should-not)
-2. Split 60/40 train/validation (proportional mix in each)
-3. Run each query 3 times, compute trigger rate
-4. Pass threshold: 0.5
-5. Near-miss negatives are most valuable (share keywords, need different thing)
-6. Iterate on train set only, validate on held-out set
-7. Select best by validation pass rate, not last iteration
-8. 5 iterations usually sufficient
-
-### Description Anti-patterns
-
-- "Helps with PDFs" — too vague, no trigger context
-- "Process CSV files" — no when/why, no user-intent focus
-- Implementation details instead of user intent
-- Missing edge case triggers (user doesn't name the domain)
-
-## Instruction Best Practices
-
-### Gotchas — Highest-Value Content
-
-Concrete corrections, not general advice:
-
-```markdown
-## Gotchas
-- The `users` table uses soft deletes. Queries must include
-  `WHERE deleted_at IS NULL`.
-- User ID is `user_id` in DB, `uid` in auth, `accountId` in billing.
-  All three refer to the same value.
-- The `/health` endpoint returns 200 even if DB is down. Use `/ready`.
-```
-
-### Calibrating Control
-
-Prescriptive when:
-- Operations are fragile
-- Consistency matters
-- Specific sequence must be followed
-
-Flexible when:
-- Multiple approaches are valid
-- Task tolerates variation
-- Explaining WHY is more effective than rigid rules
-
-### Instruction Patterns
-
-1. **Validation loops**: Do work → validate → fix → repeat
-2. **Plan-validate-execute**: Create plan → validate vs source of truth → execute
-3. **Checklists**: Track progress, enforce dependencies, validation gates
-4. **Bundled scripts**: If agent reinvents same logic each run, bundle it
-5. **Templates**: Concrete output structures > prose descriptions
-
-## Script Design
-
-### Hard Requirements
-- No interactive prompts (hard requirement — agents hang indefinitely)
-- All input via flags, env vars, or stdin
-
-### Agent-Friendly Design
-- --help as primary interface documentation
-- Helpful error messages: what wrong + what expected + what to try
-- Structured output (JSON/CSV/TSV), data on stdout, diagnostics on stderr
-- Idempotent operations (agents may retry)
-- Dry-run for destructive operations
-- Meaningful exit codes documented in --help
-- Output size control: default to summaries, support --offset pagination
-- Agent harnesses truncate at 10-30K characters
-
-## Evaluation Framework
-
-### Test Case Structure
-```json
-{
-  "skill_name": "name",
-  "evals": [{
-    "id": 1,
-    "prompt": "realistic user message",
-    "expected_output": "what success looks like",
-    "files": ["evals/files/input.csv"],
-    "assertions": ["specific, verifiable checks"]
-  }]
-}
-```
-
-### Running Evals
-- With-skill vs without-skill (or previous version) comparison
-- Clean context per run (subagents or separate sessions)
-- Capture timing: total_tokens, duration_ms
-- Start with 2-3 test cases, expand after first results
-
-### Assertion Quality
-Good: Programmatically verifiable, specific, countable
-Weak: Vague ("the output is good")
-Brittle: Exact phrase matching
-
-Principle: Require concrete evidence for PASS. No benefit of the doubt.
-
-### Iteration Loop
-1. Run evals → grade assertions → aggregate benchmarks
-2. Identify failures (assertions, human feedback, execution transcripts)
-3. Feed all three + SKILL.md to LLM for proposed changes
-4. Apply changes → re-run → compare
-5. Stop when consistently empty feedback or no meaningful improvement