code-anchored-context 0.2.0 → 0.2.1

package/context/README.md

@@ -10,10 +10,6 @@ implementation plans, and release-documentation notes. Do not use
 
 ## Start Here
 
-- `code-anchored-context.html` is a human-friendly visual brief for this
-  opinionated context practice.
-- `giving-ai-agents-context-around-code.md` is an article-form explanation of
-  Code-Anchored Context for human-agent collaboration.
 - `terminology.md` defines the shared vocabulary.
 - `current.md` points to the active release context.
 - `programs/` contains durable multi-release working context.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "code-anchored-context",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Install repo-local agent context, release initiatives, and release-anchored docs scaffolding into an existing project.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "code-anchored-context": "./bin/code-anchored-context.js"
+    "code-anchored-context": "bin/code-anchored-context.js"
   },
   "files": [
     "AGENTS.md",
@@ -14,11 +14,7 @@
     "context/README.md",
     "context/_templates/",
     "context/backlog/",
-    "context/code-anchored-context-structure.md",
-    "context/code-anchored-context-why.md",
-    "context/code-anchored-context.html",
     "context/current.md",
-    "context/giving-ai-agents-context-around-code.md",
     "context/programs/",
     "context/releases/v0_1_0/README.md",
     "context/releases/v0_1_0/backlog.md",

package/context/code-anchored-context-structure.md

@@ -1,133 +0,0 @@
-# Code-Anchored Context: The Structure
-
-This is the companion to the
-[reasoning article](code-anchored-context-why.md). It covers how working
-context is laid out so both humans and agents can navigate it.
-
-## Denormalize Navigation, Not Knowledge
-
-Agents and IDEs do not always open from the repo root. They may start in
-product code, CI/CD config, infrastructure code, generated artifacts, or a
-nested app. If all guidance lives at the top, it gets missed. If each area
-keeps its own plans, cross-project work fragments.
-
-> Denormalize navigation, not knowledge.
-
-Local `AGENTS.md` files point agents toward the right place. But plans, specs,
-ADRs, release context, testing strategy, delivery notes, and infrastructure
-context live centrally under `context/`.
-
-## The Core Model
-
-Vocabulary is captured in `context/terminology.md`. The main containers:
-
-```text
-Program                  Long-lived multi-release effort.
-Planned initiative       A scoped future slice inside a program.
-Release initiative       Active or historical work for a specific release.
-Context backlog item     Isolated work cut from scope but worth preserving.
-Program release slice    What a release contributes to a program.
-```
-
-Each kind of context gets a home:
-
-```text
-context/
-  terminology.md
-  current.md
-  programs/
-  backlog/
-  releases/
-  _templates/
-```
-
-Structure follows delivery concerns, not technologies. Name a file for the
-knowledge it preserves, not the tool that produced it.
-
-## Release Initiatives
-
-The main unit of active delivery:
-
-```text
-context/releases/<version>/initiatives/<initiative>/
-  README.md   plan.md   spec.md   interface.md   architecture.md
-  testing.md  delivery.md  infrastructure.md  operations.md
-  backlog.md  decisions/  release-doc-notes.md
-```
-
-The most important file is `plan.md` — the working alignment space. It can be
-messy with notes, options, and tradeoffs, with one rule:
-
-> `plan.md` may be messy, but it must not be the only place settled truth lives.
-
-Once something stabilizes, it moves to a durable file:
-
-```text
-spec.md              What the system should do.
-interface.md         How clients, APIs, config, or tools interact with it.
-architecture.md      Internal shape, boundaries, data flow, tradeoffs.
-testing.md           Verification strategy, coverage, gates, known gaps.
-delivery.md          CI/CD, build, deployment, promotion, release toggles.
-infrastructure.md    Environments, IaC, networking, identity, storage, secrets.
-operations.md        Runtime/support: observability, failure modes, rollback.
-backlog.md           Trackable work items and progress.
-decisions/           Durable decisions and consequences (ADRs).
-release-doc-notes.md What should become product documentation later.
-```
-
-Not every initiative needs every file. The point is to give stable knowledge a
-place to land — testing, delivery, and infrastructure are first-class context,
-not afterthoughts buried in pipeline files or PRs.
-
-## Programs And Planned Initiatives
-
-Some work is bigger than one release. A program holds durable multi-release
-context:
-
-```text
-context/programs/<program>/
-  README.md  context.md  roadmap.md  backlog.md
-  decisions/  planned-initiatives/  releases/
-```
-
-Future work that is clear enough to plan — but whose target release is not
-current yet — becomes a planned initiative:
-
-```text
-context/programs/<program>/planned-initiatives/<initiative>/
-```
-
-When the target release becomes current, it is promoted into
-`context/releases/<version>/initiatives/<initiative>/`. Promotion is
-explicit; the original planned initiative stays as historical context.
-
-## Context Backlog
-
-Work cut from scope but worth preserving — when it doesn't justify a program or
-planned initiative — lives in:
-
-```text
-context/backlog/items/<originating-initiative>--<item>.md
-```
-
-Each item records where it came from, why it was deferred, future value, and
-re-entry criteria. If picked up later, it is marked promoted and linked — never
-silently rewritten.
-
-## Release Transitions
-
-Changing the current release is more than editing a pointer. When
-`context/current.md` moves to a new release, agents should scan program
-planned initiatives, promote items targeting the new release into the release
-folder, update links both ways, and preserve the originals as history.
-
-```mermaid
-flowchart TD
-  Start["Set a new current release"]
-  Scan["Scan program planned initiatives"]
-  Promote["Promote into releases/<version>/initiatives/"]
-  Link["Update links both ways"]
-  Preserve["Preserve original as history"]
-
-  Start --> Scan --> Promote --> Link --> Preserve
-```

package/context/code-anchored-context-why.md

@@ -1,80 +0,0 @@
-# Code-Anchored Context: Giving AI Agents The Context Around The Code
-
-AI agents are good at reading repositories, editing files, and following
-instructions. But in large codebases, code is not the whole story.
-
-The hard part is not whether an agent can change a file. It is whether it
-understands the intent behind the change, the current release scope, the
-decisions already made, the work deliberately deferred, how the change should
-be verified, how it ships, and what infrastructure or operational risks
-surround it.
-
-That context usually exists — in chats, tickets, pull request comments,
-planning notes, and people's heads — but agents need it in a structured,
-discoverable form.
-
-## Docs vs Working Context
-
-This is why I separate **released product documentation** from **working
-context**:
-
-```text
-docs/   What shipped.
-context/      What we are planning, building, deciding, testing,
-                  shipping, hosting, deferring, and learning.
-```
-
-Product documentation stays stable and release-accurate: it describes a known
-release, not an unfinished branch. Working context is allowed to evolve —
-it is where humans and agents work through ambiguity.
-
-## The Principle
-
-I think of this as **Code-Anchored Context**. Not a methodology — a rule of
-thumb:
-
-> Keep truth as close to code as possible, and keep the surrounding context
-> structured enough that both humans and agents can find it.
-
-It is opinionated on purpose: prefer repository-local context, explicit
-lifetimes, and navigable structure over scattered notes that only make sense
-to the people who were in the room. Repository-local context scales beyond one
-person.
-
-## Why It Travels
-
-When context is materialized in the repository, it stops being tied to one
-chat transcript, IDE, agent, or session. A team can switch tools without
-losing the trail of why the system is shaped the way it is. The next human or
-agent opens the repo and continues from the same accumulated understanding
-instead of reconstructing it from memory.
-
-```mermaid
-flowchart LR
-  Code["Codebase<br/>What exists"]
-  Dev["context/<br/>What is being planned, built, decided, tested, shipped, deferred"]
-  Docs["docs/<br/>What shipped in a known release"]
-  Agents["Agents and humans"]
-
-  Agents --> Code
-  Agents --> Dev
-  Dev -->|"release-doc-notes.md captures future docs impact"| Docs
-  Docs -->|"stable release truth"| Agents
-```
-
-## Why It Matters
-
-Code-Anchored Context is context continuity. It helps agents and humans answer:
-
-- What is active now, and what belongs to a future phase?
-- What was cut from scope, and why was a decision made?
-- How should this be tested, and what gates must pass before release?
-- How will it ship, and what infrastructure does it depend on?
-- What should become product documentation later?
-- What reasoning needs to survive a change of IDE, agent, or session?
-
-Code tells an agent *what exists*. Working context tells it *why* it
-exists, where it is going, what has been decided, and what was left for later.
-
-For the concrete folder layout, see the companion article,
-[Code-Anchored Context: The Structure](code-anchored-context-structure.md).