code-anchored-context 0.1.0

package/Development/terminology.md

@@ -0,0 +1,120 @@
+# Development Terminology
+
+This glossary defines the terms used by the Code-Anchored Context practice in
+`Development/`. 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. |
+
+## 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` |
+
+## Choosing The Right Container
+
+Use a release initiative when work is active in the current release or is
+historical delivery context for a specific release.
+
+Use a program when the work spans releases, has phases, has durable decisions,
+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
+scope and should be preserved, but it does not need program-level context.
+
+## Files
+
+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
+both readable Markdown for agents and renderable visual context for humans.
+
+| Term | Meaning |
+| --- | --- |
+| `README.md` | Entry point for a folder. It should explain status, scope, links, and where to start. |
+| `plan.md` | Working alignment space for humans and agents. It may be messy, but settled truth must move into stable files. |
+| `spec.md` | Stable description of what the system should do. |
+| `interface.md` | Stable description of how humans, clients, APIs, config, reports, or tools interact with the work. |
+| `architecture.md` | Stable description of internal shape, boundaries, data flow, contracts, and tradeoffs. |
+| `testing.md` | Stable description of verification strategy, automated and manual coverage, test data, and release gates. |
+| `delivery.md` | Stable description of CI/CD, build behavior, deployment flow, environment promotion, release toggles, and delivery automation. |
+| `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/`. |
+| ADR | Architecture Decision Record. Use for durable decisions and tradeoffs. |
+| `brief.html` | Optional human-friendly presentation layer. |
+
+## Status Terms
+
+| Status | Meaning |
+| --- | --- |
+| Draft | Early context exists, but scope or direction is not settled. |
+| Planned | Future scope is known, but it is not active in the current release. |
+| Active | Work is part of the current release's delivery scope. |
+| Implementing | Code or documentation work is actively being changed. |
+| Blocked | Work cannot proceed until a dependency, decision, or external condition changes. |
+| Parked | Intentionally paused, but not abandoned. |
+| Deferred | Removed from current scope and kept for possible later work. |
+| Promoted | Planned or backlog work has been materialized into a release initiative. |
+| Superseded | Replaced by another plan, initiative, decision, or backlog item. |
+| Released | Delivered and preserved as historical release context. |
+
+## Promotion
+
+Promotion materializes future or deferred work into a release initiative.
+Promotion is explicit and traceable.
+
+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>/
+```
+
+Backlog items are promoted when someone decides to pick them up:
+
+```text
+Development/backlog/items/<originating-initiative>--<item>.md
+  -> Development/releases/<version>/initiatives/<initiative>/
+```
+
+Promotion does not silently move or delete the original context. Leave the
+original planned initiative or backlog item in place, update its status to
+`Promoted`, and link to the release initiative.
+
+## Release Transition
+
+A release transition is the act of changing `Development/current.md` to a new
+release. This is not just a line edit.
+
+During a release transition, agents should:
+
+- create the release folder if missing
+- scan programs for planned initiatives targeting the new release
+- promote matching planned initiatives into the release's `initiatives/`
+  folder
+- update links both ways
+- leave planned initiatives as historical planning context
+
+Use `Development/_templates/release-transition.md` as the checklist.

package/Documentation/.order

@@ -0,0 +1,2 @@
+Welcome
+releases

package/Documentation/Welcome.md

@@ -0,0 +1,43 @@
+# PROJECT_NAME Documentation
+
+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/`.
+
+## How This Documentation Is Organized
+
+```text
+Documentation/
+  .order
+  Welcome.md
+  releases/
+    index.md
+  _authoring/
+    README.md
+    workflow.md
+    terminology.md
+    areas/
+      <area>.md
+  <Area>/
+    README.md
+    features/
+      <feature>.md
+```
+
+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/`
+
+## Contributing
+
+- Refresh docs only when explicitly asked.
+- Write for non-developer technical readers unless the project states
+  otherwise.
+- 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`.

package/Documentation/_authoring/README.md

