@zalom/plastic 2.0.0-alpha.27 → 2.0.0-alpha.29

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 (207) hide show
  1. package/PLASTIC.md +13 -139
  2. package/README.md +345 -133
  3. package/agents/plastic-enforcer.md +9 -10
  4. package/agents/plastic-executor.md +1 -1
  5. package/bin/crap +4 -0
  6. package/bin/lib/context_budget.rb +35 -1
  7. package/bin/lib/skill_census.rb +839 -0
  8. package/bin/plastic +6 -0
  9. package/bin/plastic-skill-census +114 -0
  10. package/bin/verify-change +345 -0
  11. package/deprecations.yml +1 -1
  12. package/{skills/agent-advisor/references → docs/help}/advisor-protocol.md +4 -7
  13. package/{skills/auto/references → docs/help}/agent-architecture.md +7 -7
  14. package/{skills/conventions/references → docs/help}/completion-and-done.md +1 -1
  15. package/{skills/auto/references → docs/help}/human-report-contract.md +17 -19
  16. package/{skills/conventions/references → docs/help}/roadmaps.md +2 -2
  17. package/{skills/tutorial/references → docs/help}/track-1-guided.md +8 -8
  18. package/{skills/tutorial/references → docs/help}/track-2-auto.md +5 -5
  19. package/{skills/tutorial/references → docs/help}/track-3-projects-and-roadmaps.md +24 -17
  20. package/package.json +3 -2
  21. package/scripts/append-ledger +2 -1
  22. package/scripts/dashboard.rb +10 -9
  23. package/scripts/day-summary +2 -1
  24. package/scripts/doctor.rb +48 -42
  25. package/scripts/end-intent +2 -8
  26. package/scripts/file-session-intent +2 -1
  27. package/scripts/hook-capture +4 -3
  28. package/scripts/hook-close +2 -1
  29. package/scripts/hook-record +3 -2
  30. package/scripts/hook-savepoint +3 -2
  31. package/scripts/hook-session-start +5 -4
  32. package/scripts/hook-stop +2 -1
  33. package/scripts/insight-append +1 -2
  34. package/scripts/install.rb +3 -1
  35. package/scripts/lib/active_delivery.rb +1 -1
  36. package/scripts/lib/arm.rb +2 -1
  37. package/scripts/lib/backup.rb +65 -0
  38. package/scripts/lib/cli/command.rb +85 -0
  39. package/scripts/lib/cli/commands/auto.rb +18 -0
  40. package/scripts/lib/cli/commands/auto_brief.rb +44 -0
  41. package/scripts/lib/cli/commands/auto_lock.rb +60 -0
  42. package/scripts/lib/cli/commands/auto_report.rb +50 -0
  43. package/scripts/lib/cli/commands/auto_take.rb +25 -0
  44. package/scripts/lib/cli/commands/backup.rb +43 -0
  45. package/scripts/lib/cli/commands/checkout.rb +25 -0
  46. package/scripts/lib/cli/commands/continue.rb +66 -0
  47. package/scripts/lib/cli/commands/doctor.rb +20 -0
  48. package/scripts/lib/cli/commands/feedback.rb +40 -0
  49. package/scripts/lib/cli/commands/help.rb +69 -0
  50. package/scripts/lib/cli/commands/hook.rb +32 -0
  51. package/scripts/lib/cli/commands/index.rb +23 -0
  52. package/scripts/lib/cli/commands/install.rb +21 -0
  53. package/scripts/lib/cli/commands/installer_verb.rb +37 -0
  54. package/scripts/lib/cli/commands/intent.rb +19 -0
  55. package/scripts/lib/cli/commands/intent_answer.rb +37 -0
  56. package/scripts/lib/cli/commands/intent_command.rb +53 -0
  57. package/scripts/lib/cli/commands/intent_end.rb +61 -0
  58. package/scripts/lib/cli/commands/intent_new.rb +62 -0
  59. package/scripts/lib/cli/commands/intent_note.rb +43 -0
  60. package/scripts/lib/cli/commands/intent_rule.rb +36 -0
  61. package/scripts/lib/cli/commands/intent_show.rb +25 -0
  62. package/scripts/lib/cli/commands/intent_spec.rb +44 -0
  63. package/scripts/lib/cli/commands/intent_step.rb +43 -0
  64. package/scripts/lib/cli/commands/intent_verify.rb +26 -0
  65. package/scripts/lib/cli/commands/migrate.rb +16 -0
  66. package/scripts/lib/cli/commands/migrate_stores.rb +31 -0
  67. package/scripts/lib/cli/commands/next.rb +49 -0
  68. package/scripts/lib/cli/commands/project.rb +19 -0
  69. package/scripts/lib/cli/commands/project_links.rb +42 -0
  70. package/scripts/lib/cli/commands/project_list.rb +20 -0
  71. package/scripts/lib/cli/commands/project_new.rb +72 -0
  72. package/scripts/lib/cli/commands/query.rb +31 -0
  73. package/scripts/lib/cli/commands/render.rb +25 -0
  74. package/scripts/lib/cli/commands/roadmap.rb +19 -0
  75. package/scripts/lib/cli/commands/roadmap_check.rb +44 -0
  76. package/scripts/lib/cli/commands/roadmap_log.rb +54 -0
  77. package/scripts/lib/cli/commands/roadmap_next.rb +34 -0
  78. package/scripts/lib/cli/commands/roadmap_show.rb +45 -0
  79. package/scripts/lib/cli/commands/rollback.rb +20 -0
  80. package/scripts/lib/cli/commands/search.rb +60 -0
  81. package/scripts/lib/cli/commands/session.rb +18 -0
  82. package/scripts/lib/cli/commands/session_commit.rb +42 -0
  83. package/scripts/lib/cli/commands/session_handoff.rb +34 -0
  84. package/scripts/lib/cli/commands/session_summary.rb +35 -0
  85. package/scripts/lib/cli/commands/status.rb +68 -0
  86. package/scripts/lib/cli/commands/subcommand_list.rb +36 -0
  87. package/scripts/lib/cli/commands/sync.rb +46 -0
  88. package/scripts/lib/cli/commands/uninstall.rb +20 -0
  89. package/scripts/lib/cli/commands/update.rb +20 -0
  90. package/scripts/lib/cli/commands/version.rb +53 -0
  91. package/scripts/lib/cli/frontier.rb +84 -0
  92. package/scripts/lib/cli/legacy.rb +50 -0
  93. package/scripts/lib/cli/output.rb +102 -0
  94. package/scripts/lib/cli/scope.rb +127 -0
  95. package/scripts/lib/cli/table.rb +64 -0
  96. package/scripts/lib/cli.rb +94 -0
  97. package/scripts/lib/compact_instructions.rb +8 -0
  98. package/scripts/lib/day_summary.rb +4 -3
  99. package/scripts/lib/doctor_core.rb +7 -32
  100. package/scripts/lib/doctor_session_ledger.rb +2 -1
  101. package/scripts/lib/feedback_report.rb +1 -1
  102. package/scripts/lib/graph_measure_models.rb +3 -1
  103. package/scripts/lib/index_entry.rb +9 -0
  104. package/scripts/lib/installer_core.rb +73 -19
  105. package/scripts/lib/intent_screen.rb +3 -3
  106. package/scripts/lib/lock.rb +2 -2
  107. package/scripts/lib/node_input.rb +3 -2
  108. package/scripts/lib/preflight.rb +4 -6
  109. package/scripts/lib/project_config.rb +2 -1
  110. package/scripts/lib/project_validator.rb +3 -2
  111. package/scripts/lib/qmd_sync.rb +8 -7
  112. package/scripts/lib/reference_archive.rb +45 -0
  113. package/scripts/lib/release_guard.rb +2 -0
  114. package/scripts/lib/report_screen.rb +4 -3
  115. package/scripts/lib/rlm/corpus.rb +13 -0
  116. package/scripts/lib/rlm/probe.rb +29 -0
  117. package/scripts/lib/rlm/query.rb +22 -0
  118. package/scripts/lib/roadmap_queue.rb +2 -2
  119. package/scripts/lib/roadmap_savepoint.rb +1 -1
  120. package/scripts/lib/runner_absorb.rb +3 -2
  121. package/scripts/lib/search_index.rb +55 -0
  122. package/scripts/lib/session_git.rb +4 -3
  123. package/scripts/lib/sqlite.rb +22 -0
  124. package/scripts/lib/store_discovery.rb +7 -6
  125. package/scripts/lib/store_layout.rb +54 -0
  126. package/scripts/lib/store_provisioning.rb +2 -1
  127. package/scripts/lib/store_sync.rb +85 -0
  128. package/scripts/lib/stores_move.rb +93 -0
  129. package/scripts/lib/verify_intent.rb +2 -7
  130. package/scripts/lib/version_number.rb +48 -0
  131. package/scripts/lib/work_graph.rb +59 -0
  132. package/scripts/lib/worktree.rb +3 -8
  133. package/scripts/lib/worktree_sweep.rb +3 -2
  134. package/scripts/link-suggest +2 -1
  135. package/scripts/migrate-to-global +1 -1
  136. package/scripts/new-intent +3 -12
  137. package/scripts/plastic-lock +3 -2
  138. package/scripts/promote-session-item +3 -2
  139. package/scripts/release-check +10 -5
  140. package/scripts/report-screen +1 -1
  141. package/scripts/session-commit +2 -1
  142. package/scripts/spawn-preamble +2 -2
  143. package/scripts/update.rb +25 -4
  144. package/scripts/write-handoff +2 -1
  145. package/templates/agents.md +6 -6
  146. package/templates/render.css +10 -0
  147. package/bin/plastic.js +0 -70
  148. package/skills/agent-advisor/SKILL.md +0 -84
  149. package/skills/auto/SKILL.md +0 -297
  150. package/skills/auto/evals/evals.json +0 -255
  151. package/skills/auto/references/end-tail.md +0 -64
  152. package/skills/conventions/SKILL.md +0 -29
  153. package/skills/dashboard/SKILL.md +0 -180
  154. package/skills/dashboard/evals/evals.json +0 -38
  155. package/skills/dashboard/references/classification.md +0 -22
  156. package/skills/dashboard/templates/dashboard-global.md +0 -20
  157. package/skills/dashboard/templates/dashboard-project.md +0 -19
  158. package/skills/direct/SKILL.md +0 -66
  159. package/skills/direct/references/request-signals.md +0 -59
  160. package/skills/doctor/SKILL.md +0 -305
  161. package/skills/doctor/report.md +0 -102
  162. package/skills/feedback/SKILL.md +0 -98
  163. package/skills/feedback/references/transport-and-privacy.md +0 -65
  164. package/skills/feedback/report.md +0 -36
  165. package/skills/install/SKILL.md +0 -215
  166. package/skills/intent-continuing/SKILL.md +0 -156
  167. package/skills/intent-continuing/references/board-fill.md +0 -52
  168. package/skills/intent-continuing/references/boarding-matrix.md +0 -35
  169. package/skills/intent-continuing/references/context-management.md +0 -28
  170. package/skills/intent-continuing/references/liveness-ranking.md +0 -57
  171. package/skills/intent-creating/SKILL.md +0 -89
  172. package/skills/intent-creating/evals/evals.json +0 -72
  173. package/skills/intent-creating/references/lifecycle.md +0 -81
  174. package/skills/intent-creating/references/wikilinks.md +0 -8
  175. package/skills/intent-ending/SKILL.md +0 -182
  176. package/skills/intent-ending/evals/evals.json +0 -74
  177. package/skills/intent-executing/SKILL.md +0 -87
  178. package/skills/intent-executing/evals/evals.json +0 -66
  179. package/skills/intent-executing/implementer-prompt.md +0 -47
  180. package/skills/intent-executing/spec-reviewer-prompt.md +0 -27
  181. package/skills/intent-speccing/SKILL.md +0 -136
  182. package/skills/intent-speccing/evals/evals.json +0 -126
  183. package/skills/intent-speccing/references/design-principles.md +0 -44
  184. package/skills/intent-speccing/references/per-section-fill-rules.md +0 -92
  185. package/skills/intent-speccing/references/self-verify-checklist.md +0 -37
  186. package/skills/project-creating/SKILL.md +0 -162
  187. package/skills/project-creating/references/hubs-projects.md +0 -55
  188. package/skills/project-creating/references/project-scaffolding.md +0 -97
  189. package/skills/releasing/SKILL.md +0 -376
  190. package/skills/releasing/references/deprecations.md +0 -60
  191. package/skills/releasing/references/promotion-and-tagging.md +0 -70
  192. package/skills/releasing/references/release-lines.md +0 -105
  193. package/skills/roadmap/SKILL.md +0 -90
  194. package/skills/roadmap/references/file-format.md +0 -134
  195. package/skills/roadmap/references/operations.md +0 -112
  196. package/skills/rollback/SKILL.md +0 -91
  197. package/skills/tutorial/SKILL.md +0 -66
  198. package/skills/tutorial/evals/evals.json +0 -186
  199. package/skills/uninstall/SKILL.md +0 -75
  200. package/skills/update/SKILL.md +0 -126
  201. /package/{skills/auto/references → docs/help}/agent-report-contract.md +0 -0
  202. /package/{skills/intent-executing → docs/help}/code-quality-reviewer-prompt.md +0 -0
  203. /package/{skills/conventions/references → docs/help}/knowledge-graph.md +0 -0
  204. /package/{skills/conventions/references → docs/help}/lifecycle-and-savepoints.md +0 -0
  205. /package/{skills/conventions/references → docs/help}/locks-and-worktrees.md +0 -0
  206. /package/{skills/conventions/references → docs/help}/maintenance-and-revisions.md +0 -0
  207. /package/{skills/intent-executing → docs/help}/plan-reviewer-prompt.md +0 -0
