@zalom/plastic 1.0.0-beta.8 → 1.0.0

package/skills/writing-plans/references/plan-format.md

@@ -0,0 +1,102 @@
+# Plan, Checklist, and Action Format
+
+The exact templates for `plan.md`'s header and task structure, and for the
+`checklist.md` and `actions/ACTION_N.md` artifacts. Read this before writing
+plan.md so the shape matches on the first pass.
+
+## Table of Contents
+
+- [Plan Document Header](#plan-document-header)
+- [Task Structure (worked example)](#task-structure-worked-example)
+- [checklist.md format](#checklistmd-format)
+- [actions/ACTION_N.md format](#actionsaction_nmd-format)
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Intent:** {id} — {name}
+
+---
+```
+
+## Task Structure (worked example)
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.rb`
+- Modify: `exact/path/to/existing.rb:123-145`
+- Test: `test/exact/path/to/test.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+def test_specific_behavior
+  result = function(input)
+  assert_equal expected, result
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: FAIL with "undefined method"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ruby
+def function(input)
+  expected
+end
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/path/test.rb lib/path/file.rb
+git commit -m "feat: add specific feature"
+```
+````
+
+## checklist.md format
+
+Execution registry with one checkbox per task. Format:
+
+```markdown
+# Checklist — Intent {id}: {name}
+
+- [ ] Task 1: {task title}
+- [ ] Task 2: {task title}
+- [ ] Task 3: {task title}
+...
+```
+
+## actions/ACTION_N.md format
+
+One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
+
+```markdown
+# Action {N}: {task title}
+
+{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
+```
+
+Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`

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/templates/roadmap.md

@@ -0,0 +1,30 @@
+# Roadmap: <name>
+
+(one-line meta: what this roadmap delivers, and which tier it lives in. `roadmaps/` is a sibling
+of `INDEX.md` — a project's root or the global `~/.plastic/`, never inside `store/`. When this
+roadmap's goal is reached, move this file from `roadmaps/{slug}.md` to
+`roadmaps/archived/{slug}.md`; `roadmaps/` itself lists only live roadmaps.)
+
+## Goal
+(a checkable prose condition — one or a few sentences a human or coordinator reads to decide the
+roadmap is done. Not an executable checker.)
+
+## Waves
+Entries in a wave are parallel-safe; waves run top to bottom. The checkbox is checked once an entry
+is delivered, unchecked otherwise; the trailing token after the em-dash is the precise mirrored
+status (queued | delivering | delivered | abandoned | blocked) from INDEX.md. INDEX always wins on
+any conflict between the checkbox/token here and INDEX's real status.
+
+### Wave 1
+- [ ] <intent-id> <title> — queued
+- [ ] <intent-id> <title> — queued
+
+### Wave 2
+- [x] <intent-id> <title> — delivered
+
+## Log
+(append-only, dated, one line per event. Each line is one plain-language, EM-to-CTO-voice sentence:
+what shipped and its impact for a non-expert reader, no jargon or internal codenames, ending with a
+link to that entry-intent's `outcome.md`. Never restate outcome detail here; link to it instead.
+Newest at the bottom.)
+- 2026-01-01 00:00 UTC Shipped the first wave of this roadmap; see store/<intent-id>--<slug>/outcome.md.

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