@zalom/plastic 1.0.0-alpha.10 → 1.0.0-alpha.11

package/skills/auto/references/agent-architecture.md

@@ -0,0 +1,60 @@
+# Agent Architecture
+
+## Main Orchestrator
+
+The Main Orchestrator manages the global store (Main Knowledge Base). It:
+- Recognizes, creates, updates, and groups intents
+- Spawns Project Orchestrators for registered projects
+- Receives contributions back from Project Orchestrators
+- Is the only agent that runs in a loop (continuous Build→Observe→Repeat)
+
+## Project Orchestrators
+
+Project Orchestrators manage project stores (Project Knowledge Bases). They:
+- Care about intents and execution within their project
+- Spawn teams to develop and execute intents
+- Contribute back to the Main Orchestrator when new intents are born
+  that could enrich the Main Knowledge Base
+
+Rules:
+- 1 Main Orchestrator : 1 Global Store (`~/.plastic/`)
+- 1 Main Orchestrator : N Project Orchestrators
+- 1 Project Orchestrator : 1 Project Store
+- 1 Agent : 1 Intent (exclusive assignment)
+- 1 Agent : N Sub-agents (for parallel Actions within an intent)
+
+## Two Modes
+
+- **Human-driven:** Human chats with Main Orchestrator, creates intents,
+  brainstorms, then Main Orchestrator dispatches Project Orchestrators and
+  Agents for execution.
+- **Autonomous:** Human gives Main Orchestrator a starting intent with defined
+  outcomes. Main Orchestrator runs the full cycle — Agents do the lifecycle
+  (What→Why→How→Exec), Main Orchestrator reviews Insights, spawns next intents,
+  dispatches again.
+
+## Autonomous Delivery
+
+Human owns What and Why for human-initiated intents. Agent assists (research,
+exploration) but human drives until handoff. When Why is complete — or human
+triggers `plastic:auto` — the agent takes over How and Exec autonomously.
+
+- **Safe-by-default:** Agent always prefers non-destructive routes (rename vs
+  delete, additive migrations, backups before changes). Destructive actions on
+  existing projects require human approval unless `--skip-permissions` is set.
+- **One agent per intent.** Agent follows the full W→W→H→E lifecycle.
+- **Notification only on:** finish or hard stop (blocked on destructive action,
+  unresolvable error). No progress reports — `## Insights` tracks everything.
+- **Greenfield autonomy:** During initial project creation, all decisions are
+  non-destructive (nothing to destroy). Agent has full autonomy for greenfield choices.
+- **Autonomous decisions** are logged in `## Insights` with `(autonomous)` marker.
+
+## Coordinator Loop
+
+When "work on Project X":
+1. Read `projects.yml` → find project path
+2. Load global config (defaults)
+3. Load project config (overrides)
+4. Load global INDEX.md → find hub intents tagged `project-<name>`
+5. Load project INDEX.md → tactical intents
+6. Coordinator has full picture, dispatches Agent teams

package/skills/continuing/SKILL.md

@@ -102,3 +102,7 @@ Auto-commit all triage changes.
 2. **Project context** — if in a registered project, show governing intent + tactical intents
 3. **Stale future intents** — surface for triage
 4. **Fresh future intents** — offer as next work
+
+## References
+
+- Read `references/context-management.md` for the full save/continue protocol when resuming from a savepoint or when the resume flow needs debugging

package/skills/continuing/references/context-management.md

@@ -0,0 +1,32 @@
+# Context Management (Start-Save-Continue)
+
+## Save Point
+Triggered by PreCompact hook or manually:
+1. Find active intent(s) from `~/.plastic/INDEX.md`
+2. Update active intent's `checklist.md` (check off completed items)
+3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
+4. Add observations to `## Insights`
+5. Update INDEX.md
+6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
+7. Notify user to `/clear`
+
+## Continue
+Triggered by UserPromptSubmit hook when user says "continue". Priority order:
+
+**1. Active intents first (resume work):**
+1. Read INDEX.md → find active intent(s)
+2. Read active intent's `intent.md` → what and why
+3. Read active intent's `savepoint.md` → where we left off
+4. Read active intent's `checklist.md` → what's next
+5. Announce: intent name, current state, next step, blockers
+6. Resume
+
+**2. No active intents → offer future intents:**
+1. List all future intents from INDEX.md
+2. Present them as options
+3. When user picks one, move to Active in INDEX.md
+
+**3. Stale future intents (untouched 3+ days) → triage:**
+- **activate** — start working on it now
+- **abandon** — mark as abandoned
+- **defer to agent** — implement, research, or ideate

