@zalom/plastic 1.0.0-alpha.2 → 1.0.0-alpha.20

package/skills/auto/references/agent-architecture.md

@@ -0,0 +1,60 @@
+# Agent Architecture
+
+## Main Orchestrator
+
+The Main Orchestrator manages the global store (Main Knowledge Base). It:
+- Recognizes, creates, updates, and groups intents
+- Spawns Project Orchestrators for registered projects
+- Receives contributions back from Project Orchestrators
+- Is the only agent that runs in a loop (continuous Build→Observe→Repeat)
+
+## Project Orchestrators
+
+Project Orchestrators manage project stores (Project Knowledge Bases). They:
+- Care about intents and execution within their project
+- Spawn teams to develop and execute intents
+- Contribute back to the Main Orchestrator when new intents are born
+  that could enrich the Main Knowledge Base
+
+Rules:
+- 1 Main Orchestrator : 1 Global Store (`~/.plastic/`)
+- 1 Main Orchestrator : N Project Orchestrators
+- 1 Project Orchestrator : 1 Project Store
+- 1 Agent : 1 Intent (exclusive assignment)
+- 1 Agent : N Sub-agents (for parallel Actions within an intent)
+
+## Two Modes
+
+- **Human-driven:** Human chats with Main Orchestrator, creates intents,
+  brainstorms, then Main Orchestrator dispatches Project Orchestrators and
+  Agents for execution.
+- **Autonomous:** Human gives Main Orchestrator a starting intent with defined
+  outcomes. Main Orchestrator runs the full cycle — Agents do the lifecycle
+  (What→Why→How→Exec), Main Orchestrator reviews Insights, spawns next intents,
+  dispatches again.
+
+## Autonomous Delivery
+
+Human owns What and Why for human-initiated intents. Agent assists (research,
+exploration) but human drives until handoff. When Why is complete — or human
+triggers `plastic-auto` — the agent takes over How and Exec autonomously.
+
+- **Safe-by-default:** Agent always prefers non-destructive routes (rename vs
+  delete, additive migrations, backups before changes). Destructive actions on
+  existing projects require human approval unless `--skip-permissions` is set.
+- **One agent per intent.** Agent follows the full W→W→H→E lifecycle.
+- **Notification only on:** finish or hard stop (blocked on destructive action,
+  unresolvable error). No progress reports — `## Insights` tracks everything.
+- **Greenfield autonomy:** During initial project creation, all decisions are
+  non-destructive (nothing to destroy). Agent has full autonomy for greenfield choices.
+- **Autonomous decisions** are logged in `## Insights` with `(autonomous)` marker.
+
+## Coordinator Loop
+
+When "work on Project X":
+1. Read `projects.yml` → find project path
+2. Load global config (defaults)
+3. Load project config (overrides)
+4. Load global INDEX.md → find hub intents tagged `project-<name>`
+5. Load project INDEX.md → tactical intents
+6. Coordinator has full picture, dispatches Agent teams

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: plastic-brainstorming
+description: "Explore intent requirements and design before implementation. Produces spec.md in the active intent directory."
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Announce: "I'm using the brainstorming skill to explore the design for intent {id} — {name}."
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## 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}/`
+
+All artifacts go to the intent directory. Never write to external paths.
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits, read active intent
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write spec** — save to `{intent_dir}/spec.md` and commit to store repo
+6. **Spec self-review** — placeholder scan, consistency, scope, ambiguity
+7. **User reviews written spec** — ask user to review before proceeding
+8. **Transition to planning** — invoke `plastic-writing-plans`
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write spec" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke plastic-writing-plans" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write spec" [label="yes"];
+    "Write spec" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write spec" [label="changes requested"];
+    "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
+}
+```
+
+**The terminal state is invoking `plastic-writing-plans`.** Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is `plastic-writing-plans`.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**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.
+
+## After the Design
+**Documentation:**
+- Write the validated design (spec) to `{intent_dir}/spec.md` using the `${CLAUDE_PLUGIN_ROOT}/templates/spec.md` form
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit to the store repo:
+  ```
+  cd {store_root} && git add . && git commit -m "docs: spec for intent {id} — {name}"
+  ```
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+> "Spec written and committed to `{intent_dir}/spec.md`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+- Invoke `plastic-writing-plans` to create the implementation plan
+- Do NOT invoke any other skill. `plastic-writing-plans` is the next step.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/skills/brainstorming-grill-me/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:brainstorming-grill-me
+name: plastic-brainstorming-grill-me
 description: >-
   Deep brainstorming that interviews the user relentlessly about a plan or design until reaching shared understanding.
   Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
@@ -83,18 +83,18 @@ If ALL items pass, offer autonomous delivery:
 >
 > Want to grill more, or should I go autonomous?"
 
-- If human says go → invoke `plastic:auto`
+- If human says go → invoke `plastic-auto`
 - If human says grill more → continue grilling (reset to step 2)
 - If human says neither (wants to drive manually) → proceed as before (offer planning)
 
 This offer replaces the final question in Close Out ("Ready to plan implementation, or do you want another pass?"). The new options are:
-1. Go autonomous (`plastic:auto`)
+1. Go autonomous (`plastic-auto`)
 2. Grill more (continue interrogation)
 3. Plan manually (invoke `superpowers:writing-plans` or proceed with human-driven planning)
 
 ## Relationship to superpowers:brainstorming
 
-| | superpowers:brainstorming | plastic:brainstorming-grill-me |
+| | superpowers:brainstorming | plastic-brainstorming-grill-me |
 |---|---|---|
 | Speed | Quick (5-10 min) | Thorough (20-45 min) |
 | Depth | Surface-level exploration | Exhaustive decision tree |
@@ -102,4 +102,4 @@ This offer replaces the final question in Close Out ("Ready to plan implementati
 | Output | Initial spec | Battle-tested spec with all branches resolved |
 | Style | Collaborative, exploratory | Interrogative, relentless |
 
-Use `superpowers:brainstorming` to generate ideas. Use `plastic:brainstorming-grill-me` to pressure-test them.
+Use `superpowers:brainstorming` to generate ideas. Use `plastic-brainstorming-grill-me` to pressure-test them.

package/skills/continuing/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:continuing
+name: plastic-continuing
 description: Use when the user says "continue" after a /clear, or when resuming work in a new session. Reads intent state from global store (~/.plastic/) or local store, offers active intents first, then future intents, and surfaces stale intents for triage.
 ---
 
@@ -14,10 +14,22 @@ description: Use when the user says "continue" after a /clear, or when resuming
 
 1. Check `~/.plastic/INDEX.md` → global mode
 2. 
-3. If neither exists → announce "No Plastic store found. Run /plastic:install."
+3. If neither exists → announce "No Plastic store found. Run /plastic-install."
 
 ## Workflow
 
+### 0. Render the dashboard (overview)
+For the "where are we / what's next" overview, run the deterministic dashboard and show
+its output verbatim instead of hand-summarizing intents:
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb continue
+```
+
+This is the uniform, model-agnostic cockpit (active + last touched, then the Value×Effort
+matrix). Then continue with the steps below to actually resume a specific intent. See the
+`plastic-dashboard` skill for how to read the matrix.
+
 ### 1. Read INDEX.md
 Read the INDEX.md from the active store. Extract intents under `## Active` and `## Future`.
 
