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

package/skills/savepoint/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/update/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: update
-description: Use when updating Plastic after a plugin update, or when the user says "update plastic". Runs the npx installer to sync core files and re-register agent adapters.
+name: plastic:update
+description: Use when updating Plastic. Queries npm for available versions across all channels, presents options interactively, or accepts --alpha/--beta/--latest flags for direct update.
 ---
 
 # Update Plastic
@@ -10,43 +10,98 @@ description: Use when updating Plastic after a plugin update, or when the user s
 - Statusline shows "Plastic update available"
 - After a version bump notification
 
+## Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--alpha` | Update to latest alpha, skip interactive prompt |
+| `--beta` | Update to latest beta, skip interactive prompt |
+| `--latest` | Update to latest stable, skip interactive prompt |
+
+No flag = interactive mode (show all available versions).
+
 ## Prerequisites
 
 Global install must exist (`~/.plastic/INDEX.md` present). If not, tell the
-user to run `npx @zalom/plastic@latest` first.
+user to run `npx @zalom/plastic@alpha --claude` first.
 
 ## Procedure
 
-### Step 1: Verify global install exists
+### Step 1: Read current version
+
+```bash
+cat ~/.plastic/VERSION
+```
+
+Parse the version string to determine the current channel:
+- Contains `-alpha` → alpha channel
+- Contains `-beta` → beta channel
+- No pre-release suffix → stable/latest channel
+
+### Step 2: Query npm for available versions
 
 ```bash
-if [ ! -f ~/.plastic/INDEX.md ]; then
-  echo "No global install found. Run: npx @zalom/plastic@latest"
-  exit
-fi
+npm view @zalom/plastic dist-tags --json
+```
+
+This returns a JSON object like:
+```json
+{
+  "latest": "0.0.1",
+  "alpha": "1.0.0-alpha.14",
+  "beta": "1.0.0-beta.2"
+}
+```
+
+A missing dist-tag means no release exists on that channel.
+
+### Step 3: Present options or act on flag
+
+**If a channel flag was provided** (`--alpha`, `--beta`, `--latest`):
+
+Skip the interactive prompt. Install the flagged channel directly. Go to Step 4.
+
+**If no flag (interactive mode):**
+
+Present the available updates to the user:
+
 ```
+Currently installed: 1.0.0-alpha.11 (alpha channel)
 
-### Step 2: Run the installer
+Available updates:
+  alpha:  1.0.0-alpha.14  ← your channel
+  beta:   1.0.0-beta.2
+  stable: (no stable release yet)
+
+Which channel do you want to install?
+```
+
+Use AskUserQuestion with the available channels as options. Mark the user's
+current channel with "← your channel". If a dist-tag points to the same
+version as currently installed, show "(up to date)" instead of the version.
+If a dist-tag doesn't exist, show "(no release yet)".
+
+Wait for user selection.
+
+### Step 4: Run the installer
 
 ```bash
-npx @zalom/plastic@latest --claude
+npx @zalom/plastic@{selected-tag} --claude
 ```
 
-This re-runs the installer which:
-- Downloads the latest version from npm
-- Syncs core files (PLASTIC.md, scripts, hooks) to ~/.plastic/
-- Re-registers hooks and skills into Claude Code's ~/.claude/
-- Preserves all user data (INDEX.md, config.yml, projects.yml, store/)
+Replace `{selected-tag}` with `alpha`, `beta`, or `latest` based on the
+user's selection or the flag provided. Replace `--claude` with the appropriate
+agent flag(s) — detect current agents from `~/.claude/`, `~/.agents/`,
+`~/.hermes/` directories.
 
-### Step 3: Announce key changes
+### Step 5: Announce key changes
 
 After the installer completes, read `~/.plastic/PLASTIC.md` and announce any
-convention changes that affect the current session. This corrects the agent's
-in-context understanding without needing /clear.
+convention changes that affect the current session.
 
 Format:
 ```
-Plastic updated to vX.Y.Z.
+Plastic updated to vX.Y.Z (channel).
 
 Key changes in this version:
 - [list notable convention changes if any]
@@ -54,24 +109,22 @@ Key changes in this version:
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Run health check
+### Step 6: Run health check
 
 Invoke `plastic:doctor` to verify the installation is healthy after the update.
 
 If all checks pass, show: **"Health check: all clear."**
 
-If issues are found, show the full doctor report and offer to fix any fixable items.
+If issues are found, show the full doctor report and offer to fix.
 
-### Step 5: Commit
+### Step 7: Commit
 
 ```bash
-cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
+cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic to $(cat ~/.plastic/VERSION)" --allow-empty
 ```
 
-### Step 6: Clear update cache
+### Step 8: Clear update cache
 
 ```bash
 rm -f ~/.plastic/.cache/update-check.json
 ```
-
-This removes the statusline warning since the update is now applied.

package/skills/writing-instructions/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: 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

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