@zalom/plastic 2.0.0-alpha.8 → 2.0.1

package/skills/intent-speccing/references/design-principles.md

@@ -1,44 +0,0 @@
-# Design Principles: Unit Boundaries and Existing Codebases
-
-General good-developer guidance behind two parts of the Process: how to design for
-isolation and clarity, and how to behave in an existing codebase. Also holds the
-Process Flow diagram (the same ordered flow the Checklist already states as numbered
-steps).
-
-## Design for isolation and clarity
-
-- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
-- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
-- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
-- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
-
-## Working in existing codebases
-
-- Explore the current structure before proposing changes. Follow existing patterns.
-- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
-- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
-
-## Process Flow (diagram)
-
-The Checklist above already states this ordered flow as numbered steps 1-6; this
-diagram is the same flow in a visual form.
-
-```dot
-digraph brainstorming {
-    "Explore project context" [shape=box];
-    "Grill in prose" [shape=box];
-    "Propose 2-3 approaches" [shape=box];
-    "Present design sections" [shape=box];
-    "Owner rules?" [shape=diamond];
-    "Collect rulings\n(persist each immediately)" [shape=box];
-    "Invoke /plastic-intent-speccing" [shape=doublecircle];
-
-    "Explore project context" -> "Grill in prose";
-    "Grill in prose" -> "Propose 2-3 approaches";
-    "Propose 2-3 approaches" -> "Present design sections";
-    "Present design sections" -> "Owner rules?";
-    "Owner rules?" -> "Present design sections" [label="no, revise"];
-    "Owner rules?" -> "Collect rulings\n(persist each immediately)" [label="yes"];
-    "Collect rulings\n(persist each immediately)" -> "Invoke /plastic-intent-speccing";
-}
-```

package/skills/intent-speccing/references/per-section-fill-rules.md

@@ -1,92 +0,0 @@
-# Per-Section Fill Rules
-
-The single shared method for turning the rulings into `spec.md`. `plastic-intent-speccing`
-(the thinking conversation) and the auto orchestrator both point here; neither restates these
-rules. One fill rule per template section, in template order.
-
-Read the ruling ledger first (built in step 2 of the SKILL.md sequence): `## Context` plus
-`### Decisions`, then `## Insights` newest-last (a later ruling supersedes an earlier
-conflicting one), then `resources/discovery--<slug>.md`, then any other `resources/*.md`.
-Every rule below names which part of that ledger feeds the section.
-
-## 1. Problem
-
-Source: the intent's `## Intent` line plus the problem narrative in `## Context`.
-
-State the problem as a problem, not a solution: what is broken, missing, or costly today, for
-whom. Do not describe the fix here, that belongs in Approach. If `## Insights` records a later
-reframe of the problem (a scope correction, a retargeted root cause), the later framing wins.
-
-## 2. Goals
-
-Source: explicit goal statements in `## Context`, plus any `### Decisions` entry that commits to
-delivering a specific outcome.
-
-One bullet per goal, each a concrete, observable outcome the delivery must reach. Encode every
-Decision that commits to an outcome as its own bullet, do not compress two Decisions into one
-vague goal. A single-line collapsed Goals section is complete if it names every
-outcome; do not pad it with restated Problem text.
-
-## 3. Non-Goals
-
-Source: `### Decisions` entries that name something explicitly out of scope, and `## Insights`
-rulings that narrowed scope after the initial brainstorm.
-
-One bullet per excluded item, each naming what is out and, briefly, why (a sibling intent owns
-it, a scope-reframe ruling cut it, it is a future intent). If a later Insight narrows scope
-further than an earlier Decision, the Insight's narrower boundary is the one recorded.
-
-## 4. Approach
-
-Source: every `### Decisions` entry that describes HOW, resolved into one coherent narrative.
-
-Write prose, not a decision list. Synthesize the chosen path so it reads as one design: what
-gets built, in what shape, and how the pieces fit. Every Decision that shapes the approach must
-be traceable to a sentence here, but do not restate each Decision by its Dn label, that
-enumeration belongs in the Decisions section. Use a table only where the Approach itself compares
-options inline (rare; usually that comparison belongs in Alternatives Considered instead).
-
-## 5. Alternatives Considered
-
-Source: `### Decisions` entries and `## Insights` rulings that name a rejected path and the
-reason it lost.
-
-Render as a table, not the template's bullet-dash form, so the reason column stays uniform and
-free of dash-glyph punctuation:
-
-| Alternative | Not chosen because |
-|---|---|
-| <rejected path> | <the ruling's stated reason, paraphrased> |
-
-One row per rejected alternative. If two Decisions reject variants of the same alternative, merge
-them into one row rather than duplicating it. Never use an em-dash or en-dash in the reason
-column; write "because" or a colon instead.
-
-## 6. Decisions
-
-Source: `### Decisions` verbatim, in the order recorded, one entry per Decision.
-
-One bullet per decision, each keeping its `Dn` label and its ruling in paraphrase or verbatim.
-Do not drop a decision because it seems minor: every Decision must appear here even if its effect
-on the shipped Approach or Goals is small. When `## Insights` records a later ruling that
-supersedes an earlier Decision, add or amend the bullet to state the later ruling and note which
-earlier Decision it supersedes.
-
-## 7. Acceptance Criteria
-
-Source: any criteria named directly in `### Decisions` or `## Insights`, plus one inferred
-criterion per Goal that has no explicit criterion on record.
-
-One checkbox bullet per criterion, each concretely checkable: a fact a reviewer can confirm true
-or false by inspection, a command, or a file, never a vague quality judgment. Every Goal must map
-to at least one criterion. A criterion that cannot be checked without more interpretation is not
-done, rewrite it or ask (the gap rule, SKILL.md step 5).
-
-## 8. Open Questions
-
-Source: any question raised during Why that has no matching Decision or Insight resolving it.
-
-List each unresolved question as its own bullet. If every question raised during Why has a
-resolving Decision or Insight, write `None` and, directly under it, one line per resolved
-question naming which Decision or Insight resolved it (so a reader can audit the resolution
-instead of taking "None" on faith).

