@samuelfaj/distill 1.4.0 → 1.4.5
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/.claude/skills/distill/SKILL.md +239 -0
- package/README.md +32 -1
- package/bin/distill.js +40 -9
- package/package.json +13 -6
- package/skills/distill/SKILL.md +239 -0
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: distill
|
|
3
|
+
description: Conversation mode that makes the LLM speak in distill compressed language for the whole thread.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Distill
|
|
7
|
+
|
|
8
|
+
Use when user invokes `/distill` or asks to use distill language.
|
|
9
|
+
|
|
10
|
+
This is a conversation style mode, not a prompt-compression request.
|
|
11
|
+
|
|
12
|
+
Do not return the user's prompt compressed as an artifact.
|
|
13
|
+
Adopt the distill language structure and keep using it for the rest of the thread.
|
|
14
|
+
|
|
15
|
+
## Core Rule
|
|
16
|
+
|
|
17
|
+
Talk with the user in distill language:
|
|
18
|
+
|
|
19
|
+
- English only, unless user explicitly requests another output language
|
|
20
|
+
- Military English baseline
|
|
21
|
+
- short command lines
|
|
22
|
+
- one idea per line
|
|
23
|
+
- explicit constraints
|
|
24
|
+
- explicit pass criteria
|
|
25
|
+
- exact paths, commands, env vars, IDs when useful
|
|
26
|
+
- no filler
|
|
27
|
+
- no cryptic code
|
|
28
|
+
- no long prose unless user asks for explanation
|
|
29
|
+
|
|
30
|
+
Compress meaning, not characters.
|
|
31
|
+
Big wins come from removing repetition, sharing glossary, sharing context, and sharing structure.
|
|
32
|
+
|
|
33
|
+
## Thread Behavior
|
|
34
|
+
|
|
35
|
+
After `/distill` is invoked:
|
|
36
|
+
|
|
37
|
+
- keep answering in distill language until user says normal mode or stop distill
|
|
38
|
+
- use distill structure for status updates, plans, summaries, reviews, and final answers
|
|
39
|
+
- do not wrap every answer in `Best`, `More aggressive`, or `Tradeoff`
|
|
40
|
+
- do not output a rewritten/compressed version of the user's latest prompt unless user explicitly asks to compress text
|
|
41
|
+
- keep hidden chain-of-thought private; never reveal it
|
|
42
|
+
- any visible reasoning or analysis summary must use distill language
|
|
43
|
+
|
|
44
|
+
## Stable DSL
|
|
45
|
+
|
|
46
|
+
Use labels when they reduce repeated structure:
|
|
47
|
+
|
|
48
|
+
- `T` task
|
|
49
|
+
- `C` context
|
|
50
|
+
- `Do` actions
|
|
51
|
+
- `No` constraints
|
|
52
|
+
- `Pass` pass criteria
|
|
53
|
+
- `Out` required output
|
|
54
|
+
|
|
55
|
+
Built-in aliases:
|
|
56
|
+
|
|
57
|
+
- `A` authentication or authorization
|
|
58
|
+
- `B` backend
|
|
59
|
+
- `F` frontend
|
|
60
|
+
- `D` database
|
|
61
|
+
- `E` end-to-end tests
|
|
62
|
+
- `C` configuration
|
|
63
|
+
- `O` documentation
|
|
64
|
+
- `V` environment
|
|
65
|
+
- `X` dependencies
|
|
66
|
+
- `P` permissions
|
|
67
|
+
- `U` user interface
|
|
68
|
+
|
|
69
|
+
Built-in macros:
|
|
70
|
+
|
|
71
|
+
- `1` add failing regression test first
|
|
72
|
+
- `2` run relevant tests
|
|
73
|
+
- `3` report summary, files, tests, and status
|
|
74
|
+
- `4` review for bugs, regressions, security, and risks
|
|
75
|
+
- `5` implement smallest safe fix
|
|
76
|
+
- `6` validate with tests or checks
|
|
77
|
+
- `7` commit and push changes
|
|
78
|
+
- `8` create or update pull request
|
|
79
|
+
- `9` release or publish flow
|
|
80
|
+
- `0` exact raw output required
|
|
81
|
+
|
|
82
|
+
Built-in defaults:
|
|
83
|
+
|
|
84
|
+
- `N1` do not change frontend
|
|
85
|
+
- `N2` do not change backend
|
|
86
|
+
- `N3` do not change UI
|
|
87
|
+
- `N4` no broad refactor
|
|
88
|
+
- `N5` preserve unrelated user changes
|
|
89
|
+
- `N6` interactive or TUI command
|
|
90
|
+
|
|
91
|
+
Example:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
T auth-fix.
|
|
95
|
+
1.
|
|
96
|
+
B-only.
|
|
97
|
+
N1.
|
|
98
|
+
2.
|
|
99
|
+
3.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Use DSL only when the user and agent share the glossary. If meaning may be ambiguous, use the full phrase.
|
|
103
|
+
|
|
104
|
+
## Good Response Forms
|
|
105
|
+
|
|
106
|
+
Tiny status:
|
|
107
|
+
|
|
108
|
+
```text
|
|
109
|
+
Done.
|
|
110
|
+
Changed: src/onboarding.ts, test/cli-entry.test.ts.
|
|
111
|
+
Verify: bun test PASS.
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Plan:
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
T: fix onboarding distill mode.
|
|
118
|
+
Do: inspect skill, patch wording, sync copies, run tests.
|
|
119
|
+
No: unrelated refactor.
|
|
120
|
+
Pass: /distill changes conversation style, not prompt output.
|
|
121
|
+
Out: files, tests, risks.
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Need info:
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
Need: target repo or exact file.
|
|
128
|
+
Blocked: cannot choose safe path from prompt alone.
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Review/result:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
Result: PASS.
|
|
135
|
+
Changed: skill now activates thread language mode.
|
|
136
|
+
Tests: bun test test/cli-entry.test.ts PASS.
|
|
137
|
+
Risk: not committed.
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Glossary And Memory
|
|
141
|
+
|
|
142
|
+
Keep an internal alias dict per conversation. Do not create files.
|
|
143
|
+
|
|
144
|
+
Use aliases only when they stay obvious:
|
|
145
|
+
|
|
146
|
+
- `be` backend
|
|
147
|
+
- `fe` frontend
|
|
148
|
+
- `db` database
|
|
149
|
+
- `e2e` end-to-end
|
|
150
|
+
- `cfg` config
|
|
151
|
+
- `docs` documentation
|
|
152
|
+
- `env` environment
|
|
153
|
+
- `deps` dependencies
|
|
154
|
+
- `repo` repository
|
|
155
|
+
- `impl` implementation
|
|
156
|
+
- `ref` refactor/reference
|
|
157
|
+
- `err` error
|
|
158
|
+
|
|
159
|
+
When aliases help the user, output one compact line:
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
Dict: B=backend F=frontend C=config
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Later additions:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
Dict+: P1=extra permission rule
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Avoid aliases for rare, short, temporary, or ambiguous terms. Avoid new terms when `A` authentication versus `P` permissions would be unclear.
|
|
172
|
+
|
|
173
|
+
Add learned aliases/macros only when likely to repeat.
|
|
174
|
+
Prefer `Dict:` for active shared terms and `Dict+` for additions. Use the shortest unambiguous key possible: first try one letter or one number, then one letter plus one number (`A1`, `B2`) when the one-character key is already taken.
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
Dict: B=backend F=frontend 1=failing-test-first
|
|
178
|
+
Dict+: A1=authentication bug fix
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Expire learned terms mentally if they stop appearing. A term should not become part of thread DSL unless it appears at least twice in a short window or the user explicitly approves it.
|
|
182
|
+
|
|
183
|
+
## Tool Calls
|
|
184
|
+
|
|
185
|
+
CRITICAL: Every non-interactive, non-TUI shell/tool command must pipe output through `distill` with an explicit prompt. Do not run plain shell commands when summarized output is enough.
|
|
186
|
+
|
|
187
|
+
CRITICAL: Skip `| distill` only when exact raw output is required or when `distill` would break an interactive/TUI workflow.
|
|
188
|
+
|
|
189
|
+
CRITICAL: Your prompt to `distill` must be fully explicit. State exactly what you want to know and exactly what the output must contain. If you want only filenames, say `Return only the filenames.` If you want JSON, say `Return valid JSON only.` Do not ask vague questions.
|
|
190
|
+
|
|
191
|
+
Bad:
|
|
192
|
+
|
|
193
|
+
- `distill "Which files are shown?"`
|
|
194
|
+
|
|
195
|
+
Good:
|
|
196
|
+
|
|
197
|
+
- `distill "Which files are shown? Return only the filenames."`
|
|
198
|
+
|
|
199
|
+
Examples:
|
|
200
|
+
|
|
201
|
+
- `bun test 2>&1 | distill "Did the tests pass? Return only: PASS or FAIL, followed by failing test names if any."`
|
|
202
|
+
- `git diff 2>&1 | distill "What changed? Return only the files changed and a one-line summary for each file."`
|
|
203
|
+
- `terraform plan 2>&1 | distill "Is this safe? Return only: SAFE, REVIEW, or UNSAFE, followed by the exact risky changes."`
|
|
204
|
+
- `npm audit 2>&1 | distill "Extract the vulnerabilities. Return valid JSON only."`
|
|
205
|
+
- `rg -n "TODO|FIXME" . 2>&1 | distill "List files containing TODO or FIXME. Return only file paths, one per line."`
|
|
206
|
+
- `ls -la 2>&1 | distill "Which files are shown? Return only the filenames."`
|
|
207
|
+
|
|
208
|
+
You may skip `distill` only in these cases:
|
|
209
|
+
|
|
210
|
+
- Exact uncompressed output is required.
|
|
211
|
+
- Using `distill` would break an interactive or TUI workflow.
|
|
212
|
+
|
|
213
|
+
CRITICAL: Wait for `distill` to finish before continuing.
|
|
214
|
+
|
|
215
|
+
## Keep Explicit
|
|
216
|
+
|
|
217
|
+
- security
|
|
218
|
+
- permissions
|
|
219
|
+
- payment
|
|
220
|
+
- data loss
|
|
221
|
+
- migrations
|
|
222
|
+
- production
|
|
223
|
+
- destructive actions
|
|
224
|
+
- user-facing behavior
|
|
225
|
+
- test expectations
|
|
226
|
+
- exact paths, endpoints, commands, env vars, IDs
|
|
227
|
+
|
|
228
|
+
## Quality Gate
|
|
229
|
+
|
|
230
|
+
Before returning, check:
|
|
231
|
+
|
|
232
|
+
- Did you answer the user instead of rewriting their prompt?
|
|
233
|
+
- Are constraints explicit?
|
|
234
|
+
- Is success defined when relevant?
|
|
235
|
+
- Did compression remove meaning?
|
|
236
|
+
- Are aliases obvious or defined?
|
|
237
|
+
- Is the answer short but still safe?
|
|
238
|
+
|
|
239
|
+
If not, use more words.
|
package/README.md
CHANGED
|
@@ -1,7 +1,38 @@
|
|
|
1
1
|
# @samuelfaj/distill
|
|
2
2
|
|
|
3
|
-
Install
|
|
3
|
+
Install:
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
npm i -g @samuelfaj/distill
|
|
7
7
|
```
|
|
8
|
+
|
|
9
|
+
Run onboarding:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
distill
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
After onboarding, use `/distill` in Claude/Codex to make the agent keep talking in distill language for the whole thread. It should adopt the language style, not return your prompt rewritten.
|
|
16
|
+
|
|
17
|
+
`/distill` also has DSL memory:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
distill dsl show
|
|
21
|
+
distill dsl show --candidates
|
|
22
|
+
distill dsl learn --dry-run "Dict+: A1=authentication fix"
|
|
23
|
+
distill dsl learn-thread --stdin --dry-run < transcript.txt
|
|
24
|
+
distill dsl promote --dry-run
|
|
25
|
+
distill dsl add alias A1 "authentication bug fix" --scope project
|
|
26
|
+
distill dsl prune --dry-run
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Normal runs load compact active DSL memory into the prompt. Reusable `Dict+` entries from `/distill` output are learned as project candidates using the shortest available key and can later be promoted with `distill dsl promote`.
|
|
30
|
+
|
|
31
|
+
At thread end, pipe a transcript into `distill dsl learn-thread --stdin`. It learns repeated workflow language as candidates after reviewer approval and sensitive-term filtering.
|
|
32
|
+
|
|
33
|
+
You can also pipe command output into `distill`:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
bun test 2>&1 | distill "Did tests pass? Return PASS or FAIL, followed by failing test names if any."
|
|
37
|
+
git diff | distill "What changed? Return only files changed and one-line summary for each."
|
|
38
|
+
```
|
package/bin/distill.js
CHANGED
|
@@ -1,23 +1,40 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
const { spawn } = require("node:child_process");
|
|
4
|
+
const fs = require("node:fs");
|
|
4
5
|
const path = require("node:path");
|
|
5
6
|
const { createRequire } = require("node:module");
|
|
6
7
|
|
|
7
8
|
const requireFromHere = createRequire(__filename);
|
|
8
9
|
|
|
9
10
|
const PACKAGE_BY_TARGET = {
|
|
10
|
-
"darwin-arm64":
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
"darwin-arm64": {
|
|
12
|
+
packageName: "@samuelfaj/distill-darwin-arm64",
|
|
13
|
+
binaryName: "distill"
|
|
14
|
+
},
|
|
15
|
+
"darwin-x64": {
|
|
16
|
+
packageName: "@samuelfaj/distill-darwin-x64",
|
|
17
|
+
binaryName: "distill"
|
|
18
|
+
},
|
|
19
|
+
"linux-arm64": {
|
|
20
|
+
packageName: "@samuelfaj/distill-linux-arm64",
|
|
21
|
+
binaryName: "distill"
|
|
22
|
+
},
|
|
23
|
+
"linux-x64": {
|
|
24
|
+
packageName: "@samuelfaj/distill-linux-x64",
|
|
25
|
+
binaryName: "distill"
|
|
26
|
+
},
|
|
27
|
+
"win32-x64": {
|
|
28
|
+
packageName: "@samuelfaj/distill-win32-x64",
|
|
29
|
+
binaryName: "distill.exe"
|
|
30
|
+
}
|
|
14
31
|
};
|
|
15
32
|
|
|
16
33
|
function resolveBinaryPath() {
|
|
17
34
|
const target = `${process.platform}-${process.arch}`;
|
|
18
|
-
const
|
|
35
|
+
const targetSpec = PACKAGE_BY_TARGET[target];
|
|
19
36
|
|
|
20
|
-
if (!
|
|
37
|
+
if (!targetSpec) {
|
|
21
38
|
console.error(
|
|
22
39
|
`[distill] Unsupported platform: ${process.platform}/${process.arch}.`
|
|
23
40
|
);
|
|
@@ -25,11 +42,24 @@ function resolveBinaryPath() {
|
|
|
25
42
|
}
|
|
26
43
|
|
|
27
44
|
try {
|
|
28
|
-
const packageJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
|
|
29
|
-
return path.join(path.dirname(packageJsonPath), "bin",
|
|
45
|
+
const packageJsonPath = requireFromHere.resolve(`${targetSpec.packageName}/package.json`);
|
|
46
|
+
return path.join(path.dirname(packageJsonPath), "bin", targetSpec.binaryName);
|
|
30
47
|
} catch (error) {
|
|
48
|
+
const workspaceBinaryPath = path.resolve(
|
|
49
|
+
__dirname,
|
|
50
|
+
"..",
|
|
51
|
+
"..",
|
|
52
|
+
`distill-${target}`,
|
|
53
|
+
"bin",
|
|
54
|
+
targetSpec.binaryName
|
|
55
|
+
);
|
|
56
|
+
|
|
57
|
+
if (fs.existsSync(workspaceBinaryPath)) {
|
|
58
|
+
return workspaceBinaryPath;
|
|
59
|
+
}
|
|
60
|
+
|
|
31
61
|
console.error(
|
|
32
|
-
`[distill] Missing platform package ${packageName}. Reinstall @samuelfaj/distill for this platform.`
|
|
62
|
+
`[distill] Missing platform package ${targetSpec.packageName}. Reinstall @samuelfaj/distill for this platform.`
|
|
33
63
|
);
|
|
34
64
|
process.exit(1);
|
|
35
65
|
}
|
|
@@ -134,6 +164,7 @@ const child = spawn(binPath, process.argv.slice(2), {
|
|
|
134
164
|
stdio: ["inherit", "pipe", "pipe"],
|
|
135
165
|
env: {
|
|
136
166
|
...process.env,
|
|
167
|
+
DISTILL_PACKAGE_ROOT: path.resolve(__dirname, ".."),
|
|
137
168
|
DISTILL_PROGRESS_PROTOCOL: "stderr"
|
|
138
169
|
}
|
|
139
170
|
});
|
package/package.json
CHANGED
|
@@ -1,25 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@samuelfaj/distill",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.5",
|
|
4
4
|
"description": "Compress command output for downstream LLMs.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
7
7
|
"distill": "bin/distill.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
|
+
".claude",
|
|
10
11
|
"bin",
|
|
11
|
-
"README.md"
|
|
12
|
+
"README.md",
|
|
13
|
+
"skills"
|
|
12
14
|
],
|
|
13
15
|
"engines": {
|
|
14
16
|
"node": ">=18"
|
|
15
17
|
},
|
|
16
18
|
"optionalDependencies": {
|
|
17
|
-
"@samuelfaj/distill-darwin-arm64": "1.4.
|
|
18
|
-
"@samuelfaj/distill-darwin-x64": "1.4.
|
|
19
|
-
"@samuelfaj/distill-linux-arm64": "1.4.
|
|
20
|
-
"@samuelfaj/distill-linux-x64": "1.4.
|
|
19
|
+
"@samuelfaj/distill-darwin-arm64": "1.4.5",
|
|
20
|
+
"@samuelfaj/distill-darwin-x64": "1.4.5",
|
|
21
|
+
"@samuelfaj/distill-linux-arm64": "1.4.5",
|
|
22
|
+
"@samuelfaj/distill-linux-x64": "1.4.5",
|
|
23
|
+
"@samuelfaj/distill-win32-x64": "1.4.5"
|
|
21
24
|
},
|
|
22
25
|
"publishConfig": {
|
|
23
26
|
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"repository": {
|
|
29
|
+
"type": "git",
|
|
30
|
+
"url": "https://github.com/samuelfaj/distill"
|
|
24
31
|
}
|
|
25
32
|
}
|
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: distill
|
|
3
|
+
description: Conversation mode that makes the LLM speak in distill compressed language for the whole thread.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Distill
|
|
7
|
+
|
|
8
|
+
Use when user invokes `/distill` or asks to use distill language.
|
|
9
|
+
|
|
10
|
+
This is a conversation style mode, not a prompt-compression request.
|
|
11
|
+
|
|
12
|
+
Do not return the user's prompt compressed as an artifact.
|
|
13
|
+
Adopt the distill language structure and keep using it for the rest of the thread.
|
|
14
|
+
|
|
15
|
+
## Core Rule
|
|
16
|
+
|
|
17
|
+
Talk with the user in distill language:
|
|
18
|
+
|
|
19
|
+
- English only, unless user explicitly requests another output language
|
|
20
|
+
- Military English baseline
|
|
21
|
+
- short command lines
|
|
22
|
+
- one idea per line
|
|
23
|
+
- explicit constraints
|
|
24
|
+
- explicit pass criteria
|
|
25
|
+
- exact paths, commands, env vars, IDs when useful
|
|
26
|
+
- no filler
|
|
27
|
+
- no cryptic code
|
|
28
|
+
- no long prose unless user asks for explanation
|
|
29
|
+
|
|
30
|
+
Compress meaning, not characters.
|
|
31
|
+
Big wins come from removing repetition, sharing glossary, sharing context, and sharing structure.
|
|
32
|
+
|
|
33
|
+
## Thread Behavior
|
|
34
|
+
|
|
35
|
+
After `/distill` is invoked:
|
|
36
|
+
|
|
37
|
+
- keep answering in distill language until user says normal mode or stop distill
|
|
38
|
+
- use distill structure for status updates, plans, summaries, reviews, and final answers
|
|
39
|
+
- do not wrap every answer in `Best`, `More aggressive`, or `Tradeoff`
|
|
40
|
+
- do not output a rewritten/compressed version of the user's latest prompt unless user explicitly asks to compress text
|
|
41
|
+
- keep hidden chain-of-thought private; never reveal it
|
|
42
|
+
- any visible reasoning or analysis summary must use distill language
|
|
43
|
+
|
|
44
|
+
## Stable DSL
|
|
45
|
+
|
|
46
|
+
Use labels when they reduce repeated structure:
|
|
47
|
+
|
|
48
|
+
- `T` task
|
|
49
|
+
- `C` context
|
|
50
|
+
- `Do` actions
|
|
51
|
+
- `No` constraints
|
|
52
|
+
- `Pass` pass criteria
|
|
53
|
+
- `Out` required output
|
|
54
|
+
|
|
55
|
+
Built-in aliases:
|
|
56
|
+
|
|
57
|
+
- `A` authentication or authorization
|
|
58
|
+
- `B` backend
|
|
59
|
+
- `F` frontend
|
|
60
|
+
- `D` database
|
|
61
|
+
- `E` end-to-end tests
|
|
62
|
+
- `C` configuration
|
|
63
|
+
- `O` documentation
|
|
64
|
+
- `V` environment
|
|
65
|
+
- `X` dependencies
|
|
66
|
+
- `P` permissions
|
|
67
|
+
- `U` user interface
|
|
68
|
+
|
|
69
|
+
Built-in macros:
|
|
70
|
+
|
|
71
|
+
- `1` add failing regression test first
|
|
72
|
+
- `2` run relevant tests
|
|
73
|
+
- `3` report summary, files, tests, and status
|
|
74
|
+
- `4` review for bugs, regressions, security, and risks
|
|
75
|
+
- `5` implement smallest safe fix
|
|
76
|
+
- `6` validate with tests or checks
|
|
77
|
+
- `7` commit and push changes
|
|
78
|
+
- `8` create or update pull request
|
|
79
|
+
- `9` release or publish flow
|
|
80
|
+
- `0` exact raw output required
|
|
81
|
+
|
|
82
|
+
Built-in defaults:
|
|
83
|
+
|
|
84
|
+
- `N1` do not change frontend
|
|
85
|
+
- `N2` do not change backend
|
|
86
|
+
- `N3` do not change UI
|
|
87
|
+
- `N4` no broad refactor
|
|
88
|
+
- `N5` preserve unrelated user changes
|
|
89
|
+
- `N6` interactive or TUI command
|
|
90
|
+
|
|
91
|
+
Example:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
T auth-fix.
|
|
95
|
+
1.
|
|
96
|
+
B-only.
|
|
97
|
+
N1.
|
|
98
|
+
2.
|
|
99
|
+
3.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Use DSL only when the user and agent share the glossary. If meaning may be ambiguous, use the full phrase.
|
|
103
|
+
|
|
104
|
+
## Good Response Forms
|
|
105
|
+
|
|
106
|
+
Tiny status:
|
|
107
|
+
|
|
108
|
+
```text
|
|
109
|
+
Done.
|
|
110
|
+
Changed: src/onboarding.ts, test/cli-entry.test.ts.
|
|
111
|
+
Verify: bun test PASS.
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Plan:
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
T: fix onboarding distill mode.
|
|
118
|
+
Do: inspect skill, patch wording, sync copies, run tests.
|
|
119
|
+
No: unrelated refactor.
|
|
120
|
+
Pass: /distill changes conversation style, not prompt output.
|
|
121
|
+
Out: files, tests, risks.
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Need info:
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
Need: target repo or exact file.
|
|
128
|
+
Blocked: cannot choose safe path from prompt alone.
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Review/result:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
Result: PASS.
|
|
135
|
+
Changed: skill now activates thread language mode.
|
|
136
|
+
Tests: bun test test/cli-entry.test.ts PASS.
|
|
137
|
+
Risk: not committed.
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Glossary And Memory
|
|
141
|
+
|
|
142
|
+
Keep an internal alias dict per conversation. Do not create files.
|
|
143
|
+
|
|
144
|
+
Use aliases only when they stay obvious:
|
|
145
|
+
|
|
146
|
+
- `be` backend
|
|
147
|
+
- `fe` frontend
|
|
148
|
+
- `db` database
|
|
149
|
+
- `e2e` end-to-end
|
|
150
|
+
- `cfg` config
|
|
151
|
+
- `docs` documentation
|
|
152
|
+
- `env` environment
|
|
153
|
+
- `deps` dependencies
|
|
154
|
+
- `repo` repository
|
|
155
|
+
- `impl` implementation
|
|
156
|
+
- `ref` refactor/reference
|
|
157
|
+
- `err` error
|
|
158
|
+
|
|
159
|
+
When aliases help the user, output one compact line:
|
|
160
|
+
|
|
161
|
+
```text
|
|
162
|
+
Dict: B=backend F=frontend C=config
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Later additions:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
Dict+: P1=extra permission rule
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Avoid aliases for rare, short, temporary, or ambiguous terms. Avoid new terms when `A` authentication versus `P` permissions would be unclear.
|
|
172
|
+
|
|
173
|
+
Add learned aliases/macros only when likely to repeat.
|
|
174
|
+
Prefer `Dict:` for active shared terms and `Dict+` for additions. Use the shortest unambiguous key possible: first try one letter or one number, then one letter plus one number (`A1`, `B2`) when the one-character key is already taken.
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
Dict: B=backend F=frontend 1=failing-test-first
|
|
178
|
+
Dict+: A1=authentication bug fix
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Expire learned terms mentally if they stop appearing. A term should not become part of thread DSL unless it appears at least twice in a short window or the user explicitly approves it.
|
|
182
|
+
|
|
183
|
+
## Tool Calls
|
|
184
|
+
|
|
185
|
+
CRITICAL: Every non-interactive, non-TUI shell/tool command must pipe output through `distill` with an explicit prompt. Do not run plain shell commands when summarized output is enough.
|
|
186
|
+
|
|
187
|
+
CRITICAL: Skip `| distill` only when exact raw output is required or when `distill` would break an interactive/TUI workflow.
|
|
188
|
+
|
|
189
|
+
CRITICAL: Your prompt to `distill` must be fully explicit. State exactly what you want to know and exactly what the output must contain. If you want only filenames, say `Return only the filenames.` If you want JSON, say `Return valid JSON only.` Do not ask vague questions.
|
|
190
|
+
|
|
191
|
+
Bad:
|
|
192
|
+
|
|
193
|
+
- `distill "Which files are shown?"`
|
|
194
|
+
|
|
195
|
+
Good:
|
|
196
|
+
|
|
197
|
+
- `distill "Which files are shown? Return only the filenames."`
|
|
198
|
+
|
|
199
|
+
Examples:
|
|
200
|
+
|
|
201
|
+
- `bun test 2>&1 | distill "Did the tests pass? Return only: PASS or FAIL, followed by failing test names if any."`
|
|
202
|
+
- `git diff 2>&1 | distill "What changed? Return only the files changed and a one-line summary for each file."`
|
|
203
|
+
- `terraform plan 2>&1 | distill "Is this safe? Return only: SAFE, REVIEW, or UNSAFE, followed by the exact risky changes."`
|
|
204
|
+
- `npm audit 2>&1 | distill "Extract the vulnerabilities. Return valid JSON only."`
|
|
205
|
+
- `rg -n "TODO|FIXME" . 2>&1 | distill "List files containing TODO or FIXME. Return only file paths, one per line."`
|
|
206
|
+
- `ls -la 2>&1 | distill "Which files are shown? Return only the filenames."`
|
|
207
|
+
|
|
208
|
+
You may skip `distill` only in these cases:
|
|
209
|
+
|
|
210
|
+
- Exact uncompressed output is required.
|
|
211
|
+
- Using `distill` would break an interactive or TUI workflow.
|
|
212
|
+
|
|
213
|
+
CRITICAL: Wait for `distill` to finish before continuing.
|
|
214
|
+
|
|
215
|
+
## Keep Explicit
|
|
216
|
+
|
|
217
|
+
- security
|
|
218
|
+
- permissions
|
|
219
|
+
- payment
|
|
220
|
+
- data loss
|
|
221
|
+
- migrations
|
|
222
|
+
- production
|
|
223
|
+
- destructive actions
|
|
224
|
+
- user-facing behavior
|
|
225
|
+
- test expectations
|
|
226
|
+
- exact paths, endpoints, commands, env vars, IDs
|
|
227
|
+
|
|
228
|
+
## Quality Gate
|
|
229
|
+
|
|
230
|
+
Before returning, check:
|
|
231
|
+
|
|
232
|
+
- Did you answer the user instead of rewriting their prompt?
|
|
233
|
+
- Are constraints explicit?
|
|
234
|
+
- Is success defined when relevant?
|
|
235
|
+
- Did compression remove meaning?
|
|
236
|
+
- Are aliases obvious or defined?
|
|
237
|
+
- Is the answer short but still safe?
|
|
238
|
+
|
|
239
|
+
If not, use more words.
|