@zalom/plastic 1.0.0-alpha.1

package/skills/managing-index/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: plastic:managing-index
+description: Use after creating, completing, or abandoning intents, when the user says "index" or "organize", or when INDEX.md needs maintenance. Curates the INDEX.md structure note.
+---
+
+# Managing the Index
+
+## When to Use
+- After creating a new intent (automatic — part of creating-intent workflow)
+- After completing or abandoning an intent
+- User says "index", "organize", or "clean up"
+- Periodic maintenance when the store grows
+
+## INDEX.md Structure
+
+INDEX.md is a Zettelkasten main structure note — the brain's entry point. It has four sections:
+
+### Active
+Intents currently being worked on. Max 1-2 for focus.
+```markdown
+## Active
+- [1a2 — Design Plastic](store/1a2--design-plastic-state-system/1a2.md) — decision, human
+```
+
+### Future
+Intents parked for later. May be picked up by agents.
+```markdown
+## Future
+- [1b1 — Build Reddit KB](store/1b1--build-reddit-knowledge-base/1b1.md) — implementation, human
+```
+
+### Clusters
+Topic-based groupings. Manually curated. Create a new cluster when 3+ intents share a topic.
+```markdown
+## Clusters
+### Reddit Knowledge Base
+- [1a — Research](store/1a--research-reddit-saved-posts/1a.md)
+- [1a1 — Plan](store/1a1--plan-reddit-knowledge-base/1a1.md)
+```
+
+### Completed
+All completed intents with dates. Links preserved, never deleted.
+
+## Workflow
+
+### Rebuild Sections
+Scan the active store's `store/` directory for intent files and rebuild each section:
+
+```bash
+for dir in $STORE_ROOT/store/*/; do
+  f=$(find "$dir" -maxdepth 1 -name "*.md" ! -name "spec.md" ! -name "plan.md" ! -name "checklist.md" ! -name "outcome.md" ! -name "savepoint.md" | head -1)
+  [ -n "$f" ] && dirname_slug=$(basename "$dir") && ruby -e '
+    data = File.read(ARGV[0]).split("---")[1]
+    parsed = YAML.safe_load(data)
+    puts "#{parsed["id"]}|#{parsed["intent"]}|#{ARGV[1]}"
+  ' "$f" "$dirname_slug" 2>/dev/null
+done | sort -t'|' -k1
+```
+
+### Suggest Clusters
+When 3+ intents share tags but aren't in a cluster, suggest a new cluster heading.
+
+### Flag Orphans
+Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
+
+REQUIRED BACKGROUND: linking-intents (for understanding connection types and Zettelkasten theory)

package/skills/managing-index/references/zettelkasten-linking.md

@@ -0,0 +1,27 @@
+# Zettelkasten Linking Reference
+
+## Three Structural Layers
+
+1. **Content notes** — individual intents (`~/.plastic/store/ID--slug/ID--slug.md`)
+2. **Structure notes** — INDEX.md clusters that organize related intents
+3. **Main structure note** — INDEX.md itself, the top-level entry point
+
+## Three Connection Types (Ranked)
+
+1. **Direct links** (strongest) — wikilinks in `## Links` section
+2. **Sources/Chain** (knowledge graph) — `sources` array (backward), `chain` array (forward) in frontmatter
+3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
+
+## When to Create a Cluster
+
+A cluster is a structure note heading. Create one when:
+- 3+ intents share a topic but aren't grouped
+- You notice a pattern across intents
+- A topic area is growing and needs an entry point
+
+## Principles
+
+- Links are the primary organizational mechanism, not folders
+- Structure is a lens, not a container — intents remain first-class citizens
+- Clusters are manually curated, not auto-generated
+- Facts are invalidated, never deleted — completed intents stay in INDEX.md

package/skills/releasing/SKILL.md

