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

package/skills/continuing/SKILL.md

@@ -54,15 +54,37 @@ 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:
-
-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 =
-   current stage**.
-2. **Verify the stage file.** Confirm the file the ledger names exists and is non-empty
-   (ledger `How  plan.md created` → `plan.md` must be present and non-empty).
+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` FIRST (intent 81).** It is a deterministic, append-only ledger
+   (one line per event, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. Classify
+   the state from the **last line** alone, then verify ONLY that line's artifact. The bookends
+   are fixed: first line `What  created`, last line either a cycle position or
+   `Done  delivered|abandoned`.
+
+   | Last line | State | Verify only |
+   |---|---|---|
+   | `What  {id}--{slug}.md` | born / parked | intent file exists |
+   | `Why  started` | Why entered, no spec yet | spec.md not yet real; continue Why |
+   | `Why  spec.md created` | Why done | spec.md present; continue to How |
+   | `How  started` / `How  plan.md created` | How in progress | plan.md; continue How |
+   | `How  checklist.md created` / `Exec  started` | ready for / in Exec | plan.md + checklist.md present; continue Exec |
+   | `Exec  outcome.md created` | Exec done | outcome.md present; ready to complete |
+   | `Done  delivered` / `Done  abandoned` | terminal | do NOT cycle-resume; INDEX is authoritative |
+
+2. **Verify the stage file.** Confirm only the last line's artifact exists and is non-empty
+   (ledger `How  plan.md created` → `plan.md` must be present and non-empty). Do not re-probe
+   every lifecycle file.
 3. **Drift handling.** If the ledger's last line disagrees with files-on-disk, rebuild the
-   ledger from filesystem state and note the correction:
+   ledger from filesystem state and note the correction. A rebuilt ledger is the file-landing
+   skeleton (no `started`/`Done` lines), which still pins cycle position:
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
    ```

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`.
@@ -54,12 +62,18 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
     direct-ascendant provenance (D1).
   - **Merely related to / inspired by another intent** (it did NOT come out of that
     intent's lifecycle): carry NO `--sources`. Record the relation on the PREDECESSOR's
-    `chain` instead, and mirror it as a `[[id]]` wikilink in `## Links` (the
-    related-but-not-spawned rule).
+    `chain` instead (the related-but-not-spawned rule); the `## Links` section follows
+    from that edge, you do not write it by hand.
 - **Rule of thumb:** if the intent could exist without its parent, make it a root; only set
   `--sources` when it was genuinely created from / emerged from that intent's lifecycle.
   Topic similarity alone is not a `sources` edge.
 