@@ -68,7 +80,7 @@ Last autonomous action: [last (autonomous) insight entry]
 Next step: [from checklist or savepoint]
 ```
 
-**Then:** Continue autonomous execution by invoking `plastic:auto`. The auto skill will pick up from the current lifecycle stage (it reads filesystem state to determine where to resume).
+**Then:** Continue autonomous execution by invoking `plastic-auto`. The auto skill will pick up from the current lifecycle stage (it reads filesystem state to determine where to resume).
 
 If NOT found — resume normally as described in step 3.
 
@@ -91,7 +103,7 @@ Stale future intents (no action taken):
      - implement: agent builds it
      - research: agent investigates feasibility
      - ideate: agent explores the problem space
-  d) Auto — go fully autonomous (invokes plastic:auto — agent delivers the intent end-to-end)
+  d) Auto — go fully autonomous (invokes plastic-auto — agent delivers the intent end-to-end)
 ```
 
 Auto-commit all triage changes.
@@ -102,3 +114,7 @@ Auto-commit all triage changes.
 2. **Project context** — if in a registered project, show governing intent + tactical intents
 3. **Stale future intents** — surface for triage
 4. **Fresh future intents** — offer as next work
+
+## References
+
+- Read `references/context-management.md` for the full save/continue protocol when resuming from a savepoint or when the resume flow needs debugging

