@zalom/plastic 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/PLASTIC-reference.md +11 -11
  2. package/PLASTIC.md +7 -7
  3. package/README.md +47 -0
  4. package/agents/plastic-enforcer.md +3 -3
  5. package/agents/plastic-intent-curator.md +9 -10
  6. package/agents/plastic-spec-specialist.md +9 -6
  7. package/bin/plastic.js +2 -2
  8. package/package.json +1 -1
  9. package/scripts/dashboard.rb +1 -1
  10. package/scripts/doctor.rb +52 -4
  11. package/scripts/end-intent +330 -0
  12. package/scripts/hook-code-gate +1 -1
  13. package/scripts/hook-continue +1 -1
  14. package/scripts/hook-create-gate +2 -2
  15. package/scripts/hook-session-start +1 -1
  16. package/scripts/lib/bridge.rb +35 -3
  17. package/scripts/lib/installer_core.rb +8 -6
  18. package/scripts/lib/store_provisioning.rb +1 -1
  19. package/scripts/new-intent +1 -1
  20. package/scripts/{versions.rb → rollback.rb} +33 -41
  21. package/scripts/update.rb +1 -1
  22. package/skills/_active-intent-gate.md +1 -1
  23. package/skills/_decision-tables.md +50 -0
  24. package/skills/auto/SKILL.md +47 -64
  25. package/skills/auto/evals/evals.json +4 -4
  26. package/skills/auto/references/agent-architecture.md +2 -2
  27. package/skills/dashboard/SKILL.md +2 -2
  28. package/skills/doctor/SKILL.md +3 -3
  29. package/skills/install/SKILL.md +1 -1
  30. package/skills/{brainstorming → intent-brainstorming}/SKILL.md +43 -45
  31. package/skills/intent-brainstorming/evals/evals.json +67 -0
  32. package/skills/{brainstorming → intent-brainstorming}/references/design-principles.md +12 -17
  33. package/skills/{continuing → intent-continuing}/SKILL.md +3 -3
  34. package/skills/{continuing → intent-continuing}/evals/evals.json +24 -24
  35. package/skills/{creating-intent → intent-creating}/SKILL.md +3 -3
  36. package/skills/{creating-intent → intent-creating}/evals/evals.json +1 -1
  37. package/skills/{intent-discovery → intent-discovering}/SKILL.md +1 -1
  38. package/skills/intent-ending/SKILL.md +151 -0
  39. package/skills/intent-ending/evals/evals.json +74 -0
  40. package/skills/{executing-plan → intent-executing}/SKILL.md +75 -15
  41. package/skills/intent-executing/evals/evals.json +66 -0
  42. package/skills/{brainstorming-grill-me → intent-grilling}/SKILL.md +4 -4
  43. package/skills/{linking-intents → intent-linking}/SKILL.md +1 -1
  44. package/skills/{linking-intents → intent-linking}/evals/evals.json +1 -1
  45. package/skills/{lock → intent-locking}/SKILL.md +1 -1
  46. package/skills/{writing-plans → intent-planning}/SKILL.md +48 -20
  47. package/skills/intent-planning/evals/evals.json +66 -0
  48. package/skills/{writing-plans → intent-planning}/references/plan-format.md +31 -7
  49. package/skills/{research → intent-researching}/SKILL.md +2 -2
  50. package/skills/{research → intent-researching}/evals/evals.json +1 -1
  51. package/skills/{savepoint → intent-savepoint}/SKILL.md +1 -1
  52. package/skills/intent-speccing/SKILL.md +69 -0
  53. package/skills/intent-speccing/evals/evals.json +126 -0
  54. package/skills/intent-speccing/references/per-section-fill-rules.md +92 -0
  55. package/skills/intent-speccing/references/self-verify-checklist.md +38 -0
  56. package/skills/intent-starting/SKILL.md +2 -2
  57. package/skills/intent-starting/evals/evals.json +2 -2
  58. package/skills/{creating-project → project-creating}/SKILL.md +2 -2
  59. package/skills/releasing/SKILL.md +18 -14
  60. package/skills/{versions → rollback}/SKILL.md +30 -20
  61. package/skills/{creating-skills → skill-creating}/SKILL.md +2 -2
  62. package/skills/{creating-skills → skill-creating}/evals/evals.json +5 -5
  63. package/skills/{creating-skills → skill-creating}/references/progressive-disclosure.md +2 -2
  64. package/skills/{evaluating-skills → skill-evaluating}/SKILL.md +1 -1
  65. package/skills/{evaluating-skills → skill-evaluating}/evals/evals.json +3 -3
  66. package/skills/{intent-curator → store-curating}/SKILL.md +6 -7
  67. package/skills/{intent-curator → store-curating}/evals/evals.json +1 -1
  68. package/skills/{managing-index → store-indexing}/SKILL.md +6 -7
  69. package/skills/{managing-index → store-indexing}/evals/evals.json +1 -1
  70. package/skills/{add-project-store → store-provisioning}/SKILL.md +2 -2
  71. package/skills/tutorial/SKILL.md +65 -0
  72. package/skills/tutorial/evals/evals.json +186 -0
  73. package/skills/tutorial/references/track-1-guided.md +123 -0
  74. package/skills/tutorial/references/track-2-auto.md +95 -0
  75. package/skills/tutorial/references/track-3-projects-and-roadmaps.md +110 -0
  76. package/skills/update/SKILL.md +1 -1
  77. package/templates/agents.md +7 -7
  78. package/skills/brainstorming/evals/evals.json +0 -22
  79. /package/skills/{continuing → intent-continuing}/references/context-management.md +0 -0
  80. /package/skills/{creating-intent → intent-creating}/references/lifecycle.md +0 -0
  81. /package/skills/{creating-intent → intent-creating}/references/wikilinks.md +0 -0
  82. /package/skills/{executing-plan → intent-executing}/code-quality-reviewer-prompt.md +0 -0
  83. /package/skills/{executing-plan → intent-executing}/implementer-prompt.md +0 -0
  84. /package/skills/{executing-plan → intent-executing}/spec-reviewer-prompt.md +0 -0
  85. /package/skills/{linking-intents → intent-linking}/references/zettelkasten.md +0 -0
  86. /package/skills/{savepoint → intent-savepoint}/references/context-management.md +0 -0
  87. /package/skills/{creating-project → project-creating}/references/hubs-projects.md +0 -0
  88. /package/skills/{creating-project → project-creating}/references/project-scaffolding.md +0 -0
  89. /package/skills/{creating-skills → skill-creating}/references/agents.md +0 -0
  90. /package/skills/{creating-skills → skill-creating}/references/evals.md +0 -0
  91. /package/skills/{creating-skills → skill-creating}/references/hooks.md +0 -0
  92. /package/skills/{creating-skills → skill-creating}/references/scripts.md +0 -0
  93. /package/skills/{creating-skills → skill-creating}/references/skills.md +0 -0
  94. /package/skills/{creating-skills → skill-creating}/scripts/scaffold.rb +0 -0
  95. /package/skills/{evaluating-skills → skill-evaluating}/assets/eval-template.json +0 -0
  96. /package/skills/{evaluating-skills → skill-evaluating}/references/convention-checks.md +0 -0
  97. /package/skills/{evaluating-skills → skill-evaluating}/references/eval-methodology.md +0 -0
  98. /package/skills/{managing-index → store-indexing}/references/zettelkasten-linking.md +0 -0