@@ -1,84 +0,0 @@
1
- ---
2
- name: plastic-agent-advisor
3
- description: >-
4
- Consult the advisor for expensive reasoning: one-way doors, plans, adversarial
5
- review of a plan or conclusion before an irreversible step, a deadlock after two
6
- failed attempts, or ranking several plausible options. Use when the user asks for
7
- a second opinion, a hard design decision, an architecture review, help breaking a
8
- deadlock, or says "ask the advisor". Also sets which advisor is the default when
9
- asked ("make Primary Advisor my default", "switch my advisor", "use Secondary Advisor").
10
- user-invocable: true
11
- ---
12
-
13
- # Agent Advisor
14
-
15
- Plastic ships two consultation agents, never dispatched by the auto pipeline, summoned
16
- only when you decide the reasoning is worth buying:
17
-
18
- - **Primary Advisor** (`plastic-primary-advisor`): Fable at medium effort. Use it for
19
- normal consultation.
20
- - **Secondary Advisor** (`plastic-secondary-advisor`): Fable at high effort. Use it only
21
- as an explicit escalation for harder or higher-risk reasoning.
22
-
23
- ## When to consult (and when not to)
24
-
25
- Buy a consultation for: decisions with one-way doors (architecture, migration order,
26
- public contracts); turning a goal plus evidence into a step plan with checks;
27
- adversarial review of your plan or conclusion before an irreversible step; a deadlock
28
- after two failed attempts where you cannot say why; ranking several plausible options
29
- when the ordering decides where you spend the next day.
30
-
31
- Never buy a consultation for: anything a tool can answer (search, reading code, running
32
- tests, documentation), writing code at volume, confirming a decision you already made,
33
- style or naming a linter would settle, or anything reversible and cheap you have not
34
- tried first. The full buy/never-buy list, answer-shape table, and entry test live in
35
- `references/advisor-protocol.md`; read it before writing a brief for the first time in
36
- a session.
37
-
38
- ## Routing: which advisor answers
39
-
40
- 1. Read the harness-scoped config: `advisor.claude.default`, the only advisor routing key
41
- the installer writes. If unset, use `plastic-primary-advisor`, the shipped default.
42
- 2. If the user explicitly asks for Primary Advisor or Secondary Advisor, honor that choice for
43
- this consultation. Otherwise, dispatch the configured agent from step 1.
44
- 3. If `advisor.enabled` reads `false`, neither advisor agent nor this skill is
45
- installed; this step should not be reachable, but if it is, tell the user the
46
- advisor is disabled and point at "Setting the default" below.
47
- 4. Dispatch the resolved agent with a brief built per `references/advisor-protocol.md`
48
- section 4 (natural prose, the block is a completeness check, not a form to fill).
49
- State the answer shape explicitly. Primary uses medium effort and Secondary uses high;
50
- only an explicit owner config override changes either value.
51
- 5. Consume the answer per the protocol's section 5: run the Operating Manual's
52
- five-question self-test on the advisor's plan before executing it. Advice is input,
53
- not authority; the plan is the advisor's, the outcome is yours.
54
-
55
- Read the resolved config value with:
56
-
57
- ```bash
58
- ruby ~/.plastic/scripts/read-config advisor.claude.default --project <repo>
59
- ```
60
-
61
- (Omit `--project` outside a registered project; falls back to the global value.)
62
-
63
- ## Setting the default advisor
64
-
65
- When asked to change the default, present the two options in plain language and write the
66
- choice:
67
-
68
- - **Primary Advisor** (`plastic-primary-advisor`, recommended): Fable at medium effort.
69
- - **Secondary Advisor** (`plastic-secondary-advisor`): Fable at high effort.
70
-
71
- These are the same two options the installer offers at install and update time. Write
72
- the choice to `advisor.claude.default` in the global `~/.plastic/config.yml` (or the
73
- project's `.plastic_store/config.yml` when the user scopes the change to one project):
74
- read the file as YAML, set `advisor.claude.default` to the agent name (`plastic-primary-advisor`
75
- or `plastic-secondary-advisor`, never a model name or nickname), and write it back. Confirm
76
- the new default back to the user in one line.
77
-
78
- ## References
79
-
80
- - `references/advisor-protocol.md`: the full shipped Advisor Protocol (what to buy,
81
- answer shape, the entry test, how to write a brief that earns its cost, the
82
- answer contract, session economics, anti-patterns). Read it before the first
83
- consultation in a session; the second consultation in the same advisor thread costs a
84
- fraction of the first, so keep follow-ups on one thread rather than opening a new one.
@@ -1,297 +0,0 @@
1
- ---
2
- name: plastic-auto
3
- description: >-
4
- Autonomous intent delivery - a background team takes a registered intent from How to End.
5
- Use when user says "auto", "take it from here", "deliver this", or when a thinking
6
- conversation concludes and the user confirms autonomous execution. Requires an active intent
7
- in INDEX.md.
8
- user-invocable: true
9
- ---
10
-
11
- # Auto - Autonomous Intent Delivery
12
-
13
- Announce: "Taking over intent [ID] - [name] for autonomous delivery."
14
-
15
- **Advisory (not a rule).** At auto-mode start, recommend once that the user run this
16
- orchestrating session on the best available thinking model (Fable, Opus, or whatever supersedes
17
- them); this is advice only, and dispatched agents keep their configured model, never resolving
18
- to Fable without an explicit `agents.models.<name>` config override. Primary Advisor and
19
- Secondary Advisor are consultation roles the user or this session summons deliberately;
20
- the auto pipeline never dispatches them.
21
-
22
- ## Precondition
23
-
24
- An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found.
25
- Create one first with /plastic-intent-creating."
26
-
27
- If several active intents exist, ask which to deliver (the one question auto asks at boarding).
28
-
29
- **Picking work when no intent is specified.** If the user says "auto" without naming an intent
30
- and none is active, consult the roadmap first (the primary planning surface), then fall back to
31
- the dashboard queue:
32
-
33
- ```bash
34
- ruby ~/.plastic/scripts/roadmap-next --roadmaps-dir <tier>/roadmaps
35
- ```
36
-
37
- Branch on `state`: `dispatchable` means work its `dispatchable_queue` in `rank` order (the
38
- current batch's `queued` intents, parallel-safe within the batch); `in_flight` means the
39
- frontier batch is still delivering, report it and wait, never dispatch a later batch; `none` or
40
- `exhausted` means fall back to `ruby ~/.plastic/scripts/dashboard.rb all --json` and work its
41
- `dispatchable_queue` in `rank` order, leaving `human_only` and `next_big_thing` for the user.
42
-
43
- QMD-first (when available): when the user describes the work instead of naming an intent, run
44
- `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` first, then open the hit's authoritative intent file; a no-op when QMD is absent.
45
-
46
- ## Take the intent (do this FIRST)
47
-
48
- Immediately after selecting the intent, take it for this session. One verb acquires the durable
49
- `delivery.lock` in the intent directory (stamped `run_mode: auto`) and provisions the code worktree
50
- at `<repo>/.claude/worktrees/{id}--{slug}` on branch `plastic/{id}--{slug}`; the delivery lock
51
- names this session as the one delivering the intent, so the record hook writes savepoint lines
52
- and heartbeats for it instead of the day ledger:
53
-
54
- ```bash
55
- codex="${CODEX_THREAD_ID:-}"; claude="${CLAUDE_CODE_SESSION_ID:-}"
56
- ruby ~/.plastic/scripts/plastic-lock arm --intent-dir "<STORE>/<dir>" --mode auto \
57
- --agent plastic-enforcer \
58
- ${codex:+--harness codex --session "$codex" --thread "$codex"} \
59
- ${claude:+--harness claude --session "$claude"}
60
- ```
61
-
62
- Replace `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`) and `<dir>` (the
63
- `ID--slug` directory). The snippet trusts a nonblank `CODEX_THREAD_ID` as Codex, otherwise a
64
- nonblank `CLAUDE_CODE_SESSION_ID` as Claude, otherwise passes no identity and the verb keys the
65
- lock by a derived session key. Never guess identity from an absent runtime variable; an
66
- unknown harness or thread stays unknown. Exit 1 means the lock is held, stale, excluded, or
67
- corrupt - or `inline_refused`: a conversation session may not arm an intent at all (owner rule
68
- 2026-08-31); dispatch the delivery team instead. `--allow-inline` exists only for an explicit
69
- owner override. Do not proceed as the owner after an exit 1.
70
-
71
- Read `../plastic-conventions/references/locks-and-worktrees.md` for what the lock and the
72
- worktree mean and the station table behind them. Code edits happen only inside the worktree.
73
-
74
- ## The shape
75
-
76
- Work is a graph (`graph.md`: Goal, Decisions, Graph, Status; one `nodes/*.md` per node) or,
77
- for work small enough to skip speccing, delivered inline with no separate plan review. There
78
- is no intent tier and no stage agent; depth follows the work.
79
-
80
- `runner step` computes readiness and prints a spawn block per dispatched node - agent, model,
81
- node input path, the test command, the call cap - fenced for a session to paste into the Agent
82
- tool; the runner never spawns (327 D42). `runner status` renders the ledger; `runner answer`
83
- closes a `needs_decision` node.
84
-
85
- A lead is a choice, not a requirement (D8, 355). A lead earns its keep on a graph carrying a
86
- decision node, weighing its `needs_decision` stop; a graph with none runs end to end from
87
- `runner step` alone. When this session leads, it is the `plastic-enforcer` role, never a
88
- dispatched agent.
89
-
90
- ## Team
91
-
92
- - **plastic-enforcer**: this session. Writes the Why and How record, dispatches, applies
93
- review findings, verifies, closes.
94
- - **plastic-executor**: one dispatch per intent, implements the consolidated action tests first,
95
- ticks the checklist, appends `## Insights`, drives the suite green.
96
- - **the plan reviewer**: an optional dispatch before code, from `plastic-intent-executing`'s
97
- `plan-reviewer-prompt.md`; a fresh agent, never the lead.
98
- - **the post-execution reviewer**: dispatched only by the risk rule, from
99
- `code-quality-reviewer-prompt.md`; a fresh agent, never the maker.
100
-
101
- Spawn preamble (live-state injection): before dispatching any agent, run
102
- `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to the prompt. The
103
- preamble is a deterministic, filesystem-only snapshot of the intent (id, intent line, current
104
- stage, the worktree path when it exists) plus the honoring instruction and the report contract.
105
-
106
- Dispatch-time model contract: resolve each agent's model through the config chain
107
- (`read-config agents.models.<basename> --project <repo>`: project override, then global, then
108
- the shipped default) and pass it explicitly at dispatch; never rely on the role's frontmatter
109
- alone.
110
-
111
- Completion report (require, then synthesize): every dispatched agent MUST end with a structured
112
- completion report as its final message (`references/agent-report-contract.md`). When an agent
113
- returns no usable report, run `scripts/agent-report <intent_dir> --role <role>` to synthesize a
114
- deterministic filesystem-derived one, so the handoff account always exists.
115
-
116
- ### Delegation (agents writing under the owner's lock)
117
-
118
- This session owns the delivery lock. A dispatched agent runs in its own session, so register
119
- each one as a delegate before (or when) it needs to write into the intent dir:
120
-
121
- 1. Instruct each spawned agent to report its session id and runtime identity in its first
122
- message: `CODEX_THREAD_ID` for Codex, or `CLAUDE_CODE_SESSION_ID` for Claude. Use the
123
- agent's own identity when known; never infer a harness or model from missing context.
124
- 2. As the lock owner, run:
125
- `ruby ~/.plastic/scripts/plastic-lock delegate --intent-dir <intent-dir> --delegate <specialist-session-id> --harness <specialist-harness-when-known> --agent <role> --model <resolved-model-when-known> --thread <reported-CODEX_THREAD_ID-when-Codex>`
126
- Omit `--harness`, `--model`, or `--thread` when that value is unknown; `--agent <role>` is
127
- always known from the roster.
128
- 3. Immediately after the specialist returns, and before validating or dispatching
129
- the next handoff, classify the return and record its activity status as the owner:
130
- - `finished` means the specialist returned a usable completion report, whether
131
- agent-authored or synthesized through `scripts/agent-report`.
132
- - `failed` means the specialist returned blocked, errored, or without a usable
133
- completion report that can be synthesized.
134
- 4. Record the classification with exactly one of:
135
- ```bash
136
- ruby ~/.plastic/scripts/plastic-lock delegate --intent-dir <intent-dir> \
137
- --delegate <specialist-session-id> --status finished --harness <same-specialist-harness-when-known> \
138
- --agent <same-role> --model <same-resolved-model-when-known> --thread <same-CODEX_THREAD_ID-when-Codex>
139
- ruby ~/.plastic/scripts/plastic-lock delegate --intent-dir <intent-dir> \
140
- --delegate <specialist-session-id> --status failed --harness <same-specialist-harness-when-known> \
141
- --agent <same-role> --model <same-resolved-model-when-known> --thread <same-CODEX_THREAD_ID-when-Codex>
142
- ```
143
- Apply the same omission rule to unknown values on terminal status commands. A failed agent
144
- stops that handoff under the error procedure; never dispatch the next agent first.
145
-
146
- Only the owner can delegate. Delegates cannot re-delegate or release.
147
-
148
- Headless note: in a headless or background run the session id may be unset; the arm verb then keys the lock by a derived key and the record hook still writes the ledger.
149
- Verify with `plastic-lock status` rather than assuming.
150
-
151
- Solo fallback: on a harness with no agent dispatch (Codex CLI today), this session walks the
152
- graph (or the plan) itself, still writing the matrix and the tests first and reviewing its own
153
- plan against the matrix before code, saying so in `## Insights`.
154
-
155
- ## Stage-Aware Entry
156
-
157
- Read the active intent's `savepoint.md` FIRST: the last line classifies the stage, and you
158
- verify only that line's artifact before entering. Fall back to the filesystem probe when the
159
- ledger is missing (then rebuild it with `Savepoint.rebuild_savepoint`).
160
-
161
- | Ledger last line | Enter |
162
- |---|---|
163
- | `What {id}--{slug}.md` (born) or no spec | Why (write spec.md) |
164
- | `Why spec.md created` | How |
165
- | `How plan.md created` / `How checklist.md created` / `Exec started` | Exec (verify plan, matrix, checklist) |
166
- | `Exec outcome.md created` | Exec done; complete the intent |
167
- | A terminal savepoint line (`delivered` or `abandoned`) | Terminal; do not resume |
168
- | A node or `Intent` transition line (`n1 running ...`, `Intent needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye. `scripts/graph-measure` is the read-only sibling over that same ledger, with its own three public verbs `intent`, `budget`, and `cohorts` - it never dispatches and never writes |
169
-
170
- Filesystem fallback, in order: `checklist.md` with items checked means resume Exec from the
171
- first unchecked item; `plan.md` plus `checklist.md` means enter Exec; `spec.md` alone means
172
- enter How; `## Context` with content means complete Why; only `## Intent` means start Why.
173
-
174
- Announce which stage you are entering and why.
175
-
176
- ## Why (the lead)
177
-
178
- For a graph delivery, Why is already written into `graph.md`'s Goal and Decisions; nothing
179
- else to do here. For work with no graph: read `## Context` and `### Decisions`, assess the
180
- gaps, research them yourself (code, docs, related intents through `## Links`, the web if
181
- needed; no questions to the human), record each decision in `## Context > ### Decisions` with
182
- its rationale, log it in `## Insights` with the `(autonomous)` marker through
183
- `scripts/insight-append`, and write `spec.md` only when the intent needs one (speccing is
184
- optional). Then How.
185
-
186
- ## How (the lead), then the plan review
187
-
188
- For a graph delivery, How is `graph.md` itself: no `plan.md`, no separate plan review (D1,
189
- 341). For work with no graph: write `plan.md` (numbered steps) and at least one real
190
- `actions/ACTION_N.md` carrying the failure-mode matrix (one row per operation, the failure
191
- mode, the test that catches it; a `.gitkeep`-only `actions/` is not a finished How), then
192
- `checklist.md` covering every action. The plan reviewer is optional, not a required step:
193
- when the delivery warrants review before code, dispatch it (boot 1) with
194
- `plastic-intent-executing`'s `plan-reviewer-prompt.md`, the spawn preamble, and the intent
195
- directory, apply every finding to the spec, the matrix, and the tests, and record what was
196
- dropped and why in the action file's review notes. A REVISE verdict is applied and not
197
- re-reviewed unless a finding changes a decision.
198
-
199
- Print `ruby ~/.plastic/scripts/report-screen plan <intent_dir>` as the first characters of
200
- the reply, nothing before it, no fence, before dispatching the executor (see
201
- `references/human-report-contract.md` for the full binding table). It informs; it does not wait.
202
-
203
- Then Exec.
204
-
205
- ## Exec (the executor)
206
-
207
- For a graph delivery, `runner step` prints the spawn block for the next ready node; paste it
208
- into the Agent tool, verbatim. For work with no graph, dispatch `plastic-executor` (boot 2)
209
- through `plastic-intent-executing` with the whole consolidated action pasted in.
210
-
211
- 1. Read the executor's return by code: DONE or DONE_WITH_CONCERNS proceeds; NEEDS_CONTEXT
212
- re-dispatches with the missing context; BLOCKED stops under the error procedure.
213
- 2. Tick the checklist as items land (the executor does this); verify tick-versus-diff against
214
- the diff. A mismatch is a review finding, not a lead cleanup.
215
-
216
- ## Review by risk (boot 3, only when a rule fires)
217
-
218
- Dispatch the post-execution reviewer with `code-quality-reviewer-prompt.md` when any of these
219
- holds, each checkable from disk with no judgment; otherwise the green suite is the review:
220
-
221
- 1. `git diff --name-only <red-commit>..HEAD` touches a path on the risk list in
222
- `references/agent-architecture.md` (hooks, the lock, the arming module, the installer, a
223
- release file).
224
- 2. A row of any failure-mode matrix (an `actions/ACTION_N.md` or a `nodes/*.md` file) names a
225
- test file that is not in that diff, or a test the green run did not execute.
226
- 3. The executor's completion report carries a status other than `delivered`, or a non-empty
227
- `deviations` or `blockers` field.
228
-
229
- The reviewer returns a pass or a list of fixes; the executor (re-dispatched) applies them, then
230
- the suite runs once more. On a graph, the risk rule maps onto the verify nodes named in
231
- `graph.md`'s decisions; at most one review-fix round, never more.
232
- ## Project Creation
233
-
234
- If the plan calls for creating a new project, determine the path from `~/.plastic/config.yml`
235
- `project_roots` or the intent context, confirm the path with the user (the one human
236
- interaction added mid-delivery), invoke `plastic-project-creating`, and continue from the
237
- project directory on the tactical intent.
238
-
239
- ## Permission Model - Safe-by-Default
240
-
241
- Prefer non-destructive routes: rename instead of drop, additive migrations plus backfill, move
242
- files instead of deleting them, feature flags off instead of removed code, a backup before a
243
- migration. When a destructive action on an existing project has no safe alternative, log it in
244
- `## Insights`, notify the user ("Blocked on destructive action: ..."), and STOP unless
245
- `--skip-permissions` was given, in which case log and proceed. During initial project creation
246
- every choice is non-destructive and the team has full autonomy.
247
-
248
- ## Completion
249
-
250
- Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means.
251
-
252
- 1. This is the merge gate: verify every checklist item is checked, verify tick-versus-diff against the diff, and confirm the suite is green once on the branch.
253
- 2. Write `outcome.md` from `~/.plastic/templates/outcome.md` with `disposition: delivered`,
254
- `## Delivered` as the labeled table whose row labels match the action-file headings (317a).
255
- 3. Release, if configured: match the working directory against `~/.plastic/projects.yml`, read
256
- `project.yml`'s `release` block, and act on `on_complete` (`commit`, `commit_and_push`,
257
- `manual`), `verify` (green proceeds; red follows `on_red`: `fix_and_retry` up to twice,
258
- `stop`, or `manual`), and `on_green` (delegate entirely to `plastic-releasing`).
259
- 4. Review `## Insights` for observations that should become future intents; create them through
260
- `plastic-intent-creating` and update `chain`.
261
- 5. Close through `plastic-intent-ending`, which runs `scripts/end-intent`: outcome, INDEX,
262
- savepoint, the store commit, and the disarm (the worktree released, `delivery.lock`
263
- cleared), then the QMD reindex last and the single owner
264
- report. Pass `--session` and `--index-note`:
265
- ```bash
266
- ruby ~/.plastic/scripts/end-intent --store <store_path> --id <ID> --disposition delivered \
267
- --session "$CLAUDE_CODE_SESSION_ID" \
268
- --index-note "<what shipped>; <suite result>"
269
- ```
270
- Exit 4: a live foreign session holds the lock. 5: the worktree is dirty (commit first, or
271
- pass `--discard-worktree-changes` deliberately). 3: the lock survived the disarm
272
- (`/plastic-doctor check the lock status`). 6: the structure check refused. Never leave an
273
- orphaned worktree; run `git worktree prune` on a stale reference.
274
- 6. Print `ruby ~/.plastic/scripts/report-screen delivered <intent_dir>` once (D15/331f), and
275
- `report-screen state` at each of the five triggers in `references/human-report-contract.md`
276
- (a review verdict, a blocker, a merge/release, or an owner status ask; a mid-batch ask
277
- instead runs `report-screen session <tier_root> --session "$CLAUDE_CODE_SESSION_ID"`, intent
278
- 330). Print each as the first characters of the reply: nothing before it, no fence, or the
279
- hook cannot paint it.
280
-
281
- ## Error Handling
282
-
283
- If the team gets stuck (an unresolvable gap, a missing dependency, a suite that stays red):
284
- log the blocker in `## Insights`, make sure `savepoint.md` reflects the state, notify the user
285
- ("Blocked on intent [ID] - [name]: ..."), and STOP. Never work around a blocker in a way that
286
- leaves the project broken.
287
-
288
- ## References
289
-
290
- - Read `references/agent-architecture.md` for the team model, the risk list, the headless note,
291
- and the solo fallback when dispatching or when a harness has no agent dispatch.
292
- - Read `references/human-report-contract.md` for the three report screens and the five
293
- triggers before printing the How or Completion screen above.
294
- - Read `references/agent-report-contract.md` for the completion report format when reading a
295
- dispatched agent's return or synthesizing one.
296
- - Read `references/end-tail.md` for what `Arm.disarm` does at the End tail and why the reindex
297
- runs last, before closing an intent.
@@ -1,255 +0,0 @@
1
- {
2
- "skill_name": "plastic-auto",
3
- "notes": "Intent 27. Scopes: description triggering (1-8) and behavior/output quality (9). Assertions written after observing Step-3 runs (one clean subagent router per case). Intent 63 added cases 10-11 (auto-mode enforcer-led team spin-up and solo fallback).",
4
- "results": {
5
- "triggering": {
6
- "cases": 8,
7
- "passed": 8,
8
- "pass_at_1": 1.0,
9
- "run": "2026-06-10, one subagent per case"
10
- },
11
- "behavior": {
12
- "cases": 1,
13
- "passed": 1,
14
- "evidence": "dogfood: intent 27 itself delivered via auto produced spec->plan->checklist before any code edit; code-gate unit test proves pre-How project-code edits are blocked"
15
- }
16
- },
17
- "evals": [
18
- {
19
- "id": 1,
20
- "scope": "triggering",
21
- "set": "train",
22
- "prompt": "auto",
23
- "expected_output": "Activates plastic-auto (the bare 'auto' keyword is the documented trigger).",
24
- "files": [],
25
- "assertions": [
26
- {
27
- "type": "code",
28
- "check": "router CHOICE == plastic-auto",
29
- "observed": "plastic-auto",
30
- "result": "pass"
31
- }
32
- ]
33
- },
34
- {
35
- "id": 2,
36
- "scope": "triggering",
37
- "set": "train",
38
- "prompt": "take it from here and deliver intent 27 end to end",
39
- "expected_output": "Activates plastic-auto (autonomous delivery of an active intent).",
40
- "files": [],
41
- "assertions": [
42
- {
43
- "type": "code",
44
- "check": "router CHOICE == plastic-auto",
45
- "observed": "plastic-auto",
46
- "result": "pass"
47
- }
48
- ]
49
- },
50
- {
51
- "id": 3,
52
- "scope": "triggering",
53
- "set": "validation",
54
- "prompt": "go fully autonomous on the active intent, don't ask me questions",
55
- "expected_output": "Activates plastic-auto.",
56
- "files": [],
57
- "assertions": [
58
- {
59
- "type": "code",
60
- "check": "router CHOICE == plastic-auto",
61
- "observed": "plastic-auto",
62
- "result": "pass"
63
- }
64
- ]
65
- },
66
- {
67
- "id": 4,
68
- "scope": "triggering",
69
- "set": "train",
70
- "prompt": "deliver this intent for me",
71
- "expected_output": "Activates plastic-auto.",
72
- "files": [],
73
- "assertions": [
74
- {
75
- "type": "code",
76
- "check": "router CHOICE == plastic-auto",
77
- "observed": "plastic-auto",
78
- "result": "pass"
79
- }
80
- ]
81
- },
82
- {
83
- "id": 5,
84
- "scope": "triggering",
85
- "set": "train",
86
- "prompt": "set up a hook to automatically format the file on every save",
87
- "expected_output": "Does NOT activate plastic-auto. Near-miss: shares 'auto*' but is a settings/hooks task (update-config).",
88
- "files": [],
89
- "assertions": [
90
- {
91
- "type": "code",
92
- "check": "router CHOICE != plastic-auto",
93
- "observed": "update-config",
94
- "result": "pass"
95
- }
96
- ]
97
- },
98
- {
99
- "id": 6,
100
- "scope": "triggering",
101
- "set": "validation",
102
- "prompt": "deliver the built package to the dist directory",
103
- "expected_output": "Does NOT activate plastic-auto. Near-miss: shares 'deliver' but is a build/file task.",
104
- "files": [],
105
- "assertions": [
106
- {
107
- "type": "code",
108
- "check": "router CHOICE != plastic-auto",
109
- "observed": "none",
110
- "result": "pass"
111
- }
112
- ]
113
- },
114
- {
115
- "id": 7,
116
- "scope": "triggering",
117
- "set": "train",
118
- "prompt": "create a new intent for the dashboard idea",
119
- "expected_output": "Does NOT activate plastic-auto; activates plastic-intent-creating.",
120
- "files": [],
121
- "assertions": [
122
- {
123
- "type": "code",
124
- "check": "router CHOICE != plastic-auto",
125
- "observed": "plastic-intent-creating",
126
- "result": "pass"
127
- }
128
- ]
129
- },
130
- {
131
- "id": 8,
132
- "scope": "triggering",
133
- "set": "validation",
134
- "prompt": "what's the status of my active intents?",
135
- "expected_output": "Does NOT activate plastic-auto; this is a read/intent-continuing query.",
136
- "files": [],
137
- "assertions": [
138
- {
139
- "type": "code",
140
- "check": "router CHOICE != plastic-auto",
141
- "observed": "plastic-intent-continuing",
142
- "result": "pass"
143
- }
144
- ]
145
- },
146
- {
147
- "id": 9,
148
- "scope": "behavior",
149
- "set": "train",
150
- "prompt": "Active intent X exists with only a '## Intent' section. Deliver it in auto mode.",
151
- "expected_output": "Arms the lifecycle gate first, then produces spec.md (Why), then plan.md + actions/ + checklist.md (How), and edits NO project code before plan.md + checklist.md exist. Disarms on completion.",
152
- "files": [],
153
- "assertions": [
154
- {
155
- "type": "human",
156
- "check": "spec.md written before plan.md before any project-code edit",
157
- "observed": "dogfood run of intent 27 followed this order",
158
- "result": "pass"
159
- },
160
- {
161
- "type": "code",
162
- "check": "code-gate blocks project-code Edit/Write while pre-How (test/code_gate_test.rb)",
163
- "observed": "test green",
164
- "result": "pass"
165
- }
166
- ]
167
- },
168
- {
169
- "id": 10,
170
- "scope": "behavior",
171
- "set": "train",
172
- "prompt": "Active intent X exists. Deliver it in auto mode on a harness that supports subagents.",
173
- "expected_output": "Spins up one enforcer-led team per intent (plastic-enforcer, executor, an on-request reviewer). The enforcer IS the orchestrator: it writes spec.md, the action files, and checklist.md itself, dispatches one executor for the consolidated action on one branch, and dispatches an independent reviewer subagent at the final gate only.",
174
- "files": [],
175
- "assertions": [
176
- {
177
- "type": "human",
178
- "check": "enforcer writes Why and How itself; one executor dispatched; independent reviewer only at final gate",
179
- "observed": "dogfood: intents 60-62 delivered by exactly this enforcer-led team on a shared branch",
180
- "result": "pass"
181
- },
182
- {
183
- "type": "code",
184
- "check": "agents/plastic-*.md role files ship and install into the harness agent dir, manifest-tracked (test/install_packaging_test.rb)",
185
- "observed": "test green",
186
- "result": "pass"
187
- }
188
- ]
189
- },
190
- {
191
- "id": 11,
192
- "scope": "behavior",
193
- "set": "validation",
194
- "prompt": "Active intent X exists. Deliver it in auto mode on a harness with no subagent dispatch.",
195
- "expected_output": "Falls back to a single agent walking the full What, Why, How, Exec cycle itself, preserving current behavior. The enforcer gate discipline still applies (arm the gate first, no project-code edits before plan.md + checklist.md exist).",
196
- "files": [],
197
- "assertions": [
198
- {
199
- "type": "human",
200
- "check": "solo agent walks the full cycle when subagent dispatch is unavailable; gate discipline preserved",
201
- "observed": "SKILL.md Team Spin-Up documents the solo fallback explicitly",
202
- "result": "pass"
203
- }
204
- ]
205
- },
206
- {
207
- "id": 12,
208
- "scope": "behavior",
209
- "set": "validation",
210
- "prompt": "A power-tool is present (qmd on PATH, or a .serena marker / serena on PATH). A substantive prompt arrives in auto mode.",
211
- "expected_output": "The agent prefers the present tool because PLASTIC.md (loaded at session start) recommends QMD for intents and Enola, or Serena when Enola is absent, for code navigation. No hook appends a per-prompt line: the power-tools hook was removed in 2.0 (intent 309).",
212
- "files": [],
213
- "assertions": [
214
- {
215
- "type": "code",
216
- "check": "PLASTIC.md carries the recommendation (doctrine_305_test) and PowerTools presence probes still back doctor's readiness checks (power_tools_test.rb)",
217
- "observed": "doctrine_305_test test_plastic_md_carries_the_power_tools_mandate_as_a_recommendation; power_tools_test.rb presence probes",
218
- "result": "pass"
219
- }
220
- ]
221
- },
222
- {
223
- "id": 13,
224
- "scope": "behavior",
225
- "set": "validation",
226
- "prompt": "Neither qmd nor serena is present (no qmd on PATH, no .serena marker, no serena on PATH). A substantive prompt arrives.",
227
- "expected_output": "Detect-then-degrade: PLASTIC.md's recommendation applies only when a tool is present, so nothing is required to install and no per-prompt line appears (there is no hook to emit one since intent 309).",
228
- "files": [],
229
- "assertions": [
230
- {
231
- "type": "code",
232
- "check": "PowerTools.mandate returns nil when neither tool is present",
233
- "observed": "power_tools_test.rb test_mandate_neither_is_nil",
234
- "result": "pass"
235
- }
236
- ]
237
- },
238
- {
239
- "id": 14,
240
- "scope": "behavior",
241
- "set": "validation",
242
- "prompt": "QMD is present. In auto mode the user says: deliver the work on the uploader retry policy (no intent id given).",
243
- "expected_output": "Before scanning the store with grep/Read to find the matching intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"uploader retry policy\"` to surface the candidate intent, then opens the authoritative intent file for the hit it takes over. This discovery step is distinct from the completion-time reindex step. No-op fallback to INDEX.md / file scan when QMD is absent.",
244
- "files": [],
245
- "assertions": [
246
- {
247
- "type": "human",
248
- "check": "qmd-sync search is run before grep/Read during discovery; authoritative file opened for the hit; reindex step stays separate",
249
- "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
250
- "result": "pass"
251
- }
252
- ]
253
- }
254
- ]
255
- }