@zalom/plastic 1.0.0-alpha.1 → 1.0.0-alpha.10

package/skills/doctor/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: doctor
+description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
+---
+
+# Doctor — Plastic Health Check
+
+## When to Use
+
+- User invokes `/plastic:doctor`
+- After `plastic:update` completes (automatically)
+- When hooks aren't firing, skills aren't loading, or something seems broken
+- When the user says "check plastic", "diagnose", "what's wrong with plastic"
+
+## Procedure
+
+### Step 1: Run the diagnostic script
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Replace `claude` with the current agent type if known (`codex`, `hermes`).
+
+Parse the JSON output from stdout. The script is read-only and never modifies
+files. Errors go to stderr.
+
+Exit codes indicate check results, not script failure:
+- `0` — all checks passed
+- `1` — warnings found
+- `2` — failures found
+
+All three exit codes mean the script ran successfully. Do not treat non-zero
+as an error.
+
+### Step 2: Determine overall status
+
+Read the `status` field from the JSON root:
+
+| Status | Meaning |
+|--------|---------|
+| `pass` | Everything is healthy |
+| `warn` | Warnings found but Plastic works normally |
+| `fail` | Blocking issues that prevent Plastic from operating |
+
+### Step 3: Fill the report template
+
+Read `report.md` from the same directory as this SKILL.md
+(`~/.plastic/skills/doctor/report.md` at runtime, or the plugin source
+`skills/doctor/report.md` during development).
+
+Group checks by category. For each category, list the checks with their
+status icon and message. If a check has `details`, list them as sub-items.
+
+Present the filled template to the user.
+
+### Step 4: Offer fixes (if applicable)
+
+If any checks have `fixable: true` AND status is not `pass`:
+
+1. Group fixable items by category
+2. Show what each fix would do (from `fix_hint`)
+3. Ask the user: **"Fix all / Select individually / Skip"**
+
+If no fixable issues exist, skip this step.
+
+### Step 5: Apply fixes
+
+Use the `fix_hint` value to determine the correct action:
+
+| Fix hint pattern | Agent action |
+|---|---|
+| "chmod +x on the listed files" | Run `chmod +x` on each file listed in `details` |
+| "Create missing directory" | Run `mkdir -p` on the path |
+| "Create INDEX.md with required sections" | Write INDEX.md with the 5 sections: Active, Future, Clusters, Abandoned, Completed |
+| "Add missing entries to INDEX.md" | Add orphaned intents to the appropriate INDEX.md section |
+| "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
+| "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+
+For fixes the agent cannot handle automatically, explain what the user needs
+to do manually.
+
+### Step 6: Verify
+
+After applying fixes, re-run the diagnostic script:
+
+```bash
+ruby ~/.plastic/scripts/doctor.rb --agent claude
+```
+
+Show the updated results.
+
+- If all checks pass: announce success.
+- If issues remain: explain what is still wrong and what the user can do.
+
+## Post-Update Mode
+
+When invoked from `plastic:update` (not directly by the user):
+
+1. Run the diagnostic script as in Step 1.
+2. If all checks pass: show a single line — **"Health check: all clear."**
+3. If issues are found: show the full report (Steps 3-6).
+
+This keeps the update flow clean when nothing is wrong.
+
+## Important Notes
+
+- The script is **read-only**. It inspects but never modifies files.
+  All fixes are performed by the agent using standard tools.
+- The script outputs JSON to stdout. Any diagnostic errors go to stderr.
+- Non-zero exit codes mean "issues found", not "script crashed".
+  Always parse stdout regardless of exit code.

package/skills/doctor/report.md