package/skills/creating-intent/SKILL.md

@@ -120,3 +120,8 @@ cd <store-root> && git add . && git commit -m "feat: create intent ID — [name]
 ### 8. Announce
 
 "Created intent ID — [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
+
+## References
+
+- Read `references/lifecycle.md` for the full What→Why→How→Exec stage detail, filesystem-as-schema conventions, and creating-intent step-by-step
+- Read `references/wikilinks.md` for the wikilink syntax table when adding `## Links` to intents

package/skills/creating-intent/references/lifecycle.md

@@ -0,0 +1,74 @@
+# Building an Intent — Full Lifecycle Detail
+
+## What → `## Intent` section
+
+The desire. One paragraph. What the human or agent wants.
+This exists from the moment the intent is created.
+
+**Deliverable:** `{ID}--{slug}.md`
+
+## Why → `## Context` + `### Decisions` sections
+
+Why this intent exists. Grows over time through brainstorming and exploration.
+
+- **Context** — what we knew going in + what we decided along the way
+- **Decisions** — main premises derived from Context plus decisions from brainstorming/grilling
+- Decisions are Why-level: "status belongs on actions because multiple workstreams", not How-level: "use ACTION_N.md files"
+
+**Deliverable:** `spec.md` (consolidated specification from Context + Decisions + brainstorming)
+
+## How → Planning and preparation
+
+Research decisions, create the implementation plan, define actions.
+
+**Deliverable:** `plan.md` + `actions/` + `checklist.md` (execution registry with checkboxes covering all actions)
+
+## Exec → Execute actions
+
+Execute actions from the plan, track progress via checklist.
+
+**Deliverable:** `outcome.md` (detailed result). `## Outcome` in intent.md = short summary written as last step.
+
+## `## Insights` — Append-only work log
+
+Captured throughout ALL stages. One-liner bullet points.
+Never modified, only appended.
+
+Tracks: stage transitions, decisions, shifts, blocks, cancellations, material for future intents.
+This is how execution is tracked. When this intent completes, Insights
+is where to look for what comes next. New intents spawned from Insights
+appear in the `chain` field.
+
+## `## Links`
+
+Wikilinks for Obsidian graph navigation. Human-facing counterpart to the
+frontmatter knowledge graph.
+
+## Conventions — Filesystem as Schema
+
+State is derived from what exists, not from what's declared.
+
+| Convention | Signal |
+|---|---|
+| No `## Context` | Intent is fleeting (quick capture, non-actionable) |
+| `## Context` has content | Intent is permanent (developed, actionable) |
+| `## Outcome` has content | Intent is done |
+| `## Insights` has `(autonomous)` entries | Intent is/was being delivered autonomously |
+
+### Transitions
+
+- Fleeting → permanent: add `## Context` (one-way, also makes it actionable)
+- There is no separate "non-actionable → actionable" transition — permanence implies actionability
+- Even research intents are actionable: the research itself is the action, the conclusion is the outcome
+
+## Creating an Intent — Full Steps
+
+1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
+2. Determine the Folgezettel ID: If root (no parent), find highest root number +1. If branch, run `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
+3. Create the intent directory in the chosen store (e.g., `ID--three-to-five-words`)
+4. Create `{ID}--{slug}.md` with frontmatter (id, intent, sources, chain, created, author, tags)
+5. Write `## Intent` — the What
+6. Add remaining sections: `## Context`, `## Outcome`, `## Insights`, `## Links`
+7. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
+
+A fleeting intent can skip `## Context` — just `## Intent` and empty sections.

package/skills/creating-intent/references/wikilinks.md

@@ -0,0 +1,8 @@
+# Wikilink Conventions
+
+| Syntax | Meaning |
+|--------|---------|
+| `[[ID]]` | Link to intent in same store (e.g., `[[1a1]]`) |
+| `[[ID\|display text]]` | Link with human-readable label |
+| `[[global:ID]]` | Link to intent in `~/.plastic/store/` |
+| `[[project-slug:ID]]` | Link to intent in `~/.plastic/projects/{slug}/store/` |

package/skills/creating-project/SKILL.md

@@ -164,3 +164,7 @@ Log in `## Insights` of each founding intent:
 
 Announce to user:
 > "Project `<slug>` created at `<path>`. AGENTS.md populated with [N] decisions from [founding intent IDs]. Tactical mirror `1` is now the active intent in the project store."
+
+## References
+
+- Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/creating-project/references/hubs-projects.md

