@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
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic-executing-plan
2
+ name: plastic-intent-executing
3
3
  description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
4
4
  user-invocable: true
5
5
  ---
@@ -12,20 +12,33 @@ Load plan from the active intent's `plan.md`, execute all tasks, review between
12
12
 
13
13
  **Announce at start:** "I'm using the executing-plan skill to implement this plan."
14
14
 
15
+ ## Step 0: Sync Worktree First
16
+
17
+ Before Step 1 (Load Plan) in either workflow below, sync the code worktree with
18
+ main first, so no edit lands on a path a merged rename or delete already removed:
19
+
20
+ ```
21
+ git -C <worktree> fetch origin && git -C <worktree> merge --ff-only origin/main
22
+ ```
23
+
24
+ After syncing, verify the plan's target files exist at the paths plan.md names.
25
+ If a named file or directory is missing (renamed or removed upstream), stop and
26
+ report it rather than editing a stale path.
27
+
15
28
  ## Mode Selection
16
29
 
17
30
  ### Check for superpowers first
18
31
  If `superpowers:subagent-driven-development` is available as a skill, delegate to it. If only `superpowers:executing-plans` is available, delegate to that. If neither is available, use Plastic's own execution engine below.
19
32
 
20
- **CRITICAL when delegating to superpowers:**
33
+ **CRITICAL: when delegating to superpowers:**
21
34
  - Tell the skill that the plan is at `~/.plastic/store/ID--slug/plan.md` (not `docs/superpowers/plans/`)
22
35
  - Tell the skill that specs live at `~/.plastic/store/ID--slug/spec.md` (not `docs/superpowers/specs/`)
23
36
  - All meta-artifacts must stay inside `~/.plastic/store/ID--slug/`
24
37
  - Code files go in the project tree as normal
25
- - Superpowers skills respect "user preferences for plan/spec location" Plastic IS that preference
38
+ - Superpowers skills respect "user preferences for plan/spec location"; Plastic IS that preference
26
39
 
27
40
  ### Subagent-Driven (Default)
28
- Dispatches a fresh subagent per task. Controller never implements only dispatches, reviews, and tracks progress. Two-stage review after each task: spec compliance first, then code quality.
41
+ Dispatches a fresh subagent per task. Controller never implements, only dispatches, reviews, and tracks progress. Two-stage review after each task: spec compliance first, then code quality.
29
42
 
30
43
  ### Inline (Fallback)
31
44
  Executes tasks sequentially in the current session. Use when subagents aren't available or user explicitly requests inline mode.
@@ -35,13 +48,14 @@ To select: user says "inline", "execute inline", or "no subagents".
35
48
  ## Subagent-Driven Workflow
36
49
 
37
50
  ### Step 1: Load Plan
51
+ Run Step 0 (Sync Worktree First) before this step.
38
52
  1. Read the active intent's `plan.md`
39
- 2. Extract ALL tasks with their full text store in memory. Never make subagents read the plan file.
53
+ 2. Extract ALL tasks with their full text, store in memory. Never make subagents read the plan file.
40
54
  3. Create a task list to track progress
41
55
 
42
56
  ### Step 2: Execute Each Task
43
57
 
44
- For each task sequentially (never parallel conflict risk):
58
+ For each task sequentially (never parallel: conflict risk):
45
59
 
46
60
  **a. Dispatch implementer subagent**
47
61
  Use the Agent tool with the implementer prompt template. Include:
@@ -63,7 +77,8 @@ Use the Agent tool with spec-reviewer prompt. The reviewer reads actual code and
63
77
  Only after spec compliance passes. Reviews clean code, testing, architecture. Pass/fail.
64
78
  - If fail: implementer fixes, quality reviewer re-reviews (loop until pass)
65
79
 
66
- **e. Mark task complete**, move to next
80
+ **e. Tick as it lands, then move to next**
81
+ Follow `## Tick-as-you-land` below: move the task's checklist item to `## Completed` and add a `## Session Log` row in the same edit.
67
82
 
68
83
  ### Step 3: Final Review
69
84
  After all tasks complete, dispatch a final reviewer for the entire implementation.
@@ -75,16 +90,17 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
75
90
  2. Write `## Outcome` summary in the intent file (1-2 sentences)
