drawbore 0.0.0-stage → 0.1.0
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 +21 -0
- package/LICENSE +21 -0
- package/README.md +76 -3
- package/bin/drawbore.js +267 -0
- package/lib/checker.js +399 -0
- package/lib/index.js +14 -0
- package/lib/installer.js +405 -0
- package/lib/prompts.js +374 -0
- package/package.json +42 -5
- 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/CHANGELOG.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Consent-aware installer for `.agents`, `.claude`, `.codex`, `.cursor`, `.omp`, and `.opencode`.
|
|
13
|
+
- `.drawbore/` notebook templates and a structural checker.
|
|
14
|
+
- `drawbore init` and `drawbore check` CLI commands.
|
|
15
|
+
- Seven portable skills: `discover`, `recall`, `frame`, `record`, `review`, `init-project`, and `release`.
|
|
16
|
+
- `init-project` generates a release pipeline from the project's answers — publish mode, build steps, and provider — instead of copying a template, and records the result in the root `AGENTS.md` under `publish mode` and `pipeline`.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- Skill conflicts are decided by content rather than by name. A skill directory is foreign only when its contents diverge from what the package ships; a file/directory mismatch is preserved instead of blocking the install.
|
|
21
|
+
- `release` branches on `publish mode` and `pipeline`, reading them from `AGENTS.md`. Sections written before those fields existed are still handled: the mode is inferred from the prose and the CI file, and the package field is read as either `package` or `npm package`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arthur Biazon Machado
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,76 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# Drawbore
|
|
2
|
+
|
|
3
|
+
[](https://gitlab.com/abmach/drawbore/-/pipelines)
|
|
4
|
+
|
|
5
|
+
**You code. It holds.**
|
|
6
|
+
|
|
7
|
+
Durable context for AI-assisted software development.
|
|
8
|
+
|
|
9
|
+
Drawbore adds repository-aware context, engineering rules, and portable agent workflows on top of the repository and harness you already use. It adapts to the project rather than replacing the agent, the harness, or the repository’s own structure.
|
|
10
|
+
|
|
11
|
+
## Status
|
|
12
|
+
|
|
13
|
+
The installer, notebook templates, structural checker, and portable skills are implemented.
|
|
14
|
+
|
|
15
|
+
## What it provides
|
|
16
|
+
|
|
17
|
+
- **Durable context** — a `.drawbore/` containing purpose, scope, architecture, glossary, principles, decisions, current behavior, and technical choices.
|
|
18
|
+
- **Portable skills** — `discover`, `recall`, `frame`, `record`, `review`, `init-project`, and `release`.
|
|
19
|
+
- **Structural checks** — duplicate decision IDs, broken supersession, invalid records, missing headings, and stale-candidate warnings.
|
|
20
|
+
- **Consent-aware installation** — no file is overwritten without an explicit choice; locally modified skills are preserved.
|
|
21
|
+
- **Provider-neutral operation** — no forge, registry, or CI provider is assumed.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
npx drawbore init
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The installer asks which harness locations should receive the skills, whether to create `.drawbore/`, and which instruction file should carry the Drawbore block. In non-interactive environments, use explicit flags:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
npx drawbore init --location .agents --notebook --instruction AGENTS.md --yes
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Supported locations
|
|
36
|
+
|
|
37
|
+
`.agents`, `.claude`, `.codex`, `.cursor`, `.omp`, `.opencode`
|
|
38
|
+
|
|
39
|
+
Each location receives its skills under `<location>/skills/`. The instruction file is selected from `AGENTS.md` or `CLAUDE.md`.
|
|
40
|
+
|
|
41
|
+
## Check the notebook
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
npx drawbore check
|
|
45
|
+
npx drawbore check --json
|
|
46
|
+
npx drawbore check --fix
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`check` is read-only unless `--fix` is passed. `--fix` only aligns decision IDs to filenames and renumbers duplicates; it never rewrites record bodies.
|
|
50
|
+
|
|
51
|
+
## Skills
|
|
52
|
+
|
|
53
|
+
| Skill | Role |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `discover` | Analyze an existing repository and propose its initial durable context |
|
|
56
|
+
| `recall` | Consult durable context before work and reconcile the implementation afterward |
|
|
57
|
+
| `frame` | Shape scope and maintain a Change Brief before implementation |
|
|
58
|
+
| `record` | Record confirmed terms, principles, decisions, behavior, and technical choices |
|
|
59
|
+
| `review` | Analyze a repository and propose a ranked plan, then implement only the approved items |
|
|
60
|
+
| `init-project` | Scaffold a provider-neutral project, including its release pipeline |
|
|
61
|
+
| `release` | Run a provider-neutral release flow |
|
|
62
|
+
|
|
63
|
+
## Repository
|
|
64
|
+
|
|
65
|
+
This repository is canonical on GitLab. GitHub is a read-only distribution mirror: issues and releases live on GitLab.
|
|
66
|
+
|
|
67
|
+
## Development
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
npm install
|
|
71
|
+
npm test
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## License
|
|
75
|
+
|
|
76
|
+
MIT
|
package/bin/drawbore.js
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import {
|
|
5
|
+
addInstruction,
|
|
6
|
+
checkNotebook,
|
|
7
|
+
createNotebook,
|
|
8
|
+
findProjectRoot,
|
|
9
|
+
fixMechanical,
|
|
10
|
+
inspectProject,
|
|
11
|
+
installMarkerFile,
|
|
12
|
+
installSkills,
|
|
13
|
+
loadPackageData,
|
|
14
|
+
notebookDirectory,
|
|
15
|
+
SkillConflictError,
|
|
16
|
+
summarize,
|
|
17
|
+
supportedLocations,
|
|
18
|
+
writeInstallMarker,
|
|
19
|
+
} from "../lib/index.js";
|
|
20
|
+
|
|
21
|
+
const CHECK_FLAGS = new Set(["--json", "--strict", "--fix"]);
|
|
22
|
+
const SUPPORTED_INSTRUCTIONS = new Set(["AGENTS.md", "CLAUDE.md"]);
|
|
23
|
+
|
|
24
|
+
const args = process.argv.slice(2);
|
|
25
|
+
const packageData = await loadPackageData();
|
|
26
|
+
const command = args[0];
|
|
27
|
+
|
|
28
|
+
if (args.includes("--help") || args.includes("-h")) {
|
|
29
|
+
if (command === "check") printCheckHelp(packageData.version);
|
|
30
|
+
else printHelp(packageData.version);
|
|
31
|
+
process.exit(0);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
if (args.includes("--version") || args.includes("-v")) {
|
|
35
|
+
console.log(packageData.version);
|
|
36
|
+
process.exit(0);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
if (command === "check") {
|
|
40
|
+
await runCheck(args.slice(1));
|
|
41
|
+
} else if (command !== "init") {
|
|
42
|
+
console.error("Usage: drawbore init | drawbore check");
|
|
43
|
+
process.exit(2);
|
|
44
|
+
} else {
|
|
45
|
+
let plan;
|
|
46
|
+
try {
|
|
47
|
+
plan = parseExplicitOptions(args.slice(1), packageData);
|
|
48
|
+
} catch (error) {
|
|
49
|
+
console.error(error.message);
|
|
50
|
+
printHelp(packageData.version);
|
|
51
|
+
process.exit(2);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const root = await findProjectRoot();
|
|
55
|
+
await inspectProject(root);
|
|
56
|
+
const selectedLocations = plan?.locations ?? [".agents"];
|
|
57
|
+
const createNotebookDirectory = plan?.notebook ?? true;
|
|
58
|
+
const instructionTargets = plan?.instructions ?? [{ instructionFile: "AGENTS.md" }];
|
|
59
|
+
|
|
60
|
+
try {
|
|
61
|
+
console.log(`Drawbore ${packageData.version}`);
|
|
62
|
+
console.log(`Project: ${root}`);
|
|
63
|
+
|
|
64
|
+
const selection = plan?.skills ? { ...packageData, skills: plan.skills } : packageData;
|
|
65
|
+
const preservedSkillFiles = [];
|
|
66
|
+
const replacedSkillFiles = [];
|
|
67
|
+
const skillHashes = {};
|
|
68
|
+
|
|
69
|
+
for (const location of selectedLocations) {
|
|
70
|
+
const result = await installSkills(root, location, selection, {
|
|
71
|
+
replaceExisting: plan?.replaceSkills === true,
|
|
72
|
+
force: plan?.force === true,
|
|
73
|
+
});
|
|
74
|
+
preservedSkillFiles.push(...result.preserved);
|
|
75
|
+
replacedSkillFiles.push(...result.replaced);
|
|
76
|
+
skillHashes[location] = result.hashes;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
let notebookCreated = false;
|
|
80
|
+
if (createNotebookDirectory) {
|
|
81
|
+
await createNotebook(root);
|
|
82
|
+
notebookCreated = true;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const instructionFiles = [];
|
|
86
|
+
for (const target of instructionTargets) {
|
|
87
|
+
await addInstruction(root, target.instructionFile, packageData);
|
|
88
|
+
instructionFiles.push(target.instructionFile);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
await writeInstallMarker(root, selection, selectedLocations, notebookCreated, [...new Set(instructionFiles)], skillHashes);
|
|
92
|
+
console.log(formatInstallResult(selectedLocations, notebookCreated, instructionFiles, preservedSkillFiles, replacedSkillFiles));
|
|
93
|
+
} catch (error) {
|
|
94
|
+
if (error instanceof SkillConflictError) {
|
|
95
|
+
console.error(error.message);
|
|
96
|
+
process.exit(1);
|
|
97
|
+
}
|
|
98
|
+
throw error;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function parseExplicitOptions(options, packageData) {
|
|
103
|
+
if (options.length === 0) {
|
|
104
|
+
return {
|
|
105
|
+
locations: [".agents"],
|
|
106
|
+
notebook: true,
|
|
107
|
+
instructions: [{ instructionFile: "AGENTS.md" }],
|
|
108
|
+
replaceSkills: false,
|
|
109
|
+
force: false,
|
|
110
|
+
skills: null,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
const locations = [];
|
|
115
|
+
const instructions = [];
|
|
116
|
+
let notebook = null;
|
|
117
|
+
let replaceSkills = false;
|
|
118
|
+
let force = false;
|
|
119
|
+
let skills = null;
|
|
120
|
+
|
|
121
|
+
for (let index = 0; index < options.length; index += 1) {
|
|
122
|
+
const option = options[index];
|
|
123
|
+
if (option === "--location") {
|
|
124
|
+
const value = options[++index];
|
|
125
|
+
if (value === undefined) throw new Error("Missing value for --location");
|
|
126
|
+
for (const location of splitList(value)) {
|
|
127
|
+
if (!supportedLocations[location]) throw new Error(`Unsupported location: ${location}`);
|
|
128
|
+
locations.push(location);
|
|
129
|
+
}
|
|
130
|
+
} else if (option === "--notebook") {
|
|
131
|
+
notebook = true;
|
|
132
|
+
} else if (option === "--instruction") {
|
|
133
|
+
const value = options[++index];
|
|
134
|
+
if (value === undefined) throw new Error("Missing value for --instruction");
|
|
135
|
+
for (const instructionFile of splitList(value)) {
|
|
136
|
+
if (!SUPPORTED_INSTRUCTIONS.has(instructionFile)) throw new Error(`Unsupported instruction file: ${instructionFile}`);
|
|
137
|
+
instructions.push({ instructionFile });
|
|
138
|
+
}
|
|
139
|
+
} else if (option === "--skills") {
|
|
140
|
+
const value = options[++index];
|
|
141
|
+
if (value === undefined) throw new Error("Missing value for --skills");
|
|
142
|
+
const requested = splitList(value);
|
|
143
|
+
const unknown = requested.filter((skill) => !packageData.skills.includes(skill));
|
|
144
|
+
if (unknown.length > 0) throw new Error(`Unknown skill(s): ${unknown.join(", ")}`);
|
|
145
|
+
skills = [...new Set(requested)];
|
|
146
|
+
} else if (option === "--replace-skills") {
|
|
147
|
+
replaceSkills = true;
|
|
148
|
+
} else if (option === "--force") {
|
|
149
|
+
force = true;
|
|
150
|
+
} else if (option === "--yes") {
|
|
151
|
+
// accepted for compatibility
|
|
152
|
+
} else {
|
|
153
|
+
throw new Error(`Unknown option: ${option}`);
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
if (locations.length === 0) locations.push(".agents");
|
|
158
|
+
if (notebook === null) notebook = true;
|
|
159
|
+
if (instructions.length === 0) {
|
|
160
|
+
for (const instructionFile of new Set(locations.map((location) => supportedLocations[location]))) {
|
|
161
|
+
instructions.push({ instructionFile });
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
return {
|
|
166
|
+
locations: [...new Set(locations)],
|
|
167
|
+
notebook,
|
|
168
|
+
replaceSkills,
|
|
169
|
+
force,
|
|
170
|
+
skills,
|
|
171
|
+
instructions: [...new Map(instructions.map((target) => [target.instructionFile, target])).values()],
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
function splitList(value) {
|
|
176
|
+
return value.split(",").map((item) => item.trim()).filter(Boolean);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
async function runCheck(options) {
|
|
180
|
+
for (const option of options) {
|
|
181
|
+
if (!CHECK_FLAGS.has(option)) {
|
|
182
|
+
console.error(`Unknown option for check: ${option}`);
|
|
183
|
+
process.exit(2);
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const json = options.includes("--json");
|
|
188
|
+
const strict = options.includes("--strict");
|
|
189
|
+
const fix = options.includes("--fix");
|
|
190
|
+
const root = await findProjectRoot();
|
|
191
|
+
const notebookDir = path.join(root, notebookDirectory);
|
|
192
|
+
|
|
193
|
+
if (fix) {
|
|
194
|
+
const { fixed } = await fixMechanical(notebookDir);
|
|
195
|
+
if (json) {
|
|
196
|
+
console.log(JSON.stringify({ fixed, changed: fixed.length > 0 }, null, 2));
|
|
197
|
+
} else if (fixed.length === 0) {
|
|
198
|
+
console.log("Nothing to fix.");
|
|
199
|
+
} else {
|
|
200
|
+
for (const item of fixed) {
|
|
201
|
+
console.log(`fixed ${item.code} ${item.file}: ${item.message}`);
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const findings = await checkNotebook(notebookDir);
|
|
207
|
+
const summary = summarize(findings);
|
|
208
|
+
|
|
209
|
+
if (json) {
|
|
210
|
+
console.log(JSON.stringify({
|
|
211
|
+
ok: summary.ok,
|
|
212
|
+
errors: summary.errors,
|
|
213
|
+
warnings: summary.warnings,
|
|
214
|
+
stale: summary.stale,
|
|
215
|
+
}, null, 2));
|
|
216
|
+
} else if (findings.length === 0) {
|
|
217
|
+
console.log("No structural issues found.");
|
|
218
|
+
} else {
|
|
219
|
+
for (const finding of findings) {
|
|
220
|
+
const where = finding.file ? ` (${finding.file})` : "";
|
|
221
|
+
const tag = finding.code.startsWith("S") ? "review" : finding.code.startsWith("W") ? "warn" : "error";
|
|
222
|
+
console.log(`${finding.code} [${tag}]${where}: ${finding.message}`);
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
const failed = !summary.ok || (strict && summary.warnings.length > 0);
|
|
227
|
+
process.exit(failed ? 1 : 0);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function formatInstallResult(locations, notebookCreated, instructionFiles, preservedSkillFiles, replacedSkillFiles) {
|
|
231
|
+
const lines = ["", "Installed:"];
|
|
232
|
+
for (const location of locations) lines.push(`- skills: ${location}/skills/`);
|
|
233
|
+
if (notebookCreated) lines.push(`- record: ${notebookDirectory}/`);
|
|
234
|
+
for (const file of instructionFiles) lines.push(`- instruction: ${file}`);
|
|
235
|
+
lines.push(`- marker: ${installMarkerFile}`);
|
|
236
|
+
if (preservedSkillFiles.length > 0) lines.push("", `Preserved ${preservedSkillFiles.length} file(s).`);
|
|
237
|
+
if (replacedSkillFiles.length > 0) lines.push(`Replaced ${replacedSkillFiles.length} file(s).`);
|
|
238
|
+
lines.push("", "Run the discover skill in your agent to propose the first durable records.");
|
|
239
|
+
return lines.join("\n");
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
function printCheckHelp(version) {
|
|
243
|
+
console.log(`Drawbore ${version}\n\nUsage:\n drawbore check [--json] [--strict] [--fix]`);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
function printHelp(version) {
|
|
247
|
+
console.log(`Drawbore ${version}
|
|
248
|
+
|
|
249
|
+
Usage:
|
|
250
|
+
drawbore init [options]
|
|
251
|
+
drawbore check [--json] [--strict] [--fix]
|
|
252
|
+
drawbore --version
|
|
253
|
+
drawbore --help
|
|
254
|
+
|
|
255
|
+
init options:
|
|
256
|
+
--location <dir> Harness location to install into (repeatable).
|
|
257
|
+
One of: .agents, .claude, .codex, .cursor, .omp, .opencode.
|
|
258
|
+
--notebook Create or refresh the .drawbore templates.
|
|
259
|
+
--instruction <file> Add the Drawbore block to an instruction file (repeatable).
|
|
260
|
+
One of: AGENTS.md, CLAUDE.md.
|
|
261
|
+
--skills <list> Comma-separated subset of skills to install.
|
|
262
|
+
--replace-skills Replace installed skill files that differ.
|
|
263
|
+
--force Replace skills owned by another package.
|
|
264
|
+
--yes Accept defaults without prompting.
|
|
265
|
+
|
|
266
|
+
Drawbore is provider-neutral: it does not assume a forge, registry, or CI provider.`);
|
|
267
|
+
}
|