package/skills/continuing/references/context-management.md

@@ -0,0 +1,32 @@
+# Context Management (Start-Save-Continue)
+
+## Save Point
+Triggered by PreCompact hook or manually:
+1. Find active intent(s) from `~/.plastic/INDEX.md`
+2. Update active intent's `checklist.md` (check off completed items)
+3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
+4. Add observations to `## Insights`
+5. Update INDEX.md
+6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
+7. Notify user to `/clear`
+
+## Continue
+Triggered by UserPromptSubmit hook when user says "continue". Priority order:
+
+**1. Active intents first (resume work):**
+1. Read INDEX.md → find active intent(s)
+2. Read active intent's `intent.md` → what and why
+3. Read active intent's `savepoint.md` → where we left off
+4. Read active intent's `checklist.md` → what's next
+5. Announce: intent name, current state, next step, blockers
+6. Resume
+
+**2. No active intents → offer future intents:**
+1. List all future intents from INDEX.md
+2. Present them as options
+3. When user picks one, move to Active in INDEX.md
+
+**3. Stale future intents (untouched 3+ days) → triage:**
+- **activate** — start working on it now
+- **abandon** — mark as abandoned
+- **defer to agent** — implement, research, or ideate

package/skills/creating-intent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: plastic:creating-intent
+name: plastic-creating-intent
 description: Use when new work begins, the user expresses a new goal, says "new intent", or no active intent exists for the current task. Creates intents in the global store (~/.plastic/store/) or in a project's store (~/.plastic/projects/{slug}/store/) depending on context.
 ---
 
@@ -60,6 +60,16 @@ IDs are scoped to the store they live in. Use the correct store path:
 "${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "<STORE>" "<parent_id>"
 ```
 
+**Branch vs root — decide before assigning the ID.** Having a "parent" in mind does
+NOT automatically mean branch. Choose by meaning:
+
+- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation. It only
+  makes sense as part of the parent's work.
+- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
+  Capture the inspiration in `sources` (e.g., `sources: ["14"]`), not in the ID.
+- **Rule of thumb:** if the intent could exist without its parent, make it a root and
+  set `sources`. Only branch when it genuinely cannot stand alone.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:
@@ -120,3 +130,8 @@ cd <store-root> && git add . && git commit -m "feat: create intent ID — [name]
 ### 8. Announce
 
 "Created intent ID — [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
+
+## References
+
+- Read `references/lifecycle.md` for the full What→Why→How→Exec stage detail, filesystem-as-schema conventions, and creating-intent step-by-step
+- Read `references/wikilinks.md` for the wikilink syntax table when adding `## Links` to intents

package/skills/creating-intent/references/lifecycle.md

