@zalom/plastic 1.14.0 → 2.0.0-alpha.1

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 (190) hide show
  1. package/PLASTIC.md +101 -294
  2. package/README.md +5 -6
  3. package/agents/plastic-advisor.md +18 -17
  4. package/agents/plastic-enforcer.md +57 -69
  5. package/agents/plastic-executor.md +34 -20
  6. package/agents/plastic-faux-advisor.md +18 -18
  7. package/config_asks.yml +38 -0
  8. package/hooks/capture +4 -0
  9. package/hooks/check-update +12 -3
  10. package/hooks/close +5 -0
  11. package/hooks/hooks.json +9 -49
  12. package/hooks/record +4 -0
  13. package/package.json +3 -2
  14. package/scripts/agent-report +8 -9
  15. package/scripts/append-ledger +195 -0
  16. package/scripts/codex-hook +101 -95
  17. package/scripts/dashboard.rb +4 -4
  18. package/scripts/doctor.rb +106 -43
  19. package/scripts/end-intent +77 -76
  20. package/scripts/exec-worktree +11 -20
  21. package/scripts/file-session-intent +61 -0
  22. package/scripts/hook-capture +242 -0
  23. package/scripts/hook-close +34 -0
  24. package/scripts/hook-record +149 -0
  25. package/scripts/hook-session-start +95 -12
  26. package/scripts/install.rb +8 -6
  27. package/scripts/lib/agent_models.rb +1 -7
  28. package/scripts/lib/arm.rb +283 -0
  29. package/scripts/lib/backfill_intent.rb +316 -0
  30. package/scripts/lib/bridge.rb +24 -1597
  31. package/scripts/lib/doctor_core.rb +17 -88
  32. package/scripts/lib/doctor_session_ledger.rb +106 -0
  33. package/scripts/lib/exec_worktree.rb +14 -60
  34. package/scripts/lib/harness_text.rb +5 -4
  35. package/scripts/lib/hook_registry.rb +44 -107
  36. package/scripts/lib/insights.rb +3 -4
  37. package/scripts/lib/installer_core.rb +19 -30
  38. package/scripts/lib/lock.rb +6 -26
  39. package/scripts/lib/outcome_guard.rb +7 -5
  40. package/scripts/lib/project_validator.rb +30 -1
  41. package/scripts/lib/roadmap_queue.rb +3 -3
  42. package/scripts/lib/roadmap_savepoint.rb +1 -1
  43. package/scripts/lib/rule_catalog.rb +6 -3
  44. package/scripts/lib/savepoint.rb +320 -0
  45. package/scripts/lib/scaffold_intent.rb +13 -179
  46. package/scripts/lib/session_backfill.rb +184 -0
  47. package/scripts/lib/session_close.rb +84 -0
  48. package/scripts/lib/session_git.rb +469 -0
  49. package/scripts/lib/session_ledger.rb +497 -0
  50. package/scripts/lib/store_discovery.rb +1 -1
  51. package/scripts/lib/store_provisioning.rb +1 -1
  52. package/scripts/maintenance-run +7 -7
  53. package/scripts/new-intent +63 -4
  54. package/scripts/plastic-lock +94 -41
  55. package/scripts/promote-session-item +150 -0
  56. package/scripts/rebuild-graph +1 -1
  57. package/scripts/roadmap-next +2 -2
  58. package/scripts/rollback.rb +42 -3
  59. package/scripts/scaffold-intent +37 -63
  60. package/scripts/session-commit +116 -0
  61. package/scripts/spawn-preamble +5 -5
  62. package/scripts/update.rb +7 -3
  63. package/skills/agent-advisor/SKILL.md +3 -3
  64. package/skills/agent-advisor/references/advisor-protocol.md +20 -20
  65. package/skills/auto/SKILL.md +218 -317
  66. package/skills/auto/evals/evals.json +10 -10
  67. package/skills/auto/references/agent-architecture.md +102 -90
  68. package/skills/auto/references/agent-report-contract.md +4 -21
  69. package/skills/auto/references/end-tail.md +47 -53
  70. package/skills/auto/references/human-report-contract.md +8 -8
  71. package/skills/conventions/SKILL.md +1 -3
  72. package/skills/conventions/references/lifecycle-and-savepoints.md +35 -1
  73. package/skills/conventions/references/locks-and-worktrees.md +47 -55
  74. package/skills/conventions/references/maintenance-and-revisions.md +12 -12
  75. package/skills/dashboard/SKILL.md +1 -1
  76. package/skills/direct/SKILL.md +66 -0
  77. package/skills/direct/references/request-signals.md +59 -0
  78. package/skills/doctor/SKILL.md +58 -11
  79. package/skills/doctor/report.md +3 -1
  80. package/skills/install/SKILL.md +11 -9
  81. package/skills/intent-continuing/SKILL.md +131 -89
  82. package/skills/intent-continuing/references/boarding-matrix.md +34 -0
  83. package/skills/intent-continuing/references/context-management.md +2 -2
  84. package/skills/intent-creating/SKILL.md +2 -2
  85. package/skills/intent-creating/references/lifecycle.md +1 -1
  86. package/skills/intent-ending/SKILL.md +28 -37
  87. package/skills/intent-ending/evals/evals.json +4 -4
  88. package/skills/intent-executing/SKILL.md +12 -49
  89. package/skills/intent-executing/plan-reviewer-prompt.md +39 -0
  90. package/skills/intent-speccing/SKILL.md +108 -51
  91. package/skills/intent-speccing/evals/evals.json +5 -5
  92. package/skills/intent-speccing/references/per-section-fill-rules.md +4 -4
  93. package/skills/intent-speccing/references/self-verify-checklist.md +1 -2
  94. package/skills/project-creating/SKILL.md +1 -1
  95. package/skills/releasing/SKILL.md +7 -8
  96. package/skills/tutorial/SKILL.md +2 -2
  97. package/skills/tutorial/references/track-1-guided.md +16 -18
  98. package/skills/tutorial/references/track-2-auto.md +12 -13
  99. package/skills/tutorial/references/track-3-projects-and-roadmaps.md +2 -2
  100. package/templates/agents.md +4 -7
  101. package/templates/project.yml +7 -0
  102. package/templates/roadmap.md +1 -1
  103. package/templates/savepoint.md +2 -2
  104. package/templates/session-intent.md +29 -0
  105. package/agents/plastic-brainstorming.md +0 -48
  106. package/agents/plastic-future-intent-researcher.md +0 -35
  107. package/agents/plastic-intent-curator.md +0 -47
  108. package/agents/plastic-intent-discovery.md +0 -43
  109. package/agents/plastic-planner.md +0 -56
  110. package/agents/plastic-spec-specialist.md +0 -53
  111. package/hooks/auto-arm +0 -5
  112. package/hooks/bash-gate +0 -3
  113. package/hooks/continue +0 -31
  114. package/hooks/edit-gates +0 -3
  115. package/hooks/future-intent-check +0 -25
  116. package/hooks/gate-check +0 -12
  117. package/hooks/power-tools +0 -8
  118. package/scripts/hook-auto-arm +0 -51
  119. package/scripts/hook-bash-gate +0 -78
  120. package/scripts/hook-code-gate +0 -38
  121. package/scripts/hook-continue +0 -48
  122. package/scripts/hook-create-gate +0 -51
  123. package/scripts/hook-edit-gates +0 -58
  124. package/scripts/hook-future-intent-check +0 -90
  125. package/scripts/hook-gate-check +0 -169
  126. package/scripts/hook-links-gate +0 -54
  127. package/scripts/hook-lock-gate +0 -47
  128. package/scripts/hook-power-tools +0 -38
  129. package/scripts/hook-savepoint-pre +0 -32
  130. package/scripts/lib/codex_edit_gates.rb +0 -138
  131. package/scripts/lib/edit_gates.rb +0 -398
  132. package/scripts/lib/links_gate.rb +0 -140
  133. package/scripts/lib/qmd_hook.rb +0 -41
  134. package/scripts/lib/spec_header.rb +0 -83
  135. package/scripts/lib/start_intent.rb +0 -296
  136. package/scripts/start-intent +0 -89
  137. package/skills/_active-intent-gate.md +0 -26
  138. package/skills/auto/references/tiers.md +0 -100
  139. package/skills/continuing/SKILL.md +0 -34
  140. package/skills/continuing/evals/evals.json +0 -91
  141. package/skills/conventions/references/gates-and-enforcement.md +0 -53
  142. package/skills/conventions/references/tiers-and-dispatch.md +0 -135
  143. package/skills/doctor/references/gates-stuck-detection.md +0 -43
  144. package/skills/intent-brainstorming/SKILL.md +0 -118
  145. package/skills/intent-brainstorming/evals/evals.json +0 -67
  146. package/skills/intent-continuing/evals/evals.json +0 -145
  147. package/skills/intent-discovering/SKILL.md +0 -56
  148. package/skills/intent-grilling/SKILL.md +0 -108
  149. package/skills/intent-linking/SKILL.md +0 -128
  150. package/skills/intent-linking/evals/evals.json +0 -22
  151. package/skills/intent-linking/references/zettelkasten.md +0 -45
  152. package/skills/intent-locking/SKILL.md +0 -64
  153. package/skills/intent-planning/SKILL.md +0 -145
  154. package/skills/intent-planning/evals/evals.json +0 -81
  155. package/skills/intent-planning/references/plan-format.md +0 -130
  156. package/skills/intent-researching/SKILL.md +0 -123
  157. package/skills/intent-researching/evals/evals.json +0 -22
  158. package/skills/intent-savepoint/SKILL.md +0 -83
  159. package/skills/intent-savepoint/references/context-management.md +0 -32
  160. package/skills/intent-starting/SKILL.md +0 -151
  161. package/skills/intent-starting/evals/evals.json +0 -117
  162. package/skills/intent-starting/references/boarding-matrix.md +0 -35
  163. package/skills/project-continuing/SKILL.md +0 -119
  164. package/skills/project-continuing/evals/evals.json +0 -100
  165. package/skills/roadmap-continuing/SKILL.md +0 -89
  166. package/skills/roadmap-continuing/evals/evals.json +0 -82
  167. package/skills/skill-creating/SKILL.md +0 -75
  168. package/skills/skill-creating/evals/evals.json +0 -108
  169. package/skills/skill-creating/references/agents.md +0 -168
  170. package/skills/skill-creating/references/defaults-first.md +0 -23
  171. package/skills/skill-creating/references/evals.md +0 -41
  172. package/skills/skill-creating/references/hooks.md +0 -251
  173. package/skills/skill-creating/references/progressive-disclosure.md +0 -176
  174. package/skills/skill-creating/references/scripts.md +0 -166
  175. package/skills/skill-creating/references/skills.md +0 -169
  176. package/skills/skill-creating/scripts/scaffold.rb +0 -313
  177. package/skills/skill-evaluating/SKILL.md +0 -141
  178. package/skills/skill-evaluating/assets/eval-template.json +0 -12
  179. package/skills/skill-evaluating/evals/evals.json +0 -75
  180. package/skills/skill-evaluating/references/convention-checks.md +0 -76
  181. package/skills/skill-evaluating/references/eval-methodology.md +0 -154
  182. package/skills/store-curating/SKILL.md +0 -64
  183. package/skills/store-curating/evals/evals.json +0 -38
  184. package/skills/store-indexing/SKILL.md +0 -93
  185. package/skills/store-indexing/evals/evals.json +0 -22
  186. package/skills/store-indexing/references/zettelkasten-linking.md +0 -32
  187. package/skills/store-provisioning/SKILL.md +0 -55
  188. /package/skills/{project-continuing → intent-continuing}/references/board-fill.md +0 -0
  189. /package/skills/{roadmap-continuing → intent-continuing}/references/liveness-ranking.md +0 -0
  190. /package/skills/{intent-brainstorming → intent-speccing}/references/design-principles.md +0 -0