@@ -0,0 +1,124 @@
+---
+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.
+
+## Checklist
+
+- [ ] All tests pass
+- [ ] Merge feature branch to main
+- [ ] Bump version in plugin.json and marketplace.json
+- [ ] Commit version bump
+- [ ] Create annotated tag
+- [ ] Push to remote with tags
+
+## Workflow
+
+### 1. Verify Tests Pass
+
+```bash
+ruby test/read_config_test.rb && ruby test/config_template_test.rb
+```
+
+All tests must pass before release. Do not proceed if any fail.
+
+### 2. Determine Version Bump
+
+| Change type | Bump | Example |
+|-------------|------|---------|
+| Breaking changes | Major | 0.x.0 → 1.0.0 |
+| New features | Minor | 0.3.0 → 0.4.0 |
+| Bug fixes only | Patch | 0.4.0 → 0.4.1 |
+
+Pre-1.0: minor bumps for features, patch for fixes. No major until stable.
+
+### 3. Merge Feature Branch
+
+```bash
+git checkout main
+git merge <branch-name> --no-ff -m "feat: merge intent [ID] — [description]"
+```
+
+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"`
+
+```bash
+git add package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json
+git commit -m "chore: bump version to X.Y.Z — [one-line summary]"
+```
+
+### 5. Create Annotated Tag
+
+Generate the changelog from commits since the last tag:
+
+```bash
+git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges | grep -E "^[a-f0-9]+ (feat|fix|refactor):"
+```
+
+Create the tag with a multi-line message:
+
+```bash
+git tag -a vX.Y.Z -m "vX.Y.Z — [release name]
+
+- [changelog bullet points from feat/fix/refactor commits]"
+```
+
+### 6. Push
+
+```bash
+git push origin main --tags
+```
+
+### 7. GitHub Release
+
+Create a GitHub release from the tag. Use `--generate-notes` to auto-generate changelog from commits since the previous tag:
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z — [release name]" --generate-notes --notes-start-tag <previous-tag>
+```
+
+For the first release (no previous tag), write notes manually with `--notes "..."` instead.
+
+### 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.
+
+1. Read `~/.plastic/INDEX.md` → find active intent(s) related to this release
+2. For each active intent being delivered:
+   a. Write `outcome.md` with detailed results
+   b. Write `## Outcome` summary in the intent file (reference the release tag)
+   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>"`
+
+**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
+- **Commit prefixes** — `feat:`, `fix:`, `refactor:`, `chore:`, `docs:` (conventional commits)
+- **Version files** — package.json, plugin.json, and marketplace.json always match
+- **Branch cleanup** — delete merged feature branches: `git branch -d <branch>`
+
+## Retroactive Tagging
+
+For repos without prior tags, tag historical releases:
+
+```bash
+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).

package/skills/savepoint/SKILL.md

@@ -0,0 +1,57 @@
+---
+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.
+---
+
+# 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
+
+## Workflow
+
+### 1. Find Active Intent(s)
+Read `~/.plastic/INDEX.md` (or the project INDEX.md) and extract all intents listed under `## Active`.
+
+### 2. For Each Active Intent
+Read the intent directory at `~/.plastic/store/ID--slug/`:
+
+**a. Update checklist.md** (if exists):
+- Check off completed items
+- Add any new items discovered during the session
+
+**b. Create/update savepoint.md:**
+```markdown
+# Savepoint
+
+## Last Updated
+{{DATE}} — Session #{{N}}
+
+## In Progress
+- (what was being worked on when savepoint triggered)
+- Next: (immediate next step)
+
+## Blockers
+(any blockers or open questions)
+
+## Key Discoveries This Session
+- (important things learned)
+```
+
+**c. Update `{ID}--{slug}.md`:**
+- Add observations to `## Insights` section
+
+### 3. Update INDEX.md
+Verify the `## Active` section is accurate.
+
+### 4. Commit
+```bash
+git add .plastic/
+git commit -m "chore: savepoint — [active intent name]"
+```
+
+### 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."

package/skills/uninstall/SKILL.md

@@ -0,0 +1,48 @@
+---
+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.
+---
+
+# Uninstall Plastic
+
+## Procedure
+
+### Step 1: Detect the current agent
+
+Check environment variables to determine which agent is running:
+- `$CLAUDE_PLUGIN_ROOT` → Claude Code
+- `$CURSOR_PLUGIN_ROOT` → Cursor
+- Otherwise → unknown agent
+
+### Step 2: Deregister from the agent
+
+**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."
+
+**Other agents:** Provide manual instructions for their deregistration process.
+
+### Step 3: Offer the data decision
+
+Present clearly:
+
+```
+Plastic is deregistered from [agent name].
+
+Your intent store at ~/.plastic/ is untouched.
+
+Would you like to delete your Plastic data now?
+
+⚠️  WARNING: This permanently removes ALL intents, history,
+and any projects in ~/.plastic/projects/.
+This is irreversible.
+
+a) Keep everything (recommended) — you can re-install Plastic later
+b) Delete everything now — removes ~/.plastic/ entirely
+```
+
+### Step 4: Execute user's choice
+
+- **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."

package/skills/update/SKILL.md

@@ -0,0 +1,69 @@
+---
+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.
+---
+
+# Update Plastic
+
+## When to Use
+- User says "update plastic", "sync plastic", or "upgrade plastic"
+- Statusline shows "Plastic update available"
+- After a version bump notification
+
+## Prerequisites
+
+Global install must exist (`~/.plastic/INDEX.md` present). If not, tell the
+user to run `npx @zalom/plastic@latest` first.
+
+## Procedure
+
+### Step 1: Verify global install exists
+
+```bash
+if [ ! -f ~/.plastic/INDEX.md ]; then
+  echo "No global install found. Run: npx @zalom/plastic@latest"
+  exit
+fi
+```
+
+### Step 2: Run the installer
+
+```bash
+npx @zalom/plastic@latest --claude
+```
+
+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/)
+
+### Step 3: 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.
+
+Format:
+```
+Plastic updated to vX.Y.Z.
+
+Key changes in this version:
+- [list notable convention changes if any]
+
+Recommendation: run /clear for a clean session with all new conventions loaded.
+```
+
+### Step 4: Commit
+
+```bash
+cd ~/.plastic && git add PLASTIC.md scripts/ AGENTS.md VERSION 2>/dev/null && git commit -m "chore: update Plastic core files" --allow-empty
+```
+
+### Step 5: Clear update cache
+
+```bash
+rm -f ~/.plastic/.cache/update-check.json
+```
+
+This removes the statusline warning since the update is now applied.