@@ -115,19 +115,19 @@ Detailed conventions live inside the skills that use them, not in this file.
115
115
 
116
116
  | Topic | Skill | References in skill |
117
117
  |-------|-------|-------------------|
118
- | Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
119
- | Brainstorming, spec writing | `plastic-brainstorming` | — |
120
- | Planning, actions | `plastic-writing-plans` | — |
121
- | Execution, delivery | `plastic-executing-plan` | — |
118
+ | Creating intents, lifecycle | `plastic-intent-creating` | lifecycle, wikilinks |
119
+ | Brainstorming, spec writing | `plastic-intent-brainstorming` | — |
120
+ | Planning, actions | `plastic-intent-planning` | — |
121
+ | Execution, delivery | `plastic-intent-executing` | — |
122
122
  | Autonomous delivery | `plastic-auto` | agent architecture |
123
- | Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
124
- | Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
125
- | Projects, hubs | `plastic-creating-project` | hubs, project stores |
126
- | Provision a project store | `plastic-add-project-store` | project stores |
127
- | Index maintenance | `plastic-managing-index` | — |
123
+ | Save/restore state | `plastic-intent-savepoint`, `plastic-intent-continuing` | context management |
124
+ | Knowledge graph, linking | `plastic-intent-linking` | zettelkasten, wikilinks |
125
+ | Projects, hubs | `plastic-project-creating` | hubs, project stores |
126
+ | Provision a project store | `plastic-store-provisioning` | project stores |
127
+ | Index maintenance | `plastic-store-indexing` | — |
128
128
  | Releases, deprecations | `plastic-releasing` | deprecation process |
