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

package/skills/releasing/SKILL.md

@@ -1,30 +1,67 @@
 ---
-name: plastic:releasing
+name: plastic-releasing
 description: Use when merging a feature branch to main and tagging a release, bumping the version, or when the user says "release", "tag", or "ship it"
 ---
 
 # Releasing
 
 Merge, bump, tag, push. Annotated tags with changelogs. Semantic versioning.
+Project configuration drives the workflow — no hardcoded assumptions.
 
 ## Checklist
 
-- [ ] All tests pass
+- [ ] Read project config
+- [ ] All tests pass (or verification skipped per config)
 - [ ] Merge feature branch to main
-- [ ] Bump version in plugin.json and marketplace.json
+- [ ] Bump version in configured version files
 - [ ] Commit version bump
 - [ ] Create annotated tag
 - [ ] Push to remote with tags
+- [ ] Run post-push actions (GitHub release, npm publish, etc.)
+- [ ] Complete active intent
 
 ## Workflow
 
+### 0. Read Project Config
+
+Before anything else, determine which project we are releasing and load its config.
+
+1. Read `~/.plastic/projects.yml` — find the project whose `path` matches the current working directory.
+2. Extract the project slug (the key under `projects:`).
+3. Read `~/.plastic/projects/{slug}/project.yml` — this contains the `release:` section.
+
+Expected `release:` keys in project.yml:
+
+```yaml
+release:
+  verify: "bin/rails test"              # command to run before release
+  version_file: package.json            # single file containing the version
+  version_files:                        # multiple files (overrides version_file)
+    - package.json
+    - .claude-plugin/plugin.json
+  tag_format: "v{{version}}"            # tag naming pattern ({{version}} is replaced)
+  on_green:                             # actions to run after push succeeds
+    - github_release
+    - npm_publish
+  on_complete: commit_and_push          # what to do with the version bump commit
+  on_red: stop                          # what to do if verification fails
+```
+
+**Fallback:** If no project.yml exists or it has no `release:` section, fall back to asking the user for each step — verify command, version files, tag format, and post-push actions.
+
 ### 1. Verify Tests Pass
 
+Run the verification command from `release.verify` in project.yml:
+
 ```bash
-ruby test/read_config_test.rb && ruby test/config_template_test.rb
+# Example: release.verify = "ruby -Itest test/*_test.rb"
+<verify-command-from-config>
 ```
 
-All tests must pass before release. Do not proceed if any fail.
+- If `release.verify` is present: run it. All checks must pass before proceeding.
+- If `release.verify` is absent or empty: skip verification. Log that no verify command is configured.
+- If `release.on_red` is `stop`: abort the release on failure.
+- If `release.on_red` is `fix_and_retry`: ask the user to fix and re-run.
 
 ### 2. Determine Version Bump
 
@@ -47,18 +84,26 @@ Always `--no-ff` to preserve branch history in the merge commit.
 
 ### 4. Bump Version
 
-Update ALL THREE files — they must stay in sync:
-- `package.json` → `"version": "X.Y.Z"`
-- `.claude-plugin/plugin.json` → `"version": "X.Y.Z"`
-- `.claude-plugin/marketplace.json` → `"version": "X.Y.Z"`
+Determine which files to update from project.yml:
+
+- If `release.version_files` is set: update ALL listed files (they must stay in sync).
+- Else if `release.version_file` is set: update that single file.
+- Else: ask the user which files contain the version.
+
+Update the version string in each file, then commit:
 
 ```bash
-git add package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json
+git add <version-files>
 git commit -m "chore: bump version to X.Y.Z — [one-line summary]"
 ```
 
 ### 5. Create Annotated Tag
 
+Read `release.tag_format` from project.yml to determine the tag name:
+
+- If set (e.g. `"v{{version}}"`): replace `{{version}}` with the new version string.
+- If not set: default to `vX.Y.Z`.
+
 Generate the changelog from commits since the last tag:
 
 ```bash
@@ -68,7 +113,7 @@ git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges | grep -E
 Create the tag with a multi-line message:
 
 ```bash
-git tag -a vX.Y.Z -m "vX.Y.Z — [release name]
+git tag -a <tag-name> -m "<tag-name> — [release name]
 
 - [changelog bullet points from feat/fix/refactor commits]"
 ```
@@ -79,16 +124,50 @@ git tag -a vX.Y.Z -m "vX.Y.Z — [release name]
 git push origin main --tags
 ```
 
-### 7. GitHub Release
+### 7. Post-Push Actions
 
