code-anchored-context 0.1.0 → 0.2.0

package/{Development → context}/giving-ai-agents-context-around-code.md

@@ -16,13 +16,13 @@ infrastructure conversations, and people's heads. The problem is that agents
 need this context in a structured, discoverable form.
 
 This is why I started separating **released product documentation** from
-**development context**.
+**working context**.
 
 ```text
-Documentation/
+docs/
   What shipped.
 
-Development/
+context/
   What we are planning, building, deciding, testing, shipping, hosting,
   deferring, and learning.
 ```
@@ -31,7 +31,7 @@ Product documentation should stay stable and release-accurate. It should
 describe the behavior of a known release, not the current shape of an unfinished
 branch.
 
-Development context is different. It is allowed to evolve. It is where humans
+Working context is different. It is allowed to evolve. It is where humans
 and agents work through ambiguity.
 
 Over time, I have started thinking about this as **Code-Anchored Context**.
@@ -53,7 +53,7 @@ One practical benefit is that the reasoning travels with the work.
 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 can open the repo, read the development context, and continue from the
+agent can open the repo, read the working context, and continue from the
 same accumulated understanding instead of reconstructing it from memory. That
 continuity keeps hours of planning from being lost and makes handoffs between
 models and team members materially better.
@@ -61,8 +61,8 @@ models and team members materially better.
 ```mermaid
 flowchart LR
   Code["Codebase<br/>What exists in the system"]
-  Dev["Development/<br/>What is being planned, built, decided, tested, shipped, hosted, deferred, and learned"]
-  Docs["Documentation/<br/>What shipped in a known release"]
+  Dev["context/<br/>What is being planned, built, decided, tested, shipped, hosted, deferred, and learned"]
+  Docs["docs/<br/>What shipped in a known release"]
   Agents["Agents and humans<br/>Need context before changing behavior"]
 
   Agents --> Code
@@ -74,8 +74,8 @@ flowchart LR
 ## The Navigation Problem
 
 In large repositories, agents and IDEs do not always open the workspace from
-the root. They may start in `src/`, `deploy/`, a specific application, or a
-nested project folder.
+the root. They may start in product code, CI/CD config, infrastructure code,
+generated artifacts, a specific application, or a nested project folder.
 
 If all guidance lives at the top, it may be missed. But if each area keeps its
 own plans, cross-project work becomes fragmented.
@@ -86,15 +86,15 @@ So the rule became:
 
 Local `AGENTS.md` files can point agents toward the right place. But plans,
 specs, ADRs, release context, testing strategy, delivery notes, and
-infrastructure context should live centrally under `Development/`.
+infrastructure context should live centrally under `context/`.
 
 ```mermaid
 flowchart TD
   Root["Repository root"]
-  AreaA["src/AGENTS.md<br/>local signpost"]
-  AreaB["deploy/AGENTS.md<br/>local signpost"]
-  AreaC["apps/*/AGENTS.md<br/>local signpost"]
-  Dev["Development/<br/>central working context"]
+  AreaA["product area AGENTS.md<br/>local signpost"]
+  AreaB["delivery area AGENTS.md<br/>local signpost"]
+  AreaC["nested project AGENTS.md<br/>local signpost"]
+  Dev["context/<br/>central working context"]
   Initiative["Release initiative<br/>single delivery story"]
 
   Root --> Dev
@@ -107,7 +107,7 @@ flowchart TD
 ## The Core Model
 
 Code-Anchored Context uses explicit terminology, captured in
-`Development/terminology.md`. That matters because agents need stable
+`context/terminology.md`. That matters because agents need stable
 vocabulary as much as humans do.
 
 The main containers are:
@@ -122,7 +122,7 @@ Planned initiative
 Release initiative
   Active or historical delivery work for a specific release.
 
-Development backlog item
+Context backlog item
   Isolated work cut from scope but worth preserving.
 
 Program release slice
@@ -132,7 +132,7 @@ Program release slice
 This gives each kind of context a natural home.
 
 ```text
-Development/
+context/
   terminology.md
   current.md
   programs/
@@ -168,7 +168,7 @@ flowchart TD
 Release initiatives are the main unit of active delivery.
 
 ```text