129
129
  | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
130
- | Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
131
- | Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
130
+ | Authoring skills, agents, hooks | `plastic-skill-creating` | progressive disclosure, agentskills.io spec |
131
+ | Evaluating skills, evals | `plastic-skill-evaluating` | eval methodology, convention checks |
132
132
  | Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |
133
133
 
package/PLASTIC.md CHANGED
@@ -93,10 +93,10 @@ tags: [plastic, architecture]
93
93
 
94
94
  | Stage | Section | Deliverable | Detail |
95
95
  |-------|---------|-------------|--------|
96
- | **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-creating-intent` |
97
- | **Why** | `## Context` + Decisions | `spec.md` | `plastic-brainstorming` |
98
- | **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-writing-plans` |
99
- | **Exec** | Execution | `outcome.md` | `plastic-executing-plan` |
96
+ | **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-intent-creating` |
97
+ | **Why** | `## Context` + Decisions | `spec.md` | `plastic-intent-brainstorming` |
98
+ | **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-intent-planning` |
99
+ | **Exec** | Execution | `outcome.md` | `plastic-intent-executing` |
100
100
 
101
101
  `## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
102
102
  An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
@@ -237,7 +237,7 @@ Beyond the lifecycle agents, Plastic ships thin skills for day-to-day operation:
237
237
  for its three scopes (`--core` for the boot integrity check, `--store` per store on dashboard
238
238
  load, and the full no-flag walk after an update).
239
239
  - **Lifecycle skills** (`plastic-install`, `plastic-update`, `plastic-uninstall`,
240
- `plastic-versions`, intent 55) are thin wrappers over a single pinned
240
+ `plastic-rollback`, intent 55) are thin wrappers over a single pinned
241
241
  `npx -y @zalom/plastic@<channel> <verb>` call: initialize or repair an install, advance a
242
242
  channel, remove Plastic, and step the local versions ledger.
243
243
 
@@ -327,7 +327,7 @@ A Zettelkasten structure note, not a table of contents. Clusters by meaning.
327
327
 
328
328
  Sections: `## Active`, `## Future`, `## Clusters`, `## Abandoned`, `## Completed`.
329
329
 
330
- For index maintenance, use `plastic-managing-index`.
330
+ For index maintenance, use `plastic-store-indexing`.
331
331
 
332
332
  One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>](<dir>) <tags>`.
333
333
  The title is the title, not a summary: aim for about 80 characters, no multi-sentence
@@ -350,7 +350,7 @@ ALL work flows through intents.
350
350
  3. On completion, capture observations in `## Insights`.
351
351
  4. When done, write `outcome.md` + `## Outcome` summary. Update INDEX.md.
352
352
  5. Researches are intents. No separate folder.
353
- 6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
353
+ 6. Intents are created only via `plastic-intent-creating`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
354
354
 
355
355
  ## House Style (self-check)
356
356
 
package/README.md CHANGED
@@ -99,6 +99,53 @@ Plastic delivers all work through successive stages ->
99
99
  | How | What is the plan? | Plan and checklist | plan.md, checklist.md, actions/ACTION_1.md ... ACTION_N.md |
100
100
  | Exec | What was actually delivered? | Outcome | outcome.md |
101
101
 