@@ -0,0 +1,45 @@
+# Documentation 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
+documentation is structured, when it is refreshed, what belongs in each area,
+and which domain terminology to use.
+
+## Start Here
+
+- [`workflow.md`](workflow.md) explains how docs are versioned, refreshed, and
+  structured.
+- [`terminology.md`](terminology.md) holds project-specific domain language.
+- [`areas/`](areas/) contains one file per documented area, covering feature
+  inventory, code orientation, conventions, and what matters at release time.
+
+## Area Guide Pattern
+
+Create one authoring guide per documented area:
+
+```text
+Documentation/_authoring/areas/<area-slug>.md
+```
+
+Each area guide should identify:
+
+- the code folder or folders that own the behavior
+- the documentation root under `Documentation/`
+- feature pages that should exist
+- behavior that matters at release time
+- changes to ignore, such as pure refactors or test-only edits
+- domain terms and cross-links specific to that area
+
+Use [`areas/_template.md`](areas/_template.md) when adding a new area guide.
+
+## Relationship To `AGENTS.md`
+
+Area `AGENTS.md` files may point here, but they should not copy the detailed
+documentation workflow. Keep authoring rules in this subtree so the guidance
+has one source of truth.
+
+## Contributing
+
+Edits to this subtree usually belong with documentation workflow changes or
+release refresh work. If a project's documented area changes shape, update the
+matching authoring guide.

package/Documentation/_authoring/areas/README.md

