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

package/skills/research/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: plastic-research
+description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
+---
+
+# Research
+
+Investigate a topic related to the active intent. Choose the right depth, produce a cited report.
+
+**Announce at start:** "I'm researching [topic] for 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}/`
+
+## Depth Decision
+
+Before starting research, assess the question against these criteria:
+
+### Shallow Research
+Use when:
+- The question is narrow and factual (e.g., "what's the API for X?", "does library Y support Z?")
+- A single source or quick search is sufficient
+- The answer is likely well-documented
+- Time budget: minutes, not hours
+
+**Method:** Direct web search + codebase exploration + single-pass synthesis.
+
+### Deep Research
+Use when:
+- The question needs multiple sources and cross-verification
+- It's a landscape survey, competitive analysis, or architectural decision
+- The user explicitly asks for thorough/exhaustive/comprehensive research
+- Conflicting information exists and needs adversarial verification
+- Time budget: significant, user expects depth
+
+**Method:** Delegate to the native agent's deep research capability.
+- On Claude Code: invoke the `deep-research` skill via `Skill` tool
+- On other agents: use the agent's equivalent (see intent 7 for cross-agent mapping)
+- If no native deep research exists: fan out multiple web searches manually, cross-reference, synthesize
+
+### Decision Heuristic
+
+Ask yourself:
+1. Can I answer this with 1-2 searches? → **Shallow**
+2. Do I need to compare 3+ sources? → **Deep**
+3. Is the user asking for a survey or landscape view? → **Deep**
+4. Am I fact-checking a specific claim? → **Shallow**
+5. Could wrong information here cause architectural mistakes? → **Deep**
+
+Announce your choice: "This needs [shallow/deep] research because [reason]."
+
+## Output
+
+### File Location
+`{intent_dir}/resources/{type}--{topic}.md`
+
+Create the resources/ directory if it doesn't exist.
+
+### Naming Convention
+- `{type}` — one of: `deep-research`, `competitive-analysis`, `technical-spike`, `reference`, `landscape-survey`
+- `{topic}` — kebab-case description of the research subject
+
+Examples:
+- `deep-research--installer-patterns.md`
+- `technical-spike--sqlite-vec-performance.md`
+- `reference--claude-code-hooks-api.md`
+- `landscape-survey--ai-agent-ecosystem.md`
+
+### Report Structure
+
+```markdown
+# {Type}: {Topic}
+
+**Intent:** {id} — {name}
+**Depth:** shallow | deep
+**Date:** YYYY-MM-DD
+
+## Summary
+[2-3 sentence executive summary]
+
+## Findings
+
+### [Finding 1 title]
+[Details with inline citations where applicable]
+
+### [Finding 2 title]
+...
+
+## Sources
+- [Source 1 title](url) — what was learned from this source
+- [Source 2 title](url) — ...
+
+## Relevance to Intent
+[How these findings affect the active intent's decisions or design]
+```
+
+## After Research
+
+1. Commit to store repo:
+   ```
+   cd {store_root} && git add . && git commit -m "research: {type} — {topic} (intent {id})"
+   ```
+
+2. Log in intent's `## Insights`:
+   ```
+   - Research: {type} — {topic}. Key finding: [one sentence]. See resources/{filename}.
+   ```
+
+3. Research does NOT chain to any other skill. It's a side quest — the user decides what to do with the findings.

package/skills/savepoint/SKILL.md

@@ -1,57 +1,66 @@
 ---
-name: plastic:savepoint
-description: Use when context is being compacted (PreCompact hook), user says "save" or "savepoint", or before ending a session. Saves the active intent's state so work can resume after /clear.
+name: plastic-savepoint
+description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
 ---
 
 # Savepoint
 
-## When to Use
-- PreCompact hook fires (automatic)
-- User says "save", "savepoint", or "save progress"
-- Before ending a long session
-- Before switching to a different intent
+`savepoint.md` is a deterministic, append-only ledger of an intent's cycle steps, one line
+per lifecycle milestone, newest at the bottom:
 
-## Workflow
+```
+2026-06-16T14:02Z  What  34--cycle-step-savepoints.md
+2026-06-16T14:20Z  Why   spec.md created
+2026-06-16T15:10Z  How   plan.md created
+2026-06-16T15:11Z  How   checklist.md created
+2026-06-16T16:40Z  Exec  outcome.md created
+```
 
-### 1. Find Active Intent(s)
-Read `~/.plastic/INDEX.md` (or the project INDEX.md) and extract all intents listed under `## Active`.
+It is **sugar on top of the conventions**, not a source of truth. The gate hook
+(`hook-gate-check`) writes each line automatically when a stage file is created, so there is
+nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
+a resuming agent read the cycle's succession from one glance (last line = where we are).
 
-### 2. For Each Active Intent
-Read the intent directory at `~/.plastic/store/ID--slug/`:
+## When to Use
+- A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
+- Resuming an intent: read the ledger to learn the cycle's succession quickly.
+- The ledger looks stale, empty, or missing: rebuild it from the filesystem.
 
-**a. Update checklist.md** (if exists):
-- Check off completed items
-- Add any new items discovered during the session
+## What this skill does NOT do
+- It does not write prose, "in progress", "next step", or "blockers". The old 50%-context
+  prose savepoint is retired. The semantic trace lives in `## Insights` (append-only,
+  newest at the bottom); the byte history lives in git.
 
-**b. Create/update savepoint.md:**
-```markdown
-# Savepoint
+## Workflow
 
-## Last Updated
-{{DATE}} — Session #{{N}}
+### 1. Find Active Intent(s)
+Read the active store's `INDEX.md` and extract intents under `## Active`.
 