102
+ ## How to use Plastic
103
+
104
+ Plastic organizes all work as intents. Each intent is one directory, and it carries the same
105
+ small set of files at every stage.
106
+
107
+ **The intent directory**
108
+
109
+ | File | What it holds |
110
+ | ---- | -------------- |
111
+ | `{id}--slug.md` | The intent itself: intent line, context, decisions |
112
+ | `spec.md` | The Why, consolidated into one contract for the plan |
113
+ | `plan.md`, `checklist.md`, `actions/` | The How: the plan and its execution registry |
114
+ | `outcome.md` | The Exec record: what actually shipped |
115
+
116
+ See [`docs/architecture.md`](docs/architecture.md) for the full store layout, and
117
+ [reading a delivered intent](docs/guides/reading-a-delivered-intent.md) for how to read a
118
+ finished one fast.
119
+
120
+ **From idea to delivery, one line per stage**
121
+
122
+ | Stage | What happens |
123
+ | ----- | ------------- |
124
+ | What | Describe the idea in plain words; Plastic scaffolds the intent |
125
+ | Why | Explore it, one ruling at a time, then consolidate into `spec.md` |
126
+ | How | Turn `spec.md` into `plan.md` and `checklist.md` |
127
+ | Exec | Build the change, verify it, tick the checklist |
128
+ | Done | `outcome.md` records what shipped; the index moves the intent to Completed |
129
+
130
+ Walk this once in
131
+ [your first intent in 10 minutes](docs/guides/your-first-intent-in-10-minutes.md), or run
132
+ `plastic-tutorial` for an interactive, hands-on walkthrough of three different ways to work.
133
+
134
+ **Commands, by family**
135
+
136
+ | Family | Commands |
137
+ | ------ | -------- |
138
+ | Mode | `plastic-tutorial`, `plastic-auto` |
139
+ | Intent | `plastic-intent-creating`, `plastic-intent-starting`, `plastic-intent-brainstorming`, `plastic-intent-grilling`, `plastic-intent-speccing`, `plastic-intent-planning`, `plastic-intent-executing`, `plastic-intent-ending`, `plastic-intent-continuing`, `plastic-intent-researching` |
140
+ | Project and delivery | `plastic-project-creating`, `plastic-roadmap`, `plastic-releasing` |
141
+ | Skill | `plastic-skill-creating`, `plastic-skill-evaluating` |
142
+ | Product | `plastic-install`, `plastic-update`, `plastic-uninstall`, `plastic-rollback`, `plastic-doctor`, `plastic-humanizer` |
143
+
144
+ See [`docs/guides/index.md`](docs/guides/index.md) for task-oriented walkthroughs.
145
+
146
+ The agent helps most at Why and How: turning a rough idea into rulings, and rulings into a
147
+ plan a machine can build from exactly. Read
148
+ [pick your mode](docs/guides/pick-your-mode.md) to decide how much of that to hand over.
102
149
 
103
150
  ## Compatibility and ownership
104
151
 
@@ -56,7 +56,7 @@ ceremony, never these guarantees.
56
56
  1. Arm the gate, then dispatch the brainstorming specialist; gate its `## Context` + `### Decisions`
57
57
  2. Dispatch the spec-specialist; gate `spec.md`. Then the planner; gate `plan.md` + `checklist.md`
58
58
  3. Dispatch the executor; require a green suite. Sequential, one team per intent, on one branch when files are shared
59
- 4. Dispatch and review by default through Plastic's native engine, `plastic-executing-plan` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
59
+ 4. Dispatch and review by default through Plastic's native engine, `plastic-intent-executing` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
60
60
  5. At the final gate, dispatch an independent reviewer subagent, then complete the intent
61
61
 
62
62
  ## Human-facing stage reporting
@@ -72,5 +72,5 @@ The orchestrator consumes that internal report to write the human briefing; the
72
72
 
73
73
  - Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs
74
74
  - You never delegate gate ownership; the orchestrator is always the gate-keeper
75
- - Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
76
- - Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle
75
+ - Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-intent-executing` by default, and through the superpowers skills only when they are available or the user prefers them
76
+ - Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-intent-executing` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle
@@ -10,11 +10,11 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
10
10
 
11
11
  ## Your Responsibilities
12
12
 
