code-anchored-context 0.1.0 → 0.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/.agents/skills/README.md +1 -1
- package/.agents/skills/{development-initiative-context → code-anchored-context}/SKILL.md +38 -38
- package/AGENTS.md +15 -13
- package/README.md +14 -14
- package/bin/code-anchored-context.js +125 -43
- package/{Development → context}/AGENTS.md +13 -13
- package/{Development → context}/README.md +29 -29
- package/{Development → context}/_templates/backlog-item.md +2 -2
- package/{Development → context}/_templates/initiative/README.md +9 -5
- package/{Development → context}/_templates/initiative/backlog.md +2 -2
- package/{Development → context}/_templates/initiative/plan.md +2 -2
- package/{Development → context}/_templates/initiative/release-doc-notes.md +6 -6
- package/{Development → context}/_templates/planned-initiative/README.md +10 -6
- package/{Development → context}/_templates/planned-initiative/release-doc-notes.md +5 -5
- package/{Development → context}/_templates/program/README.md +1 -1
- package/{Development → context}/_templates/program/backlog.md +1 -1
- package/{Development → context}/_templates/program/releases/v0_1_0.md +1 -1
- package/{Development → context}/_templates/release-context/README.md +6 -6
- package/{Development → context}/_templates/release-context/backlog.md +1 -2
- package/{Development → context}/_templates/release-transition.md +7 -7
- package/{Development → context}/backlog/README.md +3 -3
- package/{Development → context}/code-anchored-context-structure.md +16 -15
- package/{Development → context}/code-anchored-context-why.md +8 -8
- package/{Development → context}/code-anchored-context.html +20 -20
- package/{Development → context}/current.md +3 -3
- package/{Development → context}/giving-ai-agents-context-around-code.md +32 -32
- package/{Development → context}/programs/README.md +2 -2
- package/{Development → context}/releases/v0_1_0/README.md +6 -6
- package/{Development → context}/releases/v0_1_0/backlog.md +1 -1
- package/{Development → context}/terminology.md +22 -22
- package/{Documentation → docs}/Welcome.md +11 -6
- package/{Documentation → docs}/_authoring/README.md +6 -5
- package/{Documentation → docs}/_authoring/areas/README.md +1 -1
- package/{Documentation → docs}/_authoring/areas/_template.md +19 -5
- package/{Documentation → docs}/_authoring/terminology.md +1 -1
- package/docs/_authoring/workflow.md +210 -0
- package/docs/_templates/area/README.md +58 -0
- package/docs/_templates/area/features/feature-template.md +71 -0
- package/{Documentation → docs}/releases/index.md +3 -1
- package/package.json +19 -18
- package/Documentation/_authoring/workflow.md +0 -123
- package/Documentation/_templates/area/README.md +0 -20
- package/Documentation/_templates/area/features/feature-template.md +0 -29
- /package/{Development → context}/_templates/initiative/architecture.md +0 -0
- /package/{Development → context}/_templates/initiative/brief.html +0 -0
- /package/{Development → context}/_templates/initiative/decisions/ADR-0000-template.md +0 -0
- /package/{Development → context}/_templates/initiative/delivery.md +0 -0
- /package/{Development → context}/_templates/initiative/infrastructure.md +0 -0
- /package/{Development → context}/_templates/initiative/interface.md +0 -0
- /package/{Development → context}/_templates/initiative/operations.md +0 -0
- /package/{Development → context}/_templates/initiative/spec.md +0 -0
- /package/{Development → context}/_templates/initiative/testing.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/architecture.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/backlog.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/decisions/ADR-0000-template.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/delivery.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/infrastructure.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/interface.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/operations.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/plan.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/spec.md +0 -0
- /package/{Development → context}/_templates/planned-initiative/testing.md +0 -0
- /package/{Development → context}/_templates/program/context.md +0 -0
- /package/{Development → context}/_templates/program/decisions/ADR-0000-template.md +0 -0
- /package/{Development → context}/_templates/program/planned-initiatives/.gitkeep +0 -0
- /package/{Development → context}/_templates/program/roadmap.md +0 -0
- /package/{Development → context}/_templates/release-context/initiatives/.gitkeep +0 -0
- /package/{Development → context}/backlog/items/.gitkeep +0 -0
- /package/{Development → context}/releases/v0_1_0/initiatives/.gitkeep +0 -0
- /package/{Documentation → docs}/.order +0 -0
|
@@ -18,7 +18,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
18
18
|
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
19
19
|
const defaultRelease = 'v0_1_0';
|
|
20
20
|
const defaultReleaseLabel = 'v0.1.0';
|
|
21
|
-
const skillName = '
|
|
21
|
+
const skillName = 'code-anchored-context';
|
|
22
22
|
const agentSectionStart = '<!-- code-anchored-context:start -->';
|
|
23
23
|
const agentSectionEnd = '<!-- code-anchored-context:end -->';
|
|
24
24
|
|
|
@@ -54,7 +54,7 @@ async function main() {
|
|
|
54
54
|
dryRun: args.dryRun
|
|
55
55
|
});
|
|
56
56
|
|
|
57
|
-
await installer.init({
|
|
57
|
+
await installer.init({ includeDocs: args.docs });
|
|
58
58
|
}
|
|
59
59
|
|
|
60
60
|
function parseArgs(argv) {
|
|
@@ -65,7 +65,7 @@ function parseArgs(argv) {
|
|
|
65
65
|
release: defaultRelease,
|
|
66
66
|
force: false,
|
|
67
67
|
dryRun: false,
|
|
68
|
-
|
|
68
|
+
docs: true,
|
|
69
69
|
help: false,
|
|
70
70
|
version: false
|
|
71
71
|
};
|
|
@@ -95,8 +95,8 @@ function parseArgs(argv) {
|
|
|
95
95
|
continue;
|
|
96
96
|
}
|
|
97
97
|
|
|
98
|
-
if (arg === '--no-
|
|
99
|
-
options.
|
|
98
|
+
if (arg === '--no-docs') {
|
|
99
|
+
options.docs = false;
|
|
100
100
|
continue;
|
|
101
101
|
}
|
|
102
102
|
|
|
@@ -170,7 +170,7 @@ Options:
|
|
|
170
170
|
--target <path> Project root to install into. Defaults to cwd.
|
|
171
171
|
--project-name <name> Name used to replace PROJECT_NAME placeholders.
|
|
172
172
|
--release <slug> Initial release slug. Defaults to ${defaultRelease}.
|
|
173
|
-
--no-
|
|
173
|
+
--no-docs Skip the docs/ starter files.
|
|
174
174
|
--force Replace existing generated directories.
|
|
175
175
|
--dry-run Show planned changes without writing files.
|
|
176
176
|
-h, --help Show help.
|
|
@@ -178,7 +178,7 @@ Options:
|
|
|
178
178
|
|
|
179
179
|
Examples:
|
|
180
180
|
npx code-anchored-context init --project-name "My App"
|
|
181
|
-
npx code-anchored-context init --release v1_0_0 --no-
|
|
181
|
+
npx code-anchored-context init --release v1_0_0 --no-docs
|
|
182
182
|
`);
|
|
183
183
|
}
|
|
184
184
|
|
|
@@ -212,30 +212,34 @@ class Installer {
|
|
|
212
212
|
this.force = force;
|
|
213
213
|
this.dryRun = dryRun;
|
|
214
214
|
this.actions = [];
|
|
215
|
+
this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
|
|
215
216
|
}
|
|
216
217
|
|
|
217
|
-
async init({
|
|
218
|
+
async init({ includeDocs }) {
|
|
218
219
|
await this.ensureDirectory(this.targetRoot);
|
|
219
220
|
|
|
220
221
|
await this.installAgentsFile();
|
|
221
222
|
await this.installSkill();
|
|
222
|
-
await this.copyTemplatePath('
|
|
223
|
+
await this.copyTemplatePath('context', 'context');
|
|
223
224
|
await this.renameReleasePaths();
|
|
224
225
|
|
|
225
|
-
if (
|
|
226
|
-
await this.copyTemplatePath('
|
|
226
|
+
if (includeDocs) {
|
|
227
|
+
await this.copyTemplatePath('docs', 'docs');
|
|
227
228
|
} else {
|
|
228
|
-
this.note('skip
|
|
229
|
+
this.note('skip docs/ (--no-docs)');
|
|
229
230
|
}
|
|
230
231
|
|
|
231
232
|
this.printSummary();
|
|
232
233
|
}
|
|
233
234
|
|
|
234
235
|
async installAgentsFile() {
|
|
235
|
-
const targetFile =
|
|
236
|
+
const targetFile = await this.findAgentsFile();
|
|
237
|
+
const targetDisplay = path.basename(targetFile);
|
|
238
|
+
this.agentsFilePath = targetFile;
|
|
236
239
|
|
|
237
240
|
if (!await exists(targetFile)) {
|
|
238
241
|
await this.copyTemplatePath('AGENTS.md', 'AGENTS.md');
|
|
242
|
+
this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
|
|
239
243
|
return;
|
|
240
244
|
}
|
|
241
245
|
|
|
@@ -249,16 +253,16 @@ class Installer {
|
|
|
249
253
|
);
|
|
250
254
|
|
|
251
255
|
if (updated === current) {
|
|
252
|
-
this.note(
|
|
256
|
+
this.note(`${targetDisplay} already has Code-Anchored Context guidance`);
|
|
253
257
|
return;
|
|
254
258
|
}
|
|
255
259
|
|
|
256
|
-
await this.writeFile(targetFile, updated,
|
|
260
|
+
await this.writeFile(targetFile, updated, `update ${targetDisplay} Code-Anchored Context section`);
|
|
257
261
|
return;
|
|
258
262
|
}
|
|
259
263
|
|
|
260
|
-
if (current.includes(
|
|
261
|
-
this.note(
|
|
264
|
+
if (current.includes(`.agents/skills/${skillName}/SKILL.md`)) {
|
|
265
|
+
this.note(`${targetDisplay} already points to the Code-Anchored Context skill`);
|
|
262
266
|
return;
|
|
263
267
|
}
|
|
264
268
|
|
|
@@ -266,21 +270,44 @@ class Installer {
|
|
|
266
270
|
await this.writeFile(
|
|
267
271
|
targetFile,
|
|
268
272
|
`${current}${separator}${section}\n`,
|
|
269
|
-
|
|
273
|
+
`append Code-Anchored Context guidance to ${targetDisplay}`
|
|
270
274
|
);
|
|
271
275
|
}
|
|
272
276
|
|
|
277
|
+
async findAgentsFile() {
|
|
278
|
+
const canonicalPath = path.join(this.targetRoot, 'AGENTS.md');
|
|
279
|
+
|
|
280
|
+
let entries;
|
|
281
|
+
|
|
282
|
+
try {
|
|
283
|
+
entries = await readdir(this.targetRoot, { withFileTypes: true });
|
|
284
|
+
} catch {
|
|
285
|
+
return canonicalPath;
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
if (entries.some((entry) => entry.isFile() && entry.name === 'AGENTS.md')) {
|
|
289
|
+
return canonicalPath;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
const match = entries
|
|
293
|
+
.filter((entry) => entry.isFile() && entry.name.toLowerCase() === 'agents.md')
|
|
294
|
+
.map((entry) => entry.name)
|
|
295
|
+
.sort((left, right) => left.localeCompare(right))[0];
|
|
296
|
+
|
|
297
|
+
return match ? path.join(this.targetRoot, match) : canonicalPath;
|
|
298
|
+
}
|
|
299
|
+
|
|
273
300
|
renderAgentSection() {
|
|
274
301
|
return `${agentSectionStart}
|
|
275
302
|
## Code-Anchored Context
|
|
276
303
|
|
|
277
304
|
In-progress specs, plans, ADRs, backlog, implementation context, and
|
|
278
|
-
release-documentation notes live under [\`
|
|
279
|
-
Start with [\`
|
|
305
|
+
release-documentation notes live under [\`context/\`](context/).
|
|
306
|
+
Start with [\`context/current.md\`](context/current.md).
|
|
280
307
|
|
|
281
308
|
For behavior-changing work, use the repo-wide skill at
|
|
282
|
-
[\`.agents/skills/
|
|
283
|
-
Keep initiative knowledge centralized under \`
|
|
309
|
+
[\`.agents/skills/${skillName}/SKILL.md\`](.agents/skills/${skillName}/SKILL.md).
|
|
310
|
+
Keep initiative knowledge centralized under \`context/\`; area
|
|
284
311
|
\`AGENTS.md\` files should point there rather than copying active plans.
|
|
285
312
|
${agentSectionEnd}`;
|
|
286
313
|
}
|
|
@@ -291,7 +318,13 @@ ${agentSectionEnd}`;
|
|
|
291
318
|
`.agents/skills/${skillName}`
|
|
292
319
|
);
|
|
293
320
|
|
|
294
|
-
const
|
|
321
|
+
const readmeTarget = await this.findExistingTargetPath('.agents/skills/README.md');
|
|
322
|
+
const readmePath = readmeTarget.exists
|
|
323
|
+
? readmeTarget.path
|
|
324
|
+
: path.join(this.targetRoot, '.agents/skills/README.md');
|
|
325
|
+
const readmeDisplay = readmeTarget.exists
|
|
326
|
+
? readmeTarget.display
|
|
327
|
+
: '.agents/skills/README.md';
|
|
295
328
|
|
|
296
329
|
if (!await exists(readmePath)) {
|
|
297
330
|
await this.copyTemplatePath('.agents/skills/README.md', '.agents/skills/README.md');
|
|
@@ -301,7 +334,7 @@ ${agentSectionEnd}`;
|
|
|
301
334
|
const current = await readFile(readmePath, 'utf8');
|
|
302
335
|
|
|
303
336
|
if (current.includes(skillName)) {
|
|
304
|
-
this.note(
|
|
337
|
+
this.note(`${readmeDisplay} already lists the Code-Anchored Context skill`);
|
|
305
338
|
return;
|
|
306
339
|
}
|
|
307
340
|
|
|
@@ -309,33 +342,82 @@ ${agentSectionEnd}`;
|
|
|
309
342
|
'',
|
|
310
343
|
'## Code-Anchored Context',
|
|
311
344
|
'',
|
|
312
|
-
`- \`${skillName}\` - use central \`
|
|
345
|
+
`- \`${skillName}\` - use central \`context/\` initiatives for planning, implementation context, programs, planned initiatives, ADRs, backlog, and release-documentation notes.`,
|
|
313
346
|
''
|
|
314
347
|
].join('\n');
|
|
315
348
|
|
|
316
349
|
await this.writeFile(
|
|
317
350
|
readmePath,
|
|
318
351
|
`${current.trimEnd()}\n${entry}`,
|
|
319
|
-
|
|
352
|
+
`append Code-Anchored Context skill to ${readmeDisplay}`
|
|
320
353
|
);
|
|
321
354
|
}
|
|
322
355
|
|
|
323
356
|
async copyTemplatePath(sourceRelative, targetRelative) {
|
|
324
357
|
const sourcePath = path.join(packageRoot, sourceRelative);
|
|
358
|
+
const targetInfo = await this.findExistingTargetPath(targetRelative);
|
|
325
359
|
const targetPath = path.join(this.targetRoot, targetRelative);
|
|
326
360
|
|
|
327
|
-
if (
|
|
361
|
+
if (targetInfo.exists) {
|
|
362
|
+
const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
|
|
363
|
+
|
|
328
364
|
if (!this.force) {
|
|
329
|
-
this.note(`skip ${targetRelative} (already exists; use --force to replace)`);
|
|
365
|
+
this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
|
|
330
366
|
return;
|
|
331
367
|
}
|
|
332
368
|
|
|
333
|
-
await this.removePath(
|
|
369
|
+
await this.removePath(targetInfo.path, `replace ${targetInfo.display}`);
|
|
334
370
|
}
|
|
335
371
|
|
|
336
372
|
await this.copyRecursive(sourcePath, targetPath, targetRelative);
|
|
337
373
|
}
|
|
338
374
|
|
|
375
|
+
async findExistingTargetPath(targetRelative) {
|
|
376
|
+
const parts = targetRelative.split('/').filter(Boolean);
|
|
377
|
+
let currentPath = this.targetRoot;
|
|
378
|
+
const displayParts = [];
|
|
379
|
+
|
|
380
|
+
for (const part of parts) {
|
|
381
|
+
let entries;
|
|
382
|
+
|
|
383
|
+
try {
|
|
384
|
+
entries = await readdir(currentPath, { withFileTypes: true });
|
|
385
|
+
} catch {
|
|
386
|
+
return this.missingTargetPath(targetRelative);
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
const exactMatch = entries.find((entry) => entry.name === part);
|
|
390
|
+
const caseMatch = exactMatch ?? entries.find(
|
|
391
|
+
(entry) => entry.name.toLowerCase() === part.toLowerCase()
|
|
392
|
+
);
|
|
393
|
+
|
|
394
|
+
if (!caseMatch) {
|
|
395
|
+
return this.missingTargetPath(targetRelative);
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
currentPath = path.join(currentPath, caseMatch.name);
|
|
399
|
+
displayParts.push(caseMatch.name);
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
const display = displayParts.join('/');
|
|
403
|
+
|
|
404
|
+
return {
|
|
405
|
+
caseVariant: display !== targetRelative,
|
|
406
|
+
display,
|
|
407
|
+
exists: true,
|
|
408
|
+
path: currentPath
|
|
409
|
+
};
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
missingTargetPath(targetRelative) {
|
|
413
|
+
return {
|
|
414
|
+
caseVariant: false,
|
|
415
|
+
display: targetRelative,
|
|
416
|
+
exists: false,
|
|
417
|
+
path: path.join(this.targetRoot, targetRelative)
|
|
418
|
+
};
|
|
419
|
+
}
|
|
420
|
+
|
|
339
421
|
async copyRecursive(sourcePath, targetPath, displayPath) {
|
|
340
422
|
if (this.shouldSkipTemplatePath(displayPath)) {
|
|
341
423
|
this.note(`skip ${displayPath} (template repository context)`);
|
|
@@ -369,7 +451,7 @@ ${agentSectionEnd}`;
|
|
|
369
451
|
}
|
|
370
452
|
|
|
371
453
|
shouldSkipTemplatePath(displayPath) {
|
|
372
|
-
const initiativePrefix = `
|
|
454
|
+
const initiativePrefix = `context/releases/${defaultRelease}/initiatives/`;
|
|
373
455
|
|
|
374
456
|
return (
|
|
375
457
|
displayPath.startsWith(initiativePrefix) &&
|
|
@@ -378,11 +460,11 @@ ${agentSectionEnd}`;
|
|
|
378
460
|
}
|
|
379
461
|
|
|
380
462
|
transformText(contents, displayPath) {
|
|
381
|
-
if (displayPath === '
|
|
463
|
+
if (displayPath === 'context/current.md') {
|
|
382
464
|
return this.renderStarterCurrent();
|
|
383
465
|
}
|
|
384
466
|
|
|
385
|
-
if (displayPath === `
|
|
467
|
+
if (displayPath === `context/releases/${defaultRelease}/backlog.md`) {
|
|
386
468
|
return this.renderStarterReleaseBacklog();
|
|
387
469
|
}
|
|
388
470
|
|
|
@@ -394,7 +476,7 @@ ${agentSectionEnd}`;
|
|
|
394
476
|
}
|
|
395
477
|
|
|
396
478
|
renderStarterCurrent() {
|
|
397
|
-
return `# Current
|
|
479
|
+
return `# Current Context
|
|
398
480
|
|
|
399
481
|
Current release: \`${this.release}\`
|
|
400
482
|
|
|
@@ -421,8 +503,8 @@ Registered initiatives:
|
|
|
421
503
|
|
|
422
504
|
- None yet.
|
|
423
505
|
|
|
424
|
-
To start an initiative, copy \`
|
|
425
|
-
\`
|
|
506
|
+
To start an initiative, copy \`context/_templates/initiative/\` into
|
|
507
|
+
\`context/releases/${this.release}/initiatives/<initiative-slug>/\`, then update the
|
|
426
508
|
copied \`README.md\` first so agents have a clear entry point before editing the
|
|
427
509
|
supporting files.
|
|
428
510
|
`;
|
|
@@ -431,7 +513,7 @@ supporting files.
|
|
|
431
513
|
renderStarterReleaseBacklog() {
|
|
432
514
|
return `# ${this.releaseLabel()} Backlog
|
|
433
515
|
|
|
434
|
-
This file tracks release-level
|
|
516
|
+
This file tracks release-level working context that is not yet captured
|
|
435
517
|
by an initiative, plus a short summary of initiative progress once
|
|
436
518
|
initiatives exist.
|
|
437
519
|
|
|
@@ -455,15 +537,15 @@ No initiatives registered yet.
|
|
|
455
537
|
}
|
|
456
538
|
|
|
457
539
|
await this.renamePath(
|
|
458
|
-
path.join(this.targetRoot, '
|
|
459
|
-
path.join(this.targetRoot, '
|
|
460
|
-
`rename
|
|
540
|
+
path.join(this.targetRoot, 'context/releases', defaultRelease),
|
|
541
|
+
path.join(this.targetRoot, 'context/releases', this.release),
|
|
542
|
+
`rename context/releases/${defaultRelease} to context/releases/${this.release}`
|
|
461
543
|
);
|
|
462
544
|
|
|
463
545
|
await this.renamePath(
|
|
464
|
-
path.join(this.targetRoot, '
|
|
465
|
-
path.join(this.targetRoot, '
|
|
466
|
-
`rename
|
|
546
|
+
path.join(this.targetRoot, 'context/_templates/program/releases', `${defaultRelease}.md`),
|
|
547
|
+
path.join(this.targetRoot, 'context/_templates/program/releases', `${this.release}.md`),
|
|
548
|
+
`rename context/_templates/program/releases/${defaultRelease}.md to ${this.release}.md`
|
|
467
549
|
);
|
|
468
550
|
}
|
|
469
551
|
|
|
@@ -533,7 +615,7 @@ No initiatives registered yet.
|
|
|
533
615
|
console.log(`${prefix}Code-Anchored Context ready for ${this.projectName}.`);
|
|
534
616
|
|
|
535
617
|
if (!this.dryRun) {
|
|
536
|
-
console.log(`Next: ask your agent to read ${
|
|
618
|
+
console.log(`Next: ask your agent to read ${this.agentsFilePath}.`);
|
|
537
619
|
}
|
|
538
620
|
}
|
|
539
621
|
}
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# Agent Guidance -
|
|
1
|
+
# Agent Guidance - context/
|
|
2
2
|
|
|
3
|
-
Scope: everything under `/
|
|
3
|
+
Scope: everything under `/context`.
|
|
4
4
|
|
|
5
5
|
## Purpose
|
|
6
6
|
|
|
7
|
-
This folder is the canonical home for in-progress
|
|
7
|
+
This folder is the canonical home for in-progress working context: specs,
|
|
8
8
|
interface notes, architecture notes, actionable operations notes, ADRs,
|
|
9
9
|
backlogs, implementation plans, and release-documentation notes.
|
|
10
10
|
|
|
@@ -13,30 +13,30 @@ work is verified, shipped, deployed, or hosted. Operational notes belong here
|
|
|
13
13
|
only when they are actionable runtime, support, observability, rollback, or
|
|
14
14
|
repair context.
|
|
15
15
|
|
|
16
|
-
`
|
|
17
|
-
`
|
|
16
|
+
`context/` describes what is being planned, built, debated, or validated.
|
|
17
|
+
`docs/` describes what has shipped for a release.
|
|
18
18
|
|
|
19
19
|
## Editing Rules
|
|
20
20
|
|
|
21
|
-
- Use `
|
|
21
|
+
- Use `context/terminology.md` as the canonical vocabulary for programs,
|
|
22
22
|
planned initiatives, release initiatives, backlog items, and promotion.
|
|
23
23
|
- Keep initiative knowledge centralized here. Area `AGENTS.md` files may point
|
|
24
24
|
here, but they should not duplicate initiative content.
|
|
25
|
-
- Do not move in-progress plans into `
|
|
25
|
+
- Do not move in-progress plans into `docs/`.
|
|
26
26
|
- Use `release-doc-notes.md` inside an initiative to capture what may need to
|
|
27
27
|
become product documentation later.
|
|
28
|
-
- Create initiatives from `
|
|
29
|
-
- Create durable multi-release programs from `
|
|
28
|
+
- Create initiatives from `context/_templates/initiative/`.
|
|
29
|
+
- Create durable multi-release programs from `context/_templates/program/`.
|
|
30
30
|
- Create scoped future program work from
|
|
31
|
-
`
|
|
31
|
+
`context/_templates/planned-initiative/` under a program's
|
|
32
32
|
`planned-initiatives/` folder.
|
|
33
33
|
- Create deferred isolated backlog items from
|
|
34
|
-
`
|
|
34
|
+
`context/_templates/backlog-item.md`.
|
|
35
35
|
- Keep release initiative history in the release folder. Use `programs/` for
|
|
36
36
|
multi-release context, `planned-initiatives/` for scoped future program work,
|
|
37
37
|
and `backlog/items/` for isolated deferred work.
|
|
38
|
-
- Treat changes to `
|
|
39
|
-
`
|
|
38
|
+
- Treat changes to `context/current.md` as release transitions. Use
|
|
39
|
+
`context/_templates/release-transition.md` and promote matching planned
|
|
40
40
|
initiatives for the new current release.
|
|
41
41
|
- When a backlog item is picked up later, mark it as promoted and link to the
|
|
42
42
|
new release initiative instead of rewriting the item into an active plan.
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# context/
|
|
2
2
|
|
|
3
|
-
This folder is the working memory for active and historical
|
|
4
|
-
|
|
3
|
+
This folder is the working memory for active and historical context in this
|
|
4
|
+
repository.
|
|
5
5
|
|
|
6
6
|
Use it for specs, interface notes, architecture notes, testing notes, delivery
|
|
7
7
|
notes, infrastructure notes, actionable operations notes, ADRs, backlog items,
|
|
8
8
|
implementation plans, and release-documentation notes. Do not use
|
|
9
|
-
`
|
|
9
|
+
`docs/` for in-progress development planning.
|
|
10
10
|
|
|
11
11
|
## Start Here
|
|
12
12
|
|
|
@@ -16,24 +16,24 @@ implementation plans, and release-documentation notes. Do not use
|
|
|
16
16
|
Code-Anchored Context for human-agent collaboration.
|
|
17
17
|
- `terminology.md` defines the shared vocabulary.
|
|
18
18
|
- `current.md` points to the active release context.
|
|
19
|
-
- `programs/` contains durable multi-release
|
|
19
|
+
- `programs/` contains durable multi-release working context.
|
|
20
20
|
- `backlog/` contains deferred isolated work cut from initiatives.
|
|
21
|
-
- `releases/` contains release-scoped
|
|
21
|
+
- `releases/` contains release-scoped working context.
|
|
22
22
|
- `_templates/initiative/` contains the standard initiative shape.
|
|
23
23
|
- `_templates/planned-initiative/` contains the standard future initiative
|
|
24
24
|
shape for scoped program work outside the current release.
|
|
25
25
|
- `_templates/release-context/` contains the standard release folder shell.
|
|
26
26
|
|
|
27
|
-
## Relationship To
|
|
27
|
+
## Relationship To docs/
|
|
28
28
|
|
|
29
|
-
`
|
|
29
|
+
`context/` and `docs/` serve different jobs:
|
|
30
30
|
|
|
31
31
|
| Folder | Meaning | Updated when |
|
|
32
32
|
| --- | --- | --- |
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
33
|
+
| `context/` | What we are planning, building, deciding, or validating. | During normal development. |
|
|
34
|
+
| `docs/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
Working context can feed release documentation, but it is not product
|
|
37
37
|
documentation. Capture that bridge in each initiative's
|
|
38
38
|
`release-doc-notes.md`.
|
|
39
39
|
|
|
@@ -50,16 +50,16 @@ Some context needs to outlive a single release initiative:
|
|
|
50
50
|
|
|
51
51
|
| Place | Use for |
|
|
52
52
|
| --- | --- |
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
53
|
+
| `context/programs/` | Long-lived multi-release efforts, phase history, roadmaps, and durable decisions. |
|
|
54
|
+
| `context/programs/<program>/planned-initiatives/` | Scoped future delivery slices that belong to a program but are not in the current release yet. |
|
|
55
|
+
| `context/backlog/items/` | Deferred isolated work cut from an initiative but worth preserving. |
|
|
56
|
+
| `context/releases/<version>/initiatives/` | Release-scoped delivery slices and historical implementation context. |
|
|
57
57
|
|
|
58
58
|
The rule is:
|
|
59
59
|
|
|
60
60
|
> Active work belongs in a release initiative. Multi-release context belongs in
|
|
61
61
|
> a program. Scoped future program work belongs in a planned initiative.
|
|
62
|
-
> Deferred isolated work belongs in the
|
|
62
|
+
> Deferred isolated work belongs in the context backlog.
|
|
63
63
|
|
|
64
64
|
The delivery-surface rule is:
|
|
65
65
|
|
|
@@ -82,7 +82,7 @@ not copy specs, plans, or ADRs into area-local documents.
|
|
|
82
82
|
## Standard Layout
|
|
83
83
|
|
|
84
84
|
```text
|
|
85
|
-
|
|
85
|
+
context/
|
|
86
86
|
current.md
|
|
87
87
|
programs/
|
|
88
88
|
<program-slug>/
|
|
@@ -140,11 +140,11 @@ Release initiatives should link to their program when one exists. Programs
|
|
|
140
140
|
should link back to the release initiatives that delivered each slice.
|
|
141
141
|
|
|
142
142
|
Do not use a program for a small leftover task. Use
|
|
143
|
-
`
|
|
143
|
+
`context/backlog/items/` for deferred isolated work.
|
|
144
144
|
|
|
145
|
-
##
|
|
145
|
+
## Context Backlog
|
|
146
146
|
|
|
147
|
-
Use `
|
|
147
|
+
Use `context/backlog/items/` for isolated work that was taken out of an
|
|
148
148
|
initiative's scope but should be kept for later. Each backlog item records its
|
|
149
149
|
origin initiative and release.
|
|
150
150
|
|
|
@@ -214,23 +214,23 @@ Use when relevant:
|
|
|
214
214
|
When an initiative produces context that needs to survive after the release:
|
|
215
215
|
|
|
216
216
|
- Move multi-release strategy, roadmap, and durable decisions into
|
|
217
|
-
`
|
|
217
|
+
`context/programs/<program-slug>/`.
|
|
218
218
|
- Move scoped future delivery slices into
|
|
219
|
-
`
|
|
219
|
+
`context/programs/<program-slug>/planned-initiatives/<initiative-slug>/`.
|
|
220
220
|
- Move isolated deferred work into
|
|
221
|
-
`
|
|
221
|
+
`context/backlog/items/<originating-initiative-slug>--<item-slug>.md`.
|
|
222
222
|
- Keep release-scoped plans, implementation history, and final release notes
|
|
223
223
|
inside the original initiative.
|
|
224
224
|
|
|
225
225
|
## Changing The Current Release
|
|
226
226
|
|
|
227
|
-
Changing `
|
|
228
|
-
edit. Use `
|
|
229
|
-
Create missing release folders from `
|
|
227
|
+
Changing `context/current.md` is a release transition, not just a line
|
|
228
|
+
edit. Use `context/_templates/release-transition.md` as the checklist.
|
|
229
|
+
Create missing release folders from `context/_templates/release-context/`.
|
|
230
230
|
|
|
231
231
|
When setting a release as current, agents should scan all program planned
|
|
232
232
|
initiatives for matching `Target release:` metadata and promote matching items
|
|
233
|
-
into `
|
|
233
|
+
into `context/releases/<version>/initiatives/`.
|
|
234
234
|
|
|
235
235
|
The promotion rule is:
|
|
236
236
|
|
|
@@ -241,7 +241,7 @@ The promotion rule is:
|
|
|
241
241
|
When changing behavior, agents should:
|
|
242
242
|
|
|
243
243
|
1. Read the local `AGENTS.md`.
|
|
244
|
-
2. Open `
|
|
244
|
+
2. Open `context/current.md`.
|
|
245
245
|
3. Check the current release's initiatives for matching context.
|
|
246
246
|
4. Use `plan.md` for live alignment, open questions, and rough thinking.
|
|
247
247
|
Promote settled conclusions into the stable initiative files.
|
|
@@ -251,7 +251,7 @@ When changing behavior, agents should:
|
|
|
251
251
|
7. Create or update a program planned initiative when future scoped work is
|
|
252
252
|
clear but belongs outside the current release.
|
|
253
253
|
8. Record future product-doc impact in `release-doc-notes.md`, not in
|
|
254
|
-
`
|
|
254
|
+
`docs/`, unless a human explicitly asks for documentation refresh.
|
|
255
255
|
|
|
256
256
|
The key rule for planning is:
|
|
257
257
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Backlog Item Title
|
|
2
2
|
|
|
3
3
|
Status: Candidate
|
|
4
|
-
Originating initiative: `
|
|
4
|
+
Originating initiative: `context/releases/v0_1_0/initiatives/<initiative-slug>/`
|
|
5
5
|
Originating release: `v0_1_0`
|
|
6
6
|
Area: TBD
|
|
7
7
|
Reason deferred: TBD
|
|
@@ -35,6 +35,6 @@ section and leave the item as a historical record.
|
|
|
35
35
|
|
|
36
36
|
```md
|
|
37
37
|
Status: Promoted
|
|
38
|
-
Promoted to: `
|
|
38
|
+
Promoted to: `context/releases/<version>/initiatives/<initiative-slug>/`
|
|
39
39
|
```
|
|
40
40
|
|
|
@@ -12,11 +12,15 @@ produce.
|
|
|
12
12
|
|
|
13
13
|
## Touched Areas
|
|
14
14
|
|
|
15
|
-
- `
|
|
16
|
-
- `
|
|
17
|
-
- `
|
|
15
|
+
- Product or runtime code: `path/to/...`
|
|
16
|
+
- Interfaces, APIs, or contracts: `path/to/...`
|
|
17
|
+
- Tests or verification: `path/to/...`
|
|
18
|
+
- Delivery, CI/CD, build, or artifacts: `path/to/...`
|
|
19
|
+
- Infrastructure, IaC, or environment config: `path/to/...`
|
|
20
|
+
- Docs or release notes: `path/to/...`
|
|
18
21
|
|
|
19
|
-
Remove entries that do not apply and add the real paths.
|
|
22
|
+
Remove entries that do not apply and add the real paths. Prefer naming the
|
|
23
|
+
delivery concern over assuming a specific folder layout.
|
|
20
24
|
|
|
21
25
|
## Current Source Of Truth
|
|
22
26
|
|
|
@@ -55,5 +59,5 @@ support, observability, rollback, or repair context.
|
|
|
55
59
|
Promote settled conclusions into the stable initiative files.
|
|
56
60
|
- Update `release-doc-notes.md` when shipped behavior or product-facing
|
|
57
61
|
behavior changes.
|
|
58
|
-
- Do not update `
|
|
62
|
+
- Do not update `docs/` from this initiative unless a human
|
|
59
63
|
explicitly asks for release documentation work.
|
|
@@ -19,10 +19,10 @@
|
|
|
19
19
|
Use this section only for work deferred within the active initiative.
|
|
20
20
|
|
|
21
21
|
If a deferred item should outlive this initiative as future isolated work,
|
|
22
|
-
create a backlog item from `
|
|
22
|
+
create a backlog item from `context/_templates/backlog-item.md` under:
|
|
23
23
|
|
|
24
24
|
```text
|
|
25
|
-
|
|
25
|
+
context/backlog/items/<originating-initiative-slug>--<item-slug>.md
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
- None yet.
|
|
@@ -51,7 +51,7 @@ the canonical initiative files.
|
|
|
51
51
|
- [ ] Move settled environment and IaC context into `infrastructure.md`
|
|
52
52
|
- [ ] Move actionable runtime/support concerns into `operations.md`
|
|
53
53
|
- [ ] Move executable work into `backlog.md`
|
|
54
|
-
- [ ] Move multi-release context into `
|
|
55
|
-
- [ ] Move isolated deferred work into `
|
|
54
|
+
- [ ] Move multi-release context into `context/programs/`
|
|
55
|
+
- [ ] Move isolated deferred work into `context/backlog/items/`
|
|
56
56
|
- [ ] Move durable decisions into `decisions/`
|
|
57
57
|
- [ ] Move product-documentation impact into `release-doc-notes.md`
|
|
@@ -1,20 +1,20 @@
|
|
|
1
|
-
# Release
|
|
1
|
+
# Release Doc Notes
|
|
2
2
|
|
|
3
3
|
Use this file to capture product-documentation impact while development is
|
|
4
|
-
in progress. At release time, these notes help refresh `
|
|
4
|
+
in progress. At release time, these notes help refresh `docs/`
|
|
5
5
|
against the final shipped behavior.
|
|
6
6
|
|
|
7
|
-
Do not edit `
|
|
7
|
+
Do not edit `docs/` from normal development work unless a human
|
|
8
8
|
explicitly asks for a documentation refresh or a specific documentation fix.
|
|
9
9
|
|
|
10
10
|
## Product Behavior Changes
|
|
11
11
|
|
|
12
12
|
- None yet.
|
|
13
13
|
|
|
14
|
-
## Candidate
|
|
14
|
+
## Candidate Docs Areas
|
|
15
15
|
|
|
16
|
-
- `
|
|
17
|
-
- `
|
|
16
|
+
- `docs/<Area>/README.md`
|
|
17
|
+
- `docs/<Area>/features/<feature>.md`
|
|
18
18
|
|
|
19
19
|
## QA Or Support Notes
|
|
20
20
|
|