drawbore 0.0.0-stage → 0.1.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/CHANGELOG.md +29 -0
- package/LICENSE +21 -0
- package/README.md +75 -2
- package/bin/drawbore.js +335 -0
- package/lib/checker.js +399 -0
- package/lib/index.js +16 -0
- package/lib/installer.js +405 -0
- package/lib/prompts.js +376 -0
- package/package.json +40 -3
- package/skills/discover/SKILL.md +77 -0
- package/skills/frame/SKILL.md +85 -0
- package/skills/frame/references/change-brief.md +55 -0
- package/skills/init-project/SKILL.md +86 -0
- package/skills/recall/SKILL.md +62 -0
- package/skills/record/SKILL.md +99 -0
- package/skills/record/references/artifact-formats.md +131 -0
- package/skills/release/SKILL.md +108 -0
- package/skills/review/SKILL.md +117 -0
- package/templates/instruction.md +9 -0
- package/templates/manifest.json +12 -0
- package/templates/record/context.md +14 -0
- package/templates/record/decisions/.gitkeep +0 -0
- package/templates/record/glossary.md +7 -0
- package/templates/record/index.md +16 -0
- package/templates/record/principles.md +3 -0
- package/templates/record/stack.md +7 -0
- package/templates/record/system.md +3 -0
- package/templates/record/work/.gitkeep +0 -0
package/lib/prompts.js
ADDED
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
// Prompt adapter for the Drawbore installer CLI.
|
|
2
|
+
//
|
|
3
|
+
// The installer supports two surfaces:
|
|
4
|
+
// - a real terminal, where @inquirer/prompts gives arrow-key multiselect
|
|
5
|
+
// checkboxes, confirmations with a stated default, and a spinner;
|
|
6
|
+
// - a non-TTY stream (pipes, CI, test harnesses), where a small readline
|
|
7
|
+
// fallback keeps the same questions answerable line by line.
|
|
8
|
+
//
|
|
9
|
+
// Both paths return the same values, so the install code never branches on how
|
|
10
|
+
// the answer was collected.
|
|
11
|
+
|
|
12
|
+
import { createInterface } from "node:readline";
|
|
13
|
+
|
|
14
|
+
import { installMarkerFile, notebookDirectory, supportedLocations } from "./installer.js";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Build location multiselect choices from a project inspection result.
|
|
18
|
+
*
|
|
19
|
+
* Nothing starts selected: the user must opt into each harness location
|
|
20
|
+
* explicitly. Each choice carries a short state hint (already installed /
|
|
21
|
+
* instruction already present / not installed).
|
|
22
|
+
*
|
|
23
|
+
* @param {{ locations: Array<{ path: string, instructionName: string, instructionExists: boolean, skillsExist: boolean }> }} project
|
|
24
|
+
*/
|
|
25
|
+
export function buildLocationChoices(project) {
|
|
26
|
+
return project.locations.map((location) => {
|
|
27
|
+
const state = location.skillsExist
|
|
28
|
+
? "already installed"
|
|
29
|
+
: location.instructionExists
|
|
30
|
+
? "instruction already present"
|
|
31
|
+
: "not installed";
|
|
32
|
+
return {
|
|
33
|
+
name: `${location.path} — ${state}`,
|
|
34
|
+
value: location.path,
|
|
35
|
+
checked: false,
|
|
36
|
+
};
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Build checkbox choices for always-read instruction files. Values are the
|
|
42
|
+
* instruction target file names; every choice starts checked.
|
|
43
|
+
*
|
|
44
|
+
* @param {Array<{ instructionFile: string, exists?: boolean }>} targets
|
|
45
|
+
*/
|
|
46
|
+
export function buildInstructionChoices(targets) {
|
|
47
|
+
return targets.map((target) => ({
|
|
48
|
+
name: `${target.instructionFile}${target.exists ? " — already exists" : " — will be created"}`,
|
|
49
|
+
value: target.instructionFile,
|
|
50
|
+
checked: true,
|
|
51
|
+
}));
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Create the UI adapter for this process.
|
|
56
|
+
*
|
|
57
|
+
* `isTTY` is an explicit parameter (not read from process) so tests and
|
|
58
|
+
* non-TTY harnesses can force the readline fallback path. An explicit `false`
|
|
59
|
+
* always selects the fallback; an explicit `true` requires usable streams.
|
|
60
|
+
*
|
|
61
|
+
* @param {{ isTTY?: boolean, stdin?: unknown, stdout?: unknown, stderr?: unknown, prompts?: object }} [options]
|
|
62
|
+
*/
|
|
63
|
+
export function createUi({ isTTY, stdin, stdout, stderr, prompts } = {}) {
|
|
64
|
+
const input = stdin ?? process.stdin;
|
|
65
|
+
const output = stdout ?? process.stdout;
|
|
66
|
+
const errorOutput = stderr ?? process.stderr;
|
|
67
|
+
const interactive = isTTY ?? (Boolean(input.isTTY) && Boolean(output.isTTY));
|
|
68
|
+
|
|
69
|
+
if (interactive) {
|
|
70
|
+
return createTtyUi({ stdin: input, stdout: output, stderr: errorOutput, prompts });
|
|
71
|
+
}
|
|
72
|
+
return createFallbackUi({ stdin: input, stdout: output, stderr: errorOutput });
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// ---------------------------------------------------------------------------
|
|
76
|
+
// TTY path (@inquirer/prompts)
|
|
77
|
+
// ---------------------------------------------------------------------------
|
|
78
|
+
|
|
79
|
+
function createTtyUi({ stdin, stdout, stderr, prompts }) {
|
|
80
|
+
// One shared loader keeps the dynamic import — and its error translation —
|
|
81
|
+
// in exactly one place. Inquirer writes prompts to stderr by default; the
|
|
82
|
+
// explicit streams keep the banner (stdout) and prompts (stderr)
|
|
83
|
+
// separable and testable. `prompts` may be injected for tests.
|
|
84
|
+
async function load() {
|
|
85
|
+
if (prompts) return prompts;
|
|
86
|
+
try {
|
|
87
|
+
return await import("@inquirer/prompts");
|
|
88
|
+
} catch (error) {
|
|
89
|
+
throw new Error(
|
|
90
|
+
`Interactive prompts unavailable (${error.message}). ` +
|
|
91
|
+
`Run with explicit flags instead: drawbore init --location .agents --notebook --instruction AGENTS.md`,
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function handlePromptError(error) {
|
|
97
|
+
if (error?.name === "ExitPromptError") {
|
|
98
|
+
console.error("Installation cancelled. Nothing was installed.");
|
|
99
|
+
process.exit(0);
|
|
100
|
+
}
|
|
101
|
+
throw error instanceof Error ? error : new Error(String(error));
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// Hint shown in every prompt message: Ctrl+C (and Ctrl+D) abort via the
|
|
105
|
+
// prompts' built-in ExitPromptError handling above. Inquirer reserves
|
|
106
|
+
// Ctrl+* for its own shortcuts, so a custom "press q to cancel" key
|
|
107
|
+
// cannot coexist with it — Ctrl+C is the cancel key.
|
|
108
|
+
const CANCEL_HINT = "(Ctrl+C to cancel)";
|
|
109
|
+
|
|
110
|
+
async function selectLocations(choices) {
|
|
111
|
+
if (choices.length === 0) {
|
|
112
|
+
return [];
|
|
113
|
+
}
|
|
114
|
+
try {
|
|
115
|
+
// @inquirer/prompts has no `multiselect` export — the multi-select
|
|
116
|
+
// component is `checkbox`. Using a non-existent name crashes the run.
|
|
117
|
+
const { checkbox } = await load();
|
|
118
|
+
return await checkbox({
|
|
119
|
+
message: `Which harness locations should receive the Drawbore skills? ${CANCEL_HINT}`,
|
|
120
|
+
choices,
|
|
121
|
+
pageSize: Math.max(4, choices.length),
|
|
122
|
+
input: stdin,
|
|
123
|
+
output: stderr,
|
|
124
|
+
});
|
|
125
|
+
} catch (error) {
|
|
126
|
+
handlePromptError(error);
|
|
127
|
+
}
|
|
128
|
+
return [];
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
async function selectInstructions(choices) {
|
|
132
|
+
if (choices.length === 0) {
|
|
133
|
+
return [];
|
|
134
|
+
}
|
|
135
|
+
try {
|
|
136
|
+
const { checkbox } = await load();
|
|
137
|
+
return await checkbox({
|
|
138
|
+
message: `Which instruction files should get the always-on Drawbore guidance? ${CANCEL_HINT}`,
|
|
139
|
+
choices,
|
|
140
|
+
pageSize: Math.max(4, choices.length),
|
|
141
|
+
input: stdin,
|
|
142
|
+
output: stderr,
|
|
143
|
+
});
|
|
144
|
+
} catch (error) {
|
|
145
|
+
handlePromptError(error);
|
|
146
|
+
}
|
|
147
|
+
return [];
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
async function confirm({ message, defaultValue }) {
|
|
151
|
+
try {
|
|
152
|
+
const { confirm: promptConfirm } = await load();
|
|
153
|
+
return Boolean(
|
|
154
|
+
await promptConfirm({
|
|
155
|
+
message: `${message} ${CANCEL_HINT}`,
|
|
156
|
+
default: defaultValue ?? true,
|
|
157
|
+
input: stdin,
|
|
158
|
+
output: stderr,
|
|
159
|
+
}),
|
|
160
|
+
);
|
|
161
|
+
} catch (error) {
|
|
162
|
+
handlePromptError(error);
|
|
163
|
+
}
|
|
164
|
+
return false;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
return {
|
|
168
|
+
isInteractive: true,
|
|
169
|
+
renderProjectState: () => {},
|
|
170
|
+
selectLocations,
|
|
171
|
+
selectInstructions,
|
|
172
|
+
confirm,
|
|
173
|
+
startSpinner: (message) => createSpinner({ message, stderr }),
|
|
174
|
+
close: () => {},
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
// ---------------------------------------------------------------------------
|
|
179
|
+
// Fallback path (readline, piped stdin/stdout)
|
|
180
|
+
// ---------------------------------------------------------------------------
|
|
181
|
+
|
|
182
|
+
function createFallbackUi({ stdin, stdout }) {
|
|
183
|
+
const rl = createInterface({ input: stdin, output: stdout });
|
|
184
|
+
const queue = [];
|
|
185
|
+
const waiters = [];
|
|
186
|
+
let closed = false;
|
|
187
|
+
|
|
188
|
+
rl.on("line", (line) => {
|
|
189
|
+
if (waiters.length > 0) {
|
|
190
|
+
waiters.shift()(line);
|
|
191
|
+
} else {
|
|
192
|
+
queue.push(line);
|
|
193
|
+
}
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
rl.on("close", () => {
|
|
197
|
+
closed = true;
|
|
198
|
+
while (waiters.length > 0) {
|
|
199
|
+
waiters.shift()("");
|
|
200
|
+
}
|
|
201
|
+
});
|
|
202
|
+
|
|
203
|
+
function ask(question) {
|
|
204
|
+
stdout.write(question);
|
|
205
|
+
if (queue.length > 0) {
|
|
206
|
+
return Promise.resolve(queue.shift());
|
|
207
|
+
}
|
|
208
|
+
if (closed) {
|
|
209
|
+
return Promise.resolve("");
|
|
210
|
+
}
|
|
211
|
+
return new Promise((resolve) => waiters.push(resolve));
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function isDefaultYes(answer) {
|
|
215
|
+
const normalized = answer.trim().toLowerCase();
|
|
216
|
+
return normalized === "" || ["y", "yes"].includes(normalized);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
async function confirm({ message, defaultValue }) {
|
|
220
|
+
const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
|
|
221
|
+
const answer = await ask(`${message}${suffix}`);
|
|
222
|
+
const normalized = answer.trim().toLowerCase();
|
|
223
|
+
if (isCancelKeyword(normalized)) {
|
|
224
|
+
console.log("Installation cancelled. Nothing was installed.");
|
|
225
|
+
process.exit(0);
|
|
226
|
+
}
|
|
227
|
+
if (normalized === "") {
|
|
228
|
+
return Boolean(defaultValue);
|
|
229
|
+
}
|
|
230
|
+
return ["y", "yes"].includes(normalized);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
async function selectLocations(choices) {
|
|
234
|
+
const answer = await ask(
|
|
235
|
+
'Install skills into which locations? Comma-separated, or "none" [none]: ',
|
|
236
|
+
);
|
|
237
|
+
|
|
238
|
+
const requested = answer
|
|
239
|
+
.split(",")
|
|
240
|
+
.map((value) => value.trim())
|
|
241
|
+
.filter(Boolean)
|
|
242
|
+
.filter((value) => value !== "none");
|
|
243
|
+
|
|
244
|
+
if (requested.some(isCancelKeyword)) {
|
|
245
|
+
console.log("Installation cancelled. Nothing was installed.");
|
|
246
|
+
process.exit(0);
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
const offered = new Set(choices.map((choice) => choice.value));
|
|
250
|
+
const allowed = offered.size > 0 ? offered : new Set(Object.keys(supportedLocations));
|
|
251
|
+
const invalid = requested.filter((location) => !allowed.has(location));
|
|
252
|
+
if (invalid.length > 0) {
|
|
253
|
+
throw new Error(`Unsupported location(s): ${invalid.join(", ")}`);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
return [...new Set(requested)];
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
async function selectInstructions(choices) {
|
|
260
|
+
if (choices.length === 0) {
|
|
261
|
+
return [];
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
const selected = [];
|
|
265
|
+
for (const choice of choices) {
|
|
266
|
+
const preserved = choice.name.includes("already exists") ? " The existing file will be preserved." : "";
|
|
267
|
+
const answer = await ask(
|
|
268
|
+
`Add the always-on Drawbore instruction to ${choice.value}?${preserved} [Y/n] `,
|
|
269
|
+
);
|
|
270
|
+
if (isCancelKeyword(answer.trim().toLowerCase())) {
|
|
271
|
+
console.log("Installation cancelled. Nothing was installed.");
|
|
272
|
+
process.exit(0);
|
|
273
|
+
}
|
|
274
|
+
if (isDefaultYes(answer)) {
|
|
275
|
+
selected.push(choice.value);
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
return selected;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
function isCancelKeyword(normalized) {
|
|
282
|
+
return ["cancel", "q", "esc", "back"].includes(normalized);
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
return {
|
|
286
|
+
isInteractive: false,
|
|
287
|
+
renderProjectState: (project) => {
|
|
288
|
+
console.log("\nSupported harness locations:");
|
|
289
|
+
for (const location of project.locations) {
|
|
290
|
+
const state = location.skillsExist ? "skills already present" : "not installed";
|
|
291
|
+
const instruction = location.instructionExists ? "instruction exists" : "instruction absent";
|
|
292
|
+
console.log(`- ${location.path} (${state}; ${instruction})`);
|
|
293
|
+
}
|
|
294
|
+
},
|
|
295
|
+
selectLocations,
|
|
296
|
+
selectInstructions,
|
|
297
|
+
confirm,
|
|
298
|
+
startSpinner: () => () => {},
|
|
299
|
+
close() {
|
|
300
|
+
rl.close();
|
|
301
|
+
},
|
|
302
|
+
};
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
// ---------------------------------------------------------------------------
|
|
306
|
+
// Spinner
|
|
307
|
+
// ---------------------------------------------------------------------------
|
|
308
|
+
|
|
309
|
+
const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
|
|
310
|
+
|
|
311
|
+
// Spinner lives on stderr (stdout is reserved for the machine-readable
|
|
312
|
+
// result) and only animates when stderr is a TTY; otherwise it is a no-op so
|
|
313
|
+
// pipes never see half-overwritten lines. The stop function clears the line.
|
|
314
|
+
export function createSpinner({ message, stderr }) {
|
|
315
|
+
if (!stderr.isTTY) {
|
|
316
|
+
return () => {};
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
let frame = 0;
|
|
320
|
+
let active = true;
|
|
321
|
+
const tick = () => {
|
|
322
|
+
if (!active) return;
|
|
323
|
+
stderr.write(`\r${SPINNER_FRAMES[frame % SPINNER_FRAMES.length]} ${message}`);
|
|
324
|
+
frame += 1;
|
|
325
|
+
};
|
|
326
|
+
tick();
|
|
327
|
+
const timer = setInterval(tick, 80);
|
|
328
|
+
timer.unref();
|
|
329
|
+
|
|
330
|
+
return () => {
|
|
331
|
+
active = false;
|
|
332
|
+
clearInterval(timer);
|
|
333
|
+
stderr.write("\r");
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Render the final "Installed:" summary block. Used by both paths so the
|
|
339
|
+
* result text stays byte-identical for non-TTY consumers.
|
|
340
|
+
*/
|
|
341
|
+
export function formatInstallResult(
|
|
342
|
+
selectedLocations,
|
|
343
|
+
notebookCreated,
|
|
344
|
+
instructionFiles,
|
|
345
|
+
preservedSkillFiles = [],
|
|
346
|
+
replacedSkillFiles = [],
|
|
347
|
+
) {
|
|
348
|
+
const lines = ["Installed:"];
|
|
349
|
+
for (const location of selectedLocations) {
|
|
350
|
+
lines.push(`- skills: ${location}/skills/`);
|
|
351
|
+
}
|
|
352
|
+
if (notebookCreated) {
|
|
353
|
+
lines.push(`- notebook: ${notebookDirectory}/`);
|
|
354
|
+
}
|
|
355
|
+
for (const instructionFile of [...new Set(instructionFiles)]) {
|
|
356
|
+
lines.push(`- instruction: ${instructionFile}`);
|
|
357
|
+
}
|
|
358
|
+
lines.push(`- marker: ${installMarkerFile}`);
|
|
359
|
+
if (replacedSkillFiles.length > 0) {
|
|
360
|
+
lines.push("");
|
|
361
|
+
lines.push("Replaced packaged skill files:");
|
|
362
|
+
for (const file of [...new Set(replacedSkillFiles)]) {
|
|
363
|
+
lines.push(`- ${file}`);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
if (preservedSkillFiles.length > 0) {
|
|
367
|
+
lines.push("");
|
|
368
|
+
lines.push("Preserved existing differing skill files:");
|
|
369
|
+
for (const file of [...new Set(preservedSkillFiles)]) {
|
|
370
|
+
lines.push(`- ${file}`);
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
lines.push("");
|
|
374
|
+
lines.push("Run the discover skill in your agent to propose the first durable records.");
|
|
375
|
+
return lines.join("\n");
|
|
376
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "drawbore",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "You code. It holds. Durable project context, principles, and portable skills for AI-assisted software development.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"bin": {
|
|
8
|
+
"drawbore": "bin/drawbore.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"bin",
|
|
12
|
+
"lib",
|
|
13
|
+
"skills",
|
|
14
|
+
"templates",
|
|
15
|
+
"README.md",
|
|
16
|
+
"LICENSE",
|
|
17
|
+
"CHANGELOG.md"
|
|
18
|
+
],
|
|
19
|
+
"keywords": [
|
|
20
|
+
"agent-skills",
|
|
21
|
+
"ai",
|
|
22
|
+
"durable-context",
|
|
23
|
+
"workflow",
|
|
24
|
+
"workflow-enhancement"
|
|
25
|
+
],
|
|
26
|
+
"scripts": {
|
|
27
|
+
"test": "node --test"
|
|
28
|
+
},
|
|
29
|
+
"dependencies": {
|
|
30
|
+
"@inquirer/prompts": "^8.7.5"
|
|
31
|
+
},
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://gitlab.com/abmach/drawbore.git"
|
|
35
|
+
},
|
|
36
|
+
"bugs": {
|
|
37
|
+
"url": "https://gitlab.com/abmach/drawbore/-/issues"
|
|
38
|
+
},
|
|
39
|
+
"author": "Arthur Biazon Machado",
|
|
40
|
+
"engines": {
|
|
41
|
+
"node": ">=20"
|
|
42
|
+
}
|
|
6
43
|
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: discover
|
|
3
|
+
description: Use this skill when adopting Drawbore in an existing repository or refreshing its initial durable context. It analyzes repository structure, terminology, conventions, current behavior, technical choices, and history, then proposes evidence-backed glossary, context, principle, decision, system, and stack records for developer confirmation.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Discover project context
|
|
8
|
+
|
|
9
|
+
Build an accurate, minimal starting point for the project's durable context. Discovery proposes; the developer confirms.
|
|
10
|
+
|
|
11
|
+
## Inspect the project
|
|
12
|
+
|
|
13
|
+
1. Resolve the project root. Prefer the version-control repository root; otherwise use the current working directory.
|
|
14
|
+
2. Read existing guidance and documentation before proposing duplicates: `AGENTS.md`, `CLAUDE.md`, `README.md`, architecture documents, contribution guides, API documentation, and existing records.
|
|
15
|
+
3. Inspect source structure and representative code. Use configuration and lockfiles to identify the current stack.
|
|
16
|
+
4. Inspect relevant history for decisions that would surprise a future contributor, but do not invent rationale from commit messages alone.
|
|
17
|
+
5. Identify existing issue-tracking configuration only as environment evidence; do not add tracker configuration to the record.
|
|
18
|
+
|
|
19
|
+
## Propose a minimal set
|
|
20
|
+
|
|
21
|
+
Consider these durable artifacts, but create only those with confirmed content:
|
|
22
|
+
|
|
23
|
+
- `context.md` — purpose, scope, architecture, and relationships;
|
|
24
|
+
- `glossary.md` — project-specific canonical terms;
|
|
25
|
+
- `principles.md` — load-bearing rules visible in code or confirmed by the developer;
|
|
26
|
+
- `decisions/` — consequential choices supported by evidence or explicit developer confirmation;
|
|
27
|
+
- `system.md` — current user-visible capabilities and contracts;
|
|
28
|
+
- `stack.md` — current project-specific technical choices and architecture.
|
|
29
|
+
|
|
30
|
+
Do not seed generic technology preferences, testing doctrine, or design doctrine. The repository's actual choices are authoritative. Propose a rule only when project-specific evidence supports it.
|
|
31
|
+
|
|
32
|
+
## Confirm candidates in batches
|
|
33
|
+
|
|
34
|
+
Before proposing, read `.drawbore/index.md` and every existing record that could cover a candidate. Search by project concept, not only by the proposed filename, and identify the exact existing entry to amend or state that no equivalent entry exists. Do not propose a duplicate when an existing record owns the fact.
|
|
35
|
+
|
|
36
|
+
Present candidates with evidence and a concrete destination. Use these options:
|
|
37
|
+
|
|
38
|
+
- **apply as proposed**;
|
|
39
|
+
- **edit** the developer's wording;
|
|
40
|
+
- **skip**;
|
|
41
|
+
- **skip the remaining candidates** for that artifact.
|
|
42
|
+
|
|
43
|
+
Then wait for the developer's response. **Apply as proposed** approves exactly the displayed proposal; **edit** requires revised wording to be displayed and approved; **skip** changes nothing. Prefer the developer's exact wording. Mark inferred rationale as inferred. Never write, overwrite, amend, or delete an unconfirmed candidate.
|
|
44
|
+
|
|
45
|
+
## Create the record
|
|
46
|
+
|
|
47
|
+
After confirmation:
|
|
48
|
+
|
|
49
|
+
1. Create missing artifacts for confirmed candidates and apply only the confirmed amendments to existing artifacts.
|
|
50
|
+
2. Use the formats defined by the `record` skill, including its one-owner-per-fact and amendment rules.
|
|
51
|
+
3. Create or update `.drawbore/index.md` only as needed to map the confirmed records accurately.
|
|
52
|
+
4. Do not create empty `work/` or `decisions/` directories unless confirmed content requires them.
|
|
53
|
+
5. Preserve every pre-existing record file and directory unless the developer explicitly approves deleting that exact path.
|
|
54
|
+
6. Treat dependent edits—such as a decision, an affected current-truth artifact, and an index correction—as one atomic proposal: apply all or none.
|
|
55
|
+
7. Report what was created, what was skipped, what was preserved, and any unresolved disagreement.
|
|
56
|
+
|
|
57
|
+
Skipping a candidate means leaving the existing path unchanged, not deleting it. An empty or placeholder file is still an existing path. For example, do not delete `glossary.md` merely because no glossary candidate was confirmed.
|
|
58
|
+
|
|
59
|
+
## Refresh safely
|
|
60
|
+
|
|
61
|
+
If `.drawbore/` already exists:
|
|
62
|
+
|
|
63
|
+
1. Inventory the existing record paths and read them before scanning.
|
|
64
|
+
2. Identify missing, contradictory, or stale content. Treat **empty** as a content state, not as permission to delete a path.
|
|
65
|
+
3. Propose additions or amendments with evidence and show the exact resulting entry or path.
|
|
66
|
+
4. Do not overwrite, amend, or delete confirmed records without explicit developer approval of the displayed proposal.
|
|
67
|
+
5. Do not delete an existing record or directory during discovery or refresh. Deletion requires a separate explicit proposal that names the exact path and reason, followed by explicit developer approval.
|
|
68
|
+
6. Do not settle or remove transient Change Briefs during discovery. Use the `frame` and `record` skills for that workflow; preserve `work/` and its briefs here.
|
|
69
|
+
7. After applying approved additions and amendments, run `drawbore check` on the record. Fold any error it reports into a further proposal; do not report the refresh as complete while a structural error remains.
|
|
70
|
+
|
|
71
|
+
## Boundaries
|
|
72
|
+
|
|
73
|
+
- Do not infer durable project truth from generic framework conventions.
|
|
74
|
+
- Do not create milestones, plans, issues, or execution state.
|
|
75
|
+
- Do not assume an external tracker platform.
|
|
76
|
+
- Do not create empty records merely to complete the taxonomy.
|
|
77
|
+
- Do not delete or rename pre-existing record paths because they are empty, skipped, placeholder-only, or not part of the proposed refresh.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frame
|
|
3
|
+
description: Use this skill when a feature request, bug fix, refactor, or technical change needs brainstorming or a materially clearer scope before implementation. It collaborates with the developer to define purpose, inclusions, non-goals, change points, acceptance conditions, open questions, and consequences, then maintains a transient Change Brief.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Frame the change
|
|
8
|
+
|
|
9
|
+
Collaborate with the developer until the intended change is clear enough to implement. This skill shapes scope; it does not orchestrate execution.
|
|
10
|
+
|
|
11
|
+
## Choose whether scope work is needed
|
|
12
|
+
|
|
13
|
+
Use scope work when at least one material uncertainty remains:
|
|
14
|
+
|
|
15
|
+
- the purpose or desired outcome is unclear;
|
|
16
|
+
- more than one plausible interpretation would produce different behavior;
|
|
17
|
+
- the boundary between in-scope and out-of-scope work is unclear;
|
|
18
|
+
- a change point or affected contract is unknown;
|
|
19
|
+
- acceptance cannot be stated observably;
|
|
20
|
+
- the request conflicts with recorded project context.
|
|
21
|
+
|
|
22
|
+
Do not use scope work for a straightforward, well-bounded change whose answers are available in the repository.
|
|
23
|
+
|
|
24
|
+
## Establish shared understanding
|
|
25
|
+
|
|
26
|
+
1. Read `.drawbore/index.md` and the relevant context, glossary, principles, decisions, current behavior, and active Change Briefs.
|
|
27
|
+
2. Inspect the repository before asking questions it can answer.
|
|
28
|
+
3. Restate the likely purpose and intended outcome in plain language.
|
|
29
|
+
4. Ask only questions whose answers affect scope, behavior, boundaries, or acceptance. Prefer a small number of concrete questions over an exhaustive interview.
|
|
30
|
+
5. Probe meaningful alternatives and edge cases only where they could change the implementation.
|
|
31
|
+
6. Separate confirmed facts from assumptions and open questions.
|
|
32
|
+
|
|
33
|
+
## Maintain a Change Brief
|
|
34
|
+
|
|
35
|
+
Store a Change Brief in `.drawbore/work/` while the work is being shaped or implemented. Use a descriptive kebab-case filename, for example `add-user-imports.md`.
|
|
36
|
+
|
|
37
|
+
Maintain one canonical brief per logical change. Before creating or writing a brief, inspect `.drawbore/work/` for a brief describing the same change and update it in place. Create a separate brief only for a distinct change. Never overwrite an existing brief; if a filename collides with distinct work, choose a distinct kebab-case filename.
|
|
38
|
+
|
|
39
|
+
Follow [the Change Brief format](references/change-brief.md). A brief is transient working context, not a milestone plan or an execution registry.
|
|
40
|
+
|
|
41
|
+
Update the canonical brief whenever a material scope, assumption, acceptance, change-point, or decision changes. Keep `Acceptance` synchronized with the agreed behavior. Do not rely on the conversation or an earlier revision as the current brief.
|
|
42
|
+
|
|
43
|
+
Treat a brief as active while its file remains in `.drawbore/work/`. It is terminal only through explicit settlement or cancellation. For cancelled or superseded work, propose any still-durable consequences and the removal of the obsolete brief together. Remove it only after the developer explicitly approves that removal; otherwise keep it as active guidance.
|
|
44
|
+
|
|
45
|
+
Treat `work/` as tracked by default, but do not add it wholesale to an ignore file. Commit a brief only when it must remain available across sessions or to other agents and the developer explicitly consents to that commit. Ignore a specific brief only when it is intentionally private or local; before sharing that work, remove its ignore rule and ask the developer to commit the required brief.
|
|
46
|
+
|
|
47
|
+
## Define change points
|
|
48
|
+
|
|
49
|
+
A **change point** is a place where the implementation can affect established project truth or behavior. Include only applicable points:
|
|
50
|
+
|
|
51
|
+
- user-visible workflow or interface;
|
|
52
|
+
- domain rule or invariant;
|
|
53
|
+
- public or internal contract;
|
|
54
|
+
- data shape, ownership, or migration;
|
|
55
|
+
- integration boundary or external dependency;
|
|
56
|
+
- configuration, runtime, deployment, or operational behavior;
|
|
57
|
+
- documentation, terminology, glossary, or principle;
|
|
58
|
+
- test and verification surface.
|
|
59
|
+
|
|
60
|
+
For each change point, identify the affected area and the expected consequence. Do not prescribe implementation steps or milestones.
|
|
61
|
+
|
|
62
|
+
## Settle the work
|
|
63
|
+
|
|
64
|
+
"Scope agreed" ends clarification but does not settle the work. Settle only after the implementation is complete and every acceptance condition has been checked against the implemented behavior and passes.
|
|
65
|
+
|
|
66
|
+
1. Resolve each open question, or explicitly mark it irrelevant to the final scope. Any unresolved question that could affect implementation blocks settlement.
|
|
67
|
+
2. Resolve or remove every assumption before settlement.
|
|
68
|
+
3. Promote durable consequences into the appropriate records through the `record` skill:
|
|
69
|
+
- project vocabulary → glossary;
|
|
70
|
+
- purpose, scope boundaries, and domain relationships → context;
|
|
71
|
+
- enduring constraints → principles;
|
|
72
|
+
- choices that should affect future work → decisions;
|
|
73
|
+
- shipped capabilities and contracts → system behavior;
|
|
74
|
+
- current technical choices → stack.
|
|
75
|
+
4. Ensure the brief contains no unique durable rationale that was not promoted.
|
|
76
|
+
5. Remove the brief only after every proposed durable update has been applied and written successfully. If an update is skipped or pending, keep the brief and state what remains.
|
|
77
|
+
6. Remove only the exact settled brief file from `.drawbore/work/`, but keep the `work/` directory.
|
|
78
|
+
7. Do not create a settled-work archive. If the brief was committed, version-control history preserves it.
|
|
79
|
+
|
|
80
|
+
## Boundaries
|
|
81
|
+
|
|
82
|
+
- Do not create milestones, dependencies, task assignments, retries, or approval gates.
|
|
83
|
+
- Do not write code while clarifying scope.
|
|
84
|
+
- Do not turn implementation preferences into project-wide principles.
|
|
85
|
+
- Do not assume where external issues are tracked.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Change Brief format
|
|
2
|
+
|
|
3
|
+
A Change Brief captures shared understanding while scope is being shaped or implemented. It lives at `.drawbore/work/<descriptive-kebab-case-name>.md`.
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
# <Feature or bug title>
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
Why this change exists and the outcome it should produce.
|
|
11
|
+
|
|
12
|
+
## Scope
|
|
13
|
+
|
|
14
|
+
- <included behavior, change, or boundary>
|
|
15
|
+
|
|
16
|
+
## Non-goals
|
|
17
|
+
|
|
18
|
+
- <explicitly excluded work>
|
|
19
|
+
|
|
20
|
+
## Change points
|
|
21
|
+
|
|
22
|
+
- **<Area or contract>** — <expected consequence>
|
|
23
|
+
|
|
24
|
+
## Acceptance
|
|
25
|
+
|
|
26
|
+
- <observable condition that establishes completion>
|
|
27
|
+
|
|
28
|
+
## Assumptions
|
|
29
|
+
|
|
30
|
+
- <unconfirmed assumption, or omit this section when empty>
|
|
31
|
+
|
|
32
|
+
## Open questions
|
|
33
|
+
|
|
34
|
+
- <unresolved question, or "None">
|
|
35
|
+
|
|
36
|
+
## Decisions
|
|
37
|
+
|
|
38
|
+
- <durable choice made while shaping this work, with a link when captured>
|
|
39
|
+
|
|
40
|
+
## Outcome
|
|
41
|
+
|
|
42
|
+
<Final scope and the durable context records produced by the work.>
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Rules
|
|
46
|
+
|
|
47
|
+
- Use only sections that carry useful information; omit `Non-goals`, `Assumptions`, `Open questions`, or `Decisions` when empty and not yet needed.
|
|
48
|
+
- Put only unconfirmed assumptions in `Assumptions`; do not state them as agreed scope. Resolve or remove every assumption before settlement.
|
|
49
|
+
- State acceptance as observable outcomes, not implementation steps.
|
|
50
|
+
- Keep acceptance synchronized with the agreed behavior whenever scope changes.
|
|
51
|
+
- Record change points, not tasks.
|
|
52
|
+
- Keep implementation detail in the repository and current task, not in the brief.
|
|
53
|
+
- Record a durable decision here only as a link to its canonical decision record once captured; do not maintain a second copy.
|
|
54
|
+
- `Outcome` is settlement-only. Omit it while the brief is active and write it only after acceptance passes, immediately before applying the promotion and removal steps.
|
|
55
|
+
- Keep the brief transient. When work settles, promote durable consequences and remove the brief.
|