@@ -0,0 +1,96 @@
+# Plastic Doctor Report
+
+<!-- =======================================================================
+  AGENT INSTRUCTIONS -- How to fill this template
+  =========================================================================
+  1. Run the doctor script. It outputs JSON with check results.
+  2. Replace every {{placeholder}} below with the corresponding JSON value.
+  3. For the category sections: the template shows ONE example section.
+     Repeat that pattern for each unique category in the checks array.
+     The six known categories and their display names are:
+       global_store       -> "Global Store"
+       conventions        -> "Conventions"
+       agent_registration -> "Agent Registration"
+       core_files         -> "Core Files"
+       project_stores     -> "Project Stores"
+       deprecations       -> "Deprecations"
+  4. For each check within a category, emit one line with the status icon
+     and the check message. If the check has non-empty details, list them
+     as indented sub-items.
+  5. The "Fixable Issues" section should ONLY appear if at least one check
+     has fixable=true AND status is not "pass". Omit the entire section
+     otherwise.
+  6. Status icons (plain text, no emoji):
+       pass -> [PASS]
+       warn -> [WARN]
+       fail -> [FAIL]
+  7. The overall status icon in the header uses the same mapping.
+  8. After filling, remove all HTML comments -- they are instructions only.
+  ======================================================================= -->
+
+## {{overall_status_icon}} Overall: {{status}} -- Plastic v{{version}}
+
+Checked at: {{timestamp}}
+
+### Summary
+
+{{pass}} passed, {{warn}} warnings, {{fail}} failed -- {{total}} checks total
+
+---
+
+<!-- =====================================================================
+  CATEGORY SECTIONS
+  ======================================================================
+  Repeat the block below ONCE PER CATEGORY present in the checks array.
+  Group checks by their "category" field. Use the display name mapping
+  above for the heading. Within each category, list every check as a
+  single line: status icon + message. If a check has non-empty "details",
+  list each detail as an indented bullet beneath.
+
+  Example category section (for agent_registration with two checks):
+  ===================================================================== -->
+
+### Agent Registration
+
+- [PASS] Claude Code adapter registered
+- [FAIL] 2 hook scripts not executable
+  - ~/.claude/hooks/plastic-session-start
+  - ~/.claude/hooks/plastic-gate-check
+
+<!-- =====================================================================
+  Repeat the above pattern for each category found in the checks array.
+  Only include categories that have at least one check.
+  Order categories as they appear in the checks array.
+  ===================================================================== -->
+
+---
+
+<!-- =====================================================================
+  FIXABLE ISSUES SECTION
+  ======================================================================
+  Include this section ONLY if one or more checks have fixable=true AND
+  status is "warn" or "fail". If no fixable issues exist, omit everything
+  from the "Fixable Issues" heading through the end of the horizontal
+  rule that follows the table.
+
+  For each fixable check that is not "pass", emit one table row:
+    | status_icon | check_message | fix_hint |
+  ===================================================================== -->
+
+### Fixable Issues
+
+| Status | Issue | Fix |
+|--------|-------|-----|
+| [FAIL] | 2 hook scripts not executable | chmod +x on the listed files |
+
+<!-- =====================================================================
+  Repeat one row per fixable non-pass check.
+  ===================================================================== -->
+
+---
+
+<!-- =====================================================================
+  FOOTER -- always include this line exactly as written.
+  ===================================================================== -->
+
+Run `plastic doctor --fix` to auto-fix all fixable issues, or ask me to fix them now.

package/skills/releasing/SKILL.md

@@ -6,25 +6,62 @@ description: Use when merging a feature branch to main and tagging a release, bu
 # 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,42 @@ git tag -a vX.Y.Z -m "vX.Y.Z — [release name]
 git push origin main --tags
 ```
 
-### 7. GitHub Release
+### 7. Post-Push Actions
+
+Read `release.on_green` from project.yml. This is a list of actions to run after a successful push. Execute each in order:
 
-Create a GitHub release from the tag. Use `--generate-notes` to auto-generate changelog from commits since the previous tag:
+#### `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:
+
+```bash
+# For pre-release versions (0.x.y, or version contains -alpha/-beta/-rc):
+npm publish --access public --tag alpha
+
+# For stable versions (>= 1.0.0, no pre-release suffix):
+npm publish --access public
+```
+
+#### 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,17 +171,17 @@ 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>`
 
 ## Retroactive Tagging

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

@@ -54,13 +54,21 @@ Key changes in this version:
 Recommendation: run /clear for a clean session with all new conventions loaded.
 ```
 
-### Step 4: Commit
+### Step 4: Run health check
+
+Invoke `plastic:doctor` to verify the installation is healthy after the update.
+
+If all checks pass, show: **"Health check: all clear."**
+
+If issues are found, show the full doctor report and offer to fix any fixable items.
+
+### Step 5: 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
+### Step 6: Clear update cache
 
 ```bash
 rm -f ~/.plastic/.cache/update-check.json