package/templates/agents.md

@@ -0,0 +1,46 @@
+# Plastic — Project Agent Instructions
+
+> Full conventions: see `~/.plastic/PLASTIC.md` (the global conventions contract).
+> This file covers project-scoped rules only.
+
+## Your Role
+
+You are working on this project as part of a strategic intent. Your governing intent is tracked in the global Plastic store at `~/.plastic/store/`.
+
+## How to Work
+
+1. **Check active tactical intents** in `.plastic/store/` — these are your current tasks
+2. **Create new tactical intents** when you discover sub-work needed
+3. **Use [[ID]] wikilinks** to link intents to each other
+4. **Use [[global:ID]]** to link back to the governing strategic intent
+5. **Auto-commit** all intent changes in this project's git repo
+
+## Intent Lifecycle — What→Why→How→Next
+
+State is derived from filesystem conventions, not frontmatter fields:
+
+| Convention | Signal |
+|---|---|
+| `## Context` has content | Intent is permanent (not fleeting) |
+| `actions/` directory exists | Intent is actionable |
+| `## Outcome` has content | Intent is done |
+
+Sections map to the lifecycle:
+- **## Intent** — What (the desire)
+- **## Context** — Why (background + ### Decisions)
+- **## Outcome** — How (the result, deliverables)
+- **## Insights** — Next (observations, raw material for future intents)
+
+Active/Future/Completed placement is managed in INDEX.md, not in frontmatter.
+
+## Creating Tactical Intents
+
+1. Scan `.plastic/store/` for the next sequential ID
+2. Generate ID: `~/.plastic/scripts/folgezettel-id`
+3. Create `.plastic/store/ID--slug/ID--slug.md`
+4. Set frontmatter: `id`, `intent`, `sources` (array — link to governing intent), `chain` (starts empty), `created`, `author`, `tags`
+5. Add `[[global:ID]]` backlink in `## Links`
+
+## When You're Done
+
+When this project satisfies the governing intent's goal, report back. The orchestrator will complete the strategic intent.

package/templates/checklist.md

@@ -0,0 +1,11 @@
+# Checklist: {{INTENT_NAME}}
+
+## In Progress
+- [ ] ...
+
+## Completed
+(move items here when done)
+
+## Session Log
+| Date | Items Completed | Notes |
+|------|-----------------|-------|

package/templates/config.yml

@@ -0,0 +1,13 @@
+version: 3
+project_roots:
+  - ~/.plastic/projects
+stale_threshold_days: 3
+execution_mode: subagent-driven
+hash_length: 6
+hash_algorithm: sha256-base36
+max_slug_words: 5
+agent:
+  type: claude-code
+  parallel_mode: linear
+architect:
+  style:

package/templates/index.md

@@ -0,0 +1,13 @@
+# Index
+
+## Active
+(no active intents)
+
+## Future
+(no future intents)
+
+## Clusters
+(clusters emerge as intents accumulate — add headings when 3+ intents share a topic)
+
+## Completed
+(links preserved, never deleted)

package/templates/intent.md

@@ -0,0 +1,24 @@
+---
+id: "{{ID}}"
+intent: "{{INTENT}}"
+sources: [{{SOURCES}}]
+chain: []
+created: {{DATE}}
+author: {{AUTHOR}}
+tags: [{{TAGS}}]
+---
+
+## Intent
+{{DESCRIPTION}}
+
+## Context
+(why this intent exists — background, then ### Decisions after brainstorming)
+
+## Outcome
+(the result — implementation details, deliverables)
+
+## Insights
+(observations captured throughout — raw material for future intents)
+
+## Links
+- (use [[ID]] or [[ID|display text]] wikilinks to related intents)

package/templates/plan.md

@@ -0,0 +1,11 @@
+# Plan: {{INTENT_NAME}}
+
+## Goal
+{{GOAL}}
+
+## Steps
+- [ ] Step 1 — ...
+- [ ] Step 2 — ...
+
+## Notes
+(implementation notes, constraints, decisions)

package/templates/projects.yml

@@ -0,0 +1,3 @@
+# Plastic project registry
+# Maps project slugs to paths and parent intents
+projects: {}

package/templates/savepoint.md

@@ -0,0 +1,13 @@
+# Savepoint
+
+## Last Updated
+{{DATE}} — Session #{{N}}
+
+## In Progress
+- ...
+
+## Blockers
+None
+
+## Key Discoveries This Session
+- ...