13
- 1. **Intent lifecycle management** move intents between Active/Future/Completed/Abandoned in INDEX.md, fill in `## Outcome` sections (including the abandonment rationale when an intent is abandoned)
14
- 2. **INDEX.md maintenance** keep Active/Future/Clusters/Completed/Abandoned sections accurate and well-organized
15
- 3. **Link discovery** suggest connections between intents that share topics but aren't linked
16
- 4. **Cluster management** create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
17
- 5. **Orphan detection** flag intents with no links and no cluster membership
13
+ 1. **Intent lifecycle management** - move intents between Active/Future/Completed/Abandoned in INDEX.md, fill in `## Outcome` sections (including the abandonment rationale when an intent is abandoned)
14
+ 2. **INDEX.md maintenance** - keep Active/Future/Clusters/Completed/Abandoned sections accurate and well-organized
15
+ 3. **Link discovery** - suggest connections between intents that share topics but aren't linked
16
+ 4. **Cluster management** - create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
17
+ 5. **Orphan detection** - flag intents with no links and no cluster membership
18
18
  6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
19
19
 
20
20
  ## How You Work
@@ -24,17 +24,16 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
24
24
  2. Read `~/.plastic/INDEX.md` (or project INDEX.md) to understand current organization
25
25
  3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
26
26
  4. Make targeted edits to INDEX.md and intent frontmatter/links