-## In Progress
-- (what was being worked on when savepoint triggered)
-- Next: (immediate next step)
+### 2. For Each Active Intent — verify the ledger
+- Read `savepoint.md`. Confirm it exists and is non-empty.
+- Confirm the **last line's stage** matches the stage derived from files-on-disk
+  (`Bridge.derive_stage`). If they disagree, or the file is missing/empty, the ledger has
+  drifted.
 
-## Blockers
-(any blockers or open questions)
+### 3. Rebuild on drift
+Reconstruct from the filesystem rather than hand-editing:
 
-## Key Discoveries This Session
-- (important things learned)
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.rebuild_savepoint("<intent_dir>")'
 ```
 
-**c. Update `{ID}--{slug}.md`:**
-- Add observations to `## Insights` section
-
-### 3. Update INDEX.md
-Verify the `## Active` section is accurate.
+This rewrites `savepoint.md` from the milestone files present (timestamps from mtimes),
+in stage order. Safe to run anytime: the ledger is derived.
 
-### 4. Commit
+### 4. Commit (store only)
+If a rebuild changed the ledger, commit it in the store repo:
 ```bash
-git add .plastic/
-git commit -m "chore: savepoint — [active intent name]"
+cd <store-root> && git add . && git commit -m "chore: rebuild savepoint ledger — [intent]"
 ```
+Never push `~/.plastic/`.
+
+## References
 
-### 5. Notify User
-Tell the user: "Context is getting large. I've saved progress to intent [ID] — [name]. Please run `/clear` and say `continue` to resume."
+- Read `references/context-management.md` for the full save/continue protocol and how the
+  resume flow consumes the ledger.

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/uninstall/SKILL.md

@@ -1,48 +1,59 @@
 ---
-name: plastic:uninstall
-description: Use when the user wants to remove Plastic. Deregisters the plugin from the current agent (Claude Code, Cursor, etc.) and optionally deletes all data.
+name: plastic-uninstall
+description: Use when the user wants to remove Plastic from an agent. Runs the manifest-driven uninstaller (removes skills, hooks, statusline, and any legacy plugin layout), reports exactly what was removed and what was left behind, then gives verification steps. Optionally deletes the intent store.
 ---
 
 # Uninstall Plastic
 
-## Procedure
+The installer tracks every file it writes in a manifest, so uninstall is exact and
+leaves no orphans. Prefer running it through the CLI; this skill wraps the same
+underlying uninstaller and adds reporting + verification.
 
-### Step 1: Detect the current agent
+## Procedure
 
-Check environment variables to determine which agent is running:
-- `$CLAUDE_PLUGIN_ROOT` → Claude Code
-- `$CURSOR_PLUGIN_ROOT` → Cursor
-- Otherwise → unknown agent
+### Step 1: Run the uninstaller
 
-### Step 2: Deregister from the agent
+```bash
+npx @zalom/plastic@latest uninstall --claude
+```
 
-**Claude Code:**
-- Remove `"plastic"` from `extraKnownMarketplaces` in `~/.claude/settings.json`
-- Remove `"plastic@plastic"` from `enabledPlugins` in `~/.claude/settings.json`
-- Announce: "Plastic deregistered from Claude Code."
+(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx` works too.)
 
-**Other agents:** Provide manual instructions for their deregistration process.
+This removes, for the targeted agent:
+- all `~/.claude/skills/plastic-*/` skills
+- all `~/.claude/hooks/plastic-*` hooks (and restores any saved original statusline)
+- the `~/.claude/plastic/` state dir + manifest
+- any **legacy** plugin layout: `plugins/marketplaces/plastic`, `plugins/cache/plastic`,
+  the old nested `skills/plastic/`, and the `plastic@plastic` /
+  `extraKnownMarketplaces.plastic` / `known_marketplaces.json` registrations
 
-### Step 3: Offer the data decision
+### Step 2: Report removed vs left
 
-Present clearly:
+Relay the uninstaller's output to the user — what was **removed** and what was
+**left in place**:
+- **Left:** `~/.plastic/` (intent store, history, projects) and any non-Plastic
+  settings.json entries.
 
-```
-Plastic is deregistered from [agent name].
+### Step 3: Verify removal
 
-Your intent store at ~/.plastic/ is untouched.
+Tell the user to confirm:
 
-Would you like to delete your Plastic data now?
+```bash
+ls ~/.claude/skills | grep '^plastic-'    # → no output
+ls ~/.claude/hooks  | grep '^plastic-'    # → no output
+grep -n plastic ~/.claude/settings.json   # → no plastic hook/plugin refs
+```
 
-⚠️  WARNING: This permanently removes ALL intents, history,
-and any projects in ~/.plastic/projects/.
-This is irreversible.
+### Step 4: Offer the data decision
 
-a) Keep everything (recommended) — you can re-install Plastic later
-b) Delete everything now — removes ~/.plastic/ entirely
 ```
+Plastic is uninstalled from [agent].
+Your intent store at ~/.plastic/ is untouched.
 
-### Step 4: Execute user's choice
+Delete it too?
+  a) Keep everything (recommended) — re-install anytime with npx
+  b) Delete everything now — removes ~/.plastic/ entirely (irreversible)
+```
 
-- **Keep:** Done. Tell the user: "Your data is at ~/.plastic/. Re-install anytime with `/plastic:install`."
-- **Delete:** Run `rm -rf ~/.plastic/` and confirm: "Plastic data deleted."
+- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with `npx @zalom/plastic@latest install --claude`."
+- **Delete:** run `rm -rf ~/.plastic/` and confirm.

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.