+`## Links` is a DERIVED view of `sources`/`chain`. Never hand-write a `## Links` line; add the
+frontmatter edge and reproject. Links are decided by context influence (a `chain` edge has a high
+bar: the candidate's context must materially help deliver this intent), not by shared files or a
+similarity score. To gather candidates with their context and record an edge, use the
+`plastic-linking-intents` skill and `scripts/link-suggest`.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:

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/creating-intent/references/lifecycle.md

@@ -42,10 +42,15 @@ field.
 
 ## `## Links`
 
-The human-readable projection of the local knowledge graph: all `sources`
-first (top, named), then all `chain` (named), as `[[id]]` wikilinks plus a
-short label. Counterpart to the frontmatter `sources` / `chain` edges, for
-Obsidian graph navigation.
+The human-readable projection of the local knowledge graph, mirroring the
+frontmatter exactly. Each entry is `- [[id--slug|<target's full intent: text>]]`,
+a clickable `id--slug` wikilink target with the target intent's full `intent:`
+text as the label (cross-store targets render
+`- [[store:id--slug|<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. An
+intent with empty `sources` and `chain` carries the empty-state comment. Counterpart
+to the frontmatter `sources` / `chain` edges, for Obsidian graph navigation.
 
 ## Conventions — Filesystem as Schema
 

package/skills/creating-skills/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: plastic-creating-skills
+description: >
+  Author or revise a Plastic skill, a subagent or Agent role file, or a
+  lifecycle hook with progressive disclosure. Use when creating or editing a
+  SKILL.md, writing a description or frontmatter, designing the slim body,
+  building references, evals, or scripts, or scaffolding a new skill. Also use
+  when a skill is too big or over its token budget, when prompts are bloated,
+  when an agent keeps missing a step or ignoring instructions, or when the user
+  says "progressive disclosure", "write a skill", "thin router", "split into
+  references", or "make this slim".
+---
+
+# Creating Skills
+
+Author skills, agents, and hooks as thin routers over deep references. This
+body carries the rules that must stay correct without opening anything, then
+routes each authoring task to the reference that holds the depth.
+
+## Rules (must be right even if no reference is opened)
+
+- Three load levels, hard budgets: metadata around 100 tokens (always loaded),
+  body under 5000 tokens and under 500 lines (loaded on trigger), references on
+  demand. Keep the body well under budget, not at the ceiling.
+- Progressive disclosure first: the body routes, the references hold the depth.
+  Any deep how-to in the body belongs in a reference instead.
+- Description states WHEN to use, not the workflow. Write it in third person,
+  front-load concrete trigger keywords, and include at least one indirect
+  trigger (a request that never names the domain). Never summarize the steps.
+- Bind every reference link to an observable trigger condition. Never leave a
+  bare pointer to a reference.
+- References stay one level deep. Any reference over 100 lines opens with a
+  table of contents.
+- Build at least three evals before writing extensive docs.
+- Match determinism to fragility: a deterministic script for fragile or
+  repeated mechanical steps, prose for judgment calls.
+- Imperative voice, no second person. No em-dashes or en-dashes in any shipped
+  skill or doc (use commas, periods, parentheses, colons).
+
+## Route the authoring task to its reference
+
+| Authoring task | Open |
+|---|---|
+| Starting any authoring task: load the load-level model and the thin-router pattern first | `references/progressive-disclosure.md` |
+| Authoring an Agent Skill (frontmatter, description, slim body, voice) | `references/skills.md` |
+| Authoring a subagent or Agent role file | `references/agents.md` |
+| Authoring a lifecycle hook | `references/hooks.md` |
+| Deciding script versus prose, or writing a script | `references/scripts.md` |
+| Building evals for a skill | `references/evals.md` |
+
+## Shrink context, or let a skill self-improve
+
+- When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for
+  the global token levers: a PostToolUse hook that trims noisy tool output before it enters
+  context, and Programmatic Tool Calling that keeps looped tool results in code, not context.
+- When a skill should learn from its own real runs, open `references/hooks.md` (E8) for the
+  propose-only Stop or SubagentStop loop (transcript to proposed edits to human approval to
+  git, effort-gated). The dedicated skill is the future `improving-skills` skill.
+
+## Scaffolder and evals
+
+- To start a new skill, agent, or hook from a born-slim file, run
+  `scripts/scaffold.rb`.
+- To design, run, and grade evals in depth (paired runs, assertions after
+  observing, pass rates), use the `plastic-evaluating-skills` skill.

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

@@ -0,0 +1,108 @@
+{
+  "skill_name": "plastic-creating-skills",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to author a new Plastic skill, how should I structure it?",
+      "expected_output": "The skill should activate. This is a direct authoring request that names the domain. Guide the user through progressive disclosure: metadata around 100 tokens, a slim body under 5000 tokens and 500 lines that routes, and references on demand. Point to references/skills.md for frontmatter, description, and voice, and route load-level questions through references/progressive-disclosure.md first.",
+      "files": [],
+      "assertions": [
+        "The skill activates (direct authoring request that names the domain).",
+        "The response routes to references rather than dumping deep how-to inline.",
+        "The response states the load-level budgets (around 100 token metadata, body under 5000 tokens and 500 lines)."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The agent keeps ignoring my instructions and the file is huge, help me restructure it",
+      "expected_output": "The skill should activate. This is an indirect trigger that never names skills or progressive disclosure, but the symptoms (bloated file, agent missing or skipping steps) are exactly the over-budget body case the skill covers. Guide toward splitting the body into references, keeping the body a thin router, and binding each reference to an observable trigger condition.",
+      "files": [],
+      "assertions": [
+        "The skill activates on the indirect trigger (no skill or progressive-disclosure keyword in the prompt).",
+        "The response guides toward splitting the body into references and keeping a thin router."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Scaffold a new lifecycle hook for Plastic",
+      "expected_output": "The skill should activate. Authoring a lifecycle hook is in scope. Route to references/hooks.md and offer scripts/scaffold.rb to start the hook from a born-slim file.",
+      "files": [],
+      "assertions": [
+        "The skill activates (authoring a lifecycle hook is in scope).",
+        "The response routes to references/hooks.md and offers scripts/scaffold.rb."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Our prompts are bloated and we keep blowing the context budget",
+      "expected_output": "The skill should activate. This is an indirect trigger: the user describes bloated prompts and a context budget problem without naming skills. The skill restructures instructions into a thin router over deep references with hard load-level budgets, which is the fix for this symptom.",
+      "files": [],
+      "assertions": [
+        "The skill activates on the indirect context-budget trigger (no skill keyword in the prompt).",
+        "The response treats the fix as a thin router over deep references with hard load-level budgets."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Run the evals on my skill and check the pass rate",
+      "expected_output": "The skill should NOT trigger. Running evals and reading pass rates is the job of plastic-evaluating-skills, not authoring. Near-miss negative: shares the words 'skill' and 'evals' but the operation is grading an existing skill, not creating or revising one.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (running and grading evals is plastic-evaluating-skills, not authoring)."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Create a new intent for the dashboard work",
+      "expected_output": "The skill should NOT trigger. Creating an intent is plastic-creating-intent. Near-miss negative: shares the verb 'create' but the object is an intent, not a skill, agent, or hook.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (creating an intent is plastic-creating-intent)."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "I keep losing every team fight because of a skill issue in this game, any tips?",
+      "expected_output": "The skill should NOT trigger. This is a gaming question with no relation to authoring instructions. Near-miss negative: shares the word 'skill' in an unrelated sense.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (gaming question, unrelated sense of 'skill')."
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "Write unit tests for my Ruby model that validates email addresses",
+      "expected_output": "The skill should NOT trigger. Writing test code is a Ruby testing task. Near-miss negative: shares 'write' and 'test' but has nothing to do with authoring a skill, agent, or hook.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (writing test code is a Ruby testing task, not authoring a skill)."
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "Author a slim SKILL.md for a PDF-extraction skill",
+      "expected_output": "Activation is assumed for this output-quality case. Correct output is a SKILL.md whose frontmatter description is third person, front-loads concrete trigger keywords, states WHEN to use rather than the workflow, and includes at least one indirect trigger. The body stays under 5000 tokens and under 500 lines and routes to references rather than carrying deep how-to. Each reference link names an observable trigger condition with no bare pointer like 'see references/'. References stay one level deep, and no string contains an em-dash or en-dash.",
+      "files": [],
+      "assertions": [
+        "The frontmatter description is written in the third person (no 'you' or 'I').",
+        "The description front-loads concrete trigger keywords in its opening clause.",
+        "The description includes at least one indirect trigger (a symptom phrasing that never names PDF extraction or skills).",
+        "The body is under 5000 tokens and under 500 lines.",
+        "Every reference link is bound to an observable trigger condition (no bare pointer such as 'see references/').",
+        "References stay one level deep (no reference points to a deeper reference).",
+        "No string in the SKILL.md or its references contains an em-dash or en-dash."
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "Make this subagent role file slim, the description is vague and the body is too long",
+      "expected_output": "The skill should activate. Authoring or revising a subagent or Agent role file is in scope, and the symptoms (vague description, over-long body) are the progressive-disclosure case. Route to references/agents.md, tighten the description to state WHEN, and move depth into references. Output should keep the body under budget and use no em-dashes.",
+      "files": [],
+      "assertions": [
+        "The skill activates (revising a subagent or Agent role file is in scope).",
+        "The response routes to references/agents.md and tightens the description to state WHEN.",
+        "The proposed output keeps the body under budget and uses no em-dash or en-dash."
+      ]
+    }
+  ]
+}

package/skills/creating-skills/references/agents.md

@@ -0,0 +1,168 @@
+# Authoring an Agent (subagent)
+
+How to write a subagent / Agent role file: scope, tools, description, the reviewer pattern,
+collector discipline, and the skill-vs-agent decision. Rules cite section D of the
+best-practices standard (D1 through D6).
+
+## Contents
+
+- [When a skill suffices vs escalate to an agent](#when-a-skill-suffices-vs-escalate-to-an-agent)
+- [The agent definition fields](#the-agent-definition-fields)
+- [One focused task per agent](#one-focused-task-per-agent)
+- [Tight tool set](#tight-tool-set)
+- [Description: embedded when-to-use examples](#description-embedded-when-to-use-examples)
+- [Collectors, not implementers](#collectors-not-implementers)
+- [Reviewer / devil's-advocate agents](#reviewer--devils-advocate-agents)
+- [Composing skills and agents](#composing-skills-and-agents)
+- [Self-checks](#self-checks)
+
+For load levels, the three-bucket model, and description-as-trigger rules, open
+`progressive-disclosure.md` and `skills.md`. Do not re-derive them here (C7).
+
+## When a skill suffices vs escalate to an agent
+
+Decide before authoring an agent at all. A full agent carries its own context window and tool
+grant, so it is too heavyweight for quick work [D5].
+
+| Situation | Build | Why |
+| --- | --- | --- |
+| Light read-only check, single-file validation, scaffold one file | Skill | A skill loads on trigger and runs in the current context, no spin-up cost [D5] |
+| Deep multi-file audit, parallel investigation, isolated noisy work | Agent | The isolated context keeps search and log noise off the main thread [D2][D5] |
+| Same task repeated with deterministic steps | Script (see `scripts.md`) | Executed, not loaded; token-free and variance-free |
+
+Default to a skill. Escalate to an agent only when the work needs an isolated context budget or
+its own restricted tool grant.
+
+## The agent definition fields
+
+An agent file is frontmatter plus a system-prompt body. Set each field for one reason.
+
+| Field | When it matters | Set it to |
+| --- | --- | --- |
+| `name` | Always. The orchestrator and `SendMessage` address the agent by it | Lowercase-hyphen, one capability (`spec-reviewer`, `dependency-auditor`) |
+| `description` | Always. The orchestrator delegates purely on this text [D3] | Trigger conditions plus embedded when-to-use example pairs (see below) |
+| `tools` | Always. Omitting it grants every tool, which over-arms the agent [D1] | Only the tools the one task needs |
+| `model` | When the task is cheap (Haiku) or hard (Opus) | The cheapest tier that holds quality |
+| `proactive` marker | When the agent should auto-fire without an explicit ask [D3] | Include "use proactively" inside the description |
+
+Keep the body in imperative voice. State the agent's single job, its numbered process, and its
+output contract. Push reference detail into files the agent reads on demand, same as a skill body.
+
+## One focused task per agent
+
+Give each agent exactly one task. Focused scope plus a tight tool set is what makes delegation
+decidable and cheap [D1].
+
+1. Name the single responsibility in one phrase. If the name needs "and", split into two agents.
+2. Start with one agent. Add a specialist only when it materially improves isolation or tool
+   scoping [D1]. More agents widen the discovery surface and the orchestrator's choice space.
+3. Write the body around that one task. An agent that "reviews and also fixes and also reports" has
+   three jobs and no clear output contract.
+
+## Tight tool set
+
+Grant only the tools the one task requires [D1].
+
+| Agent kind | Typical tools | Excluded |
+| --- | --- | --- |
+| Reviewer / auditor | Read, Grep, Glob | Edit, Write, Bash (read-only by design) [D4] |
+| Collector / researcher | Read, Grep, Glob, WebFetch | Edit, Write (returns a summary, does not change code) [D2] |
+| Implementer | Read, Edit, Write, Bash | Only the surface its task touches |
+
+A reviewer with Edit can rewrite the code it judges. A collector with Write can leak its noisy
+context back into the tree. The tool list is the guardrail; keep it narrow.
+
+## Description: embedded when-to-use examples
+
+The orchestrator never reads the body at delegation time. It routes on the description alone, so
+the description must teach the boundary by example [D3].
+
+Write the description with:
+
+1. A trigger clause in third person ("Use when reviewing a spec before the plan stage").
+2. One or more `<example>` pairs showing a matching prompt, the assistant's choice to delegate, and
+   a one-line `<commentary>` on why. Example pairs teach the boundary a keyword list cannot [D3].
+3. "use proactively" when the agent should auto-fire without the user naming it [D3].
+
+Concrete shape:
+
+```
+description: >
+  Use when a spec is complete and needs an adversarial review before planning.
+  Use proactively after the spec-specialist writes spec.md.
+  <example>
+    Context: spec.md just landed for the active intent.
+    user: "Is this spec ready to plan?"
+    assistant: "I'll use the spec-reviewer agent to challenge the spec before planning."
+    <commentary>Adversarial review runs at the Why-to-How boundary.</commentary>
+  </example>
+```
+
+A description that summarizes the agent's workflow instead of its trigger makes the orchestrator
+act on the summary and skip the body. State when to fire, not how the agent works.
+
+## Collectors, not implementers
+
+Use a subagent as an information collector that returns a short summary, not as an implementer [D2].
+
+| Do | Avoid |
+| --- | --- |
+| Return a tight summary: findings, file paths, a verdict | Stuffing raw search output or full file dumps back into the main thread |
+| Write a plan or summary markdown file as shared memory; have the main thread read it [D2] | Passing large results inline, which defeats the isolation |
+| Keep search, log, and crawl noise inside the agent's own context [D2] | Re-emitting that noise to the orchestrator |
+
+The reason a subagent has an isolated context is to absorb noise. The filesystem (a plan or summary
+file) is the shared memory between agents; the agent's return value is the headline, not the
+transcript [D2].
+
+## Reviewer / devil's-advocate agents
+
+A reviewer agent needs four things, or it produces unscoped, unverifiable results [D4].
+
+1. Read-only tools: Read, Grep, Glob, and nothing that edits [D4]. A reviewer that can edit stops
+   being a reviewer.
+2. A numbered review process in the body, so every run covers the same checks in the same order.
+3. Explicit anti-scope: a "do not use for" clause that names what the agent must not do (implement
+   fixes, refactor, approve its own changes) [D4].
+4. A fixed, severity-bucketed output format, so findings are comparable across runs [D4].
+
+Fixed output contract:
+
+```
+## Critical
+- <finding> (file:line) -> <why it blocks>
+
+## Major
+- <finding> (file:line) -> <impact>
+
+## Minor
+- <finding> (file:line) -> <suggestion>
+
+## Verdict
+PASS | BLOCK, with one-line reason.
+```
+
+The severity buckets and the verdict are mandatory. Empty buckets stay in, marked "none", so a
+reader can tell the agent checked.
+
+## Composing skills and agents
+
+Two mechanisms load content into an agent's context. Choose by what budget the isolated agent
+should carry [D6].
+
+| Mechanism | Effect | Use when |
+| --- | --- | --- |
+| Subagent `skills:` | Preloads the full skill content into the agent at spawn [D6] | The agent must always have that skill's rules in hand |
+| Skill `context: fork` | Runs the skill body as a task prompt inside a chosen agent type [D6] | A skill should execute as an isolated agent, not inline |
+
+Pick deliberately. `skills:` spends the agent's budget up front for guaranteed availability;
+`context: fork` hands the body to a fresh agent so the work runs isolated [D6].
+
+## Self-checks
+
+- Could this be a skill instead? If the work is light or single-file, build a skill [D5].
+- Does the agent have exactly one job, named without "and"? [D1]
+- Is the tool list the minimum the job needs, and read-only for a reviewer? [D1][D4]
+- Does the description carry at least one `<example>` pair and "use proactively" if it auto-fires? [D3]
+- Does the agent return a summary and use a file as shared memory, not dump its context? [D2]
+- Does a reviewer have a numbered process, an anti-scope clause, and a severity-bucketed output? [D4]

package/skills/creating-skills/references/evals.md

@@ -0,0 +1,41 @@
+# Evals (author-time gate)
+
+This is the gate, not the method. It states the eval decisions an author makes while building a
+skill, then hands the full procedure to one place. Do not duplicate that procedure here.
+
+## Build evals before docs
+
+Build at least three evals before writing extensive documentation. A skill without an eval is an
+assertion, not a capability, so the eval forces the skill to close a real observed gap instead of an
+imagined one. [F1]
+
+Build RED-GREEN-REFACTOR. Run the scenario without the skill and record the verbatim failure (RED),
+write the minimal instructions that fix exactly that failure (GREEN), then close the loopholes the
+failure exposed (REFACTOR). Only instructions that move a failing eval earn their tokens. [F2]
+
+## What each eval must cover
+
+- Description triggering. Pair should-trigger queries with near-miss negatives: prompts that share
+  keywords with the skill but need a different skill entirely. Near-miss negatives catch
+  over-triggering, the most common description failure. State the trigger set here; do not size the
+  query count or split here. [F3]
+- Output quality. Write assertions only after observing real output. Make them specific, verifiable,
+  and countable, with no benefit of the doubt and no brittle exact-phrase matching. Assertions
+  written before observation encode hopes, not behavior, so include at least one output-quality case
+  graded this way. [F4]
+- Discipline under pressure. For a skill whose job is restraint, stack pressures (time, sunk cost,
+  authority, exhaustion) with forced options and run the case via a subagent. Reciting the rule is
+  not complying with it. [F5]
+
+## Grading and reliability decisions
+
+Grade with the cheapest sufficient tier, and track capability (pass@k) separately from reliability
+(pass^k) with k at least three. The evaluating-skills skill owns the grader taxonomy, judge
+calibration, clean-context execution, and cross-model testing. [F6, F7, F8]
+
+## Run them with the methodology skill
+
+Use the evaluating-skills skill to author and run the evals. It owns the full method: eval scope
+selection, the query-count and train/validation protocol, the grader taxonomy and judge calibration,
+the iteration loop, and graduation of stable capability evals into regression. It is the source of
+truth for those steps; this file states the author-time gate and stops there. [F6, F7, F8]