package/skills/intent-speccing/references/self-verify-checklist.md

@@ -1,37 +0,0 @@
-# Self-Verify Checklist
-
-Run this before presenting spec.md (SKILL.md step 7). Ten checks: the four points of
-brainstorming's proven Spec Self-Review, merged with the six binding output checks this skill
-adds. Fix any failing check, then re-verify from the top; do not present a spec that fails one of
-these.
-
-## Brainstorming's four Spec Self-Review points
-
-1. **Placeholder scan.** Any "TBD", "TODO", incomplete section, or vague requirement left in the
-   draft? Fix it before moving on.
-2. **Internal consistency.** Do any two sections contradict each other? Does the Approach
-   actually match what Goals and Acceptance Criteria describe?
-3. **Scope check.** Is this spec focused enough for a single implementation plan, or does the
-   Problem actually describe more than one independent piece of work that needs decomposing
-   first?
-4. **Ambiguity check.** Could any requirement be read two different ways? If so, pick one
-   reading and rewrite the line so only that reading survives.
-
-## The six binding output checks
-
-5. **No template placeholder text remains.** No literal `<intent name>`, `<alternative>`, `...`,
-   sample bracket text, or other template filler from `templates/spec.md` survives anywhere in
-   the artifact.
-6. **No header line.** The file starts at the `# Spec:` heading; there is no `Tier:` line (removed in 2.0, intent 304).
-7. **All 8 sections present, in template order.** Problem, Goals, Non-Goals, Approach,
-   Alternatives Considered, Decisions, Acceptance Criteria, Open Questions, each present once, in
-   that order, none merged into another.
-8. **Every `## Insights` ruling is traceable to a spec line.** Walk the Insights log entry by
-   entry: each one lands in some section of the spec. Where two rulings conflict, the later one
-   (further down the log) is the one that landed, and the earlier one does not silently persist
-   in a different section.
-9. **Acceptance criteria are concretely checkable.** Each Acceptance Criteria bullet reads as a
-   fact a reviewer can confirm true or false by inspection, a command, or a named file, not a
-   quality judgment a reviewer would have to interpret.
-10. **No em-dashes or en-dashes anywhere in the artifact.** Scan the full file; replace any dash
-    glyph with a comma, period, parenthesis, or colon.

package/skills/project-creating/SKILL.md