@@ -0,0 +1,74 @@
+# Building an Intent — Full Lifecycle Detail
+
+## What → `## Intent` section
+
+The desire. One paragraph. What the human or agent wants.
+This exists from the moment the intent is created.
+
+**Deliverable:** `{ID}--{slug}.md`
+
+## Why → `## Context` + `### Decisions` sections
+
+Why this intent exists. Grows over time through brainstorming and exploration.
+
+- **Context** — what we knew going in + what we decided along the way
+- **Decisions** — main premises derived from Context plus decisions from brainstorming/grilling
+- Decisions are Why-level: "status belongs on actions because multiple workstreams", not How-level: "use ACTION_N.md files"
+
+**Deliverable:** `spec.md` (consolidated specification from Context + Decisions + brainstorming)
+
+## How → Planning and preparation
+
+Research decisions, create the implementation plan, define actions.
+
+**Deliverable:** `plan.md` + `actions/` + `checklist.md` (execution registry with checkboxes covering all actions)
+
+## Exec → Execute actions
+
+Execute actions from the plan, track progress via checklist.
+
+**Deliverable:** `outcome.md` (detailed result). `## Outcome` in intent.md = short summary written as last step.
+
+## `## Insights` — Append-only work log
+
+Captured throughout ALL stages. One-liner bullet points.
+Never modified, only appended.
+
+Tracks: stage transitions, decisions, shifts, blocks, cancellations, material for future intents.
+This is how execution is tracked. When this intent completes, Insights
+is where to look for what comes next. New intents spawned from Insights
+appear in the `chain` field.
+
+## `## Links`
+
+Wikilinks for Obsidian graph navigation. Human-facing counterpart to the
+frontmatter knowledge graph.
+
+## Conventions — Filesystem as Schema
+
+State is derived from what exists, not from what's declared.
+
+| Convention | Signal |
+|---|---|
+| No `## Context` | Intent is fleeting (quick capture, non-actionable) |
+| `## Context` has content | Intent is permanent (developed, actionable) |
+| `## Outcome` has content | Intent is done |
+| `## Insights` has `(autonomous)` entries | Intent is/was being delivered autonomously |
+
+### Transitions
+
+- Fleeting → permanent: add `## Context` (one-way, also makes it actionable)
+- There is no separate "non-actionable → actionable" transition — permanence implies actionability
+- Even research intents are actionable: the research itself is the action, the conclusion is the outcome
+
+## Creating an Intent — Full Steps
+
+1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
+2. Determine the Folgezettel ID: If root (no parent), find highest root number +1. If branch, run `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
+3. Create the intent directory in the chosen store (e.g., `ID--three-to-five-words`)
+4. Create `{ID}--{slug}.md` with frontmatter (id, intent, sources, chain, created, author, tags)
+5. Write `## Intent` — the What
+6. Add remaining sections: `## Context`, `## Outcome`, `## Insights`, `## Links`
+7. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
+
+A fleeting intent can skip `## Context` — just `## Intent` and empty sections.

package/skills/creating-intent/references/wikilinks.md

@@ -0,0 +1,8 @@
+# Wikilink Conventions
+
+| Syntax | Meaning |
+|--------|---------|
+| `[[ID]]` | Link to intent in same store (e.g., `[[1a1]]`) |
+| `[[ID\|display text]]` | Link with human-readable label |
+| `[[global:ID]]` | Link to intent in `~/.plastic/store/` |
+| `[[project-slug:ID]]` | Link to intent in `~/.plastic/projects/{slug}/store/` |

package/skills/creating-project/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: plastic:creating-project
+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,
+  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.
 ---
@@ -31,9 +31,9 @@ cd <project_root>/<slug>
 git init
 ```
 
-### 3. Run `plastic:install --local`
+### 3. Run `plastic-install --local`
 
-Invoke `plastic:install --local` in the project directory. This creates:
+Invoke `plastic-install --local` in the project directory. This creates:
 ```
 .plastic/
 ├── store/
@@ -164,3 +164,7 @@ Log in `## Insights` of each founding intent:
 
 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/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

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