@@ -0,0 +1,55 @@
+# Hubs and Projects
+
+## Hubs
+
+A Hub is a cloud of intents around related topics. Hubs emerge naturally from
+Folgezettel branching — intents that spawn in the same direction cluster.
+
+- A Hub can spawn a Project. The Hub holds the founding ideas.
+- A single intent can also spawn a Project.
+- Hub-spawned projects revolve around different ideas around related topics.
+- Intent-spawned projects revolve around the single founding intent.
+- A Project is the deliverable outcome of one or more intents.
+
+Hubs are represented as clusters in INDEX.md.
+
+## Projects — Full Detail
+
+A Project is a deliverable grouping of intents. Projects have two stores:
+
+- **Global store** (`~/.plastic/store/`): strategic intents
+- **Project store** (`~/.plastic/projects/{slug}/store/`): tactical intents
+
+`projects.yml` maps project slugs to codebase paths:
+```yaml
+projects:
+  plastic:
+    path: "/path/to/plastic"
+    remote: "git@github.com:org/plastic.git"
+    registered: '2026-05-26'
+    status: active
+```
+
+Config resolution: `~/.plastic/projects/{slug}/config.yml` overrides `~/.plastic/config.yml`.
+
+Cross-linking: project intents reference global intents via `[[global:ID]]`. Global intents reference project intents via `[[project-slug:ID]]`.
+
+## Privacy and Collaboration
+
+**Plastic is personal.** All intent data lives under `~/.plastic/` — one location,
+one git repo, never pushed. Each person has their own intent store.
+
+Collaboration happens through pull requests and project conventions, not shared intents.
+When an intent delivers something that changes how a project works, the decision gets
+written into the project's shared files (README, docs, config). The intents themselves
+are private working memory.
+
+## Project Creation Flow
+
+When an implementation intent spawns a project:
+1. Determine project path from config `project_roots` or intent context
+2. `gh repo create --private` (agent-created repos are always private by default)
+3. Set up project directory, git init, AGENTS.md with founding intent decisions
+4. Register in `projects.yml`
+5. Create tactical mirror in project store
+6. The global intent completes; the tactical mirror becomes the active intent

package/skills/doctor/SKILL.md

@@ -110,3 +110,7 @@ This keeps the update flow clean when nothing is wrong.
 - The script outputs JSON to stdout. Any diagnostic errors go to stderr.
 - Non-zero exit codes mean "issues found", not "script crashed".
   Always parse stdout regardless of exit code.
+
+## References
+
+- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and stuck detection thresholds when diagnosing gate failures or stuck agents

package/skills/doctor/references/gates-stuck-detection.md

@@ -0,0 +1,38 @@
+# Gate Enforcement and Stuck Detection
+
+## Bridge File Pattern
+
+`/tmp/plastic-{session}.json` is the hot cache; the filesystem is the authority.
+SessionStart rebuilds the bridge file from the filesystem — the bridge is always disposable.
+
+## Gate Taxonomy
+
+| Gate type | Purpose |
+|---|---|
+| **Pre-flight** | Prerequisites exist? |
+| **Revision** | New info invalidated prior work? |
+| **Escalation** | Blocked items surface to user |
+| **Abort** | Inconsistent state detected |
+
+## Full Gate Enforcement
+
+| Gate | Blocked action | Required prerequisite |
+|---|---|---|
+| Pre-flight | Cannot write `plan.md` | `spec.md` must exist |
+| Pre-flight | Cannot create `actions/` | `spec.md` must exist |
+| Pre-flight | Cannot write `outcome.md` | `checklist.md` must exist with all items checked |
+| Revision | Cannot proceed to Exec | Context changed after spec.md — re-derive spec |
+| Abort | Cannot complete intent | `outcome.md` exists but checklist has unchecked items |
+
+Hard blocking — hooks exit with code 2 when gates fail.
+
+## Stuck Detection
+
+| Condition | Threshold | Action |
+|---|---|---|
+| Consecutive gate failures | 3+ | Warning |
+| Consecutive gate failures | 5+ | Force savepoint + escalate |
+| No activity | 5+ min | Warning |
+| No activity | 10+ min | Force savepoint + escalate |
+| Context pressure | 80% | Warning |
+| Context pressure | 90% | Force savepoint |

package/skills/evaluating-skills/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: evaluating-skills
+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".
+---
+
+# 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/evaluating-skills/assets/eval-template.json

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

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

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

@@ -0,0 +1,76 @@
+# 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 |