@@ -1,162 +0,0 @@
----
-name: plastic-project-creating
-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.
-user-invocable: true
----
-
-# Creating a Project
-
-## 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 from the skeleton in
-`references/project-scaffolding.md` ("AGENTS.md skeleton"): read it now and fill in
-the project name, governing intent IDs, decisions, and project-specific rules.
-
-### 5. Create Tactical Mirror
-
-Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`
-using the frontmatter, sections, and INDEX.md line in `references/project-scaffolding.md`
-("Tactical mirror intent"), including the Hub multi-intent variant if there is more
-than one founding intent.
-
-**Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
-**File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
-
-### 6. Register in projects.yml
-
-Read `~/.plastic/projects.yml` and add the entry shown in
-`references/project-scaffolding.md` ("projects.yml registration block"). For
-Hub-spawned projects, `parent` references the primary founding intent.
-
-### 7. Provision the Project Store
-
-The `provision-project-store` verb is the single source of truth for store
-creation. Run it after the project is registered in step 6 (the provisioner
-requires registration), and before the QMD step:
-
-```bash
-ruby ~/.plastic/scripts/provision-project-store <slug>
-```
-
-This ensures `~/.plastic/projects/<slug>/store/` exists with `.gitkeep`, and
-writes `INDEX.md` and `project.yml` only if missing. It is idempotent, so it is
-safe even when the tactical mirror in step 5 already created the store directory.
-Do not create the store with an inline `mkdir`; the provisioner is the only place
-a store is made. For a project that is already registered but store-less, use the
-`plastic-doctor` skill's provisioning section instead.
-
-### 8. 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)
-
-### 9. 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.
-
-### 10. 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>"
-```
-
-### 11. Register the project store with QMD (optional)
-
-If QMD is installed, register the new project's store as a search collection:
-
-```bash
-ruby ~/.plastic/scripts/qmd-sync register --store ~/.plastic/projects/<slug>/store
-```
-
-`qmd-sync` no-ops when QMD is absent, so run it unconditionally. This adds the
-`plastic-<slug>` collection and indexes it.
-
-### 12. Self-Check with validate-project
-
-Before announcing, verify the spawn actually landed everything it claims to
-have created. Run:
-
-```bash
-ruby ~/.plastic/scripts/validate-project <slug>
-```
-
-If this exits 0, proceed to step 13. If it exits non-zero, STOP: do not
-proceed to Announce. Read the `missing:` and error lines it printed to
-stderr, fix the named gap(s), for example:
-
-- missing `project.yml` or `INDEX.md` or `store/`: re-run
-  `ruby ~/.plastic/scripts/provision-project-store <slug>` (step 7), then
-  re-check
-- missing project-root `AGENTS.md`: repeat step 4 (populate AGENTS.md at the
-  project root, not `~/.plastic/projects/<slug>/`)
-- project directory missing on disk: repeat step 2
-- not registered in projects.yml: repeat step 6
-
-Re-run `validate-project <slug>` after each fix until it exits 0. Only a
-project spawn that passes this self-check moves on to be announced as
-created. A spawn that never verifies itself is exactly the bug this step
-exists to close (intent 190; the intent-26 spawn shipped with no
-`project.yml` and no root `AGENTS.md`, caught only weeks later by a doctor
-sweep).
-
-### 13. 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."
-
-## References
-
-- Read `references/project-scaffolding.md` before steps 4-6, for the AGENTS.md skeleton, the tactical mirror intent format, and the projects.yml registration block
-- Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/project-creating/references/hubs-projects.md

@@ -1,55 +0,0 @@
-# Hubs and Projects
-
-## Hubs
-
-A Hub is a cloud of intents around related topics. Hubs emerge naturally from
-Folgezettel branching — intents that spawn in the same direction cluster.
-
-- A Hub can spawn a Project. The Hub holds the founding ideas.
-- A single intent can also spawn a Project.
-- Hub-spawned projects revolve around different ideas around related topics.
-- Intent-spawned projects revolve around the single founding intent.
-- A Project is the deliverable outcome of one or more intents.
-
-Hubs are represented as clusters in INDEX.md.
-
-## Projects — Full Detail
-
-A Project is a deliverable grouping of intents. Projects have two stores:
-
-- **Global store** (`~/.plastic/store/`): strategic intents
-- **Project store** (`~/.plastic/projects/{slug}/store/`): tactical intents
-
-`projects.yml` maps project slugs to codebase paths:
-```yaml
-projects:
-  plastic:
-    path: "/path/to/plastic"
-    remote: "git@github.com:org/plastic.git"
-    registered: '2026-05-26'
-    status: active
-```
-
-Config resolution: `~/.plastic/projects/{slug}/config.yml` overrides `~/.plastic/config.yml`.
-
-Cross-linking: project intents reference global intents via `[[global:ID]]`. Global intents reference project intents via `[[project-slug:ID]]`.
-
-## Privacy and Collaboration
-
-**Plastic is personal.** All intent data lives under `~/.plastic/` — one location,
-one git repo, never pushed. Each person has their own intent store.
-
-Collaboration happens through pull requests and project conventions, not shared intents.
-When an intent delivers something that changes how a project works, the decision gets
-written into the project's shared files (README, docs, config). The intents themselves
-are private working memory.
-
-## Project Creation Flow
-
-When an implementation intent spawns a project:
-1. Determine project path from config `project_roots` or intent context
-2. `gh repo create --private` (agent-created repos are always private by default)
-3. Set up project directory, git init, AGENTS.md with founding intent decisions
-4. Register in `projects.yml`
-5. Create tactical mirror in project store
-6. The global intent completes; the tactical mirror becomes the active intent

package/skills/project-creating/references/project-scaffolding.md

@@ -1,97 +0,0 @@
-# Project Scaffolding Templates
-
-Full templates for the artifacts created while spawning a project: the AGENTS.md
-skeleton (Workflow step 4), the tactical mirror intent (step 5), and the
-projects.yml registration block (step 6).
-
-## Table of Contents
-
-- [AGENTS.md skeleton (step 4)](#agentsmd-skeleton-step-4)
-- [Tactical mirror intent (step 5)](#tactical-mirror-intent-step-5)
-- [projects.yml registration block (step 6)](#projectsyml-registration-block-step-6)
-
-## AGENTS.md skeleton (step 4)
-
-Create `AGENTS.md` in the project root with:
-
-```markdown
-# <Project Name> — Agent Instructions
-
-Read `PLASTIC.md` in `~/.plastic/` for the core conventions; deeper doctrine lives in
-the `plastic-conventions` skill's chapters. 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">
-```
-
-## Tactical mirror intent (step 5)
-
-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--<slug>.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
-
-## projects.yml registration block (step 6)
-
-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.