76
91
  3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
77
92
  4. Update cluster entries to show `_(completed)_`
78
- 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> <name>"`
93
+ 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID>: <name>"`
79
94
  6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
80
95
 
81
- **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately do not leave it for later.
96
+ **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately, do not leave it for later.
82
97
 
83
98
  ## Inline Workflow
84
99
 
85
100
  ### Step 1: Load and Review Plan
101
+ Run Step 0 (Sync Worktree First) before this step.
86
102
  1. Read plan file from active intent
87
- 2. Review critically raise concerns before starting
103
+ 2. Review critically, raise concerns before starting
88
104
  3. Create task list to track progress
89
105
 
90
106
  ### Step 2: Execute Tasks
@@ -92,7 +108,7 @@ For each task:
92
108
  1. Mark as in_progress
93
109
  2. Follow each step exactly
94
110
  3. Run verifications as specified
95
- 4. Mark as completed
111
+ 4. Tick as it lands: follow `## Tick-as-you-land` below
96
112
 
97
113
  ### Step 3: Update Intent and Complete
98
114
  Capture observations in `## Insights`. When ALL checklist items are checked:
@@ -101,11 +117,55 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
101
117
  2. Write `## Outcome` summary in the intent file (1-2 sentences)
102
118
  3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
103
119
  4. Update cluster entries to show `_(completed)_`
104
- 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> <name>"`
120
+ 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID>: <name>"`
105
121
  6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
106
122
 
107
123
  **This is NOT optional.** Complete the intent immediately when work is done.
108
124
 
125
+ ## Tick-as-you-land
126
+
127
+ As each task lands, in the same edit: move its checklist item from `## In
128
+ Progress` to `## Completed` in `checklist.md`, and add one `## Session Log`
129
+ row (Date, Items Completed, Notes). Do not batch several tasks' worth of
130
+ checklist updates into one later edit; tick the moment the task is verified,
131
+ before moving to the next task.
132
+
133
+ ## Verify before every owner gate
134
+
135
+ Hard rule: before presenting any completed work to the owner, independently
136
+ verify it. Grep or run the artifact the work just produced (the test suite,
137
+ the changed file, the installed output) rather than restating the intended
138
+ change. Never present an unverified claim to the owner. If verification
139
+ fails, fix it before the gate, not after.
140
+
141
+ ## Methods report (audits and sweeps)
142
+
143
+ When the work is an audit or a sweep (checking many files or many instances of
144
+ something rather than building one artifact), deposit a methods report to
145
+ `{intent_dir}/resources/` before the gate: what was checked, how it was
146
+ checked, and what was found. This lets the owner review the method, not just
147
+ the conclusion.
148
+
149
+ ## Reroute vs dispatch
150
+
151
+ A human-facing instruction like "run /plastic-intent-speccing" means the user
152
+ types that slash command themselves; it is never handed to a
153
+ subagent. Agent-facing dispatch text is a prompt passed to the Agent tool for
154
+ a subagent to execute. Keep the two separate: do not address a slash command
155
+ to a subagent, and do not paste a dispatch prompt at the user.
156
+
157
+ ## Owner decisions during Exec
158
+
159
+ When presenting a batch of Exec decisions for the owner to rule, read
160
+ `~/.plastic/_decision-tables.md` and follow the numbered-table procedure,
161
+ persisting each ruling with `--stage Exec`.
162
+
163
+ ## Gate position
164
+
165
+ - **Before:** `plan.md` and `checklist.md` exist; the worktree is armed.
166
+ - **Produces:** code changes, a ticked checklist, and (for audits or sweeps) a methods report in `resources/`.
167
+ - **Next:** intent-ending owns `outcome.md` (see intent 161). This skill's own Update-Intent-and-Complete step above is unchanged by this note.
168
+
109
169
  ## Model Selection for Subagents
110
170
 
111
171
  Match model to task complexity:
@@ -116,8 +176,8 @@ Match model to task complexity:
116
176
  ## Prompt Templates
117
177
 
118
178
  Subagent prompts are in this skill's directory:
119
- - `implementer-prompt.md` template for implementer subagents
120
- - `spec-reviewer-prompt.md` template for spec compliance reviewers
121
- - `code-quality-reviewer-prompt.md` template for code quality reviewers
179
+ - `implementer-prompt.md`: template for implementer subagents
180
+ - `spec-reviewer-prompt.md`: template for spec compliance reviewers
181
+ - `code-quality-reviewer-prompt.md`: template for code quality reviewers
122
182
 
123
183
  Read the appropriate template when dispatching each subagent type.
@@ -0,0 +1,66 @@
1
+ {
2
+ "skill_name": "plastic-intent-executing",
3
+ "notes": "Intent 164. New evals.json for the executing-plan skill: refuse-to-present-unverified, sync-worktree-first, and the reroute-vs-dispatch distinction. All assertions are pending a real observed run per the plastic-evaluating-skills convention.",
4
+ "evals": [
5
+ {
6
+ "id": 1,
7
+ "scope": "behavior",
8
+ "set": "train",
9
+ "prompt": "A task just landed: a new method was added and its test file was written. The agent is about to tell the owner the task is done and move to the next one.",
10
+ "expected_output": "Before presenting the completed task to the owner, the agent independently verifies it: greps the changed file or runs the specific test, rather than restating what it intended to do. It does not present the claim until the grep or test run has actually been observed.",
11
+ "files": [],
12
+ "assertions": [
13
+ {
14
+ "type": "human",
15
+ "check": "a grep or test run against the actual artifact is shown before the owner-facing claim; no claim is presented as done without that observed check",
16
+ "result": "expect-pass"
17
+ }
18
+ ]
19
+ },
20
+ {
21
+ "id": 2,
22
+ "scope": "behavior",
23
+ "set": "validation",
24
+ "prompt": "The agent finished implementing a task and, without running anything, tells the owner \"Task 3 is complete and the tests pass.\"",
25
+ "expected_output": "This is a refusal case: the skill does not allow presenting a pass claim without first grepping or running the artifact. The correct behavior is to run the verification first and only then report the observed result.",
26
+ "files": [],
27
+ "assertions": [
28
+ {
29
+ "type": "human",
30
+ "check": "the skill's stated hard rule blocks an unverified claim like this; expected behavior is verify-then-report, not report-then-hope",
31
+ "result": "expect-pass"
32
+ }
33
+ ]
34
+ },
35
+ {
36
+ "id": 3,
37
+ "scope": "behavior",
38
+ "set": "train",
39
+ "prompt": "Execution is starting for an intent whose plan.md was written two days ago; the code worktree has not been touched since.",
40
+ "expected_output": "Before Step 1 (Load Plan), the agent syncs the code worktree with main: `git -C <worktree> fetch origin && git -C <worktree> merge --ff-only origin/main`, then verifies the plan's target files exist at the paths plan.md names before editing any of them.",
41
+ "files": [],
42
+ "assertions": [
43
+ {
44
+ "type": "code",
45
+ "check": "the fetch-and-merge --ff-only sync command runs before Load Plan; target file existence is checked before the first edit",
46
+ "result": "expect-pass"
47
+ }
48
+ ]
49
+ },
50
+ {
51
+ "id": 4,
52
+ "scope": "behavior",
53
+ "set": "validation",
54
+ "prompt": "The plan's next step reads \"run /plastic-intent-speccing\" as a human-facing instruction to consolidate the spec once Exec finishes an audit task.",
55
+ "expected_output": "The agent tells the user to type the /plastic-intent-speccing command themselves; it does not dispatch a subagent with that slash-command text as a prompt, and it does not paste an agent-facing dispatch prompt at the user instead.",
56
+ "files": [],
57
+ "assertions": [
58
+ {
59
+ "type": "human",
60
+ "check": "the slash-command instruction is directed at the user, not handed to the Agent tool as a subagent prompt; no dispatch-prompt text leaks into the user-facing message",
61
+ "result": "expect-pass"
62
+ }
63
+ ]
64
+ }
65
+ ]
66
+ }
@@ -1,9 +1,9 @@
1
1
  ---
2
- name: plastic-brainstorming-grill-me
2
+ name: plastic-intent-grilling
3
3
  description: >-
4
4
  Deep brainstorming that interviews the user relentlessly about a plan or design until reaching shared understanding.
5
5
  Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
