code-anchored-context 0.1.0

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

@@ -0,0 +1,132 @@
+# Code-Anchored Context: The Structure
+
+This is the companion to the
+[reasoning article](code-anchored-context-why.md). It covers how development
+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
+`src/`, `deploy/`, 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 `Development/`.
+
+## The Core Model
+
+Vocabulary is captured in `Development/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.
+Development 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
+Development/
+  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
+Development/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
+Development/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
+Development/programs/<program>/planned-initiatives/<initiative>/
+```
+
+When the target release becomes current, it is promoted into
+`Development/releases/<version>/initiatives/<initiative>/`. Promotion is
+explicit; the original planned initiative stays as historical context.
+
+## Development Backlog
+
+Work cut from scope but worth preserving — when it doesn't justify a program or
+planned initiative — lives in:
+
+```text
+Development/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
+`Development/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/Development/code-anchored-context-why.md

@@ -0,0 +1,80 @@
+# 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.
+
+## Documentation vs Development
+
+This is why I separate **released product documentation** from **development
+context**:
+
+```text
+Documentation/   What shipped.
+Development/      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. Development 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["Development/<br/>What is being planned, built, decided, tested, shipped, deferred"]
+  Docs["Documentation/<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*. Development 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).