code-anchored-context 0.2.3 → 0.2.4

package/.agents/skills/code-anchored-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-anchored-context
-description: Use central repository context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating context/current.md, context/releases/*/initiatives/*, context/programs/*, context/programs/*/planned-initiatives/*, context/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 reference/ should be left untouched.
+description: Use central repository context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating context/current.md, context/project-profile.md, context/releases/*/initiatives/*, context/programs/*, context/programs/*/planned-initiatives/*, context/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 reference/ should be left untouched.
 ---
 
 # Code-Anchored Context
@@ -16,6 +16,9 @@ Working 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.
 
+Repo-specific stack and toolchain facts belong in
+`context/project-profile.md`, not in this reusable skill.
+
 ## Workflow
 
 ### 1) Read The Local Rules
@@ -32,6 +35,24 @@ Use `context/terminology.md` as the canonical vocabulary for programs,
 planned initiatives, release initiatives, backlog items, statuses, and
 promotion.
 
+Open `context/project-profile.md` when it exists. It is the repo-wide
+operating profile for stack, commands, source roots, verification layers,
+CI/CD, delivery automation, infrastructure, observability, and generated
+artifacts. Use it before inventing default commands or tooling assumptions.
+
+If a human explicitly asks for a project profile, tech-stack baseline, or
+repository operating baseline, create or refresh `context/project-profile.md`
+by inspecting source-backed local facts: manifests, lockfiles, runtime version
+files, build config, test config, CI/CD workflows, deployment scripts,
+infrastructure config, observability config, generated-artifact owners, and
+existing docs. Do not guess. Mark unknowns clearly and cite source paths where
+useful.
+
+If the human asks for a "baseline" without saying whether they mean an
+operating profile or accepted behavior reference, distinguish
+`context/project-profile.md` from baseline reference under `reference/` before
+editing.
+
 If the workspace starts inside a subfolder, navigate upward to the repository
 root when the environment allows it. If `context/` is not available in
 the workspace, mention that limitation in the task summary.
@@ -50,6 +71,9 @@ Search for:
 - the feature or bug name
 - affected concern names, such as product code, APIs, contracts, tests,
   delivery, CI/CD, infrastructure, config, generated artifacts, or automation
+- repo-wide toolchain facts from `context/project-profile.md`, such as test
+  commands, e2e tooling, observability tooling, deploy CLIs, source roots,
+  generated artifacts, or CI/CD files
 - 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
@@ -165,6 +189,9 @@ Use these files as the standard map:
 - `backlog.md`: work slices and implementation progress
 - `decisions/ADR-*.md`: meaningful choices and their consequences
 - `release-doc-notes.md`: reference impact to review at release
+- `context/project-profile.md`: repo-wide stack, command, testing, delivery,
+  infrastructure, observability, and generated-artifact facts; update it only
+  for stable source-backed discoveries or an explicit baseline request
 
 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.
@@ -197,6 +224,9 @@ folder. Do not create area-local copies of initiative documents.
 Before finishing behavior-changing work:
 
 - The matching initiative was read or a reason was given for why none exists.
+- `context/project-profile.md` was read when present and relevant to
+  verification, delivery, infrastructure, operations, or generated artifacts;
+  if a human requested a baseline, it was populated from source-backed facts.
 - Matching programs or context backlog items were checked when the work
   appears phased, deferred, or multi-release.
 - Planned initiatives were checked or created when future program scope is

package/AGENTS.md

@@ -8,6 +8,9 @@ subfolders layer on top of it. Read those too when working in a given area.
 In-progress specs, plans, ADRs, backlog, implementation context, and
 release-documentation notes live under [`context/`](context/).
 Start with [`context/current.md`](context/current.md).
+Use [`context/project-profile.md`](context/project-profile.md) for
+repo-wide stack, command, testing, delivery, infrastructure, observability,
+and generated-artifact facts when it has been populated.
 
 For behavior-changing work, use the repo-wide skill at
 [`.agents/skills/code-anchored-context/SKILL.md`](.agents/skills/code-anchored-context/SKILL.md).

package/README.md

@@ -8,7 +8,7 @@ It separates two kinds of truth:
 
 | Folder | Meaning | Updated when |
 | --- | --- | --- |
-| `context/` | What the team is planning, building, deciding, validating, shipping, hosting, deferring, and learning. | During normal development. |
+| `context/` | What the team is planning, building, deciding, validating, shipping, hosting, deferring, and learning, plus optional repo-wide operating facts in `project-profile.md`. | During normal development. |
 | `reference/` | What the system does as of a known release or explicit baseline. | Only during explicit reference refresh work. |
 
 The goal is to give humans and AI agents enough structured context to change a
@@ -21,7 +21,8 @@ notes.
 - `.agents/skills/code-anchored-context/SKILL.md` for the recurring
   working-context workflow.
 - `context/` with terminology, release context, backlog/program structure,
-  initiative templates, and release-documentation notes.
+  a repo-wide project profile starter, initiative templates, and
+  release-documentation notes.
 - `reference/` with a generic release-anchored reference workflow,
   authoring guide structure, and area/page templates.
 
@@ -55,9 +56,12 @@ Manual adoption still works:
 3. Set the first active release in `context/current.md`.
 4. Add or revise area-specific `AGENTS.md` files so they point back to
    `context/` and `reference/_authoring/`.
-5. Create `reference/_authoring/areas/<area>.md` for each referenced
+5. If you want a repo operating profile, ask an agent to populate
+   `context/project-profile.md` from source files, manifests, CI/CD,
+   infrastructure, test config, and observability tooling.
+6. Create `reference/_authoring/areas/<area>.md` for each referenced
    product or code area.
-6. Keep product or domain-specific reference content out of this template repo.
+7. Keep product or domain-specific reference content out of this template repo.
 
 ## Publishing The Package
 

package/bin/code-anchored-context.js

@@ -304,6 +304,9 @@ class Installer {
 In-progress specs, plans, ADRs, backlog, implementation context, and
 release-documentation notes live under [\`context/\`](context/).
 Start with [\`context/current.md\`](context/current.md).
+Use [\`context/project-profile.md\`](context/project-profile.md) for
+repo-wide stack, command, testing, delivery, infrastructure, observability,
+and generated-artifact facts when it has been populated.
 
 For behavior-changing work, use the repo-wide skill at
 [\`.agents/skills/${skillName}/SKILL.md\`](.agents/skills/${skillName}/SKILL.md).
@@ -486,6 +489,10 @@ Start here:
 - \`releases/${this.release}/backlog.md\`
 - \`releases/${this.release}/initiatives/\`
 
+Project-wide operating profile:
+
+- \`project-profile.md\`
+
 Durable or deferred context:
 
 - \`programs/\`

package/context/AGENTS.md

@@ -7,6 +7,9 @@ Scope: everything under `/context`.
 This folder is the canonical home for in-progress working context: specs,
 interface notes, architecture notes, actionable operations notes, ADRs,
 backlogs, implementation plans, and release-documentation notes.
+`project-profile.md` is the canonical home for repo-wide operating facts such
+as stack, commands, test layers, CI/CD, infrastructure, observability, and
+generated artifacts when a baseline has been populated.
 
 Testing, delivery, and infrastructure notes belong here when they affect how
 work is verified, shipped, deployed, or hosted. Operational notes belong here
@@ -20,6 +23,9 @@ repair context.
 
 - Use `context/terminology.md` as the canonical vocabulary for programs,
   planned initiatives, release initiatives, backlog items, and promotion.
+- Use `context/project-profile.md` for stable repo-wide operating facts.
+  Populate it only from source-backed discovery or an explicit human request
+  for a repository baseline.
 - 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 `reference/`.

package/context/README.md

@@ -8,10 +8,16 @@ notes, infrastructure notes, actionable operations notes, ADRs, backlog items,
 implementation plans, and release-documentation notes. Do not use
 `reference/` for in-progress development planning.
 
+Use `project-profile.md` for repo-wide operating facts such as stack,
+commands, verification layers, CI/CD, infrastructure, observability, and
+generated artifacts.
+
 ## Start Here
 
 - `terminology.md` defines the shared vocabulary.
 - `current.md` points to the active release context.
+- `project-profile.md` captures repo-wide stack, command, testing, delivery,
+  infrastructure, operations, and generated-artifact facts when populated.
 - `programs/` contains durable multi-release working context.
 - `backlog/` contains deferred isolated work cut from initiatives.
 - `releases/` contains release-scoped working context.
@@ -63,6 +69,9 @@ The delivery-surface rule is:
 
 Use `testing.md`, `delivery.md`, and `infrastructure.md` for concern-based
 context. Mention specific tools inside those files only when the tools matter.
+Use `project-profile.md` for repo-wide defaults such as package manager,
+common commands, test tools, delivery automation, infrastructure tooling, and
+observability entry points.
 
 Mermaid diagrams are encouraged for flows, dependencies, and lifecycle maps
 because they stay readable as Markdown for agents while rendering as visible
@@ -80,6 +89,7 @@ not copy specs, plans, or ADRs into area-local documents.
 ```text
 context/
   current.md
+  project-profile.md
   programs/
     <program-slug>/
       README.md
@@ -120,6 +130,27 @@ context/
           brief.html
 ```
 
+## Project Profile
+
+`project-profile.md` is the optional repo-wide operating profile. It answers
+questions future agents routinely need before changing behavior:
+
+- where code, tests, config, infrastructure, generated artifacts, and
+  reference material live
+- which runtime, package manager, frameworks, services, and hosting platform
+  the project uses
+- which commands verify, build, package, run, deploy, or release the project
+- which CI/CD, IaC, observability, support, rollback, and repair tools matter
+
+Populate it when a human asks for a project profile, tech-stack baseline, or
+repository operating baseline, or when a concrete repo-wide fact is discovered
+during work. Do not guess. Mark unknowns explicitly and cite source paths
+where possible.
+
+Initiatives can rely on the project profile for stable defaults. Put only the
+initiative-specific changes, exceptions, and release gates in the initiative's
+`testing.md`, `delivery.md`, `infrastructure.md`, or `operations.md`.
+
 ## Programs
 
 Programs preserve durable context for work that spans releases or phases. Use a

package/context/_templates/initiative/README.md

@@ -17,6 +17,8 @@ produce.
 - Tests or verification: `path/to/...`
 - Delivery, CI/CD, build, or artifacts: `path/to/...`
 - Infrastructure, IaC, or environment config: `path/to/...`
+- Repo-wide operating profile: `context/project-profile.md` if a stable
+  project fact changes
 - Reference or release notes: `path/to/...`
 
 Remove entries that do not apply and add the real paths. Prefer naming the

package/context/_templates/initiative/delivery.md

@@ -5,6 +5,10 @@ Name the concern, not the tool. Pipeline definitions, workflow files,
 deployment scripts, release toggles, and gates can all appear here when
 relevant.
 
+Start from `context/project-profile.md` for repo-wide delivery defaults.
+Capture only initiative-specific pipeline, build, deployment, artifact, or
+release changes here.
+
 ## Pipeline Impact
 
 Describe pipeline, workflow, build, packaging, or artifact changes.

package/context/_templates/initiative/infrastructure.md

@@ -4,6 +4,10 @@ Use this file for environment shape and infrastructure dependencies. Name the
 concern, not the tool. Infrastructure modules, resource templates, manifests,
 or manual environment steps can all appear here when relevant.
 
+Start from `context/project-profile.md` for repo-wide infrastructure and
+configuration defaults. Capture only initiative-specific environment, IaC,
+resource, secret, or migration changes here.
+
 ## Environment Shape
 
 Describe new or changed resources, services, networks, identity boundaries,

package/context/_templates/initiative/operations.md

@@ -7,6 +7,10 @@ If there is nothing concrete for an agent or engineer to act on, omit this
 file after copying the template or mark it as not applicable. Delivery belongs
 in `delivery.md`; environment shape and IaC belong in `infrastructure.md`.
 
+Start from `context/project-profile.md` for repo-wide observability, support,
+rollback, and repair entry points. Capture only initiative-specific actionable
+runtime or support changes here.
+
 ## Runtime Behavior
 
 Describe how the live system behaves after the initiative ships, especially

package/context/_templates/initiative/testing.md

@@ -4,6 +4,10 @@ Use this file for the initiative's verification strategy. Name the concern,
 not the tool. Specific test runners, unit test frameworks, contract tests, or
 manual scripts can all appear here when they are relevant.
 
+Start from `context/project-profile.md` for repo-wide default commands and
+test tooling. Capture only initiative-specific additions, exceptions, data
+needs, or release gates here.
+
 ## Test Strategy
 
 Describe what must be proven before this initiative can ship.

package/context/_templates/planned-initiative/README.md

@@ -19,6 +19,8 @@ and what outcome it should produce.
 - Tests or verification: `path/to/...`
 - Delivery, CI/CD, build, or artifacts: `path/to/...`
 - Infrastructure, IaC, or environment config: `path/to/...`
+- Repo-wide operating profile: `context/project-profile.md` if a stable
+  project fact is expected to change
 - Reference or release notes: `path/to/...`
 
 Remove entries that do not apply and add the real paths. Prefer naming the

package/context/_templates/planned-initiative/delivery.md

@@ -3,6 +3,10 @@
 Use this file for future CI/CD, build, release, and environment-promotion
 behavior that is already clear enough to preserve.
 
+Start from `context/project-profile.md` for repo-wide delivery defaults.
+Capture only planned initiative-specific pipeline, build, deployment,
+artifact, or release changes here.
+
 ## Pipeline Impact
 
 Describe expected pipeline, workflow, build, packaging, or artifact changes.

package/context/_templates/planned-initiative/infrastructure.md

@@ -3,6 +3,10 @@
 Use this file for future environment shape and infrastructure dependencies
 that are already clear enough to preserve.
 
+Start from `context/project-profile.md` for repo-wide infrastructure and
+configuration defaults. Capture only planned initiative-specific environment,
+IaC, resource, secret, or migration changes here.
+
 ## Environment Shape
 
 Describe expected resources, services, networks, identity boundaries, storage,

package/context/_templates/planned-initiative/operations.md

@@ -8,6 +8,10 @@ If there is nothing concrete for an agent or engineer to act on, omit this
 file after copying the template or mark it as not applicable. Delivery belongs
 in `delivery.md`; environment shape and IaC belong in `infrastructure.md`.
 
+Start from `context/project-profile.md` for repo-wide observability, support,
+rollback, and repair entry points. Capture only planned initiative-specific
+actionable runtime or support changes here.
+
 ## Runtime Behavior
 
 Describe expected live-system behavior, especially jobs, schedules, queues,

package/context/_templates/planned-initiative/testing.md

@@ -3,6 +3,10 @@
 Use this file for future verification strategy that is already clear enough to
 preserve before the target release becomes current.
 
+Start from `context/project-profile.md` for repo-wide default commands and
+test tooling. Capture only planned initiative-specific additions, exceptions,
+data needs, or release gates here.
+
 ## Test Strategy
 
 Describe what the future release initiative will need to prove.

package/context/current.md

@@ -8,6 +8,10 @@ Start here:
 - `releases/v0_1_0/backlog.md`
 - `releases/v0_1_0/initiatives/`
 
+Project-wide operating profile:
+
+- `project-profile.md`
+
 Durable or deferred context:
 
 - `programs/`

package/context/project-profile.md

@@ -0,0 +1,130 @@
+# Project Profile
+
+Project: PROJECT_NAME
+Baseline status: Not populated yet.
+Last reviewed: Not recorded.
+
+This file captures repo-wide operating facts that agents should know before
+changing behavior. It is for stable project facts such as stack, source roots,
+commands, verification layers, delivery flow, infrastructure, observability,
+and generated artifacts.
+
+Do not put initiative-specific planning here. Use release initiatives under
+`context/releases/` for work-specific behavior, testing, delivery,
+infrastructure, and operations context.
+
+## When To Populate Or Refresh
+
+Populate or refresh this file when a human explicitly asks for a project
+profile, tech-stack baseline, or repository operating baseline, or when a
+concrete repo-wide fact is discovered during work and would help future
+agents.
+
+Record facts that can be traced to source files. Do not guess. If something is
+not known yet, mark it as `Unknown` and include the source paths that still
+need review.
+
+## Source Scan Checklist
+
+Use this checklist during a baseline pass:
+
+- package manifests, lockfiles, language/runtime version files, and build
+  config
+- source roots, application boundaries, libraries, services, APIs, jobs, and
+  generated artifacts
+- test configuration, e2e tooling, fixtures, seeded data, and test
+  environments
+- CI/CD workflows, deployment scripts, release toggles, artifact publishing,
+  and environment promotion
+- infrastructure as code, service configuration, secrets references, and
+  environment dependencies
+- observability, logs, metrics, traces, alerts, dashboards, support tools,
+  rollback, and repair procedures
+
+## Repository Shape
+
+| Concern | Location | Notes |
+| --- | --- | --- |
+| Application or package code | Unknown | TBD |
+| Tests | Unknown | TBD |
+| CI/CD and delivery | Unknown | TBD |
+| Infrastructure and config | Unknown | TBD |
+| Generated artifacts | Unknown | TBD |
+| Reference material | `reference/` | Release-anchored or baseline behavior. |
+| Working context | `context/` | Plans, initiatives, programs, ADRs, backlog, and release notes. |
+
+## Stack And Runtime
+
+| Layer | Technology | Source | Notes |
+| --- | --- | --- | --- |
+| Runtime or language | Unknown | TBD | TBD |
+| Package manager | Unknown | TBD | TBD |
+| Frameworks | Unknown | TBD | TBD |
+| Data stores or services | Unknown | TBD | TBD |
+| Hosting or runtime platform | Unknown | TBD | TBD |
+
+## Commands
+
+| Concern | Command | Source | Notes |
+| --- | --- | --- | --- |
+| Install dependencies | Unknown | TBD | TBD |
+| Run locally | Unknown | TBD | TBD |
+| Build | Unknown | TBD | TBD |
+| Lint, format, or typecheck | Unknown | TBD | TBD |
+| Unit or integration tests | Unknown | TBD | TBD |
+| E2E or smoke tests | Unknown | TBD | TBD |
+| Package or release | Unknown | TBD | TBD |
+
+## Verification Profile
+
+- Default test expectation: Unknown.
+- Required release gates: Unknown.
+- Manual checks: Unknown.
+- Test data and environment dependencies: Unknown.
+- Known verification gaps: Unknown.
+
+Use initiative `testing.md` files for work-specific additions, exceptions, and
+release gates.
+
+## Delivery Profile
+
+- CI/CD workflow files: Unknown.
+- Deployment entry points: Unknown.
+- Environments and promotion flow: Unknown.
+- Release approvals or gates: Unknown.
+- Artifacts and publishing flow: Unknown.
+- Delivery automation CLIs or scripts: Unknown.
+
+Use initiative `delivery.md` files for work-specific pipeline, build,
+deployment, or release changes.
+
+## Infrastructure And Configuration
+
+- IaC, manifests, or config roots: Unknown.
+- Managed services and resources: Unknown.
+- Secrets and configuration references: Unknown.
+- Environment dependencies: Unknown.
+- Compatibility or migration constraints: Unknown.
+
+Use initiative `infrastructure.md` files for work-specific environment or IaC
+changes.
+
+## Operations Profile
+
+- Logs: Unknown.
+- Metrics, traces, or dashboards: Unknown.
+- Alerts and health checks: Unknown.
+- Support tooling: Unknown.
+- Rollback, recovery, and repair tooling: Unknown.
+
+Use initiative `operations.md` files only for actionable runtime, support,
+observability, rollback, or repair concerns tied to a specific change.
+
+## Agent Notes
+
+- Keep this file factual and source-backed.
+- Prefer commands already defined by the repo over ad hoc alternatives.
+- Mention specific tools only when they affect how agents should verify,
+  ship, deploy, observe, or support the project.
+- If a generated file or managed artifact should not be edited directly,
+  record that here with the owning source location.

package/context/terminology.md

@@ -11,6 +11,7 @@ backlog items, ADRs, agent summaries, and release-transition work.
 | `context/` | Working context: plans, specs, ADRs, implementation notes, delivery-surface context, future scope, and release-documentation notes. |
 | `reference/` | Accepted reference. It describes shipped or baseline 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/project-profile.md` | Optional repo-wide operating profile for stack, commands, source roots, verification, delivery, infrastructure, observability, and generated artifacts. |
 | `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. |
@@ -44,6 +45,8 @@ scope and should be preserved, but it does not need program-level context.
 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.
+Use `project-profile.md` for repo-wide defaults and toolchain facts, then use
+initiative files for work-specific changes and exceptions.
 
 Mermaid is the preferred diagram syntax for working context because it is
 both readable Markdown for agents and renderable visual context for humans.
@@ -51,6 +54,7 @@ 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. |
+| `project-profile.md` | Repo-wide operating profile. Populate it on human request or when source-backed facts are discovered during work. |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-anchored-context",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Install repo-local agent context, release initiatives, and release-anchored reference scaffolding into an existing project.",
   "license": "MIT",
   "type": "module",
@@ -15,6 +15,7 @@
     "context/_templates/",
     "context/backlog/",
     "context/current.md",
+    "context/project-profile.md",
     "context/programs/",
     "context/releases/v0_1_0/README.md",
     "context/releases/v0_1_0/backlog.md",

package/reference/_authoring/workflow.md

@@ -55,6 +55,10 @@ When creating a baseline:
 Baseline reference is a snapshot of the system as adopted; it is not a
 promise that every undocumented behavior is unimportant.
 
+This is different from `context/project-profile.md`, which captures the
+repo-wide operating profile: stack, commands, verification, delivery,
+infrastructure, observability, and generated-artifact facts.
+
 ### Release-Forward Reference
 
 Use this mode when the team chooses not to create a full baseline. In this