@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

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

package/skills/writing-plans/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:writing-plans
+name: plastic-writing-plans
 description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and actions/ in the active intent directory."
 ---
 
@@ -18,9 +18,9 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 Before proceeding, resolve the active intent:
 
 1. **Detect store:** Read `~/.plastic/projects.yml`, match CWD against registered project paths. If match → project store at `~/.plastic/projects/{slug}/store/`. If no match → global store at `~/.plastic/store/`.
-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"
+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}/`
-4. **Read spec:** Load `{intent_dir}/spec.md`. If no spec exists → refuse: "No spec found. Run /plastic:brainstorming first."
+4. **Read spec:** Load `{intent_dir}/spec.md`. If no spec exists → refuse: "No spec found. Run /plastic-brainstorming first."
 
 All artifacts go to the intent directory. Never write to external paths.
 
@@ -55,7 +55,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For agentic workers:** Use `plastic:executing-plan` to implement this plan task-by-task.
+> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
 
 **Goal:** [One sentence describing what this builds]
 
@@ -180,4 +180,4 @@ cd {store_root} && git add . && git commit -m "docs: plan for intent {id} — {n
 
 ## Execution Handoff
 
-Plan complete. Invoke `plastic:executing-plan` to begin execution.
+Plan complete. Invoke `plastic-executing-plan` to begin execution.

package/templates/agents.md

@@ -47,13 +47,13 @@ Plastic has its own lifecycle skills. When a Plastic skill exists for the curren
 
 | Phase | Skill | Produces |
 |-------|-------|----------|
-| What | `plastic:creating-intent` | Intent file |
-| Why | `plastic:brainstorming` | `spec.md` |
-| Why | `plastic:research` | `resources/*.md` |
-| Why | `plastic:brainstorming-grill-me` | Deep interrogation |
-| How | `plastic:writing-plans` | `plan.md`, `checklist.md`, `actions/` |
-| Exec | `plastic:executing-plan` | Code + `outcome.md` |
-| Done | `plastic:intent-curator` | Lifecycle transition |
+| What | `plastic-creating-intent` | Intent file |
+| Why | `plastic-brainstorming` | `spec.md` |
+| Why | `plastic-research` | `resources/*.md` |
+| Why | `plastic-brainstorming-grill-me` | Deep interrogation |
+| How | `plastic-writing-plans` | `plan.md`, `checklist.md`, `actions/` |
+| Exec | `plastic-executing-plan` | Code + `outcome.md` |
+| Done | `plastic-intent-curator` | Lifecycle transition |
 
 **Artifact convention:** ALL lifecycle artifacts go to the active intent directory (`store/{id}--{slug}/`). Never write specs to `docs/superpowers/specs/` or plans to `docs/superpowers/plans/`.
 

package/templates/outcome.md

@@ -0,0 +1,13 @@
+# Outcome: <intent name>
+
+## Summary
+(what was delivered)
+
+## Delivered
+- ...
+
+## Verification
+- <acceptance criterion> — verified by ... → result
+
+## Follow-ups
+None

package/templates/savepoint.md

@@ -1,13 +1,14 @@
-# Savepoint
-
-## Last Updated
-{{DATE}} — Session #{{N}}
-
-## In Progress
-- ...
-
-## Blockers
-None
-
-## Key Discoveries This Session
-- ...
+# Deterministic cycle-step ledger, written automatically by the gate hook.
+# One line per lifecycle milestone, append-only, newest at the bottom:
+#
+#   {UTC-iso8601}  {Stage}  {milestone}
+#
+# Example:
+#   2026-06-16T14:02:00Z  What  ID--slug.md
+#   2026-06-16T14:20:00Z  Why   spec.md created
+#   2026-06-16T15:10:00Z  How   plan.md created
+#   2026-06-16T15:11:00Z  How   checklist.md created
+#   2026-06-16T16:40:00Z  Exec  outcome.md created
+#
+# This file is sugar on top of the conventions, not a source of truth. It is
+# rebuildable from files-on-disk via Bridge.rebuild_savepoint. Do not hand-edit.

package/templates/spec.md

@@ -0,0 +1,25 @@
+# Spec: <intent name>
+
+## Problem
+(the problem, stated as a problem, not a solution)
+
+## Goals
+- ...
+
+## Non-Goals
+- ...
+
+## Approach
+(the chosen approach, in prose)
+
+## Alternatives Considered
+- <alternative> — not chosen because ...
+
+## Decisions
+- ...
+
+## Acceptance Criteria
+- [ ] ...
+
+## Open Questions
+None

package/bin/install.js

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-
-// Thin shim — npx entry point that delegates to the Ruby installer.
-// All logic lives in scripts/install.rb. JS is only the distribution mechanism.
-
-import { execFileSync } from 'node:child_process'
-import { resolve } from 'node:path'
-import { existsSync } from 'node:fs'
-
-const packageRoot = new URL('..', import.meta.url).pathname
-const installer = resolve(packageRoot, 'scripts', 'install.rb')
-
-if (!existsSync(installer)) {
-  console.error('Error: scripts/install.rb not found in package.')
-  process.exit(1)
-}
-
-try {
-  execFileSync('ruby', [installer, ...process.argv.slice(2)], {
-    stdio: 'inherit',
-    env: { ...process.env, PLASTIC_PACKAGE_ROOT: packageRoot },
-  })
-} catch (err) {
-  if (err.status) process.exit(err.status)
-  console.error('Error: Ruby is required to install Plastic.')
-  console.error('  macOS: Ruby is pre-installed')
-  console.error('  Linux: sudo apt install ruby / dnf install ruby')
-  process.exit(1)
-}