my-opencode 1.1.0 → 1.2.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/LICENSE +21 -21
- package/README.md +180 -180
- package/agents/architect.md +30 -30
- package/agents/code-reviewer.md +29 -29
- package/agents/executor.md +30 -30
- package/agents/fullstack-dev.md +57 -53
- package/agents/spec-writer.md +37 -37
- package/agents/team-lead.md +60 -60
- package/agents/tech-writer.md +30 -30
- package/agents/test-engineer.md +30 -30
- package/agents/verifier.md +33 -33
- package/bin/cli.js +311 -311
- package/opencode.json +167 -164
- package/package.json +48 -48
- package/scripts/postinstall.js +182 -182
- package/skills/adr/SKILL.md +91 -91
- package/skills/adr/references/templates.md +100 -100
- package/skills/adr/scripts/README.md +5 -5
- package/skills/dev-flow/SKILL.md +188 -188
- package/skills/dev-flow/references/code-phase.md +72 -72
- package/skills/dev-flow/references/contract-phase.md +81 -81
- package/skills/dev-flow/references/verify-phase.md +129 -129
- package/skills/dev-flow/scripts/README.md +3 -3
- package/skills/docs-gen/SKILL.md +162 -162
- package/skills/docs-gen/references/doc-styles.md +216 -216
- package/skills/docs-gen/scripts/README.md +5 -5
- package/skills/orchestrate/SKILL.md +112 -112
- package/skills/orchestrate/references/orchestration-patterns.md +56 -56
- package/skills/pr-review/SKILL.md +110 -110
- package/skills/pr-review/references/review-dimensions.md +117 -117
- package/skills/pr-review/references/security-checklist.md +122 -122
- package/skills/pr-review/scripts/README.md +5 -5
- package/skills/test-gen/SKILL.md +143 -143
- package/skills/test-gen/references/framework-detection.md +105 -105
- package/skills/test-gen/references/test-patterns.md +260 -260
- package/skills/test-gen/scripts/README.md +5 -5
package/scripts/postinstall.js
CHANGED
|
@@ -1,182 +1,182 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* postinstall.js — npm postinstall hook
|
|
5
|
-
*
|
|
6
|
-
* After `npm install my-opencode` in another project, this script
|
|
7
|
-
* automatically copies agents/, skills/, and opencode.json to the
|
|
8
|
-
* target project's .opencode/ directory.
|
|
9
|
-
*
|
|
10
|
-
* The package stays in node_modules/ (gitignored, no residue).
|
|
11
|
-
* The .opencode/ files are what opencode reads.
|
|
12
|
-
*
|
|
13
|
-
* To skip: npm install my-opencode --ignore-scripts
|
|
14
|
-
* To run manually: npx my-opencode init
|
|
15
|
-
*/
|
|
16
|
-
|
|
17
|
-
import { fileURLToPath } from "node:url";
|
|
18
|
-
import path from "node:path";
|
|
19
|
-
import fs from "node:fs";
|
|
20
|
-
|
|
21
|
-
const __filename = fileURLToPath(import.meta.url);
|
|
22
|
-
const __dirname = path.dirname(__filename);
|
|
23
|
-
|
|
24
|
-
const PKG_DIR = path.resolve(__dirname, "..");
|
|
25
|
-
const SKILLS_SRC = path.join(PKG_DIR, "skills");
|
|
26
|
-
const AGENTS_SRC = path.join(PKG_DIR, "agents");
|
|
27
|
-
const CONFIG_SRC = path.join(PKG_DIR, "opencode.json");
|
|
28
|
-
|
|
29
|
-
// ─── Detect project root ────────────────────────────────────────────────
|
|
30
|
-
//
|
|
31
|
-
// During npm postinstall, `process.cwd()` is typically the package root
|
|
32
|
-
// (node_modules/my-opencode/), but behavior varies by npm version.
|
|
33
|
-
// We try multiple strategies to find the parent project root.
|
|
34
|
-
|
|
35
|
-
function hasPackageJson(dir) {
|
|
36
|
-
try {
|
|
37
|
-
const pkgPath = path.join(dir, "package.json");
|
|
38
|
-
if (!fs.existsSync(pkgPath)) return false;
|
|
39
|
-
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
|
|
40
|
-
return pkg.name !== "my-opencode";
|
|
41
|
-
} catch {
|
|
42
|
-
return false;
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
function findProjectRoot() {
|
|
47
|
-
// Strategy 1: process.cwd() is the project root (npm v6 behavior)
|
|
48
|
-
let candidate = path.resolve(process.cwd());
|
|
49
|
-
if (hasPackageJson(candidate)) return candidate;
|
|
50
|
-
|
|
51
|
-
// Strategy 2: process.cwd() is node_modules/my-opencode/ (npm v7+)
|
|
52
|
-
candidate = path.resolve(process.cwd(), "..", "..");
|
|
53
|
-
if (hasPackageJson(candidate)) return candidate;
|
|
54
|
-
|
|
55
|
-
// Strategy 3: __dirname is scripts/, go up 3 levels
|
|
56
|
-
candidate = path.resolve(__dirname, "..", "..", "..");
|
|
57
|
-
if (hasPackageJson(candidate)) return candidate;
|
|
58
|
-
|
|
59
|
-
// Strategy 4: Walk up from __dirname until we find a project's package.json
|
|
60
|
-
candidate = path.resolve(__dirname);
|
|
61
|
-
while (candidate !== path.parse(candidate).root) {
|
|
62
|
-
const parent = path.resolve(candidate, "..");
|
|
63
|
-
if (hasPackageJson(parent)) return parent;
|
|
64
|
-
candidate = parent;
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
return null;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
// ─── File utilities ─────────────────────────────────────────────────────
|
|
71
|
-
|
|
72
|
-
function copyDirSync(src, dst) {
|
|
73
|
-
let count = 0;
|
|
74
|
-
fs.mkdirSync(dst, { recursive: true });
|
|
75
|
-
const entries = fs.readdirSync(src, { withFileTypes: true });
|
|
76
|
-
for (const entry of entries) {
|
|
77
|
-
const srcPath = path.join(src, entry.name);
|
|
78
|
-
const dstPath = path.join(dst, entry.name);
|
|
79
|
-
if (entry.isDirectory()) {
|
|
80
|
-
count += copyDirSync(srcPath, dstPath);
|
|
81
|
-
} else if (entry.isFile()) {
|
|
82
|
-
if (!fs.existsSync(dstPath)) {
|
|
83
|
-
fs.copyFileSync(srcPath, dstPath);
|
|
84
|
-
count++;
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
return count;
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
function copyFileIfNotExists(src, dst) {
|
|
92
|
-
if (!fs.existsSync(dst)) {
|
|
93
|
-
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
94
|
-
fs.copyFileSync(src, dst);
|
|
95
|
-
return true;
|
|
96
|
-
}
|
|
97
|
-
return false;
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
// ─── Main ───────────────────────────────────────────────────────────────
|
|
101
|
-
|
|
102
|
-
function main() {
|
|
103
|
-
const INDENT = " ";
|
|
104
|
-
const CYAN = "\x1b[36m";
|
|
105
|
-
const GREEN = "\x1b[32m";
|
|
106
|
-
const YELLOW = "\x1b[33m";
|
|
107
|
-
const RESET = "\x1b[0m";
|
|
108
|
-
|
|
109
|
-
function header(text) {
|
|
110
|
-
console.log(`\n${CYAN}━━━ ${text} ━━━${RESET}\n`);
|
|
111
|
-
}
|
|
112
|
-
function success(text) {
|
|
113
|
-
console.log(`${GREEN}✓${RESET} ${text}`);
|
|
114
|
-
}
|
|
115
|
-
function warn(text) {
|
|
116
|
-
console.log(`${YELLOW}⚠${RESET} ${text}`);
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
const projectRoot = findProjectRoot();
|
|
120
|
-
if (!projectRoot) {
|
|
121
|
-
warn(
|
|
122
|
-
"Could not detect project root for my-opencode postinstall.\n" +
|
|
123
|
-
`${INDENT}Run "npx my-opencode init" to set up manually.`,
|
|
124
|
-
);
|
|
125
|
-
process.exit(0);
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
const targetDir = path.join(projectRoot, ".opencode");
|
|
129
|
-
const targetSkills = path.join(targetDir, "skills");
|
|
130
|
-
const targetAgents = path.join(targetDir, "agents");
|
|
131
|
-
const targetConfig = path.join(targetDir, "opencode.json");
|
|
132
|
-
|
|
133
|
-
// ── Create .opencode/ ──────────────────────────────────────────────────
|
|
134
|
-
if (!fs.existsSync(targetDir)) {
|
|
135
|
-
fs.mkdirSync(targetDir, { recursive: true });
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
// ── Copy skills ────────────────────────────────────────────────────────
|
|
139
|
-
let skillCount = 0;
|
|
140
|
-
if (fs.existsSync(SKILLS_SRC)) {
|
|
141
|
-
const skills = fs
|
|
142
|
-
.readdirSync(SKILLS_SRC, { withFileTypes: true })
|
|
143
|
-
.filter((d) => d.isDirectory())
|
|
144
|
-
.map((d) => d.name);
|
|
145
|
-
|
|
146
|
-
for (const s of skills) {
|
|
147
|
-
const dst = path.join(targetSkills, s);
|
|
148
|
-
if (!fs.existsSync(dst)) {
|
|
149
|
-
copyDirSync(path.join(SKILLS_SRC, s), dst);
|
|
150
|
-
skillCount++;
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
// ── Copy agents ────────────────────────────────────────────────────────
|
|
156
|
-
let agentCount = 0;
|
|
157
|
-
if (fs.existsSync(AGENTS_SRC)) {
|
|
158
|
-
const agents = fs
|
|
159
|
-
.readdirSync(AGENTS_SRC, { withFileTypes: true })
|
|
160
|
-
.filter((d) => d.isFile() && d.name.endsWith(".md"))
|
|
161
|
-
.map((d) => d.name);
|
|
162
|
-
|
|
163
|
-
for (const a of agents) {
|
|
164
|
-
const dst = path.join(targetAgents, a);
|
|
165
|
-
if (copyFileIfNotExists(path.join(AGENTS_SRC, a), dst)) {
|
|
166
|
-
agentCount++;
|
|
167
|
-
}
|
|
168
|
-
}
|
|
169
|
-
}
|
|
170
|
-
|
|
171
|
-
// ── Copy opencode.json ────────────────────────────────────────────────
|
|
172
|
-
copyFileIfNotExists(CONFIG_SRC, targetConfig);
|
|
173
|
-
|
|
174
|
-
// Suppress output if nothing changed (quiet idempotency)
|
|
175
|
-
if (skillCount === 0 && agentCount === 0) return;
|
|
176
|
-
|
|
177
|
-
header("my-opencode: installed to .opencode/");
|
|
178
|
-
if (skillCount > 0) success(`Skills: ${skillCount}`);
|
|
179
|
-
if (agentCount > 0) success(`Agents: ${agentCount}`);
|
|
180
|
-
}
|
|
181
|
-
|
|
182
|
-
main();
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* postinstall.js — npm postinstall hook
|
|
5
|
+
*
|
|
6
|
+
* After `npm install my-opencode` in another project, this script
|
|
7
|
+
* automatically copies agents/, skills/, and opencode.json to the
|
|
8
|
+
* target project's .opencode/ directory.
|
|
9
|
+
*
|
|
10
|
+
* The package stays in node_modules/ (gitignored, no residue).
|
|
11
|
+
* The .opencode/ files are what opencode reads.
|
|
12
|
+
*
|
|
13
|
+
* To skip: npm install my-opencode --ignore-scripts
|
|
14
|
+
* To run manually: npx my-opencode init
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { fileURLToPath } from "node:url";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
import fs from "node:fs";
|
|
20
|
+
|
|
21
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
22
|
+
const __dirname = path.dirname(__filename);
|
|
23
|
+
|
|
24
|
+
const PKG_DIR = path.resolve(__dirname, "..");
|
|
25
|
+
const SKILLS_SRC = path.join(PKG_DIR, "skills");
|
|
26
|
+
const AGENTS_SRC = path.join(PKG_DIR, "agents");
|
|
27
|
+
const CONFIG_SRC = path.join(PKG_DIR, "opencode.json");
|
|
28
|
+
|
|
29
|
+
// ─── Detect project root ────────────────────────────────────────────────
|
|
30
|
+
//
|
|
31
|
+
// During npm postinstall, `process.cwd()` is typically the package root
|
|
32
|
+
// (node_modules/my-opencode/), but behavior varies by npm version.
|
|
33
|
+
// We try multiple strategies to find the parent project root.
|
|
34
|
+
|
|
35
|
+
function hasPackageJson(dir) {
|
|
36
|
+
try {
|
|
37
|
+
const pkgPath = path.join(dir, "package.json");
|
|
38
|
+
if (!fs.existsSync(pkgPath)) return false;
|
|
39
|
+
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
|
|
40
|
+
return pkg.name !== "my-opencode";
|
|
41
|
+
} catch {
|
|
42
|
+
return false;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function findProjectRoot() {
|
|
47
|
+
// Strategy 1: process.cwd() is the project root (npm v6 behavior)
|
|
48
|
+
let candidate = path.resolve(process.cwd());
|
|
49
|
+
if (hasPackageJson(candidate)) return candidate;
|
|
50
|
+
|
|
51
|
+
// Strategy 2: process.cwd() is node_modules/my-opencode/ (npm v7+)
|
|
52
|
+
candidate = path.resolve(process.cwd(), "..", "..");
|
|
53
|
+
if (hasPackageJson(candidate)) return candidate;
|
|
54
|
+
|
|
55
|
+
// Strategy 3: __dirname is scripts/, go up 3 levels
|
|
56
|
+
candidate = path.resolve(__dirname, "..", "..", "..");
|
|
57
|
+
if (hasPackageJson(candidate)) return candidate;
|
|
58
|
+
|
|
59
|
+
// Strategy 4: Walk up from __dirname until we find a project's package.json
|
|
60
|
+
candidate = path.resolve(__dirname);
|
|
61
|
+
while (candidate !== path.parse(candidate).root) {
|
|
62
|
+
const parent = path.resolve(candidate, "..");
|
|
63
|
+
if (hasPackageJson(parent)) return parent;
|
|
64
|
+
candidate = parent;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
return null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// ─── File utilities ─────────────────────────────────────────────────────
|
|
71
|
+
|
|
72
|
+
function copyDirSync(src, dst) {
|
|
73
|
+
let count = 0;
|
|
74
|
+
fs.mkdirSync(dst, { recursive: true });
|
|
75
|
+
const entries = fs.readdirSync(src, { withFileTypes: true });
|
|
76
|
+
for (const entry of entries) {
|
|
77
|
+
const srcPath = path.join(src, entry.name);
|
|
78
|
+
const dstPath = path.join(dst, entry.name);
|
|
79
|
+
if (entry.isDirectory()) {
|
|
80
|
+
count += copyDirSync(srcPath, dstPath);
|
|
81
|
+
} else if (entry.isFile()) {
|
|
82
|
+
if (!fs.existsSync(dstPath)) {
|
|
83
|
+
fs.copyFileSync(srcPath, dstPath);
|
|
84
|
+
count++;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return count;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function copyFileIfNotExists(src, dst) {
|
|
92
|
+
if (!fs.existsSync(dst)) {
|
|
93
|
+
fs.mkdirSync(path.dirname(dst), { recursive: true });
|
|
94
|
+
fs.copyFileSync(src, dst);
|
|
95
|
+
return true;
|
|
96
|
+
}
|
|
97
|
+
return false;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ─── Main ───────────────────────────────────────────────────────────────
|
|
101
|
+
|
|
102
|
+
function main() {
|
|
103
|
+
const INDENT = " ";
|
|
104
|
+
const CYAN = "\x1b[36m";
|
|
105
|
+
const GREEN = "\x1b[32m";
|
|
106
|
+
const YELLOW = "\x1b[33m";
|
|
107
|
+
const RESET = "\x1b[0m";
|
|
108
|
+
|
|
109
|
+
function header(text) {
|
|
110
|
+
console.log(`\n${CYAN}━━━ ${text} ━━━${RESET}\n`);
|
|
111
|
+
}
|
|
112
|
+
function success(text) {
|
|
113
|
+
console.log(`${GREEN}✓${RESET} ${text}`);
|
|
114
|
+
}
|
|
115
|
+
function warn(text) {
|
|
116
|
+
console.log(`${YELLOW}⚠${RESET} ${text}`);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const projectRoot = findProjectRoot();
|
|
120
|
+
if (!projectRoot) {
|
|
121
|
+
warn(
|
|
122
|
+
"Could not detect project root for my-opencode postinstall.\n" +
|
|
123
|
+
`${INDENT}Run "npx my-opencode init" to set up manually.`,
|
|
124
|
+
);
|
|
125
|
+
process.exit(0);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const targetDir = path.join(projectRoot, ".opencode");
|
|
129
|
+
const targetSkills = path.join(targetDir, "skills");
|
|
130
|
+
const targetAgents = path.join(targetDir, "agents");
|
|
131
|
+
const targetConfig = path.join(targetDir, "opencode.json");
|
|
132
|
+
|
|
133
|
+
// ── Create .opencode/ ──────────────────────────────────────────────────
|
|
134
|
+
if (!fs.existsSync(targetDir)) {
|
|
135
|
+
fs.mkdirSync(targetDir, { recursive: true });
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
// ── Copy skills ────────────────────────────────────────────────────────
|
|
139
|
+
let skillCount = 0;
|
|
140
|
+
if (fs.existsSync(SKILLS_SRC)) {
|
|
141
|
+
const skills = fs
|
|
142
|
+
.readdirSync(SKILLS_SRC, { withFileTypes: true })
|
|
143
|
+
.filter((d) => d.isDirectory())
|
|
144
|
+
.map((d) => d.name);
|
|
145
|
+
|
|
146
|
+
for (const s of skills) {
|
|
147
|
+
const dst = path.join(targetSkills, s);
|
|
148
|
+
if (!fs.existsSync(dst)) {
|
|
149
|
+
copyDirSync(path.join(SKILLS_SRC, s), dst);
|
|
150
|
+
skillCount++;
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
// ── Copy agents ────────────────────────────────────────────────────────
|
|
156
|
+
let agentCount = 0;
|
|
157
|
+
if (fs.existsSync(AGENTS_SRC)) {
|
|
158
|
+
const agents = fs
|
|
159
|
+
.readdirSync(AGENTS_SRC, { withFileTypes: true })
|
|
160
|
+
.filter((d) => d.isFile() && d.name.endsWith(".md"))
|
|
161
|
+
.map((d) => d.name);
|
|
162
|
+
|
|
163
|
+
for (const a of agents) {
|
|
164
|
+
const dst = path.join(targetAgents, a);
|
|
165
|
+
if (copyFileIfNotExists(path.join(AGENTS_SRC, a), dst)) {
|
|
166
|
+
agentCount++;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// ── Copy opencode.json ────────────────────────────────────────────────
|
|
172
|
+
copyFileIfNotExists(CONFIG_SRC, targetConfig);
|
|
173
|
+
|
|
174
|
+
// Suppress output if nothing changed (quiet idempotency)
|
|
175
|
+
if (skillCount === 0 && agentCount === 0) return;
|
|
176
|
+
|
|
177
|
+
header("my-opencode: installed to .opencode/");
|
|
178
|
+
if (skillCount > 0) success(`Skills: ${skillCount}`);
|
|
179
|
+
if (agentCount > 0) success(`Agents: ${agentCount}`);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
main();
|
package/skills/adr/SKILL.md
CHANGED
|
@@ -1,91 +1,91 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: adr
|
|
3
|
-
description: |
|
|
4
|
-
Capture architecture decisions as lightweight ADR documents.
|
|
5
|
-
Use when making design choices that affect project structure, technology selection,
|
|
6
|
-
or architectural direction. Also use during code review when spotting implicit decisions.
|
|
7
|
-
Triggers on: "adr", "architecture decision", "design decision", "why did we", "decision log"
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
# Architecture Decision Records
|
|
11
|
-
|
|
12
|
-
Capture, manage, and maintain architecture decisions using Michael Nygard's lightweight ADR format.
|
|
13
|
-
|
|
14
|
-
## When to Use
|
|
15
|
-
|
|
16
|
-
- Choosing a technology, framework, or library
|
|
17
|
-
- Defining project structure or module boundaries
|
|
18
|
-
- Making API design decisions (REST vs GraphQL, versioning strategy)
|
|
19
|
-
- Selecting database, cache, or infrastructure
|
|
20
|
-
- Changing existing architecture decisions
|
|
21
|
-
- During code review — if a PR introduces an architectural change without an ADR, flag it
|
|
22
|
-
|
|
23
|
-
## ADR Lifecycle
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
Proposed → Accepted → Deprecated → Superseded by ADR-NNN
|
|
27
|
-
↘ Reinstated
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
| Status | Meaning |
|
|
31
|
-
|--------|---------|
|
|
32
|
-
| Proposed | Decision suggested, under review |
|
|
33
|
-
| Accepted | Decision adopted, implementation follows |
|
|
34
|
-
| Deprecated | No longer recommended, existing usage OK |
|
|
35
|
-
| Superseded | Replaced by another ADR (link to it) |
|
|
36
|
-
| Reinstated | Previously deprecated decision revived |
|
|
37
|
-
|
|
38
|
-
## Workflow
|
|
39
|
-
|
|
40
|
-
### Step 1: Detect Decision Moment
|
|
41
|
-
|
|
42
|
-
An ADR is needed when:
|
|
43
|
-
- A decision has long-term impact on the codebase
|
|
44
|
-
- Multiple alternatives exist with meaningful tradeoffs
|
|
45
|
-
- The decision affects how other teams/modules will work
|
|
46
|
-
- You find yourself explaining "why we chose X" more than once
|
|
47
|
-
|
|
48
|
-
### Step 2: Write ADR
|
|
49
|
-
|
|
50
|
-
Use the template from `references/templates.md`. Save to `docs/adr/NNNN-title.md`.
|
|
51
|
-
|
|
52
|
-
Number sequentially: check existing files in `docs/adr/` and increment.
|
|
53
|
-
|
|
54
|
-
### Step 3: Review
|
|
55
|
-
|
|
56
|
-
Share with team for feedback. ADRs benefit from:
|
|
57
|
-
- Architecture review
|
|
58
|
-
- Cross-team input (if decision affects others)
|
|
59
|
-
- At least one other person reading it
|
|
60
|
-
|
|
61
|
-
### Step 4: Update Status
|
|
62
|
-
|
|
63
|
-
As decisions evolve:
|
|
64
|
-
- Mark `Accepted` when implementation starts
|
|
65
|
-
- Mark `Deprecated` when better alternatives emerge
|
|
66
|
-
- Mark `Superseded by ADR-NNN` when replaced
|
|
67
|
-
- Link related ADRs in both directions
|
|
68
|
-
|
|
69
|
-
## ADR Location
|
|
70
|
-
|
|
71
|
-
All ADRs live in `docs/adr/` with an index:
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
docs/adr/
|
|
75
|
-
├── README.md # Index of all ADRs
|
|
76
|
-
├── 001-use-postgres.md
|
|
77
|
-
├── 002-api-versioning.md
|
|
78
|
-
└── 003-monorepo-structure.md
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
## Keeping ADRs Alive
|
|
82
|
-
|
|
83
|
-
- **PR review hook:** If a PR changes architecture without a corresponding ADR, flag it
|
|
84
|
-
- **Regular index updates:** When superseding, update the old ADR's status and link
|
|
85
|
-
- **Not everything needs an ADR:** Bug fixes, routine feature additions, style choices → skip
|
|
86
|
-
- **But when in doubt, write one:** A 5-minute ADR saves hours of future confusion
|
|
87
|
-
|
|
88
|
-
## Related Skills
|
|
89
|
-
|
|
90
|
-
- `dev-flow` — Contract phase should reference ADRs for architectural context
|
|
91
|
-
- `pr-review` — Code review checks for missing ADRs on architectural changes
|
|
1
|
+
---
|
|
2
|
+
name: adr
|
|
3
|
+
description: |
|
|
4
|
+
Capture architecture decisions as lightweight ADR documents.
|
|
5
|
+
Use when making design choices that affect project structure, technology selection,
|
|
6
|
+
or architectural direction. Also use during code review when spotting implicit decisions.
|
|
7
|
+
Triggers on: "adr", "architecture decision", "design decision", "why did we", "decision log"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Architecture Decision Records
|
|
11
|
+
|
|
12
|
+
Capture, manage, and maintain architecture decisions using Michael Nygard's lightweight ADR format.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Choosing a technology, framework, or library
|
|
17
|
+
- Defining project structure or module boundaries
|
|
18
|
+
- Making API design decisions (REST vs GraphQL, versioning strategy)
|
|
19
|
+
- Selecting database, cache, or infrastructure
|
|
20
|
+
- Changing existing architecture decisions
|
|
21
|
+
- During code review — if a PR introduces an architectural change without an ADR, flag it
|
|
22
|
+
|
|
23
|
+
## ADR Lifecycle
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
Proposed → Accepted → Deprecated → Superseded by ADR-NNN
|
|
27
|
+
↘ Reinstated
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Status | Meaning |
|
|
31
|
+
|--------|---------|
|
|
32
|
+
| Proposed | Decision suggested, under review |
|
|
33
|
+
| Accepted | Decision adopted, implementation follows |
|
|
34
|
+
| Deprecated | No longer recommended, existing usage OK |
|
|
35
|
+
| Superseded | Replaced by another ADR (link to it) |
|
|
36
|
+
| Reinstated | Previously deprecated decision revived |
|
|
37
|
+
|
|
38
|
+
## Workflow
|
|
39
|
+
|
|
40
|
+
### Step 1: Detect Decision Moment
|
|
41
|
+
|
|
42
|
+
An ADR is needed when:
|
|
43
|
+
- A decision has long-term impact on the codebase
|
|
44
|
+
- Multiple alternatives exist with meaningful tradeoffs
|
|
45
|
+
- The decision affects how other teams/modules will work
|
|
46
|
+
- You find yourself explaining "why we chose X" more than once
|
|
47
|
+
|
|
48
|
+
### Step 2: Write ADR
|
|
49
|
+
|
|
50
|
+
Use the template from `references/templates.md`. Save to `docs/adr/NNNN-title.md`.
|
|
51
|
+
|
|
52
|
+
Number sequentially: check existing files in `docs/adr/` and increment.
|
|
53
|
+
|
|
54
|
+
### Step 3: Review
|
|
55
|
+
|
|
56
|
+
Share with team for feedback. ADRs benefit from:
|
|
57
|
+
- Architecture review
|
|
58
|
+
- Cross-team input (if decision affects others)
|
|
59
|
+
- At least one other person reading it
|
|
60
|
+
|
|
61
|
+
### Step 4: Update Status
|
|
62
|
+
|
|
63
|
+
As decisions evolve:
|
|
64
|
+
- Mark `Accepted` when implementation starts
|
|
65
|
+
- Mark `Deprecated` when better alternatives emerge
|
|
66
|
+
- Mark `Superseded by ADR-NNN` when replaced
|
|
67
|
+
- Link related ADRs in both directions
|
|
68
|
+
|
|
69
|
+
## ADR Location
|
|
70
|
+
|
|
71
|
+
All ADRs live in `docs/adr/` with an index:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
docs/adr/
|
|
75
|
+
├── README.md # Index of all ADRs
|
|
76
|
+
├── 001-use-postgres.md
|
|
77
|
+
├── 002-api-versioning.md
|
|
78
|
+
└── 003-monorepo-structure.md
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Keeping ADRs Alive
|
|
82
|
+
|
|
83
|
+
- **PR review hook:** If a PR changes architecture without a corresponding ADR, flag it
|
|
84
|
+
- **Regular index updates:** When superseding, update the old ADR's status and link
|
|
85
|
+
- **Not everything needs an ADR:** Bug fixes, routine feature additions, style choices → skip
|
|
86
|
+
- **But when in doubt, write one:** A 5-minute ADR saves hours of future confusion
|
|
87
|
+
|
|
88
|
+
## Related Skills
|
|
89
|
+
|
|
90
|
+
- `dev-flow` — Contract phase should reference ADRs for architectural context
|
|
91
|
+
- `pr-review` — Code review checks for missing ADRs on architectural changes
|