27
- 5. On a terminal-state transition (Completed OR Abandoned), run the closing acts in the canonical End-tail order (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`):
27
+ 5. On a terminal-state transition (Completed OR Abandoned), do these things:
28
28
  a. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
29
- b. Stamp the terminal savepoint bookend (intent 81) recording the disposition. Idempotent.
30
- c. Refresh the QMD index for that store LAST, after the terminal move, outcome.md, and savepoint, so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
29
+ b. Call `plastic-intent-ending` for the terminal-transition close (INDEX move, savepoint `Done` bookend, store commit, disarm, and the QMD reindex last): `ruby ~/.plastic/scripts/end-intent --store <store> --id <id> --disposition delivered|abandoned`, then follow that skill's own disarm and reindex steps. Never restate the INDEX/savepoint/reindex one-liners here.
31
30
  6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
32
31
  7. Report what you changed
33
32
 
34
33
  ## Constraints
35
34
 
36
35
  - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
37
- - You never create new intents that's the creating-intent skill's job
38
- - You never modify `## Insights`, `## Context`, or `## Outcome` content sections those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
36
+ - You never create new intents - that's the intent-creating skill's job
37
+ - You never modify `## Insights`, `## Context`, or `## Outcome` content sections - those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
39
38
  - For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
40
39
  - For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes
@@ -12,18 +12,21 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
12
12
 
13
13
  ## Your Responsibilities
14
14
 
15
- 1. **Consolidate the Why** turn the enriched `## Context` and `### Decisions` into one spec
16
- 2. **Follow the template** produce `spec.md` with Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria
17
- 3. **Stamp the tier** write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
15
+ 1. **Consolidate the Why**: turn the enriched `## Context` and `### Decisions` into one spec
16
+ 2. **Follow the template**: produce `spec.md` with all 8 sections in template order: Problem, Goals,
17
+ Non-Goals, Approach, Alternatives Considered, Decisions, Acceptance Criteria, Open Questions.
18
+ The shared fill method for each section is `skills/intent-speccing/references/per-section-fill-rules.md`;
19
+ read it when filling the template, it is the single owner of the method, do not fork it here.
20
+ 3. **Stamp the tier**: write a `Tier: S|M|L` line as the TOP line of spec.md, above the `#
18
21
  Spec:` heading, taking the value from the orchestrator's sizing / the brainstorming
19
22
  recommendation. This line is convention-only: read by the orchestrator, never validated by
20
23
  any gate or by doctor. It is an extra top line, not a template field, so no template changes.
21
- 4. **Accept collapsed sections at S/M** a spec.md whose Problem, Goals, Non-Goals, Approach,
24
+ 4. **Accept collapsed sections at S/M**: a spec.md whose Problem, Goals, Non-Goals, Approach,
22
25
  Decisions, or Acceptance Criteria sections are a single line each is still a complete
23
26
  spec.md under the same-structure invariant; do not pad it. The gates check file existence
24
27
  and realness, not artifact depth, so a collapsed-but-real spec passes.
25
- 5. **Make it the contract** the spec is what the planner and executor build against
26
- 6. **Hand off** leave a complete `spec.md` ready for the planner
28
+ 5. **Make it the contract**: the spec is what the planner and executor build against
29
+ 6. **Hand off**: leave a complete `spec.md` ready for the planner
27
30
 
28
31
  ## How You Work
29
32
 
package/bin/plastic.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // npx @zalom/plastic install [flags]
7
7
  // npx @zalom/plastic update [flags]
8
8
  // npx @zalom/plastic uninstall [flags]
9
- // npx @zalom/plastic versions [flags]
9
+ // npx @zalom/plastic rollback [flags]
10
10
  //
11
11
  // Back-compat: a bare `--uninstall` (no subcommand) routes to uninstall with a deprecation
12
12
  // warning; no subcommand at all defaults to install (legacy behaviour, one release).
@@ -15,7 +15,7 @@ import { execFileSync } from 'node:child_process'
15
15
  import { resolve } from 'node:path'
16
16
  import { existsSync } from 'node:fs'
17
17
 
18
- const VERBS = ['install', 'update', 'uninstall', 'versions']
18
+ const VERBS = ['install', 'update', 'uninstall', 'rollback']
19
19
  const packageRoot = new URL('..', import.meta.url).pathname
20
20
  const argv = process.argv.slice(2)
21
21
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zalom/plastic",
3
- "version": "1.0.3",
3
+ "version": "1.1.0",
4
4
  "description": "Intent-driven idea development system for AI coding agents",
5
5
  "type": "module",
6
6
  "bin": {
@@ -33,7 +33,7 @@ def today
33
33
  end
34
34
 
35
35
  # A generic "about a month" threshold, not tuned to any one store's item count.
36
- # Deliberately independent from plastic-continuing's separate stale_threshold_days
36
+ # Deliberately independent from plastic-intent-continuing's separate stale_threshold_days
37
37
  # config: that one is a proactive boot-time triage nudge, this is a board annotation.
38
38
  # Unifying the two is a follow-up, not this intent.
39
39
  STALE_DAYS = 30
package/scripts/doctor.rb CHANGED
@@ -476,7 +476,7 @@ class Doctor
476
476
  message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
477
477
  details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
478
478
  fixable: true,
479
- fix_hint: "Dispatch plastic-intent-curator to relocate each unsanctioned section into the " \
479
+ fix_hint: "Dispatch plastic-store-curating to relocate each unsanctioned section into the " \
480
480
  "intent's revisions.md via move-and-record (a missing required section is restored " \
481
481
  "or reprojected instead); see PLASTIC.md > Structural maintenance and revisions.md"
482
482
  )
@@ -660,7 +660,7 @@ class Doctor
660
660
  "(outcome.md or the savepoint Done echo is missing; advisory on immutable history)",
661
661
  details: gaps, fixable: true,
662
662
  fix_hint: "For live terminals, author a real outcome.md with the `disposition:` header via the " \
663
- "completion/abandon path (plastic-auto or plastic-intent-curator) and stamp the terminal " \
663
+ "completion/abandon path (plastic-auto or plastic-store-curating) and stamp the terminal " \
664
664
  "savepoint. Legacy terminal intents are immutable, so pre-convention gaps stay advisory."
665
665
  )
666
666
  end
@@ -882,7 +882,7 @@ class Doctor
882
882
  checks << graph_finding_check(
883
883
  "graph_i4_danglers", i4,
884
884
  "Every sources/chain id resolves to a real intent (I4)",
885
- "Dispatch plastic-intent-curator to record the dangling sources/chain edge as a " \
885
+ "Dispatch plastic-store-curating to record the dangling sources/chain edge as a " \
886
886
  "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
887
887
  "PLASTIC.md > Structural maintenance and revisions.md), or restore the missing intent"
888
888
  )
@@ -1052,6 +1052,11 @@ class Doctor
1052
1052
  # skills_exist — flat, hyphen-namespaced personal skills (plastic-<name>/)
1053
1053
  checks << flat_skills_check(agent_dir, "--claude")
