code-anchored-context 0.1.0

package/.agents/skills/README.md

@@ -0,0 +1,13 @@
+# Project Skills
+
+This directory contains repository-wide skills for agents working in this
+project.
+
+- Each skill is a folder containing a `SKILL.md` file.
+- Skills are loaded on demand for repeated workflows and project conventions.
+
+## Repository-Wide Skills
+
+- `development-initiative-context` - use central `Development/` initiatives
+  for planning, implementation context, programs, planned initiatives, ADRs,
+  backlog, and release-documentation notes.

package/.agents/skills/development-initiative-context/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: development-initiative-context
+description: Use central repository Development context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating Development/current.md, Development/releases/*/initiatives/*, Development/programs/*, Development/programs/*/planned-initiatives/*, Development/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 Documentation/ should be left untouched.
+---
+
+# Development Initiative Context
+
+## Overview
+
+Use this skill to connect code work back to the central development context
+under `Development/`. The goal is to keep initiative knowledge centralized,
+preserve durable multi-release context in programs, and keep deferred
+isolated work discoverable in the development backlog. Scoped future program
+work belongs in planned initiatives until the target release becomes current.
+Development context should also cover delivery concerns such as testing,
+delivery pipelines, and infrastructure when they affect how the work is
+verified, shipped, deployed, or hosted.
+
+## Workflow
+
+### 1) Read The Local Rules
+
+Read the nearest `AGENTS.md` files for the workspace and area being changed.
+Respect area-specific engineering rules first.
+
+### 2) Find The Current Development Context
+
+Open `Development/current.md` from the repository root. It points to the
+active release folder.
+
+Use `Development/terminology.md` as the canonical vocabulary for programs,
+planned initiatives, release initiatives, backlog items, statuses, and
+promotion.
+
+If the workspace starts inside a subfolder, navigate upward to the repository
+root when the environment allows it. If `Development/` is not available in
+the workspace, mention that limitation in the task summary.
+
+### 3) Match Existing Context
+
+Search these places for matching context:
+
+- active release initiatives under `Development/releases/<current-release>/initiatives/`
+- durable programs under `Development/programs/`
+- scoped future program work under `Development/programs/<program>/planned-initiatives/`
+- deferred items under `Development/backlog/items/`
+
+Search for:
+
+- the feature or bug name
+- affected area names, such as frontend, API, shared library, deploy, or
+  automation
+- related domain terms, APIs, jobs, entities, routes, config names, or tickets
+
+Use an existing initiative when the work belongs to it, even if the code
+change is local to one project. If the initiative is part of a multi-release
+effort, link it to the relevant program.
+
+### 4) Create An Initiative When Needed
+
+Create a new initiative for non-trivial behavior changes, cross-project
+work, release-significant work, or anything likely to need future product
+documentation.
+
+Use `Development/_templates/initiative/` as the source. Copy it to:
+
+```text
+Development/releases/<current-release>/initiatives/<initiative-slug>/
+```
+
+Update the copied `README.md` first so future agents can quickly understand
+status, scope, touched areas, open questions, and implementation state. Use
+`plan.md` for live alignment with the human before the stable initiative
+files settle.
+
+For tiny localized fixes that do not belong to an initiative, do not invent
+process. Summarize that no initiative was needed.
+
+### 5) Capture Planned Future Initiatives
+
+If future program work is known well enough to scope, split, or preserve
+implementation intent, create a planned initiative under the parent program:
+
+```text
+Development/programs/<program-slug>/planned-initiatives/<initiative-slug>/
+```
+
+Use `Development/_templates/planned-initiative/` as the source.
+
+Use a planned initiative when:
+
+- the work belongs to a program
+- the target release is not current yet
+- the future phase is clear enough for a plan, spec, or backlog
+- capturing it only in `roadmap.md` or `releases/<version>.md` would lose
+  useful scope or implementation context
+
+Do not create a future `Development/releases/<version>/` initiative just to
+hold planned work unless that release is being made current or release
+planning has explicitly begun.
+
+### 6) Carry Context Forward When Scope Changes
+
+Use the right outliving path when initiative context needs to survive beyond
+the current release:
+
+- `Development/programs/<program-slug>/`: multi-release efforts, phases,
+  roadmaps, durable decisions, and release-slice history
+- `Development/programs/<program-slug>/planned-initiatives/<initiative-slug>/`:
+  scoped future delivery slices that are not in the current release yet
+- `Development/backlog/items/<originating-initiative-slug>--<item-slug>.md`:
+  isolated deferred work cut from an initiative
+
+When creating a backlog item, use `Development/_templates/backlog-item.md`
+and link to the originating initiative and release.
+
+When picking up a backlog item later, keep the item as a historical record.
+Mark it as promoted and link to the new release initiative.
+
+### 7) Transition The Current Release
+
+When asked to set a new current release, treat it as a release transition,
+not just a `current.md` edit.
+
+Use `Development/_templates/release-transition.md` as the checklist:
+
+1. Update `Development/current.md`.
+2. Create `Development/releases/<target-release>/` from
+   `Development/_templates/release-context/` if missing.
+3. Scan `Development/programs/*/planned-initiatives/*/README.md` for
+   `Target release: <target-release>`.
+4. Promote each match into:
+
+```text
+Development/releases/<target-release>/initiatives/<initiative-slug>/
+```
+
+5. Update the planned initiative metadata to `Status: Promoted`, with
+   `Promoted to:` and `Promoted on:`.
+6. Link both directions between the program/planned initiative and the
+   promoted release initiative.
+
+Planned initiatives are promoted, not moved silently. Leave the planned
+initiative in place as historical planning context.
+
+### 8) Update The Right Files
+
+Use these files as the standard map:
+
+- `README.md`: entry point, status, touched areas, links, open questions
+- `plan.md`: working alignment space for rough notes, questions, options,
+  and notes to promote
+- `spec.md`: what the system should do
+- `interface.md`: how humans, clients, APIs, config, or tools interact with it
+- `architecture.md`: internal shape, boundaries, flows, contracts, data
+  Use Mermaid for diagrams when a flow or relationship is clearer visually;
+  it remains readable Markdown for agents and renders for humans.
+- `testing.md`: verification strategy, coverage, test data, release gates
+- `delivery.md`: CI/CD, build behavior, deployment flow, environment
+  promotion, release toggles, delivery automation
+- `infrastructure.md`: environment shape, IaC, resources, networking,
+  identity, storage, secrets, environment dependencies
+- `operations.md`: optional actionable runtime/support context such as
+  observability, failure modes, rollback, repair, and support tooling
+- `backlog.md`: work slices and implementation progress
+- `decisions/ADR-*.md`: meaningful choices and their consequences
+- `release-doc-notes.md`: product-documentation impact to review at release
+
+Not every initiative needs every file. Mark a file as not applicable or omit
+it after copying the template when it genuinely does not apply.
+
+`plan.md` is allowed to be messy, but it must not become the only place where
+settled truth lives. Promote stable conclusions into `spec.md`,
+`interface.md`, `architecture.md`, `testing.md`, `delivery.md`,
+`infrastructure.md`, `operations.md` when actionable, `backlog.md`, ADRs, or
+`release-doc-notes.md` as appropriate.
+
+### 9) Preserve The Documentation Boundary
+
+Do not edit `Documentation/` as part of normal feature work, bug fixes,
+refactors, or planning. Instead, update the initiative's
+`release-doc-notes.md`.
+
+Only update `Documentation/` when a human explicitly asks for release
+documentation work, a specific page update, or a demonstrable documentation
+fix.
+
+## Knowledge Ownership
+
+Denormalize navigation, not knowledge.
+
+Local `AGENTS.md` files may point to `Development/`, but initiative specs,
+plans, ADRs, and release-doc notes should live in the central initiative
+folder. Do not create area-local copies of initiative documents.
+
+## Completion Check
+
+Before finishing behavior-changing work:
+
+- The matching initiative was read or a reason was given for why none exists.
+- Matching programs or development backlog items were checked when the work
+  appears phased, deferred, or multi-release.
+- Planned initiatives were checked or created when future program scope is
+  already clear but outside the current release.
+- Any changed behavior, interface, architecture, testing, delivery,
+  infrastructure, actionable operations, or backlog state was reflected in the
+  initiative when appropriate.
+- Future product-documentation impact was captured in `release-doc-notes.md`.
+- `Documentation/` was left untouched unless explicitly requested.

package/AGENTS.md

@@ -0,0 +1,52 @@
+# Agent Guidance - PROJECT_NAME
+
+This file applies to the whole repo. Area-specific `AGENTS.md` files in
+subfolders layer on top of it. Read those too when working in a given area.
+
+## Development Context
+
+In-progress specs, plans, ADRs, backlog, implementation context, and
+release-documentation notes live under [`Development/`](Development/).
+Start with [`Development/current.md`](Development/current.md).
+
+For behavior-changing work, use the repo-wide skill at
+[`.agents/skills/development-initiative-context/SKILL.md`](.agents/skills/development-initiative-context/SKILL.md).
+Keep initiative knowledge centralized under `Development/`; area
+`AGENTS.md` files should point there rather than copying active plans.
+
+## Documentation Authoring
+
+### When To Edit `Documentation/`
+
+Do not edit `Documentation/` as a side effect of feature work, bug fixes,
+refactors, or other code changes. Docs in this model are release-anchored:
+they describe the behavior of a specific release tag, not the partial state of
+a working branch.
+
+Touch `Documentation/` only when:
+
+- A human explicitly asks you to refresh the docs for a release, typically
+  after a release tag is cut and QA has signed off.
+- A human explicitly asks you to update a specific page.
+- A human asks you to fix a demonstrable error in an existing page, such as a
+  broken link or factual inaccuracy.
+
+If you are unsure whether the request is one of these, ask before editing.
+
+If a project has documentation that intentionally follows a different cadence,
+document that exception in the area's README and in
+`Documentation/_authoring/areas/`.
+
+### Where The Authoring Guidance Lives
+
+All documentation workflow, per-area authoring guides, and domain terminology
+live under [`Documentation/_authoring/`](Documentation/_authoring/). Start
+with [`Documentation/_authoring/README.md`](Documentation/_authoring/README.md).
+
+If you are refreshing docs, the per-area guides in
+[`Documentation/_authoring/areas/`](Documentation/_authoring/areas/) tell you
+what matters and what to ignore for each area.
+
+`AGENTS.md` files stay lean. They are for coding conventions and agent
+restrictions, not detailed documentation guidance. If you have doc rules to
+add, add them under `_authoring/`.

package/Development/AGENTS.md

@@ -0,0 +1,46 @@
+# Agent Guidance - Development
+
+Scope: everything under `/Development`.
+
+## Purpose
+
+This folder is the canonical home for in-progress development context: specs,
+interface notes, architecture notes, actionable operations notes, ADRs,
+backlogs, implementation plans, and release-documentation notes.
+
+Testing, delivery, and infrastructure notes belong here when they affect how
+work is verified, shipped, deployed, or hosted. Operational notes belong here
+only when they are actionable runtime, support, observability, rollback, or
+repair context.
+
+`Development/` describes what is being planned, built, debated, or validated.
+`Documentation/` describes what has shipped for a release.
+
+## Editing Rules
+
+- Use `Development/terminology.md` as the canonical vocabulary for programs,
+  planned initiatives, release initiatives, backlog items, and promotion.
+- Keep initiative knowledge centralized here. Area `AGENTS.md` files may point
+  here, but they should not duplicate initiative content.
+- Do not move in-progress plans into `Documentation/`.
+- Use `release-doc-notes.md` inside an initiative to capture what may need to
+  become product documentation later.
+- Create initiatives from `Development/_templates/initiative/`.
+- Create durable multi-release programs from `Development/_templates/program/`.
+- Create scoped future program work from
+  `Development/_templates/planned-initiative/` under a program's
+  `planned-initiatives/` folder.
+- Create deferred isolated backlog items from
+  `Development/_templates/backlog-item.md`.
+- Keep release initiative history in the release folder. Use `programs/` for
+  multi-release context, `planned-initiatives/` for scoped future program work,
+  and `backlog/items/` for isolated deferred work.
+- Treat changes to `Development/current.md` as release transitions. Use
+  `Development/_templates/release-transition.md` and promote matching planned
+  initiatives for the new current release.
+- When a backlog item is picked up later, mark it as promoted and link to the
+  new release initiative instead of rewriting the item into an active plan.
+- Keep templates practical. If a file does not apply to an initiative, mark it
+  as not applicable or omit it after copying the template.
+- Use `operations.md` only for actionable runtime, support, observability,
+  rollback, or repair context.

package/Development/README.md

@@ -0,0 +1,259 @@
+# Development
+
+This folder is the working memory for active and historical development
+context in this repository.
+
+Use it for specs, interface notes, architecture notes, testing notes, delivery
+notes, infrastructure notes, actionable operations notes, ADRs, backlog items,
+implementation plans, and release-documentation notes. Do not use
+`Documentation/` for in-progress development planning.
+
+## 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 development context.
+- `backlog/` contains deferred isolated work cut from initiatives.
+- `releases/` contains release-scoped development context.
+- `_templates/initiative/` contains the standard initiative shape.
+- `_templates/planned-initiative/` contains the standard future initiative
+  shape for scoped program work outside the current release.
+- `_templates/release-context/` contains the standard release folder shell.
+
+## Relationship To Documentation
+
+`Development/` and `Documentation/` serve different jobs:
+
+| Folder | Meaning | Updated when |
+| --- | --- | --- |
+| `Development/` | What we are planning, building, deciding, or validating. | During normal development. |
+| `Documentation/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
+
+Development notes can feed release documentation, but they are not product
+documentation. Capture that bridge in each initiative's
+`release-doc-notes.md`.
+
+## Core Model
+
+The vocabulary for this context model is defined in `terminology.md`.
+
+Release initiatives are the durable unit of release-scoped development
+context. An initiative may touch one project, many projects, IaC, automation,
+tests, or all of them. Keep the release story in one initiative folder even
+when the code changes span several areas.
+
+Some context needs to outlive a single release initiative:
+
+| Place | Use for |
+| --- | --- |
+| `Development/programs/` | Long-lived multi-release efforts, phase history, roadmaps, and durable decisions. |
+| `Development/programs/<program>/planned-initiatives/` | Scoped future delivery slices that belong to a program but are not in the current release yet. |
+| `Development/backlog/items/` | Deferred isolated work cut from an initiative but worth preserving. |
+| `Development/releases/<version>/initiatives/` | Release-scoped delivery slices and historical implementation context. |
+
+The rule is:
+
+> Active work belongs in a release initiative. Multi-release context belongs in
+> a program. Scoped future program work belongs in a planned initiative.
+> Deferred isolated work belongs in the development backlog.
+
+The delivery-surface rule is:
+
+> Structure follows delivery concerns, not technologies.
+
+Use `testing.md`, `delivery.md`, and `infrastructure.md` for concern-based
+context. Mention specific tools inside those files only when the tools matter.
+
+Mermaid diagrams are encouraged for flows, dependencies, and lifecycle maps
+because they stay readable as Markdown for agents while rendering as visible
+diagrams for humans.
+
+The navigation rule is:
+
+> Denormalize navigation, not knowledge.
+
+Area `AGENTS.md` files should point agents back to this folder. They should
+not copy specs, plans, or ADRs into area-local documents.
+
+## Standard Layout
+
+```text
+Development/
+  current.md
+  programs/
+    <program-slug>/
+      README.md
+      context.md
+      roadmap.md
+      backlog.md
+      decisions/
+      planned-initiatives/
+        <planned-initiative-slug>/
+          README.md
+          plan.md
+          spec.md
+      releases/
+        v0_1_0.md
+  backlog/
+    README.md
+    items/
+      <originating-initiative-slug>--<item-slug>.md
+  releases/
+    v0_1_0/
+      README.md
+      backlog.md
+      initiatives/
+        <initiative-slug>/
+          README.md
+          plan.md
+          spec.md
+          interface.md
+          architecture.md
+          testing.md
+          delivery.md
+          infrastructure.md
+          operations.md
+          backlog.md
+          decisions/
+            ADR-0000-template.md
+          release-doc-notes.md
+          brief.html
+```
+
+## Programs
+
+Programs preserve durable context for work that spans releases or phases. Use a
+program when the larger effort has a roadmap, several release slices, important
+decisions, or remaining scope that should stay visible after a release
+initiative closes.
+
+Use `planned-initiatives/` inside a program when future work is already clear
+enough to scope, split, or preserve implementation intent, but the target
+release is not current yet. Planned initiatives are promoted into release
+initiatives when their target release becomes current.
+
+Release initiatives should link to their program when one exists. Programs
+should link back to the release initiatives that delivered each slice.
+
+Do not use a program for a small leftover task. Use
+`Development/backlog/items/` for deferred isolated work.
+
+## Development Backlog
+
+Use `Development/backlog/items/` for isolated work that was taken out of an
+initiative's scope but should be kept for later. Each backlog item records its
+origin initiative and release.
+
+When a backlog item is picked up later, keep the backlog item as a historical
+record. Mark it as promoted and link to the new release initiative instead of
+rewriting the item into the new plan.
+
+## Planned Initiatives
+
+Planned initiatives are scoped children of a program that target a future
+release. They preserve clear future scope without pretending that the future
+release is already active.
+
+Use a planned initiative when:
+
+- the future phase is clear enough to write a plan, spec, or backlog
+- the work belongs to a program
+- the target release is known or likely
+- the current release should not own active delivery for that scope yet
+
+When the target release becomes current, promote the planned initiative into
+the target release's `initiatives/` folder and leave the planned initiative
+behind as historical planning context.
+
+## Delivery Concerns
+
+Release initiatives should describe the whole delivery surface when it matters,
+not only the application code.
+
+| File | Use for |
+| --- | --- |
+| `testing.md` | Verification strategy, automated coverage, manual checks, test data, regression risk, and release gates. |
+| `delivery.md` | CI/CD, build behavior, deployment flow, environment promotion, release toggles, and delivery automation. |
+| `infrastructure.md` | Environment shape, IaC, resources, networking, identity, storage, secrets, and environment dependencies. |
+
+At the program level, use equivalent concern files only when the concern spans
+multiple releases. A release-local test plan belongs in the release initiative.
+A cross-release migration testing strategy may belong in the program.
+
+## Initiative Files
+
+Required for most initiatives:
+
+| File | Purpose |
+| --- | --- |
+| `README.md` | Agent entry point, status, scope, touched areas, links, open questions. |
+| `plan.md` | Working alignment space for humans and agents; rough notes, questions, options, and points to promote. |
+| `spec.md` | What the system should do and which behavior is in or out. |
+| `backlog.md` | What is changing now, sliced into trackable work. |
+| `release-doc-notes.md` | Product documentation impact to review at release time. |
+
+Use when relevant:
+
+| File | Purpose |
+| --- | --- |
+| `interface.md` | How humans, clients, APIs, config, reports, or tools interact with it. |
+| `architecture.md` | Internal shape, boundaries, data flow, contracts, and tradeoffs. |
+| `testing.md` | Test strategy, automated/manual coverage, test data, and release gates. |
+| `delivery.md` | CI/CD, build, deployment, environment promotion, and release toggles. |
+| `infrastructure.md` | IaC, resources, environment shape, networking, identity, storage, and secrets. |
+| `operations.md` | Optional. Use only for actionable runtime, support, observability, rollback, or repair context. |
+| `decisions/ADR-*.md` | Why an important choice was made. |
+| `brief.html` | Optional human-friendly presentation layer. |
+
+## Carrying Context Forward
+
+When an initiative produces context that needs to survive after the release:
+
+- Move multi-release strategy, roadmap, and durable decisions into
+  `Development/programs/<program-slug>/`.
+- Move scoped future delivery slices into
+  `Development/programs/<program-slug>/planned-initiatives/<initiative-slug>/`.
+- Move isolated deferred work into
+  `Development/backlog/items/<originating-initiative-slug>--<item-slug>.md`.
+- Keep release-scoped plans, implementation history, and final release notes
+  inside the original initiative.
+
+## Changing The Current Release
+
+Changing `Development/current.md` is a release transition, not just a line
+edit. Use `Development/_templates/release-transition.md` as the checklist.
+Create missing release folders from `Development/_templates/release-context/`.
+
+When setting a release as current, agents should scan all program planned
+initiatives for matching `Target release:` metadata and promote matching items
+into `Development/releases/<version>/initiatives/`.
+
+The promotion rule is:
+
+> Planned initiatives are promoted, not moved silently.
+
+## Agent Workflow
+
+When changing behavior, agents should:
+
+1. Read the local `AGENTS.md`.
+2. Open `Development/current.md`.
+3. Check the current release's initiatives for matching context.
+4. Use `plan.md` for live alignment, open questions, and rough thinking.
+   Promote settled conclusions into the stable initiative files.
+5. Update the matching initiative when the change affects its scope.
+6. Create a new initiative from `_templates/initiative/` for non-trivial
+   behavior changes that do not belong to an existing initiative.
+7. Create or update a program planned initiative when future scoped work is
+   clear but belongs outside the current release.
+8. Record future product-doc impact in `release-doc-notes.md`, not in
+   `Documentation/`, unless a human explicitly asks for documentation refresh.
+
+The key rule for planning is:
+
+> `plan.md` is allowed to be messy, but it must not become the only place where
+> settled truth lives.

package/Development/_templates/backlog-item.md

@@ -0,0 +1,40 @@
+# Backlog Item Title
+
+Status: Candidate
+Originating initiative: `Development/releases/v0_1_0/initiatives/<initiative-slug>/`
+Originating release: `v0_1_0`
+Area: TBD
+Reason deferred: TBD
+Created: YYYY-MM-DD
+
+## Summary
+
+Briefly describe the deferred work.
+
+## Why It Was Deferred
+
+Explain the scope, risk, timing, dependency, or procedure that moved this
+out of the originating initiative.
+
+## Future Value
+
+Explain why this is worth preserving for later.
+
+## Re-Entry Criteria
+
+Describe what would make this worth picking up later.
+
+## Notes
+
+Capture useful implementation, design, test, operational, or support notes.
+
+## Promotion
+
+Status remains `Candidate` until it is picked up. When promoted, update this
+section and leave the item as a historical record.
+
+```md
+Status: Promoted
+Promoted to: `Development/releases/<version>/initiatives/<initiative-slug>/`
+```
+

package/Development/_templates/initiative/README.md

@@ -0,0 +1,59 @@
+# Initiative Title
+
+Status: Draft
+Release: v0_1_0
+Primary area: TBD
+Program: None
+
+## Summary
+
+Briefly describe the change, why it exists, and what outcome it should
+produce.
+
+## Touched Areas
+
+- `src/<area>/...`
+- `deploy/...`
+- `automation/...`
+
+Remove entries that do not apply and add the real paths.
+
+## Current Source Of Truth
+
+- `plan.md`
+- `spec.md`
+- `interface.md`
+- `architecture.md`
+- `testing.md`
+- `delivery.md`
+- `infrastructure.md`
+- `operations.md` when actionable
+- `backlog.md`
+- `release-doc-notes.md`
+
+Mark files as not applicable if they do not matter for this initiative.
+Create or keep `operations.md` only when there is actionable runtime,
+support, observability, rollback, or repair context.
+
+## Carry-Forward Context
+
+- Program: None
+- Deferred backlog items: None
+
+## Open Questions
+
+- None yet.
+
+## Implementation Status
+
+- Not started.
+
+## Agent Notes
+
+- Keep initiative knowledge in this folder.
+- Use `plan.md` for live alignment, questions, options, and rough thinking.
+  Promote settled conclusions into the stable initiative files.
+- Update `release-doc-notes.md` when shipped behavior or product-facing
+  behavior changes.
+- Do not update `Documentation/` from this initiative unless a human
+  explicitly asks for release documentation work.