@@ -0,0 +1,16 @@
+# Area Authoring Guides
+
+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
+```
+
+Each guide should help a human or agent refresh docs from a release diff
+without rediscovering the area's structure from scratch.
+
+## Current Area Guides
+
+- None yet.

package/Documentation/_authoring/areas/_template.md

@@ -0,0 +1,51 @@
+# Area Name
+
+## Scope
+
+- Code root: `path/to/code`
+- Documentation root: `Documentation/<Area>/`
+- Owner or reviewer: TBD
+
+Describe what this area owns and what it intentionally does not own.
+
+## Feature Inventory
+
+| Feature | Documentation page | Notes |
+| --- | --- | --- |
+| TBD | `Documentation/<Area>/features/<feature>.md` | TBD |
+
+## What Matters At Release Time
+
+Document behavior changes that affect:
+
+- user, operator, or API-visible behavior
+- permissions, validation, or error handling
+- data creation, mutation, retention, or migration
+- integrations or external contracts
+- observability, support, or operational procedures
+- configuration, environment shape, or deployment behavior
+
+## What To Ignore
+
+Ignore changes that do not alter released behavior:
+
+- pure refactors
+- internal renames
+- formatting or lint-only changes
+- test-only changes
+- dependency bumps with no behavior impact
+- temporary migration scaffolding that will not ship as behavior
+
+## Code Orientation
+
+List the files, folders, entry points, or search terms that help an agent map a
+release diff to documentation pages.
+
+## Terminology
+
+List area-specific terms or link to `Documentation/_authoring/terminology.md`.
+
+## Cross-Links
+
+List related areas and when docs should cross-link instead of duplicating
+behavior.

package/Documentation/_authoring/terminology.md

@@ -0,0 +1,40 @@
+# Project Terminology
+
+Use this file to define the domain language that documentation should use.
+
+Documentation 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.
+
+## Core Terms
+
+| Term | Meaning | Code-level names to translate |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Relationships
+
+Use this section for named relationships between important domain concepts.
+
+| Relationship | Between | Meaning |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Guardrails
+
+Capture wording rules that prevent misleading documentation.
+
+Examples:
+
+- Prefer one canonical term over an overloaded code name.
+- Avoid implying that a relationship is permanent when it can change.
+- Call out standards-driven terms that must remain as-is.
+
+## Diagram
+
+Add a Mermaid diagram when relationships are easier to understand visually.
+
+```mermaid
+flowchart LR
+    ConceptA["Concept A"] -->|"relationship"| ConceptB["Concept B"]
+```

package/Documentation/_authoring/workflow.md

@@ -0,0 +1,123 @@
+# Documentation Workflow
+
+This file defines how documentation is versioned, refreshed, and structured
+across the repo. It applies to all documented areas; area-specific guidance
+lives in [`areas/`](areas/).
+
+## When Docs Get Edited
+
+Doc refresh is an explicit, on-request activity, not a side effect of code
+work. Humans or agents touch `Documentation/` only when:
+
+- A human explicitly asks for a release-time refresh, typically after the
+  release tag is cut and QA has signed off.
+- A human explicitly asks to update a specific page.
+- A human asks to fix a demonstrable error in an existing page, such as a
+  broken link or factual inaccuracy.
+
+Do not update docs as part of a feature PR, bug fix, refactor, or dependency
+bump. Mid-stream commits are partial work; "feature complete" is only
+well-defined once the release is accepted.
+
+Agents: if you are working on a code change and notice a doc that looks
+outdated, leave it alone. Flag the staleness in your summary or add it to the
+initiative's `release-doc-notes.md`, but do not edit the doc as part of the
+current change unless explicitly asked.
+
+## Cadence And Versioning
+
+Docs live under `Documentation/` and are refreshed once per release, at
+git-tag time, after release acceptance. Docs are anchored to the release tag;
+the docs at tag `release/v1_2_3` describe the behavior of that release.
+
+Default tag names follow the convention `release/vMAJOR_MINOR_PATCH` and match
+the release branch name. If a project uses a different release convention,
+document it here before the first refresh.
+
+## Audience
+
+Docs are written for non-developer technical readers by default: QA, product
+owners, solution owners, support engineers, customer engineers, or operators.
+Adjust this only when the project explicitly defines a different audience.
+
+- Describe behavior, inputs, outputs, permissions, error conditions, and
+  business rules in domain language.
+- Avoid code snippets, private type names, SQL, and framework jargon unless
+  the concept has no plain-language equivalent.
+- For readers who need more depth than the docs provide, link to the source
+  rather than replicating the implementation in prose.
+
+## Two Levels Of Detail
+
+Every documented area has two layers:
+
+1. High level: a summary of what the area is for and an architecture
+   description.
+2. Detailed: one page per feature, written to the audience above.
+
+Standard per-area layout:
+
+```text
+Documentation/<Area>/
+  README.md
+  features/
+    <feature>.md
+```
+
+## Diagrams
+
+Use Mermaid for architecture, flow, sequence, state, and data-relationship
+diagrams. Mermaid remains readable as Markdown source and renders in common
+Markdown viewers.
+
+Use a diagram when the relationship between moving parts is easier to show
+than to describe in prose. Prefer a short diagram over a long paragraph; prefer
+a short sentence over an unnecessary diagram.
+
+Avoid ASCII-art box drawings. When you edit a page that already has one,
+replace it with Mermaid if the diagram is still useful.
+
+Preferred diagram types:
+
+| Scenario | Mermaid type |
+| --- | --- |
+| Component, topology, or data flow | `flowchart LR` or `flowchart TD` |
+| Sequence of interactions | `sequenceDiagram` |
+| Entity or table relationships | `erDiagram` |
+| State machine | `stateDiagram-v2` |
+
+Keep diagrams small enough to read. If a diagram needs more than about 15 nodes
+or steps, simplify it or split it.
+
+## Feature Docs Cover The Full Vertical
+
+A feature doc should describe the full behavior path the feature touches:
+entry point, important services or processes, data stored or read, external
+systems, permissions, validation, errors, and operational expectations.
+
+If a feature spans multiple areas, place the doc in the area that owns the
+user-facing or operator-facing entry point. Cross-link from the other areas.
+
+## Release-Time Doc Refresh
+
+When invoked to refresh docs for a release:
+
+1. Work from the diff `<previous-release-tag>..HEAD`, scoped to one area at a
+   time.
+2. Read the matching area guide in `Documentation/_authoring/areas/`.
+3. Update the area's `README.md` if the high-level picture changed.
+4. Update feature pages for behavior that changed.
+5. Ignore pure refactors, internal renames, test-only changes, formatting,
+   lint fixes, and dependency bumps with no behavior change.
+6. Append one row to `Documentation/releases/index.md`.
+
+## What Not To Document
+
+- Internal helpers, private types, or implementation details that can change
+  without user or operator impact.
+- Anything already covered by generated API reference or inline comments. Link
+  to it when helpful.
+- Transient migration scaffolding that will be removed before or soon after
+  the release.
+- Draft plans, undecided architecture, or open implementation questions. Those
+  belong in `Development/`.

package/Documentation/_templates/area/README.md

@@ -0,0 +1,20 @@
+# Area Name
+
+Briefly describe what this area does, who uses it, and why it exists.
+
+## Architecture At A Glance
+
+```mermaid
+flowchart LR
+    User["User or operator"] -->|"uses"| Area["Area"]
+    Area -->|"reads or writes"| Data["Data store"]
+    Area -->|"calls"| External["External system"]
+```
+
+## Responsibilities
+
+- TBD
+
+## Feature Pages
+
+- [Feature Name](features/feature-template.md)

package/Documentation/_templates/area/features/feature-template.md

@@ -0,0 +1,29 @@
+# Feature Name
+
+Describe the shipped behavior in domain language.
+
+## Who Uses It
+
+- TBD
+
+## Behavior
+
+- TBD
+
+## Inputs And Outputs
+
+| Input or output | Description |
+| --- | --- |
+| TBD | TBD |
+
+## Permissions And Validation
+
+- TBD
+
+## Errors And Edge Cases
+
+- TBD
+
+## Operational Notes
+
+- TBD

package/Documentation/releases/index.md

@@ -0,0 +1,18 @@
+# Release Documentation Index
+
+One row per tagged release. Tag names default to `release/vMAJOR_MINOR_PATCH`
+unless the project documents a different convention.
+
+Docs at a given tag describe the behavior of that release.
+
+| Tag | Date | Areas refreshed | Owner | Summary |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | First documentation refresh. |
+
+## Notes For Future Release Rows
+
+- The first row may be a bootstrap refresh. Subsequent rows should describe
+  incremental refreshes from `<previous-tag>..HEAD`.
+- "Areas refreshed" lists only areas with material behavior changes.
+- Keep the summary to one sentence. Link to an area or feature doc when a
+  change deserves more space.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Mendez Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# Code-Anchored Context Template
+
+This repository is a reusable starting point for keeping repository-local
+development context and release-anchored product documentation close to the
+code they describe.
+
+It separates two kinds of truth:
+
+| Folder | Meaning | Updated when |
+| --- | --- | --- |
+| `Development/` | What the team is planning, building, deciding, validating, shipping, hosting, deferring, and learning. | During normal development. |
+| `Documentation/` | What the product does as of a known release or tag. | Only during explicit documentation refresh work. |
+
+The goal is to give humans and AI agents enough structured context to change a
+codebase without relying on chat history, tribal memory, or scattered planning
+notes.
+
+## What This Template Contains
+
+- `AGENTS.md` with repo-wide agent guidance.
+- `.agents/skills/development-initiative-context/SKILL.md` for the recurring
+  development-context workflow.
+- `Development/` with terminology, release context, backlog/program structure,
+  initiative templates, and a human-readable article and brief.
+- `Documentation/` with a generic release-anchored documentation workflow,
+  authoring guide structure, and area/page templates.
+
+## Adopting This In A Project
+
+The quickest path is the npm initializer:
+
+```bash
+npx code-anchored-context init \
+  --project-name "My Project" \
+  --release v0_1_0
+```
+
+Useful options:
+
+```bash
+npx code-anchored-context init --dry-run
+npx code-anchored-context init --no-documentation
+npx code-anchored-context init --target ../existing-project
+```
+
+The initializer copies the repo-local agent context into the target project,
+adds or updates guidance in `AGENTS.md`, installs the
+`development-initiative-context` skill under `.agents/skills/`, and replaces
+basic placeholders such as `PROJECT_NAME` and the initial release slug.
+
+Manual adoption still works:
+
+1. Copy the files into a repository root.
+2. Replace `PROJECT_NAME` placeholders with the project name.
+3. Set the first active release in `Development/current.md`.
+4. Add or revise area-specific `AGENTS.md` files so they point back to
+   `Development/` and `Documentation/_authoring/`.
+5. Create `Documentation/_authoring/areas/<area>.md` for each documented
+   product or code area.
+6. Keep product or domain-specific documentation out of this template repo.
+
+## Publishing The Package
+
+From this repository:
+
+```bash
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+If the unscoped package name is unavailable, rename the package in
+`package.json`, for example to `@your-scope/code-anchored-context`, then use:
+
+```bash
+npx @your-scope/code-anchored-context init
+```
+
+## Working Rule
+
+Development context can evolve with the branch. Product documentation should
+stay stable and release-accurate. When behavior changes during development,
+record future documentation impact in the relevant initiative's
+`release-doc-notes.md`; refresh `Documentation/` only when that work is
+explicitly requested.