-Development/releases/v0_1_0/initiatives/<initiative>/
+context/releases/v0_1_0/initiatives/<initiative>/
   README.md
   plan.md
   spec.md
@@ -276,7 +276,7 @@ stable knowledge a place to land.
 ## Testing, Delivery, And Infrastructure
 
 The model treats verification, delivery, and infrastructure as first-class
-development context.
+working context.
 
 That matters because agents often need to answer questions beyond "what code
 should change?"
@@ -332,7 +332,7 @@ Some work is bigger than one release.
 A program holds durable context for multi-release work:
 
 ```text
-Development/programs/<program>/
+context/programs/<program>/
   README.md
   context.md
   roadmap.md
@@ -350,7 +350,7 @@ future phase is clear enough to plan, but the target release is not current
 yet, it becomes a planned initiative:
 
 ```text
-Development/programs/<program>/planned-initiatives/<initiative>/
+context/programs/<program>/planned-initiatives/<initiative>/
 ```
 
 A planned initiative can also preserve future testing, delivery, or
@@ -365,7 +365,7 @@ When the target release becomes current, the planned initiative is promoted
 into:
 
 ```text
-Development/releases/<version>/initiatives/<initiative>/
+context/releases/<version>/initiatives/<initiative>/
 ```
 
 Promotion is explicit and traceable. The original planned initiative remains
@@ -386,7 +386,7 @@ flowchart LR
   History -.->|"links to promoted initiative"| Release
 ```
 
-## Development Backlog
+## Context Backlog
 
 Not every deferred item deserves a program or planned initiative.
 
@@ -394,7 +394,7 @@ Sometimes work is cut from scope because of risk, timing, or focus, but it is
 still worth preserving. That belongs in:
 
 ```text
-Development/backlog/items/
+context/backlog/items/
   <originating-initiative>--<item>.md
 ```
 
@@ -408,7 +408,7 @@ release initiative. It is not silently rewritten.
 
 Changing the current release is not just editing a pointer.
 
-`Development/current.md` identifies the active release, but moving from one
+`context/current.md` identifies the active release, but moving from one
 release to another is a release transition. During that transition, agents
 should scan program planned initiatives, find items targeting the new release,
 promote them into the release folder, and update links both ways.
