drawbore 0.1.0 → 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 +28 -20
- package/LICENSE +20 -20
- package/README.md +75 -75
- package/bin/drawbore.js +334 -266
- package/lib/checker.js +398 -398
- package/lib/index.js +3 -1
- package/lib/installer.js +404 -404
- package/lib/prompts.js +375 -373
- package/package.json +42 -42
- package/skills/discover/SKILL.md +76 -76
- package/skills/frame/SKILL.md +84 -84
- package/skills/frame/references/change-brief.md +54 -54
- package/skills/init-project/SKILL.md +85 -85
- package/skills/recall/SKILL.md +61 -61
- package/skills/record/SKILL.md +98 -98
- package/skills/record/references/artifact-formats.md +130 -130
- package/skills/release/SKILL.md +107 -107
- package/skills/review/SKILL.md +116 -116
- package/templates/instruction.md +8 -8
- package/templates/manifest.json +11 -11
- package/templates/record/context.md +13 -13
- package/templates/record/glossary.md +6 -6
- package/templates/record/index.md +15 -15
- package/templates/record/principles.md +2 -2
- package/templates/record/stack.md +6 -6
- package/templates/record/system.md +2 -2
package/package.json
CHANGED
|
@@ -1,43 +1,43 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "drawbore",
|
|
3
|
-
"version": "0.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
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "drawbore",
|
|
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
|
+
}
|
|
43
43
|
}
|
package/skills/discover/SKILL.md
CHANGED
|
@@ -1,77 +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.
|
|
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
77
|
- Do not delete or rename pre-existing record paths because they are empty, skipped, placeholder-only, or not part of the proposed refresh.
|
package/skills/frame/SKILL.md
CHANGED
|
@@ -1,85 +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.
|
|
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
85
|
- Do not assume where external issues are tracked.
|
|
@@ -1,55 +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.
|
|
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
55
|
- Keep the brief transient. When work settles, promote durable consequences and remove the brief.
|