code-anchored-context 0.1.1 → 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 +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 -29
- 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}/code-anchored-context-structure.md +12 -12
- 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 +27 -27
- 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 +19 -18
- /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
package/.agents/skills/README.md
CHANGED
|
@@ -8,6 +8,6 @@ project.
|
|
|
8
8
|
|
|
9
9
|
## Repository-Wide Skills
|
|
10
10
|
|
|
11
|
-
- `
|
|
11
|
+
- `code-anchored-context` - use central `context/` initiatives
|
|
12
12
|
for planning, implementation context, programs, planned initiatives, ADRs,
|
|
13
13
|
backlog, and release-documentation notes.
|
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
3
|
-
description: Use central repository
|
|
2
|
+
name: code-anchored-context
|
|
3
|
+
description: Use central repository context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating context/current.md, context/releases/*/initiatives/*, context/programs/*, context/programs/*/planned-initiatives/*, context/backlog/items/*, specs, plans, interface notes, architecture notes, testing notes, delivery notes, infrastructure notes, actionable operations notes, ADRs, backlog, release-doc-notes.md; when promoting planned initiatives during release transitions; or when deciding whether docs/ should be left untouched.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Code-Anchored Context
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
Use this skill to connect code work back to the central
|
|
11
|
-
under `
|
|
10
|
+
Use this skill to connect code work back to the central working context
|
|
11
|
+
under `context/`. The goal is to keep initiative knowledge centralized,
|
|
12
12
|
preserve durable multi-release context in programs, and keep deferred
|
|
13
|
-
isolated work discoverable in the
|
|
13
|
+
isolated work discoverable in the context backlog. Scoped future program
|
|
14
14
|
work belongs in planned initiatives until the target release becomes current.
|
|
15
|
-
|
|
15
|
+
Working context should also cover delivery concerns such as testing,
|
|
16
16
|
delivery pipelines, and infrastructure when they affect how the work is
|
|
17
17
|
verified, shipped, deployed, or hosted.
|
|
18
18
|
|
|
@@ -23,33 +23,33 @@ verified, shipped, deployed, or hosted.
|
|
|
23
23
|
Read the nearest `AGENTS.md` files for the workspace and area being changed.
|
|
24
24
|
Respect area-specific engineering rules first.
|
|
25
25
|
|
|
26
|
-
### 2) Find The Current
|
|
26
|
+
### 2) Find The Current Context
|
|
27
27
|
|
|
28
|
-
Open `
|
|
28
|
+
Open `context/current.md` from the repository root. It points to the
|
|
29
29
|
active release folder.
|
|
30
30
|
|
|
31
|
-
Use `
|
|
31
|
+
Use `context/terminology.md` as the canonical vocabulary for programs,
|
|
32
32
|
planned initiatives, release initiatives, backlog items, statuses, and
|
|
33
33
|
promotion.
|
|
34
34
|
|
|
35
35
|
If the workspace starts inside a subfolder, navigate upward to the repository
|
|
36
|
-
root when the environment allows it. If `
|
|
36
|
+
root when the environment allows it. If `context/` is not available in
|
|
37
37
|
the workspace, mention that limitation in the task summary.
|
|
38
38
|
|
|
39
39
|
### 3) Match Existing Context
|
|
40
40
|
|
|
41
41
|
Search these places for matching context:
|
|
42
42
|
|
|
43
|
-
- active release initiatives under `
|
|
44
|
-
- durable programs under `
|
|
45
|
-
- scoped future program work under `
|
|
46
|
-
- deferred items under `
|
|
43
|
+
- active release initiatives under `context/releases/<current-release>/initiatives/`
|
|
44
|
+
- durable programs under `context/programs/`
|
|
45
|
+
- scoped future program work under `context/programs/<program>/planned-initiatives/`
|
|
46
|
+
- deferred items under `context/backlog/items/`
|
|
47
47
|
|
|
48
48
|
Search for:
|
|
49
49
|
|
|
50
50
|
- the feature or bug name
|
|
51
|
-
- affected
|
|
52
|
-
automation
|
|
51
|
+
- affected concern names, such as product code, APIs, contracts, tests,
|
|
52
|
+
delivery, CI/CD, infrastructure, config, generated artifacts, or automation
|
|
53
53
|
- related domain terms, APIs, jobs, entities, routes, config names, or tickets
|
|
54
54
|
|
|
55
55
|
Use an existing initiative when the work belongs to it, even if the code
|
|
@@ -62,10 +62,10 @@ Create a new initiative for non-trivial behavior changes, cross-project
|
|
|
62
62
|
work, release-significant work, or anything likely to need future product
|
|
63
63
|
documentation.
|
|
64
64
|
|
|
65
|
-
Use `
|
|
65
|
+
Use `context/_templates/initiative/` as the source. Copy it to:
|
|
66
66
|
|
|
67
67
|
```text
|
|
68
|
-
|
|
68
|
+
context/releases/<current-release>/initiatives/<initiative-slug>/
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
Update the copied `README.md` first so future agents can quickly understand
|
|
@@ -82,10 +82,10 @@ If future program work is known well enough to scope, split, or preserve
|
|
|
82
82
|
implementation intent, create a planned initiative under the parent program:
|
|
83
83
|
|
|
84
84
|
```text
|
|
85
|
-
|
|
85
|
+
context/programs/<program-slug>/planned-initiatives/<initiative-slug>/
|
|
86
86
|
```
|
|
87
87
|
|
|
88
|
-
Use `
|
|
88
|
+
Use `context/_templates/planned-initiative/` as the source.
|
|
89
89
|
|
|
90
90
|
Use a planned initiative when:
|
|
91
91
|
|
|
@@ -95,7 +95,7 @@ Use a planned initiative when:
|
|
|
95
95
|
- capturing it only in `roadmap.md` or `releases/<version>.md` would lose
|
|
96
96
|
useful scope or implementation context
|
|
97
97
|
|
|
98
|
-
Do not create a future `
|
|
98
|
+
Do not create a future `context/releases/<version>/` initiative just to
|
|
99
99
|
hold planned work unless that release is being made current or release
|
|
100
100
|
planning has explicitly begun.
|
|
101
101
|
|
|
@@ -104,14 +104,14 @@ planning has explicitly begun.
|
|
|
104
104
|
Use the right outliving path when initiative context needs to survive beyond
|
|
105
105
|
the current release:
|
|
106
106
|
|
|
107
|
-
- `
|
|
107
|
+
- `context/programs/<program-slug>/`: multi-release efforts, phases,
|
|
108
108
|
roadmaps, durable decisions, and release-slice history
|
|
109
|
-
- `
|
|
109
|
+
- `context/programs/<program-slug>/planned-initiatives/<initiative-slug>/`:
|
|
110
110
|
scoped future delivery slices that are not in the current release yet
|
|
111
|
-
- `
|
|
111
|
+
- `context/backlog/items/<originating-initiative-slug>--<item-slug>.md`:
|
|
112
112
|
isolated deferred work cut from an initiative
|
|
113
113
|
|
|
114
|
-
When creating a backlog item, use `
|
|
114
|
+
When creating a backlog item, use `context/_templates/backlog-item.md`
|
|
115
115
|
and link to the originating initiative and release.
|
|
116
116
|
|
|
117
117
|
When picking up a backlog item later, keep the item as a historical record.
|
|
@@ -122,17 +122,17 @@ Mark it as promoted and link to the new release initiative.
|
|
|
122
122
|
When asked to set a new current release, treat it as a release transition,
|
|
123
123
|
not just a `current.md` edit.
|
|
124
124
|
|
|
125
|
-
Use `
|
|
125
|
+
Use `context/_templates/release-transition.md` as the checklist:
|
|
126
126
|
|
|
127
|
-
1. Update `
|
|
128
|
-
2. Create `
|
|
129
|
-
`
|
|
130
|
-
3. Scan `
|
|
127
|
+
1. Update `context/current.md`.
|
|
128
|
+
2. Create `context/releases/<target-release>/` from
|
|
129
|
+
`context/_templates/release-context/` if missing.
|
|
130
|
+
3. Scan `context/programs/*/planned-initiatives/*/README.md` for
|
|
131
131
|
`Target release: <target-release>`.
|
|
132
132
|
4. Promote each match into:
|
|
133
133
|
|
|
134
134
|
```text
|
|
135
|
-
|
|
135
|
+
context/releases/<target-release>/initiatives/<initiative-slug>/
|
|
136
136
|
```
|
|
137
137
|
|
|
138
138
|
5. Update the planned initiative metadata to `Status: Promoted`, with
|
|
@@ -175,13 +175,13 @@ settled truth lives. Promote stable conclusions into `spec.md`,
|
|
|
175
175
|
`infrastructure.md`, `operations.md` when actionable, `backlog.md`, ADRs, or
|
|
176
176
|
`release-doc-notes.md` as appropriate.
|
|
177
177
|
|
|
178
|
-
### 9) Preserve The
|
|
178
|
+
### 9) Preserve The Docs Boundary
|
|
179
179
|
|
|
180
|
-
Do not edit `
|
|
180
|
+
Do not edit `docs/` as part of normal feature work, bug fixes,
|
|
181
181
|
refactors, or planning. Instead, update the initiative's
|
|
182
182
|
`release-doc-notes.md`.
|
|
183
183
|
|
|
184
|
-
Only update `
|
|
184
|
+
Only update `docs/` when a human explicitly asks for release
|
|
185
185
|
documentation work, a specific page update, or a demonstrable documentation
|
|
186
186
|
fix.
|
|
187
187
|
|
|
@@ -189,7 +189,7 @@ fix.
|
|
|
189
189
|
|
|
190
190
|
Denormalize navigation, not knowledge.
|
|
191
191
|
|
|
192
|
-
Local `AGENTS.md` files may point to `
|
|
192
|
+
Local `AGENTS.md` files may point to `context/`, but initiative specs,
|
|
193
193
|
plans, ADRs, and release-doc notes should live in the central initiative
|
|
194
194
|
folder. Do not create area-local copies of initiative documents.
|
|
195
195
|
|
|
@@ -198,7 +198,7 @@ folder. Do not create area-local copies of initiative documents.
|
|
|
198
198
|
Before finishing behavior-changing work:
|
|
199
199
|
|
|
200
200
|
- The matching initiative was read or a reason was given for why none exists.
|
|
201
|
-
- Matching programs or
|
|
201
|
+
- Matching programs or context backlog items were checked when the work
|
|
202
202
|
appears phased, deferred, or multi-release.
|
|
203
203
|
- Planned initiatives were checked or created when future program scope is
|
|
204
204
|
already clear but outside the current release.
|
|
@@ -206,4 +206,4 @@ Before finishing behavior-changing work:
|
|
|
206
206
|
infrastructure, actionable operations, or backlog state was reflected in the
|
|
207
207
|
initiative when appropriate.
|
|
208
208
|
- Future product-documentation impact was captured in `release-doc-notes.md`.
|
|
209
|
-
- `
|
|
209
|
+
- `docs/` was left untouched unless explicitly requested.
|
package/AGENTS.md
CHANGED
|
@@ -3,27 +3,27 @@
|
|
|
3
3
|
This file applies to the whole repo. Area-specific `AGENTS.md` files in
|
|
4
4
|
subfolders layer on top of it. Read those too when working in a given area.
|
|
5
5
|
|
|
6
|
-
##
|
|
6
|
+
## Working Context
|
|
7
7
|
|
|
8
8
|
In-progress specs, plans, ADRs, backlog, implementation context, and
|
|
9
|
-
release-documentation notes live under [`
|
|
10
|
-
Start with [`
|
|
9
|
+
release-documentation notes live under [`context/`](context/).
|
|
10
|
+
Start with [`context/current.md`](context/current.md).
|
|
11
11
|
|
|
12
12
|
For behavior-changing work, use the repo-wide skill at
|
|
13
|
-
[`.agents/skills/
|
|
14
|
-
Keep initiative knowledge centralized under `
|
|
13
|
+
[`.agents/skills/code-anchored-context/SKILL.md`](.agents/skills/code-anchored-context/SKILL.md).
|
|
14
|
+
Keep initiative knowledge centralized under `context/`; area
|
|
15
15
|
`AGENTS.md` files should point there rather than copying active plans.
|
|
16
16
|
|
|
17
|
-
##
|
|
17
|
+
## Docs Authoring
|
|
18
18
|
|
|
19
|
-
### When To Edit `
|
|
19
|
+
### When To Edit `docs/`
|
|
20
20
|
|
|
21
|
-
Do not edit `
|
|
21
|
+
Do not edit `docs/` as a side effect of feature work, bug fixes,
|
|
22
22
|
refactors, or other code changes. Docs in this model are release-anchored:
|
|
23
23
|
they describe the behavior of a specific release tag, not the partial state of
|
|
24
24
|
a working branch.
|
|
25
25
|
|
|
26
|
-
Touch `
|
|
26
|
+
Touch `docs/` only when:
|
|
27
27
|
|
|
28
28
|
- A human explicitly asks you to refresh the docs for a release, typically
|
|
29
29
|
after a release tag is cut and QA has signed off.
|
|
@@ -37,16 +37,16 @@ If you are unsure whether the request is one of these, ask before editing.
|
|
|
37
37
|
|
|
38
38
|
If a project has documentation that intentionally follows a different cadence,
|
|
39
39
|
document that exception in the area's README and in
|
|
40
|
-
`
|
|
40
|
+
`docs/_authoring/areas/`.
|
|
41
41
|
|
|
42
42
|
### Where The Authoring Guidance Lives
|
|
43
43
|
|
|
44
44
|
All documentation workflow, per-area authoring guides, and domain terminology
|
|
45
|
-
live under [`
|
|
46
|
-
with [`
|
|
45
|
+
live under [`docs/_authoring/`](docs/_authoring/). Start
|
|
46
|
+
with [`docs/_authoring/README.md`](docs/_authoring/README.md).
|
|
47
47
|
|
|
48
48
|
If you are refreshing docs, the per-area guides in
|
|
49
|
-
[`
|
|
49
|
+
[`docs/_authoring/areas/`](docs/_authoring/areas/) tell you
|
|
50
50
|
what matters and what to ignore for each area.
|
|
51
51
|
|
|
52
52
|
`AGENTS.md` files stay lean. They are for coding conventions and agent
|
package/README.md
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
# Code-Anchored Context Template
|
|
2
2
|
|
|
3
3
|
This repository is a reusable starting point for keeping repository-local
|
|
4
|
-
|
|
4
|
+
working context and release-anchored product documentation close to the
|
|
5
5
|
code they describe.
|
|
6
6
|
|
|
7
7
|
It separates two kinds of truth:
|
|
8
8
|
|
|
9
9
|
| Folder | Meaning | Updated when |
|
|
10
10
|
| --- | --- | --- |
|
|
11
|
-
| `
|
|
12
|
-
| `
|
|
11
|
+
| `context/` | What the team is planning, building, deciding, validating, shipping, hosting, deferring, and learning. | During normal development. |
|
|
12
|
+
| `docs/` | What the product does as of a known release or tag. | Only during explicit documentation refresh work. |
|
|
13
13
|
|
|
14
14
|
The goal is to give humans and AI agents enough structured context to change a
|
|
15
15
|
codebase without relying on chat history, tribal memory, or scattered planning
|
|
@@ -18,11 +18,11 @@ notes.
|
|
|
18
18
|
## What This Template Contains
|
|
19
19
|
|
|
20
20
|
- `AGENTS.md` with repo-wide agent guidance.
|
|
21
|
-
- `.agents/skills/
|
|
22
|
-
|
|
23
|
-
- `
|
|
21
|
+
- `.agents/skills/code-anchored-context/SKILL.md` for the recurring
|
|
22
|
+
working-context workflow.
|
|
23
|
+
- `context/` with terminology, release context, backlog/program structure,
|
|
24
24
|
initiative templates, and a human-readable article and brief.
|
|
25
|
-
- `
|
|
25
|
+
- `docs/` with a generic release-anchored documentation workflow,
|
|
26
26
|
authoring guide structure, and area/page templates.
|
|
27
27
|
|
|
28
28
|
## Adopting This In A Project
|
|
@@ -39,23 +39,23 @@ Useful options:
|
|
|
39
39
|
|
|
40
40
|
```bash
|
|
41
41
|
npx code-anchored-context init --dry-run
|
|
42
|
-
npx code-anchored-context init --no-
|
|
42
|
+
npx code-anchored-context init --no-docs
|
|
43
43
|
npx code-anchored-context init --target ../existing-project
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
The initializer copies the repo-local agent context into the target project,
|
|
47
47
|
adds or updates guidance in `AGENTS.md`, installs the
|
|
48
|
-
`
|
|
48
|
+
`code-anchored-context` skill under `.agents/skills/`, and replaces
|
|
49
49
|
basic placeholders such as `PROJECT_NAME` and the initial release slug.
|
|
50
50
|
|
|
51
51
|
Manual adoption still works:
|
|
52
52
|
|
|
53
53
|
1. Copy the files into a repository root.
|
|
54
54
|
2. Replace `PROJECT_NAME` placeholders with the project name.
|
|
55
|
-
3. Set the first active release in `
|
|
55
|
+
3. Set the first active release in `context/current.md`.
|
|
56
56
|
4. Add or revise area-specific `AGENTS.md` files so they point back to
|
|
57
|
-
`
|
|
58
|
-
5. Create `
|
|
57
|
+
`context/` and `docs/_authoring/`.
|
|
58
|
+
5. Create `docs/_authoring/areas/<area>.md` for each documented
|
|
59
59
|
product or code area.
|
|
60
60
|
6. Keep product or domain-specific documentation out of this template repo.
|
|
61
61
|
|
|
@@ -78,8 +78,8 @@ npx @your-scope/code-anchored-context init
|
|
|
78
78
|
|
|
79
79
|
## Working Rule
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
Working context can evolve with the branch. Product docs should
|
|
82
82
|
stay stable and release-accurate. When behavior changes during development,
|
|
83
83
|
record future documentation impact in the relevant initiative's
|
|
84
|
-
`release-doc-notes.md`; refresh `
|
|
84
|
+
`release-doc-notes.md`; refresh `docs/` only when that work is
|
|
85
85
|
explicitly requested.
|
|
@@ -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
|
|
|
@@ -215,18 +215,18 @@ class Installer {
|
|
|
215
215
|
this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
|
|
216
216
|
}
|
|
217
217
|
|
|
218
|
-
async init({
|
|
218
|
+
async init({ includeDocs }) {
|
|
219
219
|
await this.ensureDirectory(this.targetRoot);
|
|
220
220
|
|
|
221
221
|
await this.installAgentsFile();
|
|
222
222
|
await this.installSkill();
|
|
223
|
-
await this.copyTemplatePath('
|
|
223
|
+
await this.copyTemplatePath('context', 'context');
|
|
224
224
|
await this.renameReleasePaths();
|
|
225
225
|
|
|
226
|
-
if (
|
|
227
|
-
await this.copyTemplatePath('
|
|
226
|
+
if (includeDocs) {
|
|
227
|
+
await this.copyTemplatePath('docs', 'docs');
|
|
228
228
|
} else {
|
|
229
|
-
this.note('skip
|
|
229
|
+
this.note('skip docs/ (--no-docs)');
|
|
230
230
|
}
|
|
231
231
|
|
|
232
232
|
this.printSummary();
|
|
@@ -261,8 +261,8 @@ class Installer {
|
|
|
261
261
|
return;
|
|
262
262
|
}
|
|
263
263
|
|
|
264
|
-
if (current.includes(
|
|
265
|
-
this.note(`${targetDisplay} already points to the
|
|
264
|
+
if (current.includes(`.agents/skills/${skillName}/SKILL.md`)) {
|
|
265
|
+
this.note(`${targetDisplay} already points to the Code-Anchored Context skill`);
|
|
266
266
|
return;
|
|
267
267
|
}
|
|
268
268
|
|
|
@@ -302,12 +302,12 @@ class Installer {
|
|
|
302
302
|
## Code-Anchored Context
|
|
303
303
|
|
|
304
304
|
In-progress specs, plans, ADRs, backlog, implementation context, and
|
|
305
|
-
release-documentation notes live under [\`
|
|
306
|
-
Start with [\`
|
|
305
|
+
release-documentation notes live under [\`context/\`](context/).
|
|
306
|
+
Start with [\`context/current.md\`](context/current.md).
|
|
307
307
|
|
|
308
308
|
For behavior-changing work, use the repo-wide skill at
|
|
309
|
-
[\`.agents/skills/
|
|
310
|
-
Keep initiative knowledge centralized under \`
|
|
309
|
+
[\`.agents/skills/${skillName}/SKILL.md\`](.agents/skills/${skillName}/SKILL.md).
|
|
310
|
+
Keep initiative knowledge centralized under \`context/\`; area
|
|
311
311
|
\`AGENTS.md\` files should point there rather than copying active plans.
|
|
312
312
|
${agentSectionEnd}`;
|
|
313
313
|
}
|
|
@@ -334,7 +334,7 @@ ${agentSectionEnd}`;
|
|
|
334
334
|
const current = await readFile(readmePath, 'utf8');
|
|
335
335
|
|
|
336
336
|
if (current.includes(skillName)) {
|
|
337
|
-
this.note(`${readmeDisplay} already lists the
|
|
337
|
+
this.note(`${readmeDisplay} already lists the Code-Anchored Context skill`);
|
|
338
338
|
return;
|
|
339
339
|
}
|
|
340
340
|
|
|
@@ -342,14 +342,14 @@ ${agentSectionEnd}`;
|
|
|
342
342
|
'',
|
|
343
343
|
'## Code-Anchored Context',
|
|
344
344
|
'',
|
|
345
|
-
`- \`${skillName}\` - use central \`
|
|
345
|
+
`- \`${skillName}\` - use central \`context/\` initiatives for planning, implementation context, programs, planned initiatives, ADRs, backlog, and release-documentation notes.`,
|
|
346
346
|
''
|
|
347
347
|
].join('\n');
|
|
348
348
|
|
|
349
349
|
await this.writeFile(
|
|
350
350
|
readmePath,
|
|
351
351
|
`${current.trimEnd()}\n${entry}`,
|
|
352
|
-
`append
|
|
352
|
+
`append Code-Anchored Context skill to ${readmeDisplay}`
|
|
353
353
|
);
|
|
354
354
|
}
|
|
355
355
|
|
|
@@ -451,7 +451,7 @@ ${agentSectionEnd}`;
|
|
|
451
451
|
}
|
|
452
452
|
|
|
453
453
|
shouldSkipTemplatePath(displayPath) {
|
|
454
|
-
const initiativePrefix = `
|
|
454
|
+
const initiativePrefix = `context/releases/${defaultRelease}/initiatives/`;
|
|
455
455
|
|
|
456
456
|
return (
|
|
457
457
|
displayPath.startsWith(initiativePrefix) &&
|
|
@@ -460,11 +460,11 @@ ${agentSectionEnd}`;
|
|
|
460
460
|
}
|
|
461
461
|
|
|
462
462
|
transformText(contents, displayPath) {
|
|
463
|
-
if (displayPath === '
|
|
463
|
+
if (displayPath === 'context/current.md') {
|
|
464
464
|
return this.renderStarterCurrent();
|
|
465
465
|
}
|
|
466
466
|
|
|
467
|
-
if (displayPath === `
|
|
467
|
+
if (displayPath === `context/releases/${defaultRelease}/backlog.md`) {
|
|
468
468
|
return this.renderStarterReleaseBacklog();
|
|
469
469
|
}
|
|
470
470
|
|
|
@@ -476,7 +476,7 @@ ${agentSectionEnd}`;
|
|
|
476
476
|
}
|
|
477
477
|
|
|
478
478
|
renderStarterCurrent() {
|
|
479
|
-
return `# Current
|
|
479
|
+
return `# Current Context
|
|
480
480
|
|
|
481
481
|
Current release: \`${this.release}\`
|
|
482
482
|
|
|
@@ -503,8 +503,8 @@ Registered initiatives:
|
|
|
503
503
|
|
|
504
504
|
- None yet.
|
|
505
505
|
|
|
506
|
-
To start an initiative, copy \`
|
|
507
|
-
\`
|
|
506
|
+
To start an initiative, copy \`context/_templates/initiative/\` into
|
|
507
|
+
\`context/releases/${this.release}/initiatives/<initiative-slug>/\`, then update the
|
|
508
508
|
copied \`README.md\` first so agents have a clear entry point before editing the
|
|
509
509
|
supporting files.
|
|
510
510
|
`;
|
|
@@ -513,7 +513,7 @@ supporting files.
|
|
|
513
513
|
renderStarterReleaseBacklog() {
|
|
514
514
|
return `# ${this.releaseLabel()} Backlog
|
|
515
515
|
|
|
516
|
-
This file tracks release-level
|
|
516
|
+
This file tracks release-level working context that is not yet captured
|
|
517
517
|
by an initiative, plus a short summary of initiative progress once
|
|
518
518
|
initiatives exist.
|
|
519
519
|
|
|
@@ -537,15 +537,15 @@ No initiatives registered yet.
|
|
|
537
537
|
}
|
|
538
538
|
|
|
539
539
|
await this.renamePath(
|
|
540
|
-
path.join(this.targetRoot, '
|
|
541
|
-
path.join(this.targetRoot, '
|
|
542
|
-
`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}`
|
|
543
543
|
);
|
|
544
544
|
|
|
545
545
|
await this.renamePath(
|
|
546
|
-
path.join(this.targetRoot, '
|
|
547
|
-
path.join(this.targetRoot, '
|
|
548
|
-
`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`
|
|
549
549
|
);
|
|
550
550
|
}
|
|
551
551
|
|
|
@@ -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.
|