@@ -462,22 +462,22 @@ It helps agents and humans answer:
 The mental model is simple:
 
 ```text
-Documentation/
+docs/
   Released truth.
 
-Development/releases/
+context/releases/
   Release-scoped delivery truth.
 
-Development/programs/
+context/programs/
   Multi-release truth.
 
-Development/programs/*/planned-initiatives/
+context/programs/*/planned-initiatives/
   Future scoped program work.
 
-Development/backlog/
+context/backlog/
   Deferred isolated work.
 
-Development/terminology.md
+context/terminology.md
   Shared vocabulary.
 
 AGENTS.md
@@ -486,7 +486,7 @@ AGENTS.md
 
 Code tells an agent what exists.
 
-Development context tells it why it exists, where it is going, what has
+Working context tells it why it exists, where it is going, what has
 already been decided, how it should be verified, how it should ship, what
 infrastructure it relies on, and what has intentionally been left for later.
 

package/{Development → context}/programs/README.md

@@ -10,7 +10,7 @@ Use a program when an effort has:
 - planned future work that should remain visible
 - context that would be lost if it lived only in one release initiative
 
-Create programs from `Development/_templates/program/`.
+Create programs from `context/_templates/program/`.
 
 ## Planned Initiatives
 
@@ -19,7 +19,7 @@ to scope, split, or preserve implementation intent, but the target release is
 not current yet.
 
 When a planned initiative's target release becomes current, promote it into
-`Development/releases/<version>/initiatives/` and leave the planned initiative
+`context/releases/<version>/initiatives/` and leave the planned initiative
 behind as historical planning context.
 
 ## Current Programs

package/{Development → context}/releases/v0_1_0/README.md

@@ -1,6 +1,6 @@
-# v0.1.0 Development Context
+# v0.1.0 Context
 
-This folder contains development context for the `v0_1_0` release.
+This folder contains working context for the `v0_1_0` release.
 
 ## Navigation
 
@@ -14,20 +14,20 @@ Create an initiative when work is non-trivial, behavior-changing,
 cross-project, release-significant, or likely to need future product
 documentation.
 
-Use `Development/_templates/initiative/` as the starting point.
+Use `context/_templates/initiative/` as the starting point.
 
 ## Carry-Forward Rule
 
 If an initiative is part of a larger phased effort, link it to a program
-under `Development/programs/`.
+under `context/programs/`.
 
 If isolated work is cut from scope but should be kept for later, create a
-backlog item under `Development/backlog/items/` and link it back to the
+backlog item under `context/backlog/items/` and link it back to the
 originating initiative.
 
 ## Planned Initiative Promotion
 
 When this release becomes current, promote matching planned initiatives from
-`Development/programs/*/planned-initiatives/` into this release's
+`context/programs/*/planned-initiatives/` into this release's
 `initiatives/` folder. Leave the planned initiative in place as historical
 planning context and update its status to `Promoted`.

package/{Development → context}/releases/v0_1_0/backlog.md

@@ -1,6 +1,6 @@
 # v0.1.0 Backlog
 
-This file tracks release-level development context that is not yet captured
+This file tracks release-level working context that is not yet captured
 by an initiative, plus a short summary of initiative progress once
 initiatives exist.
 

package/{Development → context}/terminology.md

@@ -1,29 +1,29 @@
-# Development Terminology
+# Context Terminology
 
 This glossary defines the terms used by the Code-Anchored Context practice in
-`Development/`. Use these terms consistently in programs, initiatives,
+`context/`. Use these terms consistently in programs, initiatives,
 backlog items, ADRs, agent summaries, and release-transition work.
 
 ## Core Folders
 
 | Term | Meaning |
 | --- | --- |
-| `Development/` | Working development context: plans, specs, ADRs, implementation notes, delivery-surface context, future scope, and release-documentation notes. |
-| `Documentation/` | Released product documentation. It describes shipped behavior for a release/tag and is not edited during normal development work. |
-| `Development/current.md` | Pointer to the current active release context. Updating this is a release transition. |
-| `Development/releases/<version>/` | Release-scoped development context for one version. |
-| `Development/programs/` | Durable multi-release development context. |
-| `Development/backlog/items/` | Deferred isolated work cut from initiatives but worth preserving. |
+| `context/` | Working context: plans, specs, ADRs, implementation notes, delivery-surface context, future scope, and release-documentation notes. |
+| `docs/` | Released product documentation. It describes shipped behavior for a release/tag and is not edited during normal development work. |
+| `context/current.md` | Pointer to the current active release context. Updating this is a release transition. |
+| `context/releases/<version>/` | Release-scoped working context for one version. |
+| `context/programs/` | Durable multi-release working context. |
+| `context/backlog/items/` | Deferred isolated work cut from initiatives but worth preserving. |
 
 ## Work Containers
 
 | Term | Meaning | Lives in |
 | --- | --- | --- |
-| Program | A cross-release parent effort with durable context, roadmap, phase history, and program-level decisions. | `Development/programs/<program-slug>/` |
-| Planned initiative | A scoped future delivery slice that belongs to a program but is not in the current release yet. | `Development/programs/<program-slug>/planned-initiatives/<initiative-slug>/` |
-| Release initiative | An active or historical delivery slice for a specific release. | `Development/releases/<version>/initiatives/<initiative-slug>/` |
-| Development backlog item | Isolated deferred work that was cut from an initiative and may be picked up later. | `Development/backlog/items/<originating-initiative>--<item>.md` |
-| Program release slice | A program-level summary of what a release is expected to do or did for the program. | `Development/programs/<program-slug>/releases/<version>.md` |
+| Program | A cross-release parent effort with durable context, roadmap, phase history, and program-level decisions. | `context/programs/<program-slug>/` |
+| 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>/` |
+| Release initiative | An active or historical delivery slice for a specific release. | `context/releases/<version>/initiatives/<initiative-slug>/` |
+| 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` |
+| 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` |
 
 ## Choosing The Right Container
 
