@zalom/plastic 1.0.0-alpha.1

package/skills/creating-project/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: plastic:creating-project
+description: >-
+  Create a new project from an implementation intent. Sets up project directory,
+  git init, AGENTS.md with founding intent decisions, plastic:install --local,
+  tactical mirror, projects.yml registration, and framework scaffolding.
+  Use when an implementation intent spawns a project, or manually by user.
+---
+
+# Creating a Project
+
+Announce: "Creating project `<slug>` from intent [ID] — [name]."
+
+## Precondition
+
+An active intent must exist with enough context to define a project — at minimum: name/slug, path, and key decisions from `## Context > ### Decisions`.
+
+## Workflow
+
+### 1. Determine Project Identity
+
+- **Slug:** derived from intent name (kebab-case, 2-4 words) or user-specified
+- **Path:** from `~/.plastic/config.yml` `project_roots` (first entry as default), or user-specified
+- Confirm path with user before creation
+
+### 2. Create Project Directory
+
+```bash
+mkdir -p <project_root>/<slug>
+cd <project_root>/<slug>
+git init
+```
+
+### 3. Run `plastic:install --local`
+
+Invoke `plastic:install --local` in the project directory. This creates:
+```
+.plastic/
+├── store/
+├── INDEX.md
+└── config.yml
+```
+
+### 4. Populate AGENTS.md
+
+Create `AGENTS.md` in the project root with:
+
+```markdown
+# <Project Name> — Agent Instructions
+
+Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
+Follow it exactly.
+
+This file is the operating contract for this project. Any agent entering
+this project reads this file first.
+
+## Global Store
+
+Location: `~/.plastic/`
+Governing intent(s): <list of founding intent IDs with descriptions>
+
+## Decisions
+
+<Copy ALL decisions from founding intent(s)' `## Context > ### Decisions`>
+
+Each decision should include:
+- The decision itself
+- The rationale (why this choice)
+- Date decided
+
+## Project-Specific Rules
+
+<Any rules derived from the decisions — e.g., "Use Minitest, not RSpec",
+"37signals methodology", "sqlite-vec for vector storage">
+```
+
+### 5. Create Tactical Mirror
+
+Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`:
+
+**Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
+**File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
+
+```yaml
+---
+id: '1'
+intent: "<same description as founding intent>"
+sources: ["global:<founding_intent_ID>"]
+chain: []
+created: <today>
+author: <same as founding intent author>
+tags: [<relevant tags>]
+---
+```
+
+Sections:
+- `## Intent` — same as founding intent
+- `## Context` — carry forward relevant Context and Decisions
+- `## Outcome` — (pending)
+- `## Insights` — empty
+- `## Links` — `[[global:<founding_intent_ID>|<founding intent name>]]`
+
+Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
+```markdown
+# Index
+
+## Active
+- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
+```
+
+**For multi-intent spawning (Hub):**
+- `sources`: `["global:<id1>", "global:<id2>", ...]` — all founding intents
+- All founding intents' decisions merge into AGENTS.md
+- Context carries forward from all founding intents
+
+### 6. Register in projects.yml
+
+Read `~/.plastic/projects.yml` and add:
+
+```yaml
+<slug>:
+  path: <full-path>
+  parent: "<founding_intent_ID>"
+  registered: <today>
+  status: active
+```
+
+For Hub-spawned projects, `parent` references the primary founding intent.
+
+### 7. Mark Global Intent(s) Completed
+
+For each founding intent:
+
+1. Write `## Outcome` in the intent file:
+   > "Spawned project `<slug>` at `<path>`. Decisions carried to AGENTS.md. Tactical mirror: `project-<slug>:1`."
+2. Write `outcome.md` with full details (all decisions, project path, tactical mirror ID)
+3. Update `chain` to include `project-<slug>:1`
+4. Move from `## Active` to `## Completed` in `~/.plastic/INDEX.md` (with today's date)
+
+### 8. Framework Scaffolding
+
+If decisions specify a framework, run the appropriate scaffolding command AFTER steps 3-4 (so scaffolding doesn't overwrite Plastic files or AGENTS.md):
+
+| Framework | Command |
+|---|---|
+| Rails | `rails new <slug> [options from decisions] --skip-git` (skip git — already initialized) |
+| Node/npm | `npm init -y` |
+| Ruby gem | `bundle gem <slug>` |
+| Other | As specified in decisions |
+
+After scaffolding, verify AGENTS.md and `.plastic/` still exist. If scaffolding overwrote them, restore.
+
+### 9. Auto-commit Both Stores
+
+```bash
+cd ~/.plastic && git add . && git commit -m "feat: spawn project <slug> from intent <ID>"
+cd <project> && git add . && git commit -m "feat: initialize project from intent <ID>"
+```
+
+### 10. Announce
+
+Log in `## Insights` of each founding intent:
+> "Project `<slug>` created at `<path>`. Tactical mirror: `project-<slug>:1` (autonomous)"
+
+Announce to user:
+> "Project `<slug>` created at `<path>`. AGENTS.md populated with [N] decisions from [founding intent IDs]. Tactical mirror `1` is now the active intent in the project store."

package/skills/executing-plan/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: plastic:executing-plan
+description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
+---
+
+# Executing a Plan
+
+## Overview
+
+Load plan from the active intent's `plan.md`, execute all tasks, review between tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plan skill to implement this plan."
+
+## Mode Selection
+
+### Check for superpowers first
+If `superpowers:subagent-driven-development` is available as a skill, delegate to it. If only `superpowers:executing-plans` is available, delegate to that. If neither is available, use Plastic's own execution engine below.
+
+**CRITICAL — when delegating to superpowers:**
+- Tell the skill that the plan is at `~/.plastic/store/ID--slug/plan.md` (not `docs/superpowers/plans/`)
+- Tell the skill that specs live at `~/.plastic/store/ID--slug/spec.md` (not `docs/superpowers/specs/`)
+- All meta-artifacts must stay inside `~/.plastic/store/ID--slug/`
+- Code files go in the project tree as normal
+- Superpowers skills respect "user preferences for plan/spec location" — Plastic IS that preference
+
+### Subagent-Driven (Default)
+Dispatches a fresh subagent per task. Controller never implements — only dispatches, reviews, and tracks progress. Two-stage review after each task: spec compliance first, then code quality.
+
+### Inline (Fallback)
+Executes tasks sequentially in the current session. Use when subagents aren't available or user explicitly requests inline mode.
+
+To select: user says "inline", "execute inline", or "no subagents".
+
+## Subagent-Driven Workflow
+
+### Step 1: Load Plan
+1. Read the active intent's `plan.md`
+2. Extract ALL tasks with their full text — store in memory. Never make subagents read the plan file.
+3. Create a task list to track progress
+
+### Step 2: Execute Each Task
+
+For each task sequentially (never parallel — conflict risk):
+
+**a. Dispatch implementer subagent**
+Use the Agent tool with the implementer prompt template. Include:
+- Full task text (pasted in, not file reference)
+- Project context from CLAUDE.md
+- Active intent context from `{ID}--{slug}.md`
+
+**b. Handle implementer response**
+- DONE → proceed to spec review
+- DONE_WITH_CONCERNS → note concerns, proceed to spec review
+- NEEDS_CONTEXT → provide missing context, re-dispatch
+- BLOCKED → stop, report to user, wait for resolution
+
+**c. Dispatch spec compliance reviewer**
+Use the Agent tool with spec-reviewer prompt. The reviewer reads actual code and compares against the task requirements. Pass/fail.
+- If fail: implementer fixes, spec reviewer re-reviews (loop until pass)
+
+**d. Dispatch code quality reviewer**
+Only after spec compliance passes. Reviews clean code, testing, architecture. Pass/fail.
+- If fail: implementer fixes, quality reviewer re-reviews (loop until pass)
+
+**e. Mark task complete**, move to next
+
+### Step 3: Final Review
+After all tasks complete, dispatch a final reviewer for the entire implementation.
+
+### Step 4: Update Intent and Complete
+Capture observations in `## Insights`. When ALL checklist items are checked:
+
+1. Write `outcome.md` with detailed results in the intent directory
+2. Write `## Outcome` summary in the intent file (1-2 sentences)
+3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+4. Update cluster entries to show `_(completed)_`
+5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+
+**This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
+
+## Inline Workflow
+
+### Step 1: Load and Review Plan
+1. Read plan file from active intent
+2. Review critically — raise concerns before starting
+3. Create task list to track progress
+
+### Step 2: Execute Tasks
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Update Intent and Complete
+Capture observations in `## Insights`. When ALL checklist items are checked:
+
+1. Write `outcome.md` with detailed results in the intent directory
+2. Write `## Outcome` summary in the intent file (1-2 sentences)
+3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
+4. Update cluster entries to show `_(completed)_`
+5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
+
+**This is NOT optional.** Complete the intent immediately when work is done.
+
+## Model Selection for Subagents
+
+Match model to task complexity:
+- **Mechanical tasks** (config files, boilerplate): cheapest available
+- **Standard implementation**: default model
+- **Architecture, integration, review**: most capable model
+
+## Prompt Templates
+
+Subagent prompts are in this skill's directory:
+- `implementer-prompt.md` — template for implementer subagents
+- `spec-reviewer-prompt.md` — template for spec compliance reviewers
+- `code-quality-reviewer-prompt.md` — template for code quality reviewers
+
+Read the appropriate template when dispatching each subagent type.

package/skills/executing-plan/code-quality-reviewer-prompt.md

@@ -0,0 +1,32 @@
+# Code Quality Reviewer Prompt
+
+The implementation passed spec compliance review. Now review for code quality.
+
+## Task That Was Implemented
+
+{{TASK_TEXT}}
+
+## Instructions
+
+Review the changes for:
+
+1. **Clean code** — clear naming, no unnecessary complexity, follows project conventions
+2. **Single responsibility** — each file/function does one thing
+3. **Testing quality** — tests are meaningful, not just coverage padding
+4. **No regressions** — existing tests still pass
+5. **File organization** — follows the plan's file structure, files aren't too large
+
+## Report Format
+
+**PASS** — Code quality is good. No significant issues.
+
+**FAIL** — Issues found:
+
+### Strengths
+- What was done well
+
+### Issues
+- [file:line] Issue description and suggested fix
+
+### Assessment
+Overall quality rating and whether fixes are needed before proceeding.

package/skills/executing-plan/implementer-prompt.md

@@ -0,0 +1,42 @@
+# Implementer Subagent Prompt
+
+You are implementing a specific task from a plan. You have been given the full task text below.
+
+## Your Task
+
+{{TASK_TEXT}}
+
+## Project Context
+
+{{PROJECT_CONTEXT}}
+
+## Active Intent
+
+{{INTENT_CONTEXT}}
+
+## Instructions
+
+1. Read the task carefully. If anything is unclear, report NEEDS_CONTEXT with what you need.
+2. Implement exactly what the task specifies — nothing more, nothing less.
+3. Write tests first when the task includes test steps (TDD).
+4. Follow the file paths specified in the task exactly.
+5. Commit after each logical unit of work.
+6. When done, self-review against this checklist:
+   - [ ] All steps in the task are completed
+   - [ ] Tests pass
+   - [ ] Code is clean and follows project conventions
+   - [ ] No unrelated changes
+
+## Report Format
+
+End your work with one of these status lines:
+
+**DONE** — All steps completed, tests pass, code committed.
+
+**DONE_WITH_CONCERNS** — Completed but I noticed: [describe concerns].
+
+**NEEDS_CONTEXT** — I need clarification on: [specific questions].
+
+**BLOCKED** — Cannot proceed because: [describe blocker].
+
+It is always OK to report BLOCKED or NEEDS_CONTEXT. Do not guess or improvise when uncertain.

package/skills/executing-plan/spec-reviewer-prompt.md

@@ -0,0 +1,27 @@
+# Spec Compliance Reviewer Prompt
+
+The implementer says they finished this task. Verify independently — their report may be incomplete or optimistic.
+
+## Task Requirements
+
+{{TASK_TEXT}}
+
+## Instructions
+
+1. Read the actual code that was written (not the implementer's report)
+2. Compare line by line against the task requirements
+3. Check for:
+   - Missing requirements — anything in the task that wasn't implemented
+   - Extra work — anything added that the task didn't ask for
+   - Misunderstandings — code that doesn't match what the task intended
+   - Test coverage — are all specified behaviors tested?
+
+## Report Format
+
+**PASS** — All task requirements are correctly implemented. No gaps, no extras.
+
+**FAIL** — Issues found:
+- [file:line] Description of what's wrong and what was expected
+- [file:line] Description of what's missing
+
+Be specific. Reference exact file paths and line numbers.

package/skills/install/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: plastic:install
+description: Use when initializing Plastic globally (~/.plastic/) or locally in a project. Global install is recommended — creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+---
+
+# Install Plastic
+
+## Modes
+
+### Global Install (default, recommended)
+
+Run `/plastic:install` with no arguments.
+
+#### Procedure
+
+**Step 1: Check for existing installation**
+
+Check if `~/.plastic/INDEX.md` exists.
+- If yes: announce "Plastic is already installed at ~/.plastic/. Run `/plastic:update` to sync core files."
+- If no: proceed with fresh install.
+
+**Step 2: Create ~/.plastic/ as a git repo**
+
+```bash
+mkdir -p ~/.plastic/store ~/.plastic/projects
+```
+
+Copy templates from the plugin:
+- `config.yml` from `${CLAUDE_PLUGIN_ROOT}/templates/config.yml`
+- `projects.yml` from `${CLAUDE_PLUGIN_ROOT}/templates/projects.yml`
+- `INDEX.md` from `${CLAUDE_PLUGIN_ROOT}/templates/index.md`
+- `PLASTIC.md` from `${CLAUDE_PLUGIN_ROOT}/PLASTIC.md`
+
+Create `AGENTS.md` (user-editable, not overwritten on updates):
+```markdown
+# Plastic — Agent Instructions
+
+Read `PLASTIC.md` in this directory. It contains all Plastic conventions.
+Follow it exactly. Never modify it — it is overwritten on plugin updates.
+
+This file (`AGENTS.md`) is where project-specific rules live. Users and agents
+may add content below.
+
+---
+```
+
+Add `.gitkeep` to `store/` and `projects/`.
+
+Initialize git:
+```bash
+cd ~/.plastic && git init && git add . && git commit -m "chore: initialize Plastic global intent store"
+```
+
+**Step 2b: Copy utility scripts**
+
+```bash
+mkdir -p ~/.plastic/scripts
+cp "${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" ~/.plastic/scripts/folgezettel-id
+cp "${CLAUDE_PLUGIN_ROOT}/scripts/read-config" ~/.plastic/scripts/read-config
+chmod +x ~/.plastic/scripts/folgezettel-id ~/.plastic/scripts/read-config
+```
+
+This ensures project agents can generate hashes via `~/.plastic/scripts/folgezettel-id` without depending on a specific agent's plugin cache path.
+
+**Step 2c: Detect agent type and set preferences**
+
+Detect which agent is running:
+- If `CLAUDE_CODE` env var is set or we're running inside Claude Code → `agent.type: claude-code`
+- If `HERMES_HOME` env var is set → `agent.type: hermes`
+- Otherwise → ask the user: "Which AI agent are you using? (claude-code / hermes / other)"
+
+Ask the user:
+> "Enable Agent Teams? (experimental — parallel project work with teammates)"
+> - Yes → set `parallel_mode: agent-teams`
+> - No → set `parallel_mode: linear` (subagents only)
+
+Update `~/.plastic/config.yml` with detected/chosen values using `read-config --migrate` first to ensure v3 schema, then write the agent-specific values.
+
+Auto-commit the config change.
+
+**Step 2d: Configure GitHub and push preferences**
+
+Inform the user:
+> "Plastic agents can create GitHub repositories for new projects.
+> By default, all agent-created repos are **private**. Your global
+> intent store (~/.plastic/) is never pushed — it stays local-only."
+
+Ask the user:
+> "Default visibility for agent-created repos?"
+> - Private (recommended) → set `github.default_visibility: private`
+> - Public → set `github.default_visibility: public`
+
+> "Allow agents to push to GitHub without asking?"
+> - No (recommended) → set `github.auto_push: false`
+> - Yes → set `github.auto_push: true`
+
+Update `config.yml` with chosen values. Auto-commit.
+
+**Step 3: Configure project roots**
+
+Ask the user:
+> "Where do you keep your projects? Default: ~/.plastic/projects/"
+> "Add additional roots? (e.g., ~/apps/personal/, ~/apps/companies/)"
+
+Update `config.yml` with any additional roots.
+
+Auto-commit the config change.
+
+**Step 4: Announce**
+
+> "Plastic installed globally at ~/.plastic/. Create your first intent with `/plastic:creating-intent`."
+
+### Local Install (testing/legacy)
+
+Run `/plastic:install --local`.
+
+#### Procedure
+
+**Step 1:** Check if `.plastic/` exists in CWD — if so, warn and exit.
+
+**Step 2:** Create `.plastic/` in CWD:
+- `config.yml` from templates
+- `INDEX.md` from templates
+- `store/` with `.gitkeep`
+
+**Step 3:** If global install exists (`~/.plastic/projects.yml`), register this project:
+- Determine project slug from directory name
+- Detect git remote URL if available
+- Add entry to `~/.plastic/projects.yml` with `parent: null`
+- Auto-commit in `~/.plastic/`
+
+**Step 4:** Commit in project: `git add .plastic/ && git commit -m "chore: initialize Plastic local store"`
+
+**Step 5:** Announce: "Plastic initialized locally. This is a testing/legacy mode. Consider `/plastic:install` for global mode."

package/skills/intent-curator/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: plastic:intent-curator
+description: |
+  Use when completing or reviewing intents, reorganizing the index,
+  or when the intent store needs maintenance. Examples:
+  <example>Context: User has finished implementing a feature.
+  user: "This intent is done, clean up the index"
+  assistant: "I'll use the intent-curator to update the intent status and reorganize INDEX.md"
+  <commentary>Intent lifecycle change triggers curator for index maintenance.</commentary></example>
+  <example>Context: The intent store has grown and clusters need review.
+  user: "Organize the intents"
+  assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
+  <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
+---
+
+# Intent Curator
+
+Dispatches to the `plastic:intent-curator` agent for intent store maintenance.
+
+## When to Use
+- Completing or reviewing intents
+- Reorganizing INDEX.md
+- Cluster maintenance, orphan detection, link discovery
+- Batch status updates
+
+## Workflow
+
+Invoke the `plastic:intent-curator` agent via the Agent tool with `subagent_type: "plastic:intent-curator"`. Pass the user's request as the prompt, including:
+
+1. **What to do** — complete intent, reorganize, triage stale, etc.
+2. **Which store** — global (`~/.plastic/`) or project (`.plastic/store/`)
+3. **Which intents** — by ID or "all active"
+
+The agent handles:
+- Intent lifecycle management (status transitions, Outcome sections)
+- INDEX.md maintenance (Active/Future/Clusters/Completed sections)
+- Link discovery between related intents
+- Cluster management (create, merge, rename)
+- Orphan detection
+
+After the agent completes, report what changed.

package/skills/linking-intents/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: plastic:linking-intents
+description: Use when creating connections between intents, the user says "link" or "connect", or when discovering that two intents are related. Manages sources, chain, and cross-reference links.
+---
+
+# Linking Intents
+
+## When to Use
+- During intent creation (automatic — ask about related intents)
+- User says "link", "connect", "relates to"
+- Agent discovers a relationship between intents during work
+
+## Connection Types (Ranked by Strength)
+
+### 1. Direct Links (Strongest)
+Explicit wikilinks in the `## Links` section. Bidirectional — add to both intents.
+
+```markdown
+## Links
+- [[1a]] — research this plan is based on
+```
+
+### 2. Sources (Backward)
+The `sources` array in frontmatter. What influenced this intent — backward links to parent/prior work:
+```yaml
+sources: ["1a", "1a2"]
+```
+
+### 3. Chain (Forward)
+The `chain` array in frontmatter. What this intent spawned — forward links to children/follow-on work:
+```yaml
+chain: ["1b1", "1b2"]
+```
+
+### 4. Tags (Weakest)
+Shared tags in frontmatter enable filtered discovery. Use `project-<name>` tags for project membership.
+```yaml
+tags: [plastic, project-reddit-kb]
+```
+
+## Workflow
+
+### 1. Identify Intents to Connect
+Show existing intents by scanning the store's directory for intent files:
+```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" ] && ruby -ryaml -e '
+    data = File.read(ARGV[0]).split("---")[1]
+    parsed = YAML.safe_load(data)
+    puts "#{parsed["id"]} | #{parsed["intent"]}" if parsed
+  ' "$f" 2>/dev/null
+done
+```
+
+### 2. Choose Connection Type
+Ask the user which type of connection:
+- **source** — "this was influenced by that" (add to `sources[]`, update `chain[]` on the target)
+- **cross-reference** — "these are related" (add wikilink in `## Links` of both intents)
+
+### 3. Apply Connection
+
+**For sources:**
+Update frontmatter arrays on both intents:
+- Add the parent's ID to the child's `sources` array
+- Add the child's ID to the parent's `chain` array
+
+**For cross-references:**
+Add a wikilink in the `## Links` section of **both** intents (bidirectional).
+
+### 4. Update INDEX.md Clusters
+If both intents share a topic, ensure they're in the same cluster.