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.
Files changed (70) hide show
  1. package/.agents/skills/README.md +1 -1
  2. package/.agents/skills/{development-initiative-context → code-anchored-context}/SKILL.md +38 -38
  3. package/AGENTS.md +15 -13
  4. package/README.md +14 -14
  5. package/bin/code-anchored-context.js +125 -43
  6. package/{Development → context}/AGENTS.md +13 -13
  7. package/{Development → context}/README.md +29 -29
  8. package/{Development → context}/_templates/backlog-item.md +2 -2
  9. package/{Development → context}/_templates/initiative/README.md +9 -5
  10. package/{Development → context}/_templates/initiative/backlog.md +2 -2
  11. package/{Development → context}/_templates/initiative/plan.md +2 -2
  12. package/{Development → context}/_templates/initiative/release-doc-notes.md +6 -6
  13. package/{Development → context}/_templates/planned-initiative/README.md +10 -6
  14. package/{Development → context}/_templates/planned-initiative/release-doc-notes.md +5 -5
  15. package/{Development → context}/_templates/program/README.md +1 -1
  16. package/{Development → context}/_templates/program/backlog.md +1 -1
  17. package/{Development → context}/_templates/program/releases/v0_1_0.md +1 -1
  18. package/{Development → context}/_templates/release-context/README.md +6 -6
  19. package/{Development → context}/_templates/release-context/backlog.md +1 -2
  20. package/{Development → context}/_templates/release-transition.md +7 -7
  21. package/{Development → context}/backlog/README.md +3 -3
  22. package/{Development → context}/code-anchored-context-structure.md +16 -15
  23. package/{Development → context}/code-anchored-context-why.md +8 -8
  24. package/{Development → context}/code-anchored-context.html +20 -20
  25. package/{Development → context}/current.md +3 -3
  26. package/{Development → context}/giving-ai-agents-context-around-code.md +32 -32
  27. package/{Development → context}/programs/README.md +2 -2
  28. package/{Development → context}/releases/v0_1_0/README.md +6 -6
  29. package/{Development → context}/releases/v0_1_0/backlog.md +1 -1
  30. package/{Development → context}/terminology.md +22 -22
  31. package/{Documentation → docs}/Welcome.md +11 -6
  32. package/{Documentation → docs}/_authoring/README.md +6 -5
  33. package/{Documentation → docs}/_authoring/areas/README.md +1 -1
  34. package/{Documentation → docs}/_authoring/areas/_template.md +19 -5
  35. package/{Documentation → docs}/_authoring/terminology.md +1 -1
  36. package/docs/_authoring/workflow.md +210 -0
  37. package/docs/_templates/area/README.md +58 -0
  38. package/docs/_templates/area/features/feature-template.md +71 -0
  39. package/{Documentation → docs}/releases/index.md +3 -1
  40. package/package.json +19 -18
  41. package/Documentation/_authoring/workflow.md +0 -123
  42. package/Documentation/_templates/area/README.md +0 -20
  43. package/Documentation/_templates/area/features/feature-template.md +0 -29
  44. /package/{Development → context}/_templates/initiative/architecture.md +0 -0
  45. /package/{Development → context}/_templates/initiative/brief.html +0 -0
  46. /package/{Development → context}/_templates/initiative/decisions/ADR-0000-template.md +0 -0
  47. /package/{Development → context}/_templates/initiative/delivery.md +0 -0
  48. /package/{Development → context}/_templates/initiative/infrastructure.md +0 -0
  49. /package/{Development → context}/_templates/initiative/interface.md +0 -0
  50. /package/{Development → context}/_templates/initiative/operations.md +0 -0
  51. /package/{Development → context}/_templates/initiative/spec.md +0 -0
  52. /package/{Development → context}/_templates/initiative/testing.md +0 -0
  53. /package/{Development → context}/_templates/planned-initiative/architecture.md +0 -0
  54. /package/{Development → context}/_templates/planned-initiative/backlog.md +0 -0
  55. /package/{Development → context}/_templates/planned-initiative/decisions/ADR-0000-template.md +0 -0
  56. /package/{Development → context}/_templates/planned-initiative/delivery.md +0 -0
  57. /package/{Development → context}/_templates/planned-initiative/infrastructure.md +0 -0
  58. /package/{Development → context}/_templates/planned-initiative/interface.md +0 -0
  59. /package/{Development → context}/_templates/planned-initiative/operations.md +0 -0
  60. /package/{Development → context}/_templates/planned-initiative/plan.md +0 -0
  61. /package/{Development → context}/_templates/planned-initiative/spec.md +0 -0
  62. /package/{Development → context}/_templates/planned-initiative/testing.md +0 -0
  63. /package/{Development → context}/_templates/program/context.md +0 -0
  64. /package/{Development → context}/_templates/program/decisions/ADR-0000-template.md +0 -0
  65. /package/{Development → context}/_templates/program/planned-initiatives/.gitkeep +0 -0
  66. /package/{Development → context}/_templates/program/roadmap.md +0 -0
  67. /package/{Development → context}/_templates/release-context/initiatives/.gitkeep +0 -0
  68. /package/{Development → context}/backlog/items/.gitkeep +0 -0
  69. /package/{Development → context}/releases/v0_1_0/initiatives/.gitkeep +0 -0
  70. /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 = 'development-initiative-context';
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({ includeDocumentation: args.documentation });
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
- documentation: true,
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-documentation') {
99
- options.documentation = false;
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-documentation Skip the Documentation/ starter files.
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-documentation
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({ includeDocumentation }) {
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('Development', 'Development');
223
+ await this.copyTemplatePath('context', 'context');
223
224
  await this.renameReleasePaths();
224
225
 
225
- if (includeDocumentation) {
226
- await this.copyTemplatePath('Documentation', 'Documentation');
226
+ if (includeDocs) {
227
+ await this.copyTemplatePath('docs', 'docs');
227
228
  } else {
228
- this.note('skip Documentation/ (--no-documentation)');
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 = path.join(this.targetRoot, 'AGENTS.md');
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('AGENTS.md already has Code-Anchored Context guidance');
256
+ this.note(`${targetDisplay} already has Code-Anchored Context guidance`);
253
257
  return;
254
258
  }
255
259
 
256
- await this.writeFile(targetFile, updated, 'update AGENTS.md Code-Anchored Context section');
260
+ await this.writeFile(targetFile, updated, `update ${targetDisplay} Code-Anchored Context section`);
257
261
  return;
258
262
  }
259
263
 
260
- if (current.includes('.agents/skills/development-initiative-context/SKILL.md')) {
261
- this.note('AGENTS.md already points to the development initiative skill');
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
- 'append Code-Anchored Context guidance to AGENTS.md'
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 [\`Development/\`](Development/).
279
- Start with [\`Development/current.md\`](Development/current.md).
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/development-initiative-context/SKILL.md\`](.agents/skills/development-initiative-context/SKILL.md).
283
- Keep initiative knowledge centralized under \`Development/\`; area
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 readmePath = path.join(this.targetRoot, '.agents/skills/README.md');
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('.agents/skills/README.md already lists the development initiative skill');
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 \`Development/\` initiatives for planning, implementation context, programs, planned initiatives, ADRs, backlog, and release-documentation notes.`,
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
- 'append development initiative skill to .agents/skills/README.md'
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 (await exists(targetPath)) {
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(targetPath, `replace ${targetRelative}`);
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 = `Development/releases/${defaultRelease}/initiatives/`;
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 === 'Development/current.md') {
463
+ if (displayPath === 'context/current.md') {
382
464
  return this.renderStarterCurrent();
383
465
  }
384
466
 
385
- if (displayPath === `Development/releases/${defaultRelease}/backlog.md`) {
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 Development Context
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 \`Development/_templates/initiative/\` into
425
- \`Development/releases/${this.release}/initiatives/<initiative-slug>/\`, then update the
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 development context that is not yet captured
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, 'Development/releases', defaultRelease),
459
- path.join(this.targetRoot, 'Development/releases', this.release),
460
- `rename Development/releases/${defaultRelease} to Development/releases/${this.release}`
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, 'Development/_templates/program/releases', `${defaultRelease}.md`),
465
- path.join(this.targetRoot, 'Development/_templates/program/releases', `${this.release}.md`),
466
- `rename Development/_templates/program/releases/${defaultRelease}.md to ${this.release}.md`
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 ${path.join(this.targetRoot, 'AGENTS.md')}.`);
618
+ console.log(`Next: ask your agent to read ${this.agentsFilePath}.`);
537
619
  }
538
620
  }
539
621
  }
@@ -1,10 +1,10 @@
1
- # Agent Guidance - Development
1
+ # Agent Guidance - context/
2
2
 
3
- Scope: everything under `/Development`.
3
+ Scope: everything under `/context`.
4
4
 
5
5
  ## Purpose
6
6
 
7
- This folder is the canonical home for in-progress development context: specs,
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
- `Development/` describes what is being planned, built, debated, or validated.
17
- `Documentation/` describes what has shipped for a release.
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 `Development/terminology.md` as the canonical vocabulary for programs,
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 `Documentation/`.
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 `Development/_templates/initiative/`.
29
- - Create durable multi-release programs from `Development/_templates/program/`.
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
- `Development/_templates/planned-initiative/` under a program's
31
+ `context/_templates/planned-initiative/` under a program's
32
32
  `planned-initiatives/` folder.
33
33
  - Create deferred isolated backlog items from
34
- `Development/_templates/backlog-item.md`.
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 `Development/current.md` as release transitions. Use
39
- `Development/_templates/release-transition.md` and promote matching planned
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
- # Development
1
+ # context/
2
2
 
3
- This folder is the working memory for active and historical development
4
- context in this repository.
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
- `Documentation/` for in-progress development planning.
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 development context.
19
+ - `programs/` contains durable multi-release working context.
20
20
  - `backlog/` contains deferred isolated work cut from initiatives.
21
- - `releases/` contains release-scoped development context.
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 Documentation
27
+ ## Relationship To docs/
28
28
 
29
- `Development/` and `Documentation/` serve different jobs:
29
+ `context/` and `docs/` serve different jobs:
30
30
 
31
31
  | Folder | Meaning | Updated when |
32
32
  | --- | --- | --- |
33
- | `Development/` | What we are planning, building, deciding, or validating. | During normal development. |
34
- | `Documentation/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
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
- Development notes can feed release documentation, but they are not product
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
- | `Development/programs/` | Long-lived multi-release efforts, phase history, roadmaps, and durable decisions. |
54
- | `Development/programs/<program>/planned-initiatives/` | Scoped future delivery slices that belong to a program but are not in the current release yet. |
55
- | `Development/backlog/items/` | Deferred isolated work cut from an initiative but worth preserving. |
56
- | `Development/releases/<version>/initiatives/` | Release-scoped delivery slices and historical implementation context. |
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 development backlog.
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
- Development/
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
- `Development/backlog/items/` for deferred isolated work.
143
+ `context/backlog/items/` for deferred isolated work.
144
144
 
145
- ## Development Backlog
145
+ ## Context Backlog
146
146
 
147
- Use `Development/backlog/items/` for isolated work that was taken out of an
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
- `Development/programs/<program-slug>/`.
217
+ `context/programs/<program-slug>/`.
218
218
  - Move scoped future delivery slices into
219
- `Development/programs/<program-slug>/planned-initiatives/<initiative-slug>/`.
219
+ `context/programs/<program-slug>/planned-initiatives/<initiative-slug>/`.
220
220
  - Move isolated deferred work into
221
- `Development/backlog/items/<originating-initiative-slug>--<item-slug>.md`.
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 `Development/current.md` is a release transition, not just a line
228
- edit. Use `Development/_templates/release-transition.md` as the checklist.
229
- Create missing release folders from `Development/_templates/release-context/`.
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 `Development/releases/<version>/initiatives/`.
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 `Development/current.md`.
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
- `Documentation/`, unless a human explicitly asks for documentation refresh.
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: `Development/releases/v0_1_0/initiatives/<initiative-slug>/`
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: `Development/releases/<version>/initiatives/<initiative-slug>/`
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
- - `src/<area>/...`
16
- - `deploy/...`
17
- - `automation/...`
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 `Documentation/` from this initiative unless a human
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 `Development/_templates/backlog-item.md` under:
22
+ create a backlog item from `context/_templates/backlog-item.md` under:
23
23
 
24
24
  ```text
25
- Development/backlog/items/<originating-initiative-slug>--<item-slug>.md
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 `Development/programs/`
55
- - [ ] Move isolated deferred work into `Development/backlog/items/`
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 Documentation Notes
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 `Documentation/`
4
+ in progress. At release time, these notes help refresh `docs/`
5
5
  against the final shipped behavior.
6
6
 
7
- Do not edit `Documentation/` from normal development work unless a human
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 Documentation Areas
14
+ ## Candidate Docs Areas
15
15
 
16
- - `Documentation/<Area>/README.md`
17
- - `Documentation/<Area>/features/<feature>.md`
16
+ - `docs/<Area>/README.md`
17
+ - `docs/<Area>/features/<feature>.md`
18
18
 
19
19
  ## QA Or Support Notes
20
20