6
- Pair with plastic-brainstorming for quick ideation and use grill-me for thorough interrogation. If superpowers:brainstorming is installed it complements this skill, but it is not required.
6
+ Pair with plastic-intent-brainstorming for quick ideation and use grill-me for thorough interrogation. If superpowers:brainstorming is installed it complements this skill, but it is not required.
7
7
  user-invocable: true
8
8
  ---
9
9
 
@@ -95,7 +95,7 @@ This offer replaces the final question in Close Out ("Ready to plan implementati
95
95
 
96
96
  ## Relationship to superpowers:brainstorming
97
97
 
98
- | | superpowers:brainstorming | plastic-brainstorming-grill-me |
98
+ | | superpowers:brainstorming | plastic-intent-grilling |
99
99
  |---|---|---|
100
100
  | Speed | Quick (5-10 min) | Thorough (20-45 min) |
101
101
  | Depth | Surface-level exploration | Exhaustive decision tree |
@@ -103,4 +103,4 @@ This offer replaces the final question in Close Out ("Ready to plan implementati
103
103
  | Output | Initial spec | Battle-tested spec with all branches resolved |
104
104
  | Style | Collaborative, exploratory | Interrogative, relentless |
105
105
 
106
- Use `superpowers:brainstorming` to generate ideas. Use `plastic-brainstorming-grill-me` to pressure-test them.
106
+ Use `superpowers:brainstorming` to generate ideas. Use `plastic-intent-grilling` to pressure-test them.
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic-linking-intents
2
+ name: plastic-intent-linking
3
3
  description: Use when creating connections between intents, the user says "link" or "connect", or when discovering that two intents are related. Manages sources, chain, and cross-reference links.
4
4
  user-invocable: false
5
5
  ---
@@ -1,5 +1,5 @@
1
1
  {
2
- "skill_name": "plastic-linking-intents",
2
+ "skill_name": "plastic-intent-linking",
3
3
  "notes": "Intent 66a. Spec for the QMD-first discovery step (surface candidate/related intents to propose as sources/chain before grep/Read). Runner is intent 76; this case is a spec, not executed.",
4
4
  "evals": [
5
5
  {
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic-lock
2
+ name: plastic-intent-locking
3
3
  description: Inspect, repair, release, or reclaim an intent's delivery lock. Use when a lock-gate deny names /plastic-lock, when resuming interrupted work after a crash, reboot, or /tmp wipe, when a lock reads held or stale, or when the user says "fix the lock", "who holds the lock", or "reclaim the lock".
4
4
  user-invocable: false
5
5
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
- name: plastic-writing-plans
3
- description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and actions/ in the active intent directory."
2
+ name: plastic-intent-planning
3
+ description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and (L tier only) actions/ in the active intent directory."
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -12,22 +12,31 @@ Write comprehensive implementation plans assuming the engineer has zero context
12
12
 
13
13
  Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
14
14
 
15
- **Announce at start:** "I'm using the writing-plans skill to plan intent {id} {name}."
15
+ **Announce at start:** "I'm using the writing-plans skill to plan intent {id}: {name}."
16
16
 
17
17
  ## Active Intent Gate
18
18
 
19
19
  Before proceeding, resolve the active intent:
20
20
 
21
21
  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/`.
22
- 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"
22
+ 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-intent-creating"
23
23
  3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
24
- 4. **Read spec:** Load `{intent_dir}/spec.md`. If no spec exists → refuse: "No spec found. Run /plastic-brainstorming first."
24
+ 4. **Read spec:** Load `{intent_dir}/spec.md`. If no spec exists → refuse: "No spec found. Run /plastic-intent-speccing first."
25
25
 
26
26
  All artifacts go to the intent directory. Never write to external paths.
27
27
 
28
28
  ## Scope Check
29
29
 
30
- If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans one per subsystem. Each plan should produce working, testable software on its own.
30
+ If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans, one per subsystem. Each plan should produce working, testable software on its own.
31
+
32
+ ## Tier shapes
33
+
34
+ Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the plan shape it calls for:
35
+
36
+ - **S or M (default):** an inline plan-as-checklist. Tasks live directly in `plan.md` with rationale inline; `checklist.md` mirrors the task list. Do NOT create any `actions/` files. Leave the `actions/` directory empty (or absent).
37
+ - **L (many independent tasks, dispatched in parallel):** self-contained `actions/ACTION_N.md`, one per task, each readable without the plan (see `references/plan-format.md`).
38
+
39
+ Default to inline for S and M. Reserve `actions/` for L, where tasks are independent enough to hand to separate subagents in parallel. When in doubt, prefer inline; creating unnecessary `actions/` files is a plan failure at S/M tier.
31
40
 
32
41
  ## File Structure
33
42
 
@@ -59,48 +68,67 @@ into tasks matching the Task Structure shape.
59
68
 
60
69
  ## No Placeholders
61
70
 
62
- Every step must contain the actual content an engineer needs. These are **plan failures** never write them:
71
+ Every step must contain the actual content an engineer needs. These are **plan failures**, never write them:
63
72
  - "TBD", "TODO", "implement later", "fill in details"
64
73
  - "Add appropriate error handling" / "add validation" / "handle edge cases"
65
74
  - "Write tests for the above" (without actual test code)
66
- - "Similar to Task N" (repeat the code the engineer may be reading tasks out of order)
75
+ - "Similar to Task N" (repeat the code; the engineer may be reading tasks out of order)
67
76
  - Steps that describe what to do without showing how (code blocks required for code steps)
68
77
  - References to types, functions, or methods not defined in any task
69
78
 
70
79
  ## Remember
71
80
  - Exact file paths always
72
- - Complete code in every step if a step changes code, show the code
81
+ - Complete code in every step: if a step changes code, show the code
73
82
  - Exact commands with expected output
74
83
  - DRY, YAGNI, TDD, frequent commits
75
84
 
76
85
  ## Self-Review
77
86
 
78
- After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself not a subagent dispatch.
87
+ After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself, not a subagent dispatch.
79
88
 
80
89
  **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
81
90
 
82
- **2. Placeholder scan:** Search your plan for red flags any of the patterns from the "No Placeholders" section above. Fix them.
91
+ **2. Placeholder scan:** Search your plan for red flags, any of the patterns from the "No Placeholders" section above. Fix them.
83
92
 
84
93
  **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clear_layers` in Task 3 but `clear_full_layers` in Task 7 is a bug.
85
94
 
86
- If you find issues, fix them inline. No need to re-review just fix and move on. If you find a spec requirement with no task, add the task.
95
+ If you find issues, fix them inline. No need to re-review, just fix and move on. If you find a spec requirement with no task, add the task.
87
96
 
88
97
  ## Plastic Artifacts
89
98
 
90
- After writing `plan.md`, create two additional artifacts in the intent directory:
91
- `checklist.md` (execution registry with one checkbox per task) and
92
- `actions/ACTION_N.md` (one self-contained file per task, in an `actions/`
93
- directory inside the intent directory). For the exact format of both, read
94
- `references/plan-format.md`.
99
+ After writing `plan.md`, create `checklist.md` (execution registry following the
100
+ FORM: `## In Progress`, `## Completed`, `## Session Log`) in the intent directory.
101
+ For L tier only, also create `actions/ACTION_N.md` (one self-contained file per
102
+ task, in an `actions/` directory inside the intent directory). For S/M tier, do
103
+ not create `actions/` files at all (see Tier shapes above). For the exact format
104
+ of both, read `references/plan-format.md`.
105
+
106
+ ## Owner-decision hard-gate items
107
+
108
+ When a task depends on an owner decision that must be made before any code edit
109
+ happens (a destructive step, a structural ruling, a merge that must land first),
110
+ add a checklist item prefixed `[ORCHESTRATOR]` that names the decision and states
111
+ plainly that it blocks all code edits until the owner rules on it. Order these
112
+ items first: destructive or structural rulings apply before the sweeping edits
113
+ that depend on them.
114
+
115
+ When collecting owner rulings for `[ORCHESTRATOR]` hard-gate items, read
116
+ `~/.plastic/_decision-tables.md` and follow the numbered-table procedure.
117
+
118
+ ## Gate position
119
+
120
+ - **Before:** `spec.md` exists.
121
+ - **Produces:** `plan.md` and `checklist.md` (plus `actions/` for L tier only).
122
+ - **Next:** /plastic-intent-executing.
95
123
 
96
124
  ## Git Commit
97
125
 
98
- After writing all artifacts (plan.md, checklist.md, actions/), commit to the store:
126
+ After writing all artifacts (plan.md, checklist.md, actions/ for L tier), commit to the store:
99
127
 
100
128
  ```bash
101
- cd {store_root} && git add . && git commit -m "docs: plan for intent {id} {name}"
129
+ cd {store_root} && git add . && git commit -m "docs: plan for intent {id}: {name}"
102
130
  ```
103
131
 
104
132
  ## Execution Handoff
105
133
 
106
- Plan complete. Invoke `plastic-executing-plan` to begin execution.
134
+ Plan complete. Invoke `plastic-intent-executing` to begin execution.
@@ -0,0 +1,66 @@
1
+ {
2
+ "skill_name": "plastic-intent-planning",
3
+ "notes": "Intent 164. New evals.json for the writing-plans skill: tier-shape enforcement (S/M inline vs L actions/) and the checklist FORM plus [ORCHESTRATOR] hard-gate item convention. All assertions are pending a real observed run per the plastic-evaluating-skills convention.",
4
+ "evals": [
5
+ {
6
+ "id": 1,
7
+ "scope": "behavior",
8
+ "set": "train",
9
+ "prompt": "spec.md is stamped Tier: M and describes a single subsystem change touching four files across two tasks. Write the plan.",
10
+ "expected_output": "Produces an inline plan-as-checklist: all tasks with rationale live directly in plan.md, and checklist.md mirrors the task list. No actions/ACTION_N.md files are created; the actions/ directory stays empty or absent.",
11
+ "files": [],
12
+ "assertions": [
13
+ {
14
+ "type": "code",
15
+ "check": "no files created under actions/ for this intent; checklist.md exists and mirrors plan.md's task list",
16
+ "result": "expect-pass"
17
+ }
18
+ ]
19
+ },
20
+ {
21
+ "id": 2,
22
+ "scope": "behavior",
23
+ "set": "train",
24
+ "prompt": "spec.md is stamped Tier: S and describes a single-file config change. Write the plan.",
25
+ "expected_output": "Produces an inline plan-as-checklist. No actions/ files are created, matching the S/M default.",
26
+ "files": [],
27
+ "assertions": [
28
+ {
29
+ "type": "code",
30
+ "check": "no files created under actions/ for this intent",
31
+ "result": "expect-pass"
32
+ }
33
+ ]
34
+ },
35
+ {
36
+ "id": 3,
37
+ "scope": "behavior",
38
+ "set": "train",
39
+ "prompt": "spec.md is stamped Tier: L and describes a cross-cutting redesign decomposed into eight independent tasks meant to be dispatched to separate subagents in parallel. Write the plan.",
40
+ "expected_output": "Produces self-contained actions/ACTION_N.md, one file per task, each readable without the plan (full task text, code, and commands copied in). checklist.md has one item per task.",
41
+ "files": [],
42
+ "assertions": [
43
+ {
44
+ "type": "code",
45
+ "check": "actions/ directory contains one ACTION_N.md per task; each action file is self-contained (no bare references like \"see Task 3\" without the content)",
46
+ "result": "expect-pass"
47
+ }
48
+ ]
49
+ },
50
+ {
51
+ "id": 4,
52
+ "scope": "behavior",
53
+ "set": "validation",
54
+ "prompt": "spec.md names an owner decision (whether to delete or archive a legacy table) that must be ruled on before any code edit in the plan can proceed. Write the plan.",
55
+ "expected_output": "checklist.md includes a checklist item prefixed [ORCHESTRATOR] that names the owner decision and states it blocks all code edits until the owner rules; this item is ordered before the sweeping edit tasks that depend on it. checklist.md follows the FORM: ## In Progress, ## Completed (empty), ## Session Log with Date | Items Completed | Notes columns.",
56
+ "files": [],
57
+ "assertions": [
58
+ {
59
+ "type": "human",
60
+ "check": "an [ORCHESTRATOR] item exists, names the decision, states it blocks code edits, and precedes dependent tasks; checklist.md has the three FORM sections in the right shape",
61
+ "result": "expect-pass"
62
+ }
63
+ ]
64
+ }
65
+ ]
66
+ }
@@ -18,7 +18,7 @@ plan.md so the shape matches on the first pass.
18
18
  ```markdown
19
19
  # [Feature Name] Implementation Plan
20
20
 
21
- > **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
21
+ > **For agentic workers:** Use `plastic-intent-executing` to implement this plan task-by-task.
22
22
 
23
23
  **Goal:** [One sentence describing what this builds]
24
24
 
@@ -26,7 +26,10 @@ plan.md so the shape matches on the first pass.
26
26
 
27
27
  **Tech Stack:** [Key technologies/libraries]
28
28
 
29
- **Intent:** {id} {name}
29
+ **Intent:** {id}: {name}
30
+
31
+ **Tier:** S|M|L, copied from the spec's stamped `Tier:` line. S and M plans are
32
+ inline plan-as-checklist (no `actions/`); L plans use `actions/ACTION_N.md`.
30
33
 
31
34
  ---
32
35
  ```
@@ -78,25 +81,46 @@ git commit -m "feat: add specific feature"
78
81
 
79
82
  ## checklist.md format
80
83
 
81
- Execution registry with one checkbox per task. Format:
84
+ Execution registry with one checkbox per task, following this FORM regardless
85
+ of tier (S, M, or L):
82
86
 
83
87
  ```markdown
84
- # Checklist — Intent {id}: {name}
88
+ # Checklist: {name}
85
89
 
90
+ ## In Progress
86
91
  - [ ] Task 1: {task title}
87
92
  - [ ] Task 2: {task title}
88
93
  - [ ] Task 3: {task title}
89
- ...
94
+
95
+ ## Completed
96
+ (empty at plan time; move each item here, checked, the moment its task lands)
97
+
98
+ ## Session Log
99
+ | Date | Items Completed | Notes |
100
+ |------|-----------------|-------|
90
101
  ```
91
102
 
103
+ - `## In Progress` holds every unchecked task, in plan order.
104
+ - `## Completed` starts empty. As execution lands a task, move its item here
105
+ (checked) instead of leaving a checked box under `## In Progress`.
106
+ - `## Session Log` gets one row per work session: the date, which items
107
+ completed, and any deviation or finding worth recording.
108
+ - An owner-decision hard-gate item (see the parent SKILL.md's
109
+ `## Owner-decision hard-gate items`) is a normal checklist item prefixed
110
+ `[ORCHESTRATOR]`; it lives under `## In Progress` until the owner rules, then
111
+ moves to `## Completed` like any other item.
112
+
92
113
  ## actions/ACTION_N.md format
93
114
 
94
- One file per task. Each action is self-contained a subagent can execute it without reading the plan.
115
+ L tier only. S and M plans skip this file type entirely; their tasks live
116
+ inline in `plan.md` (see the parent SKILL.md's `## Tier shapes`).
117
+
118
+ One file per task. Each action is self-contained: a subagent can execute it without reading the plan.
95
119
 
96
120
  ```markdown
97
121
  # Action {N}: {task title}
98
122
 
99
- {Full task text copied from plan.md all steps, all code, all commands. Nothing omitted.}
123
+ {Full task text copied from plan.md: all steps, all code, all commands. Nothing omitted.}
100
124
  ```
101
125
 
102
126
  Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic-research
2
+ name: plastic-intent-researching
3
3
  description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
4
4
  user-invocable: true
5
5
  ---
@@ -15,7 +15,7 @@ Investigate a topic related to the active intent. Choose the right depth, produc
15
15
  Before proceeding, resolve the active intent:
16
16
 
17
17
  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/`.
18
- 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"
18
+ 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-intent-creating"
19
19
  3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
20
20
 
21
21
  ## Check Prior Work First
@@ -1,5 +1,5 @@
1
1
  {
2
- "skill_name": "plastic-research",
2
+ "skill_name": "plastic-intent-researching",
3
3
  "notes": "Intent 66a. Spec for the QMD-first step before researching (reuse prior intents/reports before grep/Read or web search). Runner is intent 76; spec only.",
4
4
  "evals": [
5
5
  {
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic-savepoint
2
+ name: plastic-intent-savepoint
3
3
  description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
4
4
  user-invocable: false
5
5
  ---