-Create a GitHub release from the tag. Use `--generate-notes` to auto-generate changelog from commits since the previous tag:
+Read `release.on_green` from project.yml. This is a list of actions to run after a successful push. Execute each in order:
+
+#### `github_release`
+
+Create a GitHub release from the tag:
 
 ```bash
-gh release create vX.Y.Z --title "vX.Y.Z — [release name]" --generate-notes --notes-start-tag <previous-tag>
+gh release create <tag-name> --title "<tag-name> — [release name]" --generate-notes --notes-start-tag <previous-tag>
 ```
 
 For the first release (no previous tag), write notes manually with `--notes "..."` instead.
 
+#### `npm_publish`
+
+Publish the package to npm with the appropriate dist-tag:
+
+```bash
+# Alpha pre-release (version contains -alpha):
+npm publish --access public --tag alpha
+
+# Beta pre-release (version contains -beta):
+npm publish --access public --tag beta
+
+# Stable release (no pre-release suffix, >= 1.0.0):
+npm publish --access public
+```
+
+The dist-tag is derived from the version string in `package.json`:
+- Contains `-alpha` → `--tag alpha`
+- Contains `-beta` → `--tag beta`
+- No pre-release suffix → no `--tag` flag (publishes to `latest`)
+
+#### Other values
+
+If `on_green` contains an action not listed above, log it:
+
+```
+[releasing] Action "<action>" is configured but not yet implemented. Skipping.
+```
+
+If `on_green` is empty or absent: skip post-push actions entirely.
+
 ### 8. Complete Active Intent
 
 A release IS a delivery. The active intent that drove this work must be completed as part of the release process. This is NOT optional.
@@ -100,19 +179,37 @@ A release IS a delivery. The active intent that drove this work must be complete
    c. Update `## Insights` with final observations
    d. Move from `## Active` to `## Completed` in INDEX.md (with today's date)
    e. Update clusters to show `_(completed)_`
-3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> — delivered in v<X.Y.Z>"`
+3. Auto-commit: `cd ~/.plastic && git add . && git commit -m "feat: complete intent <ID> — delivered in <tag-name>"`
 
 **If no active intent exists for this release**, that itself is a problem — work happened outside the intent system. Log it and move on, but flag it.
 
 ## Conventions
 
 - **Annotated tags only** — `git tag -a`, never lightweight tags
-- **Tag format** — `vX.Y.Z` (lowercase v prefix)
-- **Tag message** — first line: `vX.Y.Z — [short name]`, then blank line, then bullet changelog
+- **Tag format** — driven by `release.tag_format` in project.yml (default: `vX.Y.Z`)
+- **Tag message** — first line: `<tag> — [short name]`, then blank line, then bullet changelog
 - **Commit prefixes** — `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
-- **Version files** — package.json, plugin.json, and marketplace.json always match
+- **Version files** — driven by project.yml; all listed files must always match
 - **Branch cleanup** — delete merged feature branches: `git branch -d <branch>`
 
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic-releasing --promote beta    # promotes current alpha → beta
+plastic-releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
 ## Retroactive Tagging
 
 For repos without prior tags, tag historical releases:
@@ -122,3 +219,7 @@ git tag -a v0.1.0 <commit-sha> -m "v0.1.0 — [description]"
 ```
 
 Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).
+
+## References
+
+- Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/deprecations.md

@@ -0,0 +1,44 @@
+# Deprecation Process
+
+When removing a feature, changing a convention, or making a breaking change:
+
+1. Add entry to `deprecations.yml` in the Plastic source root
+2. Set severity: `info` (awareness), `warning` (action needed), `critical` (urgent)
+3. Provide clear migration steps
+4. Set `removal` version at least 2 minor versions ahead
+5. SessionStart hook displays active deprecations automatically
+6. Remove the feature AND the deprecation entry together
+
+## Severity Levels
+
+| Severity | When to use | Dismissable? |
+|----------|-------------|--------------|
+| `info` | Upcoming change | Yes |
+| `warning` | Action needed | Yes (re-shown at removal) |
+| `critical` | Urgent/security | Never |
+
+## deprecations.yml Schema
+
+```yaml
+deprecations:
+  - id: unique-slug
+    severity: info | warning | critical
+    summary: "One-line description"
+    migration_steps:
+      - "Step 1"
+      - "Step 2"
+    introduced: "0.9.0"
+    removal: "1.0.0"
+    link: "optional URL"
+```
+
+## Dismissal
+
+Users dismiss by adding the id to `deprecations_dismissed` in `config.yml`:
+
+```yaml
+deprecations_dismissed:
+  - some-deprecated-feature
+```
+
+Critical deprecations and final-version warnings ignore dismissal.

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.