plastic AGENTS.md

Plastic

Intent-driven state management for AI coding sessions.

Stack

• Language: Ruby (scripts), JavaScript/Node.js (npm package, installer)
• Framework: npm package (CLI installer), flat personal skills
• Testing: Minitest. See the Testing section below for the correct full-suite command.
• Source: /Users/zlatko/apps/personal/plastic
• Remote: [email protected]:zalom/plastic.git

Defaults

• Release process: commit_and_push, github_release, npm_publish
• Version files: package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json
• Tag format: v{{version}}
• All bash scripts must work under macOS /bin/bash 3.2 (no bash 4.x features)
• Bump all 3 version files on every fix/feature release

Searching Plastic with QMD

QMD is an optional but recommended local markdown search engine over the Plastic stores. Plastic works without it (ripgrep over the store files is the fallback). When QMD is present, search it before re-deriving an existing decision, spec, or outcome.

• Collections. Plastic indexes into the DEFAULT qmd index, one collection per store, all plastic- prefixed: plastic-global for ~/.plastic/store, and plastic-<slug> for each project store (slugs come from projects.yml).
• Scope a search. One project: -c plastic-<slug>. All of Plastic: target the plastic-* collections. Pick the narrowest scope that answers the question.
• Search before re-deriving. Look in the stores for prior decisions, specs, and outcomes before re-deriving them. The stores are the memory.
• Power tools are recommended when present. When QMD (for intents), Enola, or Serena (for code navigation) is present, prefer them: the UserPromptSubmit hook appends one combined recommendation line covering QMD and at most one code-navigation tool, Enola-first when both code-navigation tools are present (one code-navigation slot, Enola wins over Serena), and the per-skill QMD-first steps run qmd-sync search before grep/Read, then open the authoritative intent file. Use the deterministic scripts/qmd-sync search "<terms>" helper, which scopes collections for you and is a clean no-op when QMD is absent.
• Completion fires an async reindex. Intent delivery reindexes the delivering store's collection in the background (non-blocking), so the index stays fresh while "index mutation is lifecycle-only" stays true. Never reindex ad-hoc.
• Index mutation is lifecycle-only. The index changes only on Plastic lifecycle events (install registers all stores, project creation registers the new project store, intent delivery reindexes the delivering store's collection). Never reindex ad-hoc.
• Query craft lives in the qmd skill. Use the installed qmd skill for structured qmd query (intent/lex/vec/hyde) and BM25 qmd search. Two notes: structured queries need ANSI-C $'...' quoting so \n becomes a real newline, and qmd search (BM25) needs no model downloads, so it is the safe model-free fallback.