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

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. Runs the `update` verb, which reads the installed VERSION, derives its channel, queries npm dist-tags, and advances to the next version on that channel (or switches channel with a flag).
 ---
 
 # Update Plastic
@@ -8,62 +8,67 @@ description: Use when updating Plastic after a plugin update, or when the user s
 ## When to Use
 - User says "update plastic", "sync plastic", or "upgrade plastic"
 - Statusline shows "Plastic update available"
-- After a version bump notification
+- After a version-bump notification
 
-## Prerequisites
+## What it does
 
-Global install must exist (`~/.plastic/INDEX.md` present). If not, tell the
-user to run `npx @zalom/plastic@latest` first.
+`update` is a single deterministic command. It reads `~/.plastic/VERSION`, derives the
+channel from the version string (`-alpha`/`-beta`/none → stable), queries `npm` dist-tags,
+and advances to the **next version on the current channel**. "Already up to date" is a
+clean no-op. You do not compute the target yourself — the script does.
 
-## Procedure
+## Flags
 
-### Step 1: Verify global install exists
+| Flag | Behaviour |
+|------|-----------|
+| (none) | Advance to the next version on the **current** channel |
+| `--latest` | Switch to / advance the **stable** channel (toward stability — frictionless) |
+| `--beta` | Switch to / advance the **beta** channel |
+| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge — confirmed if moving down in stability) |
 
-```bash
-if [ ! -f ~/.plastic/INDEX.md ]; then
-  echo "No global install found. Run: npx @zalom/plastic@latest"
-  exit
-fi
-```
+Switching toward a more stable channel is frictionless; switching toward bleeding edge is
+confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
+
+## Prerequisites
 
-### Step 2: Run the installer
+Plastic must be installed (`~/.plastic/VERSION` present). If not, run
+`npx @zalom/plastic install --claude` first.
+
+## Procedure
+
+### Step 1: Run the update
 
 ```bash
-npx @zalom/plastic@latest --claude
+npx @zalom/plastic update            # next version on the current channel
+# or: npx @zalom/plastic update --beta   /   --latest   /   --alpha
 ```
 
-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/)
+Append the agent flag(s) if not just Claude (`--codex`, `--hermes`, `--all`).
+The command prints the transition (`vX → vY`) or "already up to date", and records the
+move in the append-only `~/.plastic/versions.json` ledger.
 
-### Step 3: Announce key changes
+### Step 2: 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.
+After it completes, read `~/.plastic/PLASTIC.md` and announce 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]
+Key changes:
+- [notable convention changes, if any]
 
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Commit
+### Step 3: Health check
 
-```bash
-cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
-```
+Invoke `plastic-doctor`. If all checks pass: **"Health check: all clear."** Otherwise show
+the report and offer to fix.
 
-### Step 5: Clear update cache
+### Step 4: Commit + clear update cache
 
 ```bash
+cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION versions.json 2>/dev/null && git commit -m "chore: update Plastic to $(cat ~/.plastic/VERSION)" --allow-empty
 rm -f ~/.plastic/.cache/update-check.json
 ```
-
-This removes the statusline warning since the update is now applied.

package/skills/versions/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: plastic-versions
+description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
+---
+
+# Plastic Versions — local version time-machine
+
+## When to Use
+- "show plastic versions", "version history", "what versions have I run"
+- "roll back plastic", "downgrade", "go back to the version that worked", "revert plastic"
+- A new version broke something and the user wants their last known-good build
+
+For upgrading to a **new** release, use `plastic-update`. This skill only navigates
+versions you have **already installed** — the ones recorded in the ledger.
+
+## The ledger
+
+`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+change, never modified or deleted:
+
+```json
+{"version":"1.0.0-alpha.17","action":"install","at":"..."}
+{"version":"1.0.0-alpha.18","action":"update","at":"..."}
+```
+
+`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
+channel is derived from the version string, never stored). It is a troubleshooting record.
+
+## Procedure
+
+### Show history
+
+```bash
+npx @zalom/plastic versions
+```
+
+Prints the table with the currently-installed version marked. If the most recent action was
+a `downgrade`, it asks whether to keep rolling back.
+
+### Roll back
+
+```bash
+npx @zalom/plastic versions --downgrade                    # one step back
+npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+```
+
+Rollback targets are restricted to versions in the ledger (only builds you have actually
+run, so you only ever return to something known-good for you). The chosen version is
+re-fetched from npm and re-synced; your intent store, config, and the ledger are untouched.
+
+### Step forward (after a rollback)
+
+```bash
+npx @zalom/plastic versions --upgrade                      # one step forward in your history
+```
+
+### After any change
+
+Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
+swapped conventions.
+
+## Notes
+- The ledger is **never** edited or pruned — it is the audit trail.
+- Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
+  the user rather than forcing the rollback.

package/skills/writing-instructions/SKILL.md

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

@@ -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

@@ -0,0 +1,183 @@
+---
+name: plastic-writing-plans
+description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and actions/ in the active intent directory."
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to plan intent {id} — {name}."
+
+## Active Intent Gate
+
+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"
+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."
+
+All artifacts go to the intent directory. Never write to external paths.
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## 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
+
+````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"
+```
+````
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any task
+
+## Remember
+- Exact file paths always
+- Complete code in every step — if a step changes code, show the code
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
+
+**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
+
+**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
+
+**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clear_layers` in Task 3 but `clear_full_layers` in Task 7 is a bug.
+
+If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
+
+## Plastic Artifacts
+
+After writing `plan.md`, create two additional artifacts in the intent directory:
+
+### checklist.md
+
+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
+
+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/`
+
+## Git Commit
+
+After writing all artifacts (plan.md, checklist.md, actions/), commit to the store:
+
+```bash
+cd {store_root} && git add . && git commit -m "docs: plan for intent {id} — {name}"
+```
+
+## Execution Handoff
+
+Plan complete. Invoke `plastic-executing-plan` to begin execution.

package/templates/agents.md

@@ -41,6 +41,22 @@ Active/Future/Completed placement is managed in INDEX.md, not in frontmatter.
 4. Set frontmatter: `id`, `intent`, `sources` (array — link to governing intent), `chain` (starts empty), `created`, `author`, `tags`
 5. Add `[[global:ID]]` backlink in `## Links`
 
+## Lifecycle Skills
+
+Plastic has its own lifecycle skills. When a Plastic skill exists for the current phase, use it instead of any external skill (superpowers, superpowers-ruby, etc.).
+
+| 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 |
+
+**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/`.
+
 ## When You're Done
 
 When this project satisfies the governing intent's goal, report back. The orchestrator will complete the strategic intent.