@@ -0,0 +1,55 @@
+# 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/dashboard/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: plastic-dashboard
+description: Use when the user wants an overview of intents, asks "where are we", "what's next", "what should I work on", "show the dashboard", or invokes /plastic-dashboard. Renders a deterministic Value×Effort work cockpit across the global store and all projects, and emits a machine-readable queue that auto mode consumes.
+---
+
+# Dashboard — Plastic Work Cockpit
+
+A deterministic, template-driven overview of the intent store(s). It answers three
+questions at a glance — **where we are** (active + last touched), **where we go next**
+(a Value×Effort matrix), and **how to conduct it** (a disposition verb per intent) — and
+emits a JSON manifest that `plastic-auto` reads to pick the next dispatchable intent.
+
+The script does the rendering. The LLM is **never** in the rendering path: same store
+state → byte-identical output, regardless of model. Do not hand-summarize intents when
+this skill applies — run the script and show its output verbatim.
+
+## When to Use
+
+- User invokes `/plastic-dashboard`
+- User asks "where are we", "what's next", "what should I work on", "show me the intents"
+- `plastic-continuing` embeds the `continue` view on resume
+- `plastic-auto` reads `--json` to choose the next dispatchable intent
+
+## Procedure
+
+### Step 1 — Run the script
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>|all] [--json]
+```
+
+| Mode | Shows |
+|------|-------|
+| `continue` (default) | Cross-scope: active + last touched, then the Value×Effort matrix for all scopes |
+| `project <slug>` | One project: active line + its Value×Effort matrix |
+| `all` | Per-scope roll-up summary |
+| `--json` | The auto-mode manifest (any mode); machine-readable, not for humans |
+
+The script is **read-only**. Print its stdout verbatim — do not reformat, re-sort, or
+re-summarize. That is what keeps the output uniform.
+
+### Step 2 — Read the matrix
+
+```
+                 small effort          big effort
+   high value    QUICK WIN             ★ NEXT BIG THING
+   low value     DEFER → agent         TRIAGE / question
+   (type=research/exploration → RESEARCH band, regardless of quadrant)
+```
+
+Disposition verbs: `▸ drive` (human leads), `⇢ defer` (agent knocks off),
+`⊙ research` (research/explore agent), `⚑ triage` (human review / maybe abandon).
+Flags: `⇡ unblocked` (a dependency just completed), `(Nd)` stale age.
+
+### Step 3 — Act on it
+
+- **★ Next big thing** and `▸ drive` / `⚑ triage` items → the human leads (brainstorm → plan → exec).
+- `⇢ defer` and `⊙ research` items → dispatchable to agents.
+- In auto mode, read `--json` and work `dispatchable_queue` in `rank` order; leave
+  `human_only` for the user.
+
+## JSON contract
+
+```json
+{ "generated_for": "auto-mode", "scope": "<scope|all>",
+  "next_big_thing": "<id|null>",
+  "dispatchable_queue": [ {"id","scope","disposition","type","value","effort","flags","rank"} ],
+  "human_only": ["<id>", "..."] }
+```
+
+## How classification works (deterministic)
+
+- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
+  (plan/checklist exists), or deep refinement branches; big otherwise.
+- **Value** — high only for an explicit `value: high` frontmatter field, or a
+  human-authored root intent that has spawned follow-on work (`chain` non-empty); low otherwise.
+- **Override** — a `value: high|normal|low` field in an intent's frontmatter wins. This is
+  the only place model judgment enters, and only as pre-stamped data (never at render time).
+
+## Eval
+
+This skill's eval is **render the template**: run the engine against the test fixture
+store and assert byte-identical text + JSON output against the golden snapshots in
+`test/fixtures/dashboard/`. See `test/dashboard_test.rb`. If output drifts from the
+golden files without an intentional template change, the skill is broken.
+
+## Notes
+
+- Clusters (Zettelkasten grouping in INDEX.md) are intentionally **not** rendered — they
+  are orthogonal to "what to work on next."
+- Glyphs are monochrome Unicode (no emoji); they render in standard terminal emulators.
+- This is additive: it changes no core lifecycle, gate, or cycle logic.