code-anchored-context 0.1.1 → 0.2.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/.agents/skills/README.md +1 -1
- package/.agents/skills/{development-initiative-context → code-anchored-context}/SKILL.md +38 -38
- package/AGENTS.md +13 -13
- package/README.md +14 -14
- package/bin/code-anchored-context.js +34 -34
- package/{Development → context}/AGENTS.md +13 -13
- package/{Development → context}/README.md +29 -33
- package/{Development → context}/_templates/backlog-item.md +2 -2
- package/{Development → context}/_templates/initiative/README.md +2 -2
- 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 +3 -3
- 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}/current.md +3 -3
- 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 +6 -6
- package/{Documentation → docs}/_authoring/README.md +4 -4
- package/{Documentation → docs}/_authoring/areas/README.md +1 -1
- package/{Documentation → docs}/_authoring/areas/_template.md +4 -4
- package/{Documentation → docs}/_authoring/terminology.md +1 -1
- package/{Documentation → docs}/_authoring/workflow.md +22 -22
- package/{Documentation → docs}/releases/index.md +1 -1
- package/package.json +16 -19
- package/Development/code-anchored-context-structure.md +0 -133
- package/Development/code-anchored-context-why.md +0 -80
- package/Development/code-anchored-context.html +0 -830
- package/Development/giving-ai-agents-context-around-code.md +0 -496
- /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
- /package/{Documentation → docs}/_templates/area/README.md +0 -0
- /package/{Documentation → docs}/_templates/area/features/feature-template.md +0 -0
|
@@ -1,39 +1,35 @@
|
|
|
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
|
|
|
13
|
-
- `code-anchored-context.html` is a human-friendly visual brief for this
|
|
14
|
-
opinionated context practice.
|
|
15
|
-
- `giving-ai-agents-context-around-code.md` is an article-form explanation of
|
|
16
|
-
Code-Anchored Context for human-agent collaboration.
|
|
17
13
|
- `terminology.md` defines the shared vocabulary.
|
|
18
14
|
- `current.md` points to the active release context.
|
|
19
|
-
- `programs/` contains durable multi-release
|
|
15
|
+
- `programs/` contains durable multi-release working context.
|
|
20
16
|
- `backlog/` contains deferred isolated work cut from initiatives.
|
|
21
|
-
- `releases/` contains release-scoped
|
|
17
|
+
- `releases/` contains release-scoped working context.
|
|
22
18
|
- `_templates/initiative/` contains the standard initiative shape.
|
|
23
19
|
- `_templates/planned-initiative/` contains the standard future initiative
|
|
24
20
|
shape for scoped program work outside the current release.
|
|
25
21
|
- `_templates/release-context/` contains the standard release folder shell.
|
|
26
22
|
|
|
27
|
-
## Relationship To
|
|
23
|
+
## Relationship To docs/
|
|
28
24
|
|
|
29
|
-
`
|
|
25
|
+
`context/` and `docs/` serve different jobs:
|
|
30
26
|
|
|
31
27
|
| Folder | Meaning | Updated when |
|
|
32
28
|
| --- | --- | --- |
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
29
|
+
| `context/` | What we are planning, building, deciding, or validating. | During normal development. |
|
|
30
|
+
| `docs/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
|
|
35
31
|
|
|
36
|
-
|
|
32
|
+
Working context can feed release documentation, but it is not product
|
|
37
33
|
documentation. Capture that bridge in each initiative's
|
|
38
34
|
`release-doc-notes.md`.
|
|
39
35
|
|
|
@@ -50,16 +46,16 @@ Some context needs to outlive a single release initiative:
|
|
|
50
46
|
|
|
51
47
|
| Place | Use for |
|
|
52
48
|
| --- | --- |
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
49
|
+
| `context/programs/` | Long-lived multi-release efforts, phase history, roadmaps, and durable decisions. |
|
|
50
|
+
| `context/programs/<program>/planned-initiatives/` | Scoped future delivery slices that belong to a program but are not in the current release yet. |
|
|
51
|
+
| `context/backlog/items/` | Deferred isolated work cut from an initiative but worth preserving. |
|
|
52
|
+
| `context/releases/<version>/initiatives/` | Release-scoped delivery slices and historical implementation context. |
|
|
57
53
|
|
|
58
54
|
The rule is:
|
|
59
55
|
|
|
60
56
|
> Active work belongs in a release initiative. Multi-release context belongs in
|
|
61
57
|
> a program. Scoped future program work belongs in a planned initiative.
|
|
62
|
-
> Deferred isolated work belongs in the
|
|
58
|
+
> Deferred isolated work belongs in the context backlog.
|
|
63
59
|
|
|
64
60
|
The delivery-surface rule is:
|
|
65
61
|
|
|
@@ -82,7 +78,7 @@ not copy specs, plans, or ADRs into area-local documents.
|
|
|
82
78
|
## Standard Layout
|
|
83
79
|
|
|
84
80
|
```text
|
|
85
|
-
|
|
81
|
+
context/
|
|
86
82
|
current.md
|
|
87
83
|
programs/
|
|
88
84
|
<program-slug>/
|
|
@@ -140,11 +136,11 @@ Release initiatives should link to their program when one exists. Programs
|
|
|
140
136
|
should link back to the release initiatives that delivered each slice.
|
|
141
137
|
|
|
142
138
|
Do not use a program for a small leftover task. Use
|
|
143
|
-
`
|
|
139
|
+
`context/backlog/items/` for deferred isolated work.
|
|
144
140
|
|
|
145
|
-
##
|
|
141
|
+
## Context Backlog
|
|
146
142
|
|
|
147
|
-
Use `
|
|
143
|
+
Use `context/backlog/items/` for isolated work that was taken out of an
|
|
148
144
|
initiative's scope but should be kept for later. Each backlog item records its
|
|
149
145
|
origin initiative and release.
|
|
150
146
|
|
|
@@ -214,23 +210,23 @@ Use when relevant:
|
|
|
214
210
|
When an initiative produces context that needs to survive after the release:
|
|
215
211
|
|
|
216
212
|
- Move multi-release strategy, roadmap, and durable decisions into
|
|
217
|
-
`
|
|
213
|
+
`context/programs/<program-slug>/`.
|
|
218
214
|
- Move scoped future delivery slices into
|
|
219
|
-
`
|
|
215
|
+
`context/programs/<program-slug>/planned-initiatives/<initiative-slug>/`.
|
|
220
216
|
- Move isolated deferred work into
|
|
221
|
-
`
|
|
217
|
+
`context/backlog/items/<originating-initiative-slug>--<item-slug>.md`.
|
|
222
218
|
- Keep release-scoped plans, implementation history, and final release notes
|
|
223
219
|
inside the original initiative.
|
|
224
220
|
|
|
225
221
|
## Changing The Current Release
|
|
226
222
|
|
|
227
|
-
Changing `
|
|
228
|
-
edit. Use `
|
|
229
|
-
Create missing release folders from `
|
|
223
|
+
Changing `context/current.md` is a release transition, not just a line
|
|
224
|
+
edit. Use `context/_templates/release-transition.md` as the checklist.
|
|
225
|
+
Create missing release folders from `context/_templates/release-context/`.
|
|
230
226
|
|
|
231
227
|
When setting a release as current, agents should scan all program planned
|
|
232
228
|
initiatives for matching `Target release:` metadata and promote matching items
|
|
233
|
-
into `
|
|
229
|
+
into `context/releases/<version>/initiatives/`.
|
|
234
230
|
|
|
235
231
|
The promotion rule is:
|
|
236
232
|
|
|
@@ -241,7 +237,7 @@ The promotion rule is:
|
|
|
241
237
|
When changing behavior, agents should:
|
|
242
238
|
|
|
243
239
|
1. Read the local `AGENTS.md`.
|
|
244
|
-
2. Open `
|
|
240
|
+
2. Open `context/current.md`.
|
|
245
241
|
3. Check the current release's initiatives for matching context.
|
|
246
242
|
4. Use `plan.md` for live alignment, open questions, and rough thinking.
|
|
247
243
|
Promote settled conclusions into the stable initiative files.
|
|
@@ -251,7 +247,7 @@ When changing behavior, agents should:
|
|
|
251
247
|
7. Create or update a program planned initiative when future scoped work is
|
|
252
248
|
clear but belongs outside the current release.
|
|
253
249
|
8. Record future product-doc impact in `release-doc-notes.md`, not in
|
|
254
|
-
`
|
|
250
|
+
`docs/`, unless a human explicitly asks for documentation refresh.
|
|
255
251
|
|
|
256
252
|
The key rule for planning is:
|
|
257
253
|
|
|
@@ -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
|
|
|
@@ -17,7 +17,7 @@ produce.
|
|
|
17
17
|
- Tests or verification: `path/to/...`
|
|
18
18
|
- Delivery, CI/CD, build, or artifacts: `path/to/...`
|
|
19
19
|
- Infrastructure, IaC, or environment config: `path/to/...`
|
|
20
|
-
-
|
|
20
|
+
- Docs or release notes: `path/to/...`
|
|
21
21
|
|
|
22
22
|
Remove entries that do not apply and add the real paths. Prefer naming the
|
|
23
23
|
delivery concern over assuming a specific folder layout.
|
|
@@ -59,5 +59,5 @@ support, observability, rollback, or repair context.
|
|
|
59
59
|
Promote settled conclusions into the stable initiative files.
|
|
60
60
|
- Update `release-doc-notes.md` when shipped behavior or product-facing
|
|
61
61
|
behavior changes.
|
|
62
|
-
- Do not update `
|
|
62
|
+
- Do not update `docs/` from this initiative unless a human
|
|
63
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
|
|
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Status: Planned
|
|
4
4
|
Target release: vNEXT
|
|
5
|
-
Program: `
|
|
6
|
-
Promotion target: `
|
|
5
|
+
Program: `context/programs/<program-slug>/`
|
|
6
|
+
Promotion target: `context/releases/vNEXT/initiatives/<initiative-slug>/`
|
|
7
7
|
Promoted to: None
|
|
8
8
|
Promoted on: None
|
|
9
9
|
|
|
@@ -19,7 +19,7 @@ and what outcome it should produce.
|
|
|
19
19
|
- Tests or verification: `path/to/...`
|
|
20
20
|
- Delivery, CI/CD, build, or artifacts: `path/to/...`
|
|
21
21
|
- Infrastructure, IaC, or environment config: `path/to/...`
|
|
22
|
-
-
|
|
22
|
+
- Docs or release notes: `path/to/...`
|
|
23
23
|
|
|
24
24
|
Remove entries that do not apply and add the real paths. Prefer naming the
|
|
25
25
|
delivery concern over assuming a specific folder layout.
|
|
@@ -1,20 +1,20 @@
|
|
|
1
|
-
# Release
|
|
1
|
+
# Release Doc Notes
|
|
2
2
|
|
|
3
3
|
Use this file to capture expected product-documentation impact while future
|
|
4
4
|
work is being planned. When the planned initiative is promoted and later
|
|
5
5
|
implemented, compare these notes 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
|
## Expected 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
|
|
|
@@ -59,5 +59,5 @@ this program but are not in the current release yet.
|
|
|
59
59
|
a scoped delivery slice before the target release becomes current.
|
|
60
60
|
- Keep release-scoped implementation history in the relevant release
|
|
61
61
|
initiative.
|
|
62
|
-
- Use `
|
|
62
|
+
- Use `context/backlog/items/` for isolated deferred items that do not
|
|
63
63
|
need a program.
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
This backlog holds future work that belongs to the program as a durable
|
|
4
4
|
multi-release effort.
|
|
5
5
|
|
|
6
|
-
Use `
|
|
6
|
+
Use `context/backlog/items/` instead for isolated deferred work that does
|
|
7
7
|
not need program-level context.
|
|
8
8
|
|
|
9
9
|
Use `planned-initiatives/` instead when future work is already clear enough
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# vNEXT
|
|
1
|
+
# vNEXT Context
|
|
2
2
|
|
|
3
|
-
This folder contains
|
|
3
|
+
This folder contains working context for the `vNEXT` release.
|
|
4
4
|
|
|
5
5
|
## Navigation
|
|
6
6
|
|
|
@@ -14,20 +14,20 @@ Create an initiative when work is non-trivial, behavior-changing,
|
|
|
14
14
|
cross-project, release-significant, or likely to need future product
|
|
15
15
|
documentation.
|
|
16
16
|
|
|
17
|
-
Use `
|
|
17
|
+
Use `context/_templates/initiative/` as the starting point.
|
|
18
18
|
|
|
19
19
|
## Carry-Forward Rule
|
|
20
20
|
|
|
21
21
|
If an initiative is part of a larger phased effort, link it to a program
|
|
22
|
-
under `
|
|
22
|
+
under `context/programs/`.
|
|
23
23
|
|
|
24
24
|
If isolated work is cut from scope but should be kept for later, create a
|
|
25
|
-
backlog item under `
|
|
25
|
+
backlog item under `context/backlog/items/` and link it back to the
|
|
26
26
|
originating initiative.
|
|
27
27
|
|
|
28
28
|
## Planned Initiative Promotion
|
|
29
29
|
|
|
30
30
|
When this release becomes current, promote matching planned initiatives from
|
|
31
|
-
`
|
|
31
|
+
`context/programs/*/planned-initiatives/` into this release's
|
|
32
32
|
`initiatives/` folder. Leave the planned initiative in place as historical
|
|
33
33
|
planning context and update its status to `Promoted`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# vNEXT Backlog
|
|
2
2
|
|
|
3
|
-
This file tracks release-level
|
|
3
|
+
This file tracks release-level working context that is not yet captured
|
|
4
4
|
by an initiative, plus a short summary of initiative progress once
|
|
5
5
|
initiatives exist.
|
|
6
6
|
|
|
@@ -11,4 +11,3 @@ No backlog items recorded yet.
|
|
|
11
11
|
## Initiative Summary
|
|
12
12
|
|
|
13
13
|
No initiatives registered yet.
|
|
14
|
-
|
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
# Release Transition Checklist
|
|
2
2
|
|
|
3
|
-
Use this checklist when changing `
|
|
3
|
+
Use this checklist when changing `context/current.md` to a new current
|
|
4
4
|
release.
|
|
5
5
|
|
|
6
6
|
Target release: vNEXT
|
|
7
7
|
|
|
8
8
|
## Steps
|
|
9
9
|
|
|
10
|
-
- [ ] Update `
|
|
11
|
-
- [ ] Create `
|
|
12
|
-
`
|
|
10
|
+
- [ ] Update `context/current.md` to the target release.
|
|
11
|
+
- [ ] Create `context/releases/<target-release>/` from
|
|
12
|
+
`context/_templates/release-context/` if it does not exist.
|
|
13
13
|
- [ ] Create `README.md`, `backlog.md`, and `initiatives/` for the target
|
|
14
14
|
release if missing.
|
|
15
|
-
- [ ] Scan `
|
|
15
|
+
- [ ] Scan `context/programs/*/planned-initiatives/*/README.md` for
|
|
16
16
|
`Target release: <target-release>`.
|
|
17
17
|
- [ ] For each matching planned initiative, materialize it into:
|
|
18
18
|
|
|
19
19
|
```text
|
|
20
|
-
|
|
20
|
+
context/releases/<target-release>/initiatives/<initiative-slug>/
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
- [ ] Update the promoted release initiative so it links back to the parent
|
|
@@ -26,7 +26,7 @@ Development/releases/<target-release>/initiatives/<initiative-slug>/
|
|
|
26
26
|
|
|
27
27
|
```md
|
|
28
28
|
Status: Promoted
|
|
29
|
-
Promoted to: `
|
|
29
|
+
Promoted to: `context/releases/<target-release>/initiatives/<initiative-slug>/`
|
|
30
30
|
Promoted on: YYYY-MM-DD
|
|
31
31
|
```
|
|
32
32
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Context Backlog
|
|
2
2
|
|
|
3
3
|
This folder stores isolated deferred work that was cut from a release
|
|
4
4
|
initiative but should remain discoverable.
|
|
@@ -10,8 +10,8 @@ Use a backlog item when:
|
|
|
10
10
|
- it does not need durable program-level context
|
|
11
11
|
- it is not active in the current release
|
|
12
12
|
|
|
13
|
-
Create items from `
|
|
14
|
-
`
|
|
13
|
+
Create items from `context/_templates/backlog-item.md` and place them in
|
|
14
|
+
`context/backlog/items/`.
|
|
15
15
|
|
|
16
16
|
When a backlog item is picked up later, do not move or rewrite the original
|
|
17
17
|
item. Mark it as `Promoted` and link to the new release initiative.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Current
|
|
1
|
+
# Current Context
|
|
2
2
|
|
|
3
3
|
Current release: `v0_1_0`
|
|
4
4
|
|
|
@@ -26,7 +26,7 @@ Registered initiatives:
|
|
|
26
26
|
- `releases/v0_1_0/initiatives/npm-installer-cli/` - npm initializer for
|
|
27
27
|
installing this context template into existing projects.
|
|
28
28
|
|
|
29
|
-
To start an initiative, copy `
|
|
30
|
-
`
|
|
29
|
+
To start an initiative, copy `context/_templates/initiative/` into
|
|
30
|
+
`context/releases/v0_1_0/initiatives/<initiative-slug>/`, then update the
|
|
31
31
|
copied `README.md` first so agents have a clear entry point before editing the
|
|
32
32
|
supporting files.
|
|
@@ -10,7 +10,7 @@ Use a program when an effort has:
|
|
|
10
10
|
- planned future work that should remain visible
|
|
11
11
|
- context that would be lost if it lived only in one release initiative
|
|
12
12
|
|
|
13
|
-
Create programs from `
|
|
13
|
+
Create programs from `context/_templates/program/`.
|
|
14
14
|
|
|
15
15
|
## Planned Initiatives
|
|
16
16
|
|
|
@@ -19,7 +19,7 @@ to scope, split, or preserve implementation intent, but the target release is
|
|
|
19
19
|
not current yet.
|
|
20
20
|
|
|
21
21
|
When a planned initiative's target release becomes current, promote it into
|
|
22
|
-
`
|
|
22
|
+
`context/releases/<version>/initiatives/` and leave the planned initiative
|
|
23
23
|
behind as historical planning context.
|
|
24
24
|
|
|
25
25
|
## Current Programs
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# v0.1.0
|
|
1
|
+
# v0.1.0 Context
|
|
2
2
|
|
|
3
|
-
This folder contains
|
|
3
|
+
This folder contains working context for the `v0_1_0` release.
|
|
4
4
|
|
|
5
5
|
## Navigation
|
|
6
6
|
|
|
@@ -14,20 +14,20 @@ Create an initiative when work is non-trivial, behavior-changing,
|
|
|
14
14
|
cross-project, release-significant, or likely to need future product
|
|
15
15
|
documentation.
|
|
16
16
|
|
|
17
|
-
Use `
|
|
17
|
+
Use `context/_templates/initiative/` as the starting point.
|
|
18
18
|
|
|
19
19
|
## Carry-Forward Rule
|
|
20
20
|
|
|
21
21
|
If an initiative is part of a larger phased effort, link it to a program
|
|
22
|
-
under `
|
|
22
|
+
under `context/programs/`.
|
|
23
23
|
|
|
24
24
|
If isolated work is cut from scope but should be kept for later, create a
|
|
25
|
-
backlog item under `
|
|
25
|
+
backlog item under `context/backlog/items/` and link it back to the
|
|
26
26
|
originating initiative.
|
|
27
27
|
|
|
28
28
|
## Planned Initiative Promotion
|
|
29
29
|
|
|
30
30
|
When this release becomes current, promote matching planned initiatives from
|
|
31
|
-
`
|
|
31
|
+
`context/programs/*/planned-initiatives/` into this release's
|
|
32
32
|
`initiatives/` folder. Leave the planned initiative in place as historical
|
|
33
33
|
planning context and update its status to `Promoted`.
|
|
@@ -1,29 +1,29 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Context Terminology
|
|
2
2
|
|
|
3
3
|
This glossary defines the terms used by the Code-Anchored Context practice in
|
|
4
|
-
`
|
|
4
|
+
`context/`. Use these terms consistently in programs, initiatives,
|
|
5
5
|
backlog items, ADRs, agent summaries, and release-transition work.
|
|
6
6
|
|
|
7
7
|
## Core Folders
|
|
8
8
|
|
|
9
9
|
| Term | Meaning |
|
|
10
10
|
| --- | --- |
|
|
11
|
-
| `
|
|
12
|
-
| `
|
|
13
|
-
| `
|
|
14
|
-
| `
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
11
|
+
| `context/` | Working context: plans, specs, ADRs, implementation notes, delivery-surface context, future scope, and release-documentation notes. |
|
|
12
|
+
| `docs/` | Released product documentation. It describes shipped behavior for a release/tag and is not edited during normal development work. |
|
|
13
|
+
| `context/current.md` | Pointer to the current active release context. Updating this is a release transition. |
|
|
14
|
+
| `context/releases/<version>/` | Release-scoped working context for one version. |
|
|
15
|
+
| `context/programs/` | Durable multi-release working context. |
|
|
16
|
+
| `context/backlog/items/` | Deferred isolated work cut from initiatives but worth preserving. |
|
|
17
17
|
|
|
18
18
|
## Work Containers
|
|
19
19
|
|
|
20
20
|
| Term | Meaning | Lives in |
|
|
21
21
|
| --- | --- | --- |
|
|
22
|
-
| Program | A cross-release parent effort with durable context, roadmap, phase history, and program-level decisions. | `
|
|
23
|
-
| Planned initiative | A scoped future delivery slice that belongs to a program but is not in the current release yet. | `
|
|
24
|
-
| Release initiative | An active or historical delivery slice for a specific release. | `
|
|
25
|
-
|
|
|
26
|
-
| Program release slice | A program-level summary of what a release is expected to do or did for the program. | `
|
|
22
|
+
| Program | A cross-release parent effort with durable context, roadmap, phase history, and program-level decisions. | `context/programs/<program-slug>/` |
|
|
23
|
+
| Planned initiative | A scoped future delivery slice that belongs to a program but is not in the current release yet. | `context/programs/<program-slug>/planned-initiatives/<initiative-slug>/` |
|
|
24
|
+
| Release initiative | An active or historical delivery slice for a specific release. | `context/releases/<version>/initiatives/<initiative-slug>/` |
|
|
25
|
+
| Context backlog item | Isolated deferred work that was cut from an initiative and may be picked up later. | `context/backlog/items/<originating-initiative>--<item>.md` |
|
|
26
|
+
| Program release slice | A program-level summary of what a release is expected to do or did for the program. | `context/programs/<program-slug>/releases/<version>.md` |
|
|
27
27
|
|
|
28
28
|
## Choosing The Right Container
|
|
29
29
|
|
|
@@ -36,7 +36,7 @@ or needs a roadmap beyond one release.
|
|
|
36
36
|
Use a planned initiative when future program work is clear enough to plan,
|
|
37
37
|
specify, or split, but the target release is not current yet.
|
|
38
38
|
|
|
39
|
-
Use a
|
|
39
|
+
Use a context backlog item when an isolated piece of work was cut from
|
|
40
40
|
scope and should be preserved, but it does not need program-level context.
|
|
41
41
|
|
|
42
42
|
## Files
|
|
@@ -45,7 +45,7 @@ The structure follows delivery concerns, not technologies. Use concern names
|
|
|
45
45
|
such as `testing.md`, `delivery.md`, and `infrastructure.md`; name specific
|
|
46
46
|
tools inside those files only when the tools matter.
|
|
47
47
|
|
|
48
|
-
Mermaid is the preferred diagram syntax for
|
|
48
|
+
Mermaid is the preferred diagram syntax for working context because it is
|
|
49
49
|
both readable Markdown for agents and renderable visual context for humans.
|
|
50
50
|
|
|
51
51
|
| Term | Meaning |
|
|
@@ -60,7 +60,7 @@ both readable Markdown for agents and renderable visual context for humans.
|
|
|
60
60
|
| `infrastructure.md` | Stable description of environment shape, IaC, resources, networking, identity, storage, secrets, and environment dependencies. |
|
|
61
61
|
| `operations.md` | Optional actionable runtime support context: observability, failure modes, rollback, repair, support procedures, and tooling. |
|
|
62
62
|
| `backlog.md` | Trackable work items for the containing initiative or program. |
|
|
63
|
-
| `release-doc-notes.md` | Notes for future product documentation refresh work. This is the bridge to `
|
|
63
|
+
| `release-doc-notes.md` | Notes for future product documentation refresh work. This is the bridge to `docs/`. |
|
|
64
64
|
| ADR | Architecture Decision Record. Use for durable decisions and tradeoffs. |
|
|
65
65
|
| `brief.html` | Optional human-friendly presentation layer. |
|
|
66
66
|
|
|
@@ -88,15 +88,15 @@ Planned initiatives are promoted when their target release becomes current or
|
|
|
88
88
|
when release planning explicitly begins:
|
|
89
89
|
|
|
90
90
|
```text
|
|
91
|
-
|
|
92
|
-
->
|
|
91
|
+
context/programs/<program>/planned-initiatives/<initiative>/
|
|
92
|
+
-> context/releases/<version>/initiatives/<initiative>/
|
|
93
93
|
```
|
|
94
94
|
|
|
95
95
|
Backlog items are promoted when someone decides to pick them up:
|
|
96
96
|
|
|
97
97
|
```text
|
|
98
|
-
|
|
99
|
-
->
|
|
98
|
+
context/backlog/items/<originating-initiative>--<item>.md
|
|
99
|
+
-> context/releases/<version>/initiatives/<initiative>/
|
|
100
100
|
```
|
|
101
101
|
|
|
102
102
|
Promotion does not silently move or delete the original context. Leave the
|
|
@@ -105,7 +105,7 @@ original planned initiative or backlog item in place, update its status to
|
|
|
105
105
|
|
|
106
106
|
## Release Transition
|
|
107
107
|
|
|
108
|
-
A release transition is the act of changing `
|
|
108
|
+
A release transition is the act of changing `context/current.md` to a new
|
|
109
109
|
release. This is not just a line edit.
|
|
110
110
|
|
|
111
111
|
During a release transition, agents should:
|
|
@@ -117,4 +117,4 @@ During a release transition, agents should:
|
|
|
117
117
|
- update links both ways
|
|
118
118
|
- leave planned initiatives as historical planning context
|
|
119
119
|
|
|
120
|
-
Use `
|
|
120
|
+
Use `context/_templates/release-transition.md` as the checklist.
|
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# PROJECT_NAME
|
|
1
|
+
# PROJECT_NAME Docs
|
|
2
2
|
|
|
3
3
|
Welcome to the release-anchored documentation for PROJECT_NAME.
|
|
4
4
|
|
|
5
5
|
This folder describes shipped behavior for a known release or tag. It is not
|
|
6
6
|
the place for in-progress feature planning, implementation notes, or draft
|
|
7
|
-
architecture decisions. Put that work in `
|
|
7
|
+
architecture decisions. Put that work in `context/`.
|
|
8
8
|
|
|
9
|
-
## How
|
|
9
|
+
## How These Docs Are Organized
|
|
10
10
|
|
|
11
11
|
```text
|
|
12
|
-
|
|
12
|
+
docs/
|
|
13
13
|
.order
|
|
14
14
|
Welcome.md
|
|
15
15
|
releases/
|
|
@@ -30,7 +30,7 @@ Every documented area should have:
|
|
|
30
30
|
|
|
31
31
|
- a high-level `README.md` that explains the area's purpose and architecture
|
|
32
32
|
- one page per feature under `features/`
|
|
33
|
-
- an authoring guide under `
|
|
33
|
+
- an authoring guide under `docs/_authoring/areas/`
|
|
34
34
|
|
|
35
35
|
## Contributing
|
|
36
36
|
|
|
@@ -45,4 +45,4 @@ Every documented area should have:
|
|
|
45
45
|
- Describe behavior, inputs, outputs, permissions, errors, business rules, and
|
|
46
46
|
operational expectations in domain language.
|
|
47
47
|
- Prefer Mermaid diagrams for flows, architecture, and relationships.
|
|
48
|
-
- Add release refreshes to `
|
|
48
|
+
- Add release refreshes to `docs/releases/index.md`.
|