@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.
- package/PLASTIC.md +101 -294
- package/README.md +5 -6
- package/agents/plastic-advisor.md +18 -17
- package/agents/plastic-enforcer.md +57 -69
- package/agents/plastic-executor.md +34 -20
- package/agents/plastic-faux-advisor.md +18 -18
- package/config_asks.yml +38 -0
- package/hooks/capture +4 -0
- package/hooks/check-update +12 -3
- package/hooks/close +5 -0
- package/hooks/hooks.json +9 -49
- package/hooks/record +4 -0
- package/package.json +3 -2
- package/scripts/agent-report +8 -9
- package/scripts/append-ledger +195 -0
- package/scripts/codex-hook +101 -95
- package/scripts/dashboard.rb +4 -4
- package/scripts/doctor.rb +106 -43
- package/scripts/end-intent +77 -76
- package/scripts/exec-worktree +11 -20
- package/scripts/file-session-intent +61 -0
- package/scripts/hook-capture +242 -0
- package/scripts/hook-close +34 -0
- package/scripts/hook-record +149 -0
- package/scripts/hook-session-start +95 -12
- package/scripts/install.rb +8 -6
- package/scripts/lib/agent_models.rb +1 -7
- package/scripts/lib/arm.rb +283 -0
- package/scripts/lib/backfill_intent.rb +316 -0
- package/scripts/lib/bridge.rb +24 -1597
- package/scripts/lib/doctor_core.rb +17 -88
- package/scripts/lib/doctor_session_ledger.rb +106 -0
- package/scripts/lib/exec_worktree.rb +14 -60
- package/scripts/lib/harness_text.rb +5 -4
- package/scripts/lib/hook_registry.rb +44 -107
- package/scripts/lib/insights.rb +3 -4
- package/scripts/lib/installer_core.rb +19 -30
- package/scripts/lib/lock.rb +6 -26
- package/scripts/lib/outcome_guard.rb +7 -5
- package/scripts/lib/project_validator.rb +30 -1
- package/scripts/lib/roadmap_queue.rb +3 -3
- package/scripts/lib/roadmap_savepoint.rb +1 -1
- package/scripts/lib/rule_catalog.rb +6 -3
- package/scripts/lib/savepoint.rb +320 -0
- package/scripts/lib/scaffold_intent.rb +13 -179
- package/scripts/lib/session_backfill.rb +184 -0
- package/scripts/lib/session_close.rb +84 -0
- package/scripts/lib/session_git.rb +469 -0
- package/scripts/lib/session_ledger.rb +497 -0
- package/scripts/lib/store_discovery.rb +1 -1
- package/scripts/lib/store_provisioning.rb +1 -1
- package/scripts/maintenance-run +7 -7
- package/scripts/new-intent +63 -4
- package/scripts/plastic-lock +94 -41
- package/scripts/promote-session-item +150 -0
- package/scripts/rebuild-graph +1 -1
- package/scripts/roadmap-next +2 -2
- package/scripts/rollback.rb +42 -3
- package/scripts/scaffold-intent +37 -63
- package/scripts/session-commit +116 -0
- package/scripts/spawn-preamble +5 -5
- package/scripts/update.rb +7 -3
- package/skills/agent-advisor/SKILL.md +3 -3
- package/skills/agent-advisor/references/advisor-protocol.md +20 -20
- package/skills/auto/SKILL.md +218 -317
- package/skills/auto/evals/evals.json +10 -10
- package/skills/auto/references/agent-architecture.md +102 -90
- package/skills/auto/references/agent-report-contract.md +4 -21
- package/skills/auto/references/end-tail.md +47 -53
- package/skills/auto/references/human-report-contract.md +8 -8
- package/skills/conventions/SKILL.md +1 -3
- package/skills/conventions/references/lifecycle-and-savepoints.md +35 -1
- package/skills/conventions/references/locks-and-worktrees.md +47 -55
- package/skills/conventions/references/maintenance-and-revisions.md +12 -12
- package/skills/dashboard/SKILL.md +1 -1
- package/skills/direct/SKILL.md +66 -0
- package/skills/direct/references/request-signals.md +59 -0
- package/skills/doctor/SKILL.md +58 -11
- package/skills/doctor/report.md +3 -1
- package/skills/install/SKILL.md +11 -9
- package/skills/intent-continuing/SKILL.md +131 -89
- package/skills/intent-continuing/references/boarding-matrix.md +34 -0
- package/skills/intent-continuing/references/context-management.md +2 -2
- package/skills/intent-creating/SKILL.md +2 -2
- package/skills/intent-creating/references/lifecycle.md +1 -1
- package/skills/intent-ending/SKILL.md +28 -37
- package/skills/intent-ending/evals/evals.json +4 -4
- package/skills/intent-executing/SKILL.md +12 -49
- package/skills/intent-executing/plan-reviewer-prompt.md +39 -0
- package/skills/intent-speccing/SKILL.md +108 -51
- package/skills/intent-speccing/evals/evals.json +5 -5
- package/skills/intent-speccing/references/per-section-fill-rules.md +4 -4
- package/skills/intent-speccing/references/self-verify-checklist.md +1 -2
- package/skills/project-creating/SKILL.md +1 -1
- package/skills/releasing/SKILL.md +7 -8
- package/skills/tutorial/SKILL.md +2 -2
- package/skills/tutorial/references/track-1-guided.md +16 -18
- package/skills/tutorial/references/track-2-auto.md +12 -13
- package/skills/tutorial/references/track-3-projects-and-roadmaps.md +2 -2
- package/templates/agents.md +4 -7
- package/templates/project.yml +7 -0
- package/templates/roadmap.md +1 -1
- package/templates/savepoint.md +2 -2
- package/templates/session-intent.md +29 -0
- package/agents/plastic-brainstorming.md +0 -48
- package/agents/plastic-future-intent-researcher.md +0 -35
- package/agents/plastic-intent-curator.md +0 -47
- package/agents/plastic-intent-discovery.md +0 -43
- package/agents/plastic-planner.md +0 -56
- package/agents/plastic-spec-specialist.md +0 -53
- package/hooks/auto-arm +0 -5
- package/hooks/bash-gate +0 -3
- package/hooks/continue +0 -31
- package/hooks/edit-gates +0 -3
- package/hooks/future-intent-check +0 -25
- package/hooks/gate-check +0 -12
- package/hooks/power-tools +0 -8
- package/scripts/hook-auto-arm +0 -51
- package/scripts/hook-bash-gate +0 -78
- package/scripts/hook-code-gate +0 -38
- package/scripts/hook-continue +0 -48
- package/scripts/hook-create-gate +0 -51
- package/scripts/hook-edit-gates +0 -58
- package/scripts/hook-future-intent-check +0 -90
- package/scripts/hook-gate-check +0 -169
- package/scripts/hook-links-gate +0 -54
- package/scripts/hook-lock-gate +0 -47
- package/scripts/hook-power-tools +0 -38
- package/scripts/hook-savepoint-pre +0 -32
- package/scripts/lib/codex_edit_gates.rb +0 -138
- package/scripts/lib/edit_gates.rb +0 -398
- package/scripts/lib/links_gate.rb +0 -140
- package/scripts/lib/qmd_hook.rb +0 -41
- package/scripts/lib/spec_header.rb +0 -83
- package/scripts/lib/start_intent.rb +0 -296
- package/scripts/start-intent +0 -89
- package/skills/_active-intent-gate.md +0 -26
- package/skills/auto/references/tiers.md +0 -100
- package/skills/continuing/SKILL.md +0 -34
- package/skills/continuing/evals/evals.json +0 -91
- package/skills/conventions/references/gates-and-enforcement.md +0 -53
- package/skills/conventions/references/tiers-and-dispatch.md +0 -135
- package/skills/doctor/references/gates-stuck-detection.md +0 -43
- package/skills/intent-brainstorming/SKILL.md +0 -118
- package/skills/intent-brainstorming/evals/evals.json +0 -67
- package/skills/intent-continuing/evals/evals.json +0 -145
- package/skills/intent-discovering/SKILL.md +0 -56
- package/skills/intent-grilling/SKILL.md +0 -108
- package/skills/intent-linking/SKILL.md +0 -128
- package/skills/intent-linking/evals/evals.json +0 -22
- package/skills/intent-linking/references/zettelkasten.md +0 -45
- package/skills/intent-locking/SKILL.md +0 -64
- package/skills/intent-planning/SKILL.md +0 -145
- package/skills/intent-planning/evals/evals.json +0 -81
- package/skills/intent-planning/references/plan-format.md +0 -130
- package/skills/intent-researching/SKILL.md +0 -123
- package/skills/intent-researching/evals/evals.json +0 -22
- package/skills/intent-savepoint/SKILL.md +0 -83
- package/skills/intent-savepoint/references/context-management.md +0 -32
- package/skills/intent-starting/SKILL.md +0 -151
- package/skills/intent-starting/evals/evals.json +0 -117
- package/skills/intent-starting/references/boarding-matrix.md +0 -35
- package/skills/project-continuing/SKILL.md +0 -119
- package/skills/project-continuing/evals/evals.json +0 -100
- package/skills/roadmap-continuing/SKILL.md +0 -89
- package/skills/roadmap-continuing/evals/evals.json +0 -82
- package/skills/skill-creating/SKILL.md +0 -75
- package/skills/skill-creating/evals/evals.json +0 -108
- package/skills/skill-creating/references/agents.md +0 -168
- package/skills/skill-creating/references/defaults-first.md +0 -23
- package/skills/skill-creating/references/evals.md +0 -41
- package/skills/skill-creating/references/hooks.md +0 -251
- package/skills/skill-creating/references/progressive-disclosure.md +0 -176
- package/skills/skill-creating/references/scripts.md +0 -166
- package/skills/skill-creating/references/skills.md +0 -169
- package/skills/skill-creating/scripts/scaffold.rb +0 -313
- package/skills/skill-evaluating/SKILL.md +0 -141
- package/skills/skill-evaluating/assets/eval-template.json +0 -12
- package/skills/skill-evaluating/evals/evals.json +0 -75
- package/skills/skill-evaluating/references/convention-checks.md +0 -76
- package/skills/skill-evaluating/references/eval-methodology.md +0 -154
- package/skills/store-curating/SKILL.md +0 -64
- package/skills/store-curating/evals/evals.json +0 -38
- package/skills/store-indexing/SKILL.md +0 -93
- package/skills/store-indexing/evals/evals.json +0 -22
- package/skills/store-indexing/references/zettelkasten-linking.md +0 -32
- package/skills/store-provisioning/SKILL.md +0 -55
- /package/skills/{project-continuing → intent-continuing}/references/board-fill.md +0 -0
- /package/skills/{roadmap-continuing → intent-continuing}/references/liveness-ranking.md +0 -0
- /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
|