@@ -1,166 +0,0 @@
1
- # Scripts: when deterministic code beats prose
2
-
3
- Decide whether a skill ships a script, and write scripts that hold their determinism.
4
- Read this when choosing script versus prose, or when writing a script that ships with a
5
- skill.
6
-
7
- For which bucket holds a given piece of content (scripts versus references versus
8
- assets), read `references/progressive-disclosure.md`. This file covers only the
9
- script-or-prose decision and script discipline.
10
-
11
- ## Contents
12
-
13
- - [Ship a script or write prose](#ship-a-script-or-write-prose)
14
- - [The three-way test](#the-three-way-test)
15
- - [Make scripts solve, not punt](#make-scripts-solve-not-punt)
16
- - [Test by running](#test-by-running)
17
- - [Match freedom to fragility](#match-freedom-to-fragility)
18
- - [Wire validators into hooks](#wire-validators-into-hooks)
19
- - [Script hard requirements](#script-hard-requirements)
20
- - [Plastic conventions](#plastic-conventions)
21
- - [Worked example](#worked-example)
22
- - [Self-check](#self-check)
23
-
24
- ## Ship a script or write prose
25
-
26
- Ship a script when either condition holds:
27
-
28
- 1. The same code gets rewritten on every run.
29
- 2. Deterministic reliability matters (one wrong character breaks the result).
30
-
31
- Otherwise write prose. A script is executed, not loaded, so its body stays out of
32
- context and costs no tokens at trigger time. The price is an indirection: the agent must
33
- find the script, learn its interface, and run it. Pay that price only when repetition or
34
- determinism earns it. [G1]
35
-
36
- ## The three-way test
37
-
38
- When something repeats, route it by what repeats, not by gut feel. [G2]
39
-
40
- | What repeats | Bucket | Why |
41
- | --- | --- | --- |
42
- | Identical code | `scripts/` | Run it; do not regenerate it each time. |
43
- | Identical boilerplate output | `assets/` (template) | Copy the template into output; never read it into context. |
44
- | Re-discovered facts | `references/` | Read it once, on the trigger that needs it. |
45
-
46
- A symptom of the wrong choice: an agent pasting the same 30 lines of Ruby across three
47
- runs belongs in `scripts/`, not in prose; a fixed file header the agent retypes belongs
48
- in `assets/`; a constant the agent keeps looking up belongs in `references/`.
49
-
50
- ## Make scripts solve, not punt
51
-
52
- A script that hands its failure back to the agent loses the determinism that justified
53
- shipping it. [G3]
54
-
55
- - Handle errors inside the script. Catch the failure, print a clear diagnostic to stderr,
56
- and exit non-zero. Do not raise a raw stack trace and leave the agent to interpret it.
57
- - No voodoo constants. Every magic number, path, or threshold gets a name and a comment
58
- stating where it came from. An unexplained `0.87` is a future break.
59
- - State the mode. Say explicitly whether the agent executes the script or reads it. A
60
- validator is executed; a snippet meant to be copied is read. Ambiguity makes the agent
61
- guess.
62
-
63
- ## Test by running
64
-
65
- An untested script is a latent break. Run it against real input before shipping. [G4]
66
-
67
- - Exercise the success path and at least one failure path; confirm the exit code and the
68
- stderr message.
69
- - Delete any example or scratch files the run generated that the skill does not ship.
70
- Stray files are clutter and may load by accident.
71
-
72
- ## Match freedom to fragility
73
-
74
- Match degrees of freedom to fragility. Put guardrails on the narrow bridge, not the open
75
- field. [G6]
76
-
77
- | Task shape | Form | Reason |
78
- | --- | --- | --- |
79
- | Open, judgment-heavy | Prose | The agent needs room to adapt; code would over-constrain. |
80
- | A preferred, repeatable pattern | Parameterized script (flags/env) | One correct shape, with controlled variation. |
81
- | Fragile or destructive sequence | Fixed "do not modify" script | One exact path; any edit risks data loss. |
82
-
83
- Mark a fragile script as "do not modify" in its `--help` and in the pointer that sends the
84
- agent to it. For side-effecting workflows, gate execution behind a validator (see below)
85
- rather than trusting the agent to check preconditions by hand.
86
-
87
- ## Wire validators into hooks
88
-
89
- When a rule must hold every time, wire a deterministic validator into a hook rather than
90
- restating the rule in prose. [G5]
91
-
92
- - A `PreToolUse` validator can refuse an action before it runs; a packaging step can
93
- refuse to ship a skill that fails validation.
94
- - Gate destructive steps behind validate-then-act: the validator passes, then the action
95
- runs. A prose reminder ("remember to check X first") is probabilistic; a hook is not.
96
-
97
- For hook event selection, exit-code semantics, and path conventions, read
98
- `references/hooks.md`.
99
-
100
- ## Script hard requirements
101
-
102
- Every script that ships with a skill meets these, because an agent runs it unattended:
103
-
104
- 1. No interactive prompts. A blocking `gets` or `read -p` hangs the agent forever. Take
105
- all input up front.
106
- 2. Input via flags, environment variables, or stdin. Never mid-run questions.
107
- 3. `--help` is the primary documentation. Describe purpose, every flag, input, output, and
108
- exit codes there, so the agent learns the interface without reading the source.
109
- 4. Structured output. Data on stdout, diagnostics and progress on stderr, so the caller
110
- can capture one without the other.
111
- 5. Idempotent operations. Running twice produces the same end state; re-running after a
112
- partial failure is safe.
113
- 6. Meaningful, documented exit codes. 0 for success, distinct non-zero codes for distinct
114
- failures, each named in `--help`.
115
-
116
- ## Plastic conventions
117
-
118
- - Scripts ship in Ruby. A worked example that shows a script shows Ruby.
119
- - Any shell script runs under macOS `/bin/bash` 3.2. No `bash` 4.x features (no
120
- associative arrays, no `mapfile`, no `${var^^}`), and no heredocs inside `$(...)`.
121
-
122
- ## Worked example
123
-
124
- A skill validates that an intent slug is well formed before any directory is created. The
125
- check runs on every intent and must be exact, so it ships as a script, not prose. [G1][G3]
126
-
127
- `scripts/validate_slug.rb`:
128
-
129
- ```ruby
130
- #!/usr/bin/env ruby
131
- # Validate an intent slug. Execute this; do not inline its logic.
132
- # Usage: validate_slug.rb SLUG
133
- # Exit: 0 valid, 1 malformed, 2 wrong argument count.
134
-
135
- # Convention source: A5 of the best-practices standard (lowercase,
136
- # digits, single hyphens, no leading/trailing/consecutive hyphens).
137
- SLUG_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
138
-
139
- if ARGV.length != 1
140
- warn "usage: validate_slug.rb SLUG"
141
- exit 2
142
- end
143
-
144
- slug = ARGV.fetch(0)
145
- if SLUG_PATTERN.match?(slug)
146
- puts slug # data on stdout
147
- exit 0
148
- else
149
- warn "malformed slug: #{slug.inspect}" # diagnostic on stderr
150
- exit 1
151
- end
152
- ```
153
-
154
- This script earns its place: identical code on every run, one exact rule, errors handled
155
- inside, the named constant cites its source, data on stdout and diagnostics on stderr,
156
- documented exit codes, and the header states it is executed. An open task ("name this
157
- intent well") would stay prose; this fixed check is a script.
158
-
159
- ## Self-check
160
-
161
- - Does this code repeat or demand exactness? If not, it stays prose. [G1]
162
- - Did the right bucket win the three-way test? [G2]
163
- - Are errors handled inside, constants named, and the execute-or-read mode stated? [G3]
164
- - Did the script run green on a success path and a failure path, with scratch files
165
- removed? [G4]
166
- - Does fragility match form, with destructive steps gated by a validator? [G5][G6]
@@ -1,169 +0,0 @@
1
- # Authoring an Agent Skill
2
-
3
- Open this when writing or restructuring a single Agent Skill: the frontmatter, the
4
- description that triggers it, the body voice, and the on-disk layout. Rule ids in brackets
5
- (A1 through B10) point at the synthesis standard the rules come from.
6
-
7
- For the three load levels (metadata, body, resources), the thin-router pattern, and how to
8
- split a body into `references/`, read `progressive-disclosure.md`. This file does not repeat
9
- that model.
10
-
11
- ## Contents
12
-
13
- - Skill file layout
14
- - Frontmatter fields
15
- - The `name` field
16
- - The `description` field (triggering)
17
- - Optional frontmatter fields
18
- - Body voice
19
- - Body content
20
- - Self-check
21
-
22
- ## Skill file layout
23
-
24
- A skill is a directory whose name matches the `name` field. The directory holds `SKILL.md`
25
- plus optional buckets. Pick a bucket by how the file touches context.
26
-
27
- | Path | Loads when | Holds |
28
- |------|-----------|-------|
29
- | `SKILL.md` | The skill triggers | Frontmatter plus the body |
30
- | `references/` | The body points at it, on demand | Deep how-to, specs, variant material |
31
- | `scripts/` | Executed, never read into context | Repeated deterministic code |
32
- | `assets/` | Copied into output, never read | Templates, boilerplate the output needs |
33
- | `evals/` | Run by the eval harness | Eval cases for the skill |
34
-
35
- When picking a bucket, follow `progressive-disclosure.md` for the cross-cutting layout rules:
36
- references one level deep (C5), no orphan or auxiliary files in the skill (C9), and each fact
37
- stored once (C7).
38
-
39
- ## Frontmatter fields
40
-
41
- `SKILL.md` opens with YAML frontmatter. Two fields are required.
42
-
43
- | Field | Required | Constraints |
44
- |-------|----------|-------------|
45
- | `name` | Yes | 1 to 64 chars. Lowercase alphanumeric plus hyphens. No leading, trailing, or consecutive hyphens. Matches the directory name. |
46
- | `description` | Yes | 1 to 1024 chars. Non-empty. States what and when. |
47
-
48
- Invent no other top-level fields. Unknown fields are ignored or rejected and add noise [A6].
49
-
50
- ## The `name` field
51
-
52
- Rules [A5]:
53
-
54
- 1. 64 chars or fewer.
55
- 2. Lowercase letters, numbers, and hyphens only.
56
- 3. No leading, trailing, or consecutive hyphens.
57
- 4. Must match the parent directory name exactly.
58
- 5. Must not contain `anthropic` or `claude`.
59
- 6. Prefer the gerund form, which reads as a capability (`processing-pdfs`, `creating-skills`,
60
- not `pdf-tool`).
61
- 7. Never start with `plastic-`. That prefix is reserved for skills and hooks Plastic itself
62
- ships; doctor's ownership checks (`stray_skills`) and the installer's purge both key off it,
63
- so a user-authored skill carrying it reads as squatting on Plastic's own namespace.
64
-
65
- ## The `description` field (triggering)
66
-
67
- The description is the only text loaded at discovery time. The body is not loaded when the
68
- agent decides whether to trigger, so the description alone has to win the match.
69
-
70
- Rules:
71
-
72
- 1. Write the description as triggering conditions only ("Use when ..."), never as a summary of
73
- the workflow [A1]. A workflow summary makes the agent act on the summary and skip the body,
74
- dropping steps. Documented failure: a description that summarized "code review between
75
- tasks" produced one review instead of two.
76
- 2. Write in the third person [A2]. The description is injected into the system prompt, where
77
- mixed point of view degrades discovery.
78
- 3. State both what the skill does and when to use it, and front-load concrete trigger terms
79
- [A3]. The model picks from many skills on this text and the listing is budget-truncated, so
80
- terms placed late may never be read.
81
- 4. Include at least one indirect trigger where the user does not name the domain [A4]. Real
82
- prompts rarely name the skill, so a keyword-only description misses oblique requests.
83
-
84
- Shape:
85
-
86
- ```yaml
87
- description: >
88
- [One clause: what it does]. Use when [primary trigger], [secondary trigger],
89
- or when [indirect trigger where the user does not name the domain].
90
- ```
91
-
92
- For side-effecting workflows (deploy, release, destructive ops), set
93
- `disable-model-invocation: true` so only the user fires the skill [A7]. Auto-triggering on
94
- irreversible work is a known failure mode.
95
-
96
- ## Optional frontmatter fields
97
-
98
- Use only the documented optionals below. Add nothing beyond them [A6].
99
-
100
- | Field | Holds |
101
- |-------|-------|
102
- | `license` | Short name or filename reference |
103
- | `compatibility` | Environment requirements, 1 to 500 chars, only when needed |
104
- | `metadata` | String-to-string map with unique keys |
105
- | `allowed-tools` | Space-separated tool list (experimental) |
106
- | `model` | Claude Code extension: pin the model for this skill |
107
- | `disable-model-invocation` | Claude Code extension: only the user may fire the skill |
108
- | `user-invocable` | Claude Code extension: set false to hide the skill from the user's / slash menu while leaving it agent-invocable; default true |
109
- | `context: fork` | Claude Code extension: run the body as a forked task |
110
- | `paths` | Claude Code extension: scope the skill to matching paths |
111
-
112
- ## Body voice
113
-
114
- Rules:
115
-
116
- 1. Write in imperative or infinitive voice ("Run the validator", "Extract the text"), never
117
- second person ("you should", "you can") [B1]. Command voice is shorter and binds tighter;
118
- hedged second-person language is a known slop pattern.
119
- 2. Use one consistent term per concept ("extract", never also "pull", "get", "retrieve")
120
- [B6]. Synonym drift makes the agent unsure whether two terms name the same operation.
121
-
122
- ## Body content
123
-
124
- The body persists in context every turn the skill is active, so each line is a recurring
125
- cost. Spend lines only where the agent would otherwise go wrong.
126
-
127
- Rules:
128
-
129
- 1. State what to do, not how or why, and cut anything the model already knows [B2]. Claude is
130
- already capable; the body is for the project-specific and the non-obvious.
131
- 2. Apply the test "would the agent get this wrong without it?" to every instruction. If no,
132
- delete it [B7]. Instructions that restate default competence are pure token cost.
133
- 3. Challenge every paragraph with "does this justify its token cost?" and prefer one excellent
134
- example over many mediocre ones [B3].
135
- 4. Lead each section with one bold maxim and close it with one concrete self-check [B4]. The
136
- maxim is what survives in context; the check lets the agent apply the rule mid-task.
137
- 5. Put gotchas as concrete corrections, placed early [B5]. A correction only helps if the
138
- agent reads it before it makes the mistake. Write the specific fact, not general advice:
139
-
140
- ```markdown
141
- ## Gotchas
142
- - The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL`.
143
- - User id is `user_id` in the DB, `uid` in auth, `accountId` in billing. Same value.
144
- - The `/health` endpoint returns 200 even when the DB is down. Use `/ready`.
145
- ```
146
-
147
- 6. Carry reference and decision material in tables and numbered lists. Use a flowchart only
148
- for a genuinely non-obvious decision or an early-stop loop [B10]. Tables are denser per
149
- token; flowcharts waste tokens on reference, code, or linear steps.
150
- 7. State the tradeoff and ship an escape hatch instead of policing edge cases with long
151
- rationalization tables [B8]. Add an Excuse-and-Reality table only for a discipline skill
152
- where an eval has actually shown the agent rationalizing a violation.
153
- 8. Avoid time-sensitive content. Move deprecated material into a collapsed "Old patterns"
154
- section [B9]. Dated instructions rot and mislead.
155
-
156
- ## Self-check
157
-
158
- Before shipping the skill, confirm each line:
159
-
160
- - [ ] `name` matches the directory, is lowercase-hyphen, and carries no `claude`/`anthropic`.
161
- - [ ] `description` reads as "Use when ...", third person, with front-loaded triggers and at
162
- least one indirect trigger.
163
- - [ ] No invented frontmatter fields; optionals are drawn only from the table above.
164
- - [ ] Side-effecting skill sets `disable-model-invocation`.
165
- - [ ] Body is imperative, with one term per concept.
166
- - [ ] Every instruction passes "would the agent get this wrong without it?".
167
- - [ ] Gotchas are concrete corrections, placed early.
168
- - [ ] Reference and decision material is in tables or lists, not prose.
169
- - [ ] `references/` files are one level deep; no orphan or auxiliary files in the skill.
@@ -1,313 +0,0 @@
1
- #!/usr/bin/env ruby
2
- # frozen_string_literal: true
3
-
4
- # scaffold.rb - born-slim starting files for a new skill, agent, or hook.
5
- #
6
- # Plastic skills, agents, and hooks start small and grow by progressive
7
- # disclosure. This scaffolder emits the minimum valid skeleton so the body
8
- # stays slim and detail moves into references/ as the work earns it.
9
- #
10
- # Usage:
11
- # ruby scaffold.rb skill <name> [--out <dir>] [dest]
12
- # ruby scaffold.rb agent <name> [--out <dir>] [dest]
13
- # ruby scaffold.rb hook [<Event>] <name> [--out <dir>] [dest]
14
- # ruby scaffold.rb --help
15
- #
16
- # All input is positional plus flags. There are no interactive prompts, so an
17
- # agent never hangs waiting on input. The destination defaults to the current
18
- # directory; pass --out or a trailing positional to choose another directory.
19
- #
20
- # Exit codes:
21
- # 0 success, or --help
22
- # 1 usage error (unknown subcommand, missing argument)
23
- # 2 validation error (bad name or event)
24
- # 3 refused to overwrite an existing target, or a filesystem error
25
- #
26
- # This script and every file it emits contain no em-dashes; the emitted files
27
- # are user-facing.
28
-
29
- require "json"
30
- require "fileutils"
31
-
32
- EXIT_OK = 0
33
- EXIT_USAGE = 1
34
- EXIT_VALIDATION = 2
35
- EXIT_CONFLICT = 3
36
-
37
- NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/.freeze
38
- EVENT_PATTERN = /\A[A-Z][A-Za-z]+\z/.freeze
39
- DEFAULT_EVENT = "PostToolUse"
40
-
41
- USAGE = <<~TEXT
42
- scaffold.rb - born-slim starting files for a new skill, agent, or hook.
43
-
44
- Usage:
45
- ruby scaffold.rb skill <name> [--out <dir>] [dest]
46
- ruby scaffold.rb agent <name> [--out <dir>] [dest]
47
- ruby scaffold.rb hook [<Event>] <name> [--out <dir>] [dest]
48
- ruby scaffold.rb --help
49
-
50
- Subcommands:
51
- skill Emit <dest>/<name>/SKILL.md, references/.gitkeep, evals/evals.json.
52
- agent Emit <dest>/<name>.md agent role file.
53
- hook Emit <dest>/<name> no-op hook handler (Ruby) wired for <Event>.
54
-
55
- Names must be lowercase alphanumeric and hyphens, with no leading,
56
- trailing, or repeated hyphens, 1 to 64 characters.
57
- The hook <Event> is optional and defaults to #{DEFAULT_EVENT}.
58
- The destination defaults to the current directory.
59
-
60
- Exit codes:
61
- 0 success, or --help
62
- 1 usage error (unknown subcommand, missing argument)
63
- 2 validation error (bad name or event)
64
- 3 refused to overwrite an existing target, or a filesystem error
65
- TEXT
66
-
67
- # A small error that carries the exit code to use when it reaches the top.
68
- class ScaffoldError < StandardError
69
- attr_reader :code
70
-
71
- def initialize(message, code)
72
- super(message)
73
- @code = code
74
- end
75
- end
76
-
77
- def fail_with(message, code)
78
- raise ScaffoldError.new(message, code)
79
- end
80
-
81
- def validate_name!(name)
82
- if name.nil? || name.empty?
83
- fail_with("missing <name>. See --help for usage.", EXIT_USAGE)
84
- end
85
- unless name.length <= 64 && name =~ NAME_PATTERN
86
- fail_with(
87
- "invalid name #{name.inspect}: use lowercase letters, digits, and " \
88
- "hyphens, no leading, trailing, or repeated hyphens, 1 to 64 chars.",
89
- EXIT_VALIDATION
90
- )
91
- end
92
- name
93
- end
94
-
95
- def validate_event!(event)
96
- unless event =~ EVENT_PATTERN
97
- fail_with(
98
- "invalid event #{event.inspect}: use a CamelCase hook event name, " \
99
- "for example PostToolUse or SessionStart.",
100
- EXIT_VALIDATION
101
- )
102
- end
103
- event
104
- end
105
-
106
- # Separate --out and any trailing positional dest from the bare positionals.
107
- # Returns [positionals, out_dir]. out_dir is nil when not given.
108
- def parse_args(args)
109
- positionals = []
110
- out_dir = nil
111
- i = 0
112
- while i < args.length
113
- arg = args[i]
114
- case arg
115
- when "--out"
116
- out_dir = args[i + 1]
117
- if out_dir.nil?
118
- fail_with("--out needs a directory argument.", EXIT_USAGE)
119
- end
120
- i += 2
121
- else
122
- if arg.start_with?("--")
123
- fail_with("unknown option #{arg.inspect}. See --help for usage.", EXIT_USAGE)
124
- end
125
- positionals << arg
126
- i += 1
127
- end
128
- end
129
- [positionals, out_dir]
130
- end
131
-
132
- def refuse_if_exists!(path)
133
- if File.exist?(path)
134
- fail_with("refusing to overwrite existing #{path}. Remove it or pick another destination.", EXIT_CONFLICT)
135
- end
136
- end
137
-
138
- def write_file(path, content)
139
- refuse_if_exists!(path)
140
- FileUtils.mkdir_p(File.dirname(path))
141
- File.write(path, content)
142
- puts "created #{path}"
143
- end
144
-
145
- # -- generators ----------------------------------------------------------
146
-
147
- def skill_body(name)
148
- <<~MD
149
- ---
150
- name: #{name}
151
- description: >
152
- Use when the user needs #{name}. State here WHEN this skill should
153
- trigger, in the third person, so the agent can match it. Replace this
154
- placeholder with one or two concrete trigger conditions before shipping.
155
- ---
156
-
157
- # #{name}
158
-
159
- One line on what this skill does and why it exists.
160
-
161
- ## Gotchas
162
-
163
- - List the non-obvious failure modes here, one per line.
164
-
165
- ## Tasks
166
-
167
- Keep the body slim. Route detail to references as the work earns it.
168
-
169
- | Task | Reference |
170
- | ---- | --------- |
171
- | Replace this row with a real task | references/REPLACE-ME.md |
172
- MD
173
- end
174
-
175
- def eval_stub(name)
176
- data = {
177
- "skill_name" => name,
178
- "evals" => [
179
- {
180
- "id" => 1,
181
- "prompt" => "",
182
- "expected_output" => "",
183
- "files" => [],
184
- "assertions" => []
185
- }
186
- ]
187
- }
188
- JSON.pretty_generate(data) + "\n"
189
- end
190
-
191
- def generate_skill(name, out_dir)
192
- base = File.join(out_dir, name)
193
- refuse_if_exists!(base)
194
- write_file(File.join(base, "SKILL.md"), skill_body(name))
195
- write_file(File.join(base, "references", ".gitkeep"), "")
196
- write_file(File.join(base, "evals", "evals.json"), eval_stub(name))
197
- puts "skill scaffold ready at #{base}"
198
- end
199
-
200
- def agent_body(name)
201
- <<~MD
202
- ---
203
- name: #{name}
204
- description: >
205
- Use this agent when the user needs #{name}. State here WHEN to delegate
206
- to this agent, in the third person, so the orchestrator can route to it.
207
- Replace this placeholder with concrete delegation conditions.
208
- tools: Read, Edit, Bash
209
- ---
210
-
211
- You are the #{name} agent.
212
-
213
- ## Responsibilities
214
-
215
- - One line per durable responsibility this agent owns.
216
-
217
- ## How you work
218
-
219
- Keep this body slim. State the contract, the inputs, and the outputs.
220
- Move long procedures into a references file as the work earns it.
221
-
222
- ## Completion
223
-
224
- End your turn with a short report of what you did and how you verified it.
225
- MD
226
- end
227
-
228
- def generate_agent(name, out_dir)
229
- write_file(File.join(out_dir, "#{name}.md"), agent_body(name))
230
- puts "agent scaffold ready at #{File.join(out_dir, "#{name}.md")}"
231
- end
232
-
233
- def hook_body(name, event)
234
- <<~RUBY
235
- #!/usr/bin/env ruby
236
- # frozen_string_literal: true
237
-
238
- # #{name} - #{event} hook handler (no-op by default).
239
- #
240
- # This skeleton does nothing until you opt in. Set the environment flag
241
- # below to a non-empty value to activate the real behavior. Until then it
242
- # exits 0 so it never blocks the session.
243
- #
244
- # Wire it in settings.json under hooks.#{event}:
245
- # { "type": "command", "command": "ruby /absolute/path/to/#{name}" }
246
- #
247
- # Exit codes:
248
- # 0 no-op, or success
249
- # 2 block the action (only when you add real logic that should block)
250
-
251
- OPT_IN = "#{name.tr("-", "_").upcase}_ENABLED"
252
-
253
- if ENV[OPT_IN].nil? || ENV[OPT_IN].empty?
254
- exit 0
255
- end
256
-
257
- # Opt-in is set. Add the real handler here. The hook receives event JSON on
258
- # stdin; parse it only when you need it. Exit 0 to allow, exit 2 to block.
259
- exit 0
260
- RUBY
261
- end
262
-
263
- def generate_hook(name, event, out_dir)
264
- path = File.join(out_dir, name)
265
- write_file(path, hook_body(name, event))
266
- FileUtils.chmod("+x", path)
267
- puts "hook scaffold ready at #{path} (executable, #{event}, no-op until opt-in)"
268
- end
269
-
270
- # -- dispatch ------------------------------------------------------------
271
-
272
- def run(argv)
273
- if argv.empty? || argv.include?("--help") || argv.include?("-h")
274
- puts USAGE
275
- return EXIT_OK
276
- end
277
-
278
- subcommand = argv.shift
279
- positionals, out_flag = parse_args(argv)
280
-
281
- case subcommand
282
- when "skill", "agent"
283
- name = validate_name!(positionals[0])
284
- out_dir = out_flag || positionals[1] || "."
285
- subcommand == "skill" ? generate_skill(name, out_dir) : generate_agent(name, out_dir)
286
- when "hook"
287
- # Accept "hook <name>" or "hook <Event> <name>", with an optional trailing dest.
288
- if positionals.length >= 2 && positionals[0] =~ EVENT_PATTERN
289
- event = validate_event!(positionals[0])
290
- name = validate_name!(positionals[1])
291
- out_dir = out_flag || positionals[2] || "."
292
- else
293
- event = DEFAULT_EVENT
294
- name = validate_name!(positionals[0])
295
- out_dir = out_flag || positionals[1] || "."
296
- end
297
- generate_hook(name, event, out_dir)
298
- else
299
- fail_with("unknown subcommand #{subcommand.inspect}. See --help for usage.", EXIT_USAGE)
300
- end
301
-
302
- EXIT_OK
303
- end
304
-
305
- begin
306
- exit run(ARGV.dup)
307
- rescue ScaffoldError => e
308
- warn "scaffold.rb: #{e.message}"
309
- exit e.code
310
- rescue Errno::EACCES, Errno::ENOENT, Errno::EEXIST => e
311
- warn "scaffold.rb: filesystem error: #{e.message}"
312
- exit EXIT_CONFLICT
313
- end