@@ -36,7 +36,7 @@ or needs a roadmap beyond one release.
 Use a planned initiative when future program work is clear enough to plan,
 specify, or split, but the target release is not current yet.
 
-Use a development backlog item when an isolated piece of work was cut from
+Use a context backlog item when an isolated piece of work was cut from
 scope and should be preserved, but it does not need program-level context.
 
 ## Files
@@ -45,7 +45,7 @@ The structure follows delivery concerns, not technologies. Use concern names
 such as `testing.md`, `delivery.md`, and `infrastructure.md`; name specific
 tools inside those files only when the tools matter.
 
-Mermaid is the preferred diagram syntax for development context because it is
+Mermaid is the preferred diagram syntax for working context because it is
 both readable Markdown for agents and renderable visual context for humans.
 
 | Term | Meaning |
@@ -60,7 +60,7 @@ both readable Markdown for agents and renderable visual context for humans.
 | `infrastructure.md` | Stable description of environment shape, IaC, resources, networking, identity, storage, secrets, and environment dependencies. |
 | `operations.md` | Optional actionable runtime support context: observability, failure modes, rollback, repair, support procedures, and tooling. |
 | `backlog.md` | Trackable work items for the containing initiative or program. |
-| `release-doc-notes.md` | Notes for future product documentation refresh work. This is the bridge to `Documentation/`. |
+| `release-doc-notes.md` | Notes for future product documentation refresh work. This is the bridge to `docs/`. |
 | ADR | Architecture Decision Record. Use for durable decisions and tradeoffs. |
 | `brief.html` | Optional human-friendly presentation layer. |
 
@@ -88,15 +88,15 @@ Planned initiatives are promoted when their target release becomes current or
 when release planning explicitly begins:
 
 ```text
-Development/programs/<program>/planned-initiatives/<initiative>/
-  -> Development/releases/<version>/initiatives/<initiative>/
+context/programs/<program>/planned-initiatives/<initiative>/
+  -> context/releases/<version>/initiatives/<initiative>/
 ```
 
 Backlog items are promoted when someone decides to pick them up:
 
 ```text
-Development/backlog/items/<originating-initiative>--<item>.md
-  -> Development/releases/<version>/initiatives/<initiative>/
+context/backlog/items/<originating-initiative>--<item>.md
+  -> context/releases/<version>/initiatives/<initiative>/
 ```
 
 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
 
 ## Release Transition
 
-A release transition is the act of changing `Development/current.md` to a new
+A release transition is the act of changing `context/current.md` to a new
 release. This is not just a line edit.
 
 During a release transition, agents should:
@@ -117,4 +117,4 @@ During a release transition, agents should:
 - update links both ways
 - leave planned initiatives as historical planning context
 
-Use `Development/_templates/release-transition.md` as the checklist.
+Use `context/_templates/release-transition.md` as the checklist.

package/{Documentation → docs}/Welcome.md

@@ -1,15 +1,15 @@
-# PROJECT_NAME Documentation
+# PROJECT_NAME Docs
 
 Welcome to the release-anchored documentation for PROJECT_NAME.
 
 This folder describes shipped behavior for a known release or tag. It is not
 the place for in-progress feature planning, implementation notes, or draft
-architecture decisions. Put that work in `Development/`.
+architecture decisions. Put that work in `context/`.
 