1054
1054
 
1055
+ # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
1056
+ # e.g. an old-name copy after a rename; intent 158a AC15)
1057
+ stray_check = stray_skills_check(agent_dir, "--claude", File.join(agent_dir, "plastic", "manifest.json"))
1058
+ checks << stray_check if stray_check
1059
+
1055
1060
  # agents_exist — auto-mode role files (plastic-*.md) synced into <dir>/agents
1056
1061
  checks << flat_agents_check(agent_dir, "--claude")
1057
1062
 
@@ -1078,6 +1083,43 @@ class Doctor
1078
1083
  end
1079
1084
  end
1080
1085
 
1086
+ # Backstop for a rename or removal (intent 158a, AC15): an installed plastic-*
1087
+ # skill directory under agent_dir/skills that has NO corresponding entry in the
1088
+ # current install manifest is a stray (e.g. a leftover old-name copy the
1089
+ # install/update prune should have removed, or one it never saw because the
1090
+ # manifest predates it). Complements flat_skills_check (which only confirms at
1091
+ # least one skill exists). Defers to the manifest check when the manifest itself
1092
+ # is missing or malformed, so the two checks never double-report the same gap.
1093
+ def stray_skills_check(agent_dir, installer_flag, manifest_path)
1094
+ skills_root = File.join(agent_dir, "skills")
1095
+ manifest = read_json_safe(manifest_path)
1096
+ files = manifest.is_a?(Hash) ? manifest["files"] : nil
1097
+ return nil unless files.is_a?(Hash)
1098
+
1099
+ installed = Dir.glob(File.join(skills_root, "plastic-*", "SKILL.md"))
1100
+ .map { |f| File.basename(File.dirname(f)) }
1101
+ tracked = files.keys
1102
+ .select { |p| p.start_with?("#{skills_root}/") }
1103
+ .map { |p| p.sub("#{skills_root}/", "").split("/").first }
1104
+ .uniq
1105
+
1106
+ strays = (installed - tracked).sort
1107
+
1108
+ if strays.empty?
1109
+ check(
1110
+ category: "agent_registration", name: "stray_skills", status: "pass",
1111
+ message: "No stray plastic-* skill directories in #{tilde(skills_root)}"
1112
+ )
1113
+ else
1114
+ check(
1115
+ category: "agent_registration", name: "stray_skills", status: "warn",
1116
+ message: "#{strays.size} installed skill dir(s) not in the current manifest (stray, e.g. a leftover old-name copy)",
1117
+ details: strays,
1118
+ fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest #{installer_flag}"
1119
+ )
1120
+ end
1121
+ end
1122
+
1081
1123
  # Auto-mode role agents install as <dir>/agents/plastic-*.md. Pass if at least
1082
1124
  # one such role file is present (the installer syncs agents/ on every install).
1083
1125
  def flat_agents_check(agent_dir, installer_flag)
@@ -1104,6 +1146,12 @@ class Doctor
1104
1146
 
1105
1147
  # For codex/hermes: just check skills exist (no settings.json hooks)
1106
1148
  checks << flat_skills_check(agent_dir, "--#{agent_key}")
1149
+
1150
+ # stray_skills — installed plastic-* skill dir with no manifest entry (a leftover,
1151
+ # e.g. an old-name copy after a rename; intent 158a AC15)
1152
+ stray_check = stray_skills_check(agent_dir, "--#{agent_key}", File.join(agent_dir, "plastic-manifest.json"))
1153
+ checks << stray_check if stray_check
1154
+
1107
1155
  checks << flat_agents_check(agent_dir, "--#{agent_key}")
1108
1156
 
1109
1157
  checks
@@ -1405,7 +1453,7 @@ class Doctor
1405
1453
  checks << check(
1406
1454
  category: "project_stores", name: "project_yml_exists", status: "warn",
1407
1455
  message: "project.yml missing for project '#{slug}'",
1408
- fixable: true, fix_hint: "Create project.yml from template — see plastic-creating-project"
1456
+ fixable: true, fix_hint: "Create project.yml from template — see plastic-project-creating"
1409
1457
  )
1410
1458
  end
1411
1459