-## How This Documentation Is Organized
+## How These Docs Are Organized
 
 ```text
-Documentation/
+docs/
   .order
   Welcome.md
   releases/
@@ -30,14 +30,19 @@ Every documented area should have:
 
 - a high-level `README.md` that explains the area's purpose and architecture
 - one page per feature under `features/`
-- an authoring guide under `Documentation/_authoring/areas/`
+- an authoring guide under `docs/_authoring/areas/`
 
 ## Contributing
 
 - Refresh docs only when explicitly asked.
+- For existing projects with no docs, create baseline documentation only when
+  explicitly asked; otherwise document touched behavior during future release
+  refreshes.
 - Write for non-developer technical readers unless the project states
   otherwise.
+- Write from behavior outward: product-readable first, technically anchored
+  where details affect shipped behavior, operations, or support.
 - Describe behavior, inputs, outputs, permissions, errors, business rules, and
   operational expectations in domain language.
 - Prefer Mermaid diagrams for flows, architecture, and relationships.
-- Add release refreshes to `Documentation/releases/index.md`.
+- Add release refreshes to `docs/releases/index.md`.

package/{Documentation → docs}/_authoring/README.md

@@ -1,7 +1,7 @@
-# Documentation Authoring Guide
+# Docs Authoring Guide
 
 This subtree owns all guidance for authoring and refreshing the documentation
-under `Documentation/`. Humans and agents both read from here to know how
+under `docs/`. Humans and agents both read from here to know how
 documentation is structured, when it is refreshed, what belongs in each area,
 and which domain terminology to use.
 
@@ -18,13 +18,14 @@ and which domain terminology to use.
 Create one authoring guide per documented area:
 
 ```text
-Documentation/_authoring/areas/<area-slug>.md
+docs/_authoring/areas/<area-slug>.md
 ```
 
 Each area guide should identify:
 
-- the code folder or folders that own the behavior
-- the documentation root under `Documentation/`
+- the source locations that own the behavior, such as product code,
+  interfaces, tests, CI/CD, generated artifacts, infrastructure, or config
+- the docs root under `docs/`
 - feature pages that should exist
 - behavior that matters at release time
 - changes to ignore, such as pure refactors or test-only edits

package/{Documentation → docs}/_authoring/areas/README.md

@@ -5,7 +5,7 @@ This folder contains one authoring guide per documented area.
 Create a guide from `_template.md` when adding a documentation area:
 
 ```text
-Documentation/_authoring/areas/<area-slug>.md
+docs/_authoring/areas/<area-slug>.md
 ```
 
 Each guide should help a human or agent refresh docs from a release diff

package/{Documentation → docs}/_authoring/areas/_template.md

@@ -2,17 +2,25 @@
 
 ## Scope
 
-- Code root: `path/to/code`
-- Documentation root: `Documentation/<Area>/`
+- Source orientation: `path/to/runtime-or-product-code`, `path/to/contracts`,
+  `path/to/tests`, `path/to/ci-or-delivery`, `path/to/infra-or-config`
+- Docs root: `docs/<Area>/`
 - Owner or reviewer: TBD
 
 Describe what this area owns and what it intentionally does not own.
 
+## Audience And Depth
+
+State any area-specific audience or depth rules. By default, write for
+Product Owners, QA, support, operators, customer engineers, and technical
+readers who need behavior, rules, data effects, permissions, errors, and
+operational expectations without private implementation detail.
+
 ## Feature Inventory
 
-| Feature | Documentation page | Notes |
+| Feature | Docs page | Notes |
 | --- | --- | --- |
-| TBD | `Documentation/<Area>/features/<feature>.md` | TBD |
+| TBD | `docs/<Area>/features/<feature>.md` | TBD |
 
 ## What Matters At Release Time
 
@@ -41,9 +49,15 @@ Ignore changes that do not alter released behavior:
 List the files, folders, entry points, or search terms that help an agent map a
 release diff to documentation pages.
 
+## Baseline Discovery Notes
+
+Use this section when creating first-pass documentation for an existing
+project. List stable workflows, important entry points, source references,
+known gaps, and questions that should not yet appear in product-facing docs.
+
 ## Terminology
 
-List area-specific terms or link to `Documentation/_authoring/terminology.md`.
+List area-specific terms or link to `docs/_authoring/terminology.md`.
 
 ## Cross-Links
 

package/{Documentation → docs}/_authoring/terminology.md

@@ -2,7 +2,7 @@
 
 Use this file to define the domain language that documentation should use.
 
-Documentation should translate code-level names into reader-facing domain
+Docs should translate code-level names into reader-facing domain
 terms when those differ. The goal is consistency for QA, product, support,
 operators, and future agents.