@flancer32/skill-adsm-ctx 0.2.1

package/skill/references/upgrade-policy.md

@@ -0,0 +1,19 @@
+# Upgrade Policy
+
+- Path: `skill/references/upgrade-policy.md`
+- Changed: `20260708`
+
+Upgrades must be non-destructive by default.
+
+Safe upgrade behavior includes:
+
+- adding missing files and directories;
+- updating metadata when the migration rules are explicit;
+- preserving project-authored content unless replacement is proven safe.
+- detecting agent/skin pairs, orphan skins, and projection drift according to `skill/references/document-projections.md`;
+- preserving project-specific nested subdirectories under `ctx/docs/product/`, `ctx/docs/architecture/`, `ctx/docs/environment/`, and `ctx/docs/code/`;
+- keeping visual, generated, rendered, and auxiliary artifacts under `ctx/assets/**`.
+
+Unsafe cases should be reported for manual follow-up instead of applied automatically.
+
+Upgrade must not introduce required `README.md` files inside `ctx/docs/` and must not automatically rewrite human-controlled skins when agent/skin meaning is unclear.

package/skill/templates/AGENTS.md

@@ -0,0 +1,120 @@
+# Root Level
+
+- Path: `AGENTS.md`
+- Template Version: `20260720`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This file defines the root-level working rules for the project repository.
+
+This file is the first instruction source for every agent operating within the repository.
+
+## Level Boundary
+
+Defines:
+
+- Root-level working boundaries between the repository, the cognitive context, and the software product.
+- Repository-topology rules needed to work safely when `ctx/` may be mounted separately.
+- Root-level protection and escalation rules for this project.
+
+Does NOT define:
+
+- Product-specific meaning, requirements, or domain knowledge.
+- Implementation-level structure such as source code, runtime details, or filesystem layout.
+- Task-specific instructions, workflows, or local operational procedures.
+
+## ADSM Project Model
+
+An ADSM project consists of two interconnected spaces:
+
+- the **Cognitive Context** located in `./ctx/`
+- the **Software Product** located outside `./ctx/`
+
+The cognitive context is the long-term textual memory of the project.
+
+The cognitive context is the primary communication medium between Humans and Agents working on the project.
+
+The cognitive context is the authoritative knowledge source used by Agents when modifying the project.
+
+The software product is the implementation that must be kept consistent with the cognitive context.
+
+## Human and Agent Roles
+
+The Human defines goals, authorizes work, evaluates outcomes, and evolves the project.
+
+The Agent interprets the cognitive context, performs assigned tasks, modifies the project within task boundaries, and maintains consistency between the cognitive context and the software product.
+
+The Agent operates through text and must treat project documentation as operational memory, not as secondary commentary.
+
+## Cognitive Context
+
+The canonical execution location of the cognitive context is `./ctx/`.
+
+Project-specific knowledge, requirements, architecture, environment descriptions, and implementation guidance are defined within the cognitive context.
+
+The Agent must consult `./ctx/AGENTS.md` for project-specific instructions when `./ctx/` exists.
+
+The Agent must consult `./ctx/docs/filesystem.md` for the project filesystem structure and documentation layout when that file exists.
+
+Documentation distributed with the software product may exist outside `./ctx/`, but it does not replace, redefine, or supersede the cognitive context.
+
+## Bootstrap and Repository Topology
+
+An ADSM project may use one repository or two repositories.
+
+In a one-repository topology, the software product and the cognitive context are versioned together.
+
+In a two-repository topology, the software product and the cognitive context are independent version-controlled repositories, and the cognitive context repository is mounted under `./ctx/`.
+
+The Agent must detect whether `./ctx/` is part of the current repository or an independent repository.
+
+The Agent must preserve repository boundaries.
+
+The Agent must not mix changes between independent repositories.
+
+The Agent must not remove, replace, relocate, or unmount `./ctx/`.
+
+If `./ctx/` does not exist, the Agent may perform bootstrap operations required to create the initial cognitive context structure.
+
+After bootstrap is complete, `./ctx/AGENTS.md` becomes the entry point for project-specific instructions.
+
+## Context and Product Consistency
+
+The cognitive context is the source of truth for the project.
+
+If the cognitive context and the software product diverge, the Agent must treat the cognitive context as authoritative.
+
+The Agent must maintain consistency between the cognitive context and the software product.
+
+The Agent may modify the cognitive context when required by the assigned task and when the modification remains consistent with higher-level context constraints.
+
+The Agent may modify the software product when required by the assigned task and when the modification remains consistent with the cognitive context.
+
+## AGENTS.md Hierarchy
+
+Additional `AGENTS.md` files may exist in subdirectories.
+
+The effective working context of the agent is the aggregate of all `AGENTS.md` files located along the path from the repository root to the target directory.
+
+Rules:
+
+- deeper levels override higher levels within their scope
+- root-level invariants cannot be overridden
+- all levels must remain mutually consistent
+
+## Root File Protection
+
+This file defines root-level project control rules.
+
+The agent must not modify, replace, delete, relocate, or reinterpret this file unless explicitly instructed by the human.
+
+Violation of this rule constitutes an execution error.
+
+## Secret Handling
+
+The Agent must never read, load, print, search for, or expose secret-bearing project files, including `.env` and `.env.*` files, credentials, private keys, tokens, or secret stores. This rule applies even when a file is Git-ignored and includes broad search or command output that could reveal its contents.
+
+The Agent may use a non-secret example template such as `.env.example` only to learn the configuration shape. It must not infer or request the value of any secret.
+
+If secret data is exposed accidentally, the Agent must stop handling that value, must not repeat it, and must tell the Human that the secret should be rotated or revoked.

package/skill/templates/ai/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+- Path: `ai/AGENTS.md`
+- Template Version: `20260609`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This file defines the `ai/` level for agent-facing package documentation included in the distributable package.
+
+The `ai/` directory provides a compact machine-oriented interface for agents that need to understand and use the package correctly.
+
+## Level Boundary
+
+This level defines:
+
+- what documents exist in `ai/`;
+- what each document is for;
+- how an agent should navigate this directory.
+
+This level does not define:
+
+- repository organization;
+- development workflow and testing strategy;
+- behavior not described by the documents in `ai/`.
+
+## Level Map
+
+- `AGENTS.md` — entry point for this level; defines scope and navigation.
+- `concepts.md` — core concepts and architectural model.
+- `container.md` — container responsibilities and dependency resolution behavior.
+- `dependency-id.md` — syntax and semantics of dependency identifiers.
+- `extensions.md` — supported extension points and customization mechanisms.
+- `package-api.ts` — machine-readable description of the public programmatic interface.
+- `usage.md` — minimal usage scenarios and integration examples.
+
+## Reading Guide
+
+Read documents by task:
+
+- for API usage, start with `package-api.ts`, then `usage.md`;
+- for dependency addressing, read `dependency-id.md`;
+- for runtime behavior, read `container.md`;
+- for extension work, read `extensions.md`;
+- for architectural orientation, read `concepts.md`.
+
+If the task is broad or unclear, read in this order:
+
+1. `AGENTS.md`
+2. `package-api.ts`
+3. `usage.md`
+4. `concepts.md`
+5. remaining documents as needed
+
+## Authority
+
+The documents in `ai/` define the supported agent-facing usage semantics of the package.
+
+Agents should rely on these documents for package use and should treat behaviors not described here as undefined.

package/skill/templates/ctx/AGENTS.md

@@ -0,0 +1,45 @@
+# Cognitive Context
+
+- Path: `ctx/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This file marks `ctx/` as the project cognitive context.
+
+Use this branch for project knowledge and keep detailed ADSM methodology outside the project-facing context.
+
+## Bootstrap Marker
+
+- This context follows ADSM conventions.
+- Use skill `adsm-ctx` for structure validation, upgrade logic, and methodology rules.
+
+## Level Map
+
+- `agent/` — project-local agent and tool materials outside the reusable ADSM baseline.
+- `assets/` — visual, generated, rendered, or auxiliary artifacts that support documentation without defining authoritative meaning.
+- `docs/` — project-facing documentation and constraints.
+- `AGENTS.md` — level definition for `ctx/`.
+- `README.md` — short entry note for the cognitive context.
+- `adsm.json` — context metadata for versioning and upgrade eligibility.
+
+## Level Boundary
+
+Defines:
+
+- `ctx/` as the project cognitive context boundary.
+- The split between project-facing documentation and project-local agent materials.
+- The local entry points agents should read before deeper work.
+
+Does NOT define:
+
+- Product-specific meaning that belongs in subordinate product and architecture documents.
+- Implementation structure outside the cognitive context.
+- Detailed ADSM methodology that belongs to the skill and its references.
+
+## Local Reading Map
+
+- Read `README.md` for a short entry note.
+- Read `docs/filesystem.md` for the top-level repository map.
+- Read `docs/` for project documentation.

package/skill/templates/ctx/README.md

@@ -0,0 +1,27 @@
+# Cognitive Context
+
+- Path: `ctx/README.md`
+- Template Version: `20260623`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This directory contains the project cognitive context.
+
+The cognitive context is the project knowledge space used by humans and agents when maintaining the project.
+
+Detailed ADSM validation and methodology rules are intentionally kept out of this installed template baseline.
+
+## Entry Points
+
+- Read `AGENTS.md` for cognitive-context structure and governance rules.
+- Use skill `adsm-ctx` when you need ADSM validation, upgrade, or methodology guidance.
+- Read `docs/filesystem.md` for the top-level repository map.
+- Read `docs/` for declarative project documentation.
+- Read `agent/` only when working with repository-local agent operations or workflow assets.
+
+## Boundary
+
+This directory defines project knowledge and agent-operational context.
+
+It does not replace product source code, runtime configuration, deployment secrets, or generated build artifacts.

package/skill/templates/ctx/adsm.json

@@ -0,0 +1,7 @@
+{
+  "schema": "adsm-context",
+  "version": "0.1.0",
+  "notes": [
+    "Initial context created from the canonical adsm-ctx template set."
+  ]
+}

package/skill/templates/ctx/agent/AGENTS.md

@@ -0,0 +1,36 @@
+# Agent External Context
+
+- Path: `ctx/agent/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This file marks `ctx/agent/` as a project-local branch for agent and tool materials.
+
+## Bootstrap Marker
+
+- This branch exists in an ADSM-managed context.
+- Use skill `adsm-ctx` for methodology rules about the boundary of `ctx/agent/`.
+
+## Level Map
+
+- `AGENTS.md` — boundary definition for `ctx/agent/`.
+
+## Level Boundary
+
+Defines:
+
+- `ctx/agent/` as the local branch for project-specific agent and tool materials.
+- The boundary between the reusable ADSM baseline and project-local operational content.
+- The rule that only this file belongs to the template-managed baseline for `ctx/agent/`.
+
+Does NOT define:
+
+- Product meaning or user-facing project requirements.
+- Architecture ownership or code-level implementation constraints.
+- The required shape of future project-local subdirectories under `ctx/agent/`.
+
+## Local Rule
+
+Project-specific subdirectories and files under `ctx/agent/` are local project material rather than part of the reusable template baseline.

package/skill/templates/ctx/assets/.gitkeep

@@ -0,0 +1 @@
+

package/skill/templates/ctx/docs/AGENTS.md

@@ -0,0 +1,55 @@
+# Project Documentation
+
+- Path: `ctx/docs/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This branch holds project-facing documentation.
+
+The installed template should describe the project, not restate detailed ADSM methodology.
+
+## Bootstrap Marker
+
+- This documentation baseline follows ADSM conventions.
+- Use skill `adsm-ctx` for structure validation, document-shape discipline, and methodology rules.
+
+## Level Map
+
+- `architecture/` — project architecture documents.
+- `code/` — code-level constraints and testing guidance.
+- `environment/` — runtime and infrastructure assumptions.
+- `product/` — product meaning, roles, and use cases.
+- `AGENTS.md` — entry note for `ctx/docs/`.
+- `ai-intro.md` — compact agent orientation for the concrete project.
+- `filesystem.md` — top-level repository map.
+
+## Level Boundary
+
+Defines:
+
+- The declarative documentation boundary for the project.
+- The documentation dependency chain from product to code.
+- The local entry points used to orient agents within `ctx/docs/`.
+
+Does NOT define:
+
+- Project-local agent operations under `ctx/agent/`.
+- Product source files or runtime assets outside documentation.
+- Detailed ADSM methodology beyond the bootstrap routing marker.
+
+## Documentation Rules
+
+- Use explicit line breaks to keep each durable statement easy to scan.
+- Use section separators only where they improve navigation or clarify a level boundary.
+- Keep documents compact and avoid long uninterrupted blocks of text.
+- Keep project-facing documents below `5,000` tokens unless a longer document preserves a load-bearing distinction.
+- Treat ordinary `*.md` files as agent-facing operational context documents.
+- Treat `*.skin.<lang>.md` files as human-facing semantic skins for matching agent documents with the same basename and directory.
+- Read a matching skin before changing an agent document.
+- Report a human decision if a requested agent-document change would violate the matching skin.
+- Keep project-specific nested subdirectories inside `product/`, `architecture/`, `environment/`, and `code/` when they improve maintainability.
+- Keep each documentation level to no more than nine direct directories and nine direct ordinary files, excluding `AGENTS.md` and paired `*.skin.<lang>.md` files, where practical.
+- When a level deliberately exceeds either value, add a `## Documentation Capacity Exception` section to that level's `AGENTS.md` that states the exception and its reason.
+- Put visual, generated, rendered, or auxiliary artifacts under `ctx/assets/**`.

package/skill/templates/ctx/docs/ai-intro.md

@@ -0,0 +1,53 @@
+# AI Introduction
+
+- Path: `ctx/docs/ai-intro.md`
+- Template Version: `20260623`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+This document gives AI agents a compact first orientation to the project.
+
+It should classify the project, identify its problem space, name its primary audience, and prevent common misclassification before the agent reads deeper documentation.
+
+## Project Type
+
+Describe what kind of software product this repository defines.
+
+## Problem Space
+
+Describe the narrow problem the project exists to solve.
+
+## Product Role
+
+Describe how this project relates to adjacent tools, applications, libraries, frameworks, platforms, or automation systems.
+
+## Primary Audience
+
+Describe the humans, agents, systems, or organizations that use, operate, or maintain the project.
+
+## Technology Base
+
+Identify the major language, runtime, packaging, platform, and execution assumptions that classify the project technically.
+
+## Methodological Base
+
+Identify the project-governing methodology or design approach only where it helps classify this specific project.
+
+## Distinguishing Characteristics
+
+List the project choices that matter most for correct agent orientation.
+
+## What This Project Is Not
+
+List common but incorrect classifications that would lead to wrong implementation or documentation decisions.
+
+## Reading Angle
+
+Point agents toward the next high-value documents to read.
+
+## Boundary
+
+This document is an orientation entry point.
+
+It does not define product requirements, architecture contracts, environment constraints, code rules, or operational workflow semantics.

package/skill/templates/ctx/docs/architecture/AGENTS.md

@@ -0,0 +1,42 @@
+# Architecture Documentation
+
+- Path: `ctx/docs/architecture/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Defines the architecture documentation level.
+
+Documents at this level translate product intent into stable engineering structure, behavior, state ownership, integration boundaries, architectural constraints, durable decisions, and supervision rules.
+
+## Level Map
+
+- `AGENTS.md` — level definition for `ctx/docs/architecture/`.
+- `behavior.md` — internal architectural flows and major system behavior, not product use cases.
+- `checklists.md` — recurring supervision, diagnosis, and acceptance checklists.
+- `constraints.md` — non-negotiable architecture restrictions and trust boundaries.
+- `decisions.md` — short ADR-like records of durable decisions, rejected alternatives, and reasoning.
+- `integration.md` — external integrations and major internal contracts between architectural blocks.
+- `overview.md` — compact architectural overview and navigation index.
+- `state.md` — state ownership, sources of truth, derived state, and state-changing authority.
+- `structure.md` — major architectural blocks, runtime areas, and responsibility boundaries, not code structure.
+- `supervision.md` — human-agent architecture supervision rules, approval boundaries, and drift signals.
+
+## Level Boundary
+
+Defines:
+
+- Major architectural areas, system boundaries, and integration surfaces.
+- Internal behavior, state ownership, and authority distribution.
+- Durable architectural constraints, decisions, and supervision rules.
+
+Does NOT define:
+
+- Product meaning such as roles, domain entities, or use-case outcomes.
+- Deployment procedures, operational workflow routing, or environment-specific runbooks.
+- Source-level implementation details such as files, classes, tables, DTOs, or endpoint definitions.
+
+## Local Rules
+
+- Preserve project-specific nested architecture subdirectories such as runtime, state, integration, or lifecycle areas when they improve maintainability.

package/skill/templates/ctx/docs/architecture/behavior.md

@@ -0,0 +1,38 @@
+# Architecture Behavior
+
+- Path: `ctx/docs/architecture/behavior.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe major internal architectural flows and processing behavior.
+
+This document explains how the system works internally, not which product outcomes users want.
+
+## Major Flows
+
+Describe the main architectural flows that matter for the system.
+
+Examples may include request handling, synchronization, ingestion, supervision, background processing, or recovery.
+
+Do not rewrite product use cases here.
+
+## Flow Boundaries
+
+For each major flow, clarify:
+
+- where the flow starts;
+- which architectural areas participate;
+- where important decisions are made;
+- where the flow ends or commits durable change.
+
+## Failure And Recovery
+
+Describe important failure handling, retry, fallback, or degradation behavior at the architectural level.
+
+## Product Dependency
+
+Behavior must realize product intent.
+
+If product behavior is missing or contradictory, expose the gap instead of inventing architectural behavior silently.

package/skill/templates/ctx/docs/architecture/checklists.md

@@ -0,0 +1,25 @@
+# Architecture Checklists
+
+- Path: `ctx/docs/architecture/checklists.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Provide short recurring checklists for human supervision, diagnosis, and acceptance of architecture-level agent work.
+
+## Drift Diagnosis Checklist
+
+List the quick checks a human should run when an agent appears to move in the wrong architectural direction.
+
+## Approval Checklist
+
+List the checks a human should run before approving architecture expansion.
+
+## Compression Safety Checklist
+
+List the checks a human should run before accepting compression of architecture documents.
+
+## Reading Route
+
+Point to the small set of architecture documents a human should read next after this checklist file.

package/skill/templates/ctx/docs/architecture/constraints.md

@@ -0,0 +1,36 @@
+# Architecture Constraints
+
+- Path: `ctx/docs/architecture/constraints.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Record non-negotiable architecture restrictions and trust boundaries.
+
+## Core Constraints
+
+List stable architectural properties that downstream environment and code work must respect.
+
+Examples may include offline-first behavior, transport choices, persistence assumptions, cost ceilings, latency boundaries, or trust boundaries.
+
+## Boundary Constraints
+
+Describe what architecture must not redefine or violate.
+
+This section should make product and architecture boundaries explicit.
+
+## Change Constraints
+
+Describe which kinds of architecture changes always require human approval.
+
+At minimum, cover:
+
+- new architectural owners;
+- new persistent state;
+- new external integrations;
+- new major system boundaries.
+
+## Human Review Use
+
+List the supervision questions a human should answer quickly with this document.

package/skill/templates/ctx/docs/architecture/decisions.md

@@ -0,0 +1,33 @@
+# Architecture Decisions
+
+- Path: `ctx/docs/architecture/decisions.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Record durable architecture decisions in a short ADR-like form.
+
+## Decision Format
+
+Use short entries that contain:
+
+- the decision;
+- rejected alternatives;
+- reasoning.
+
+Keep only durable architecture decisions here.
+
+Do not use this document as a changelog or backlog.
+
+## Decision Entries
+
+Create one short section per durable decision.
+
+Prefer decisions that affect:
+
+- structural boundaries;
+- state ownership;
+- integration model;
+- trust model;
+- supervision model.

package/skill/templates/ctx/docs/architecture/integration.md

@@ -0,0 +1,27 @@
+# Architecture Integration
+
+- Path: `ctx/docs/architecture/integration.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe external integrations and major internal contracts between architectural blocks.
+
+## External Integrations
+
+List the external systems, platforms, or durable dependencies that matter architecturally.
+
+Do not expand this section into protocol or endpoint detail unless a larger project uses optional deeper documents.
+
+## Internal Contracts
+
+Describe the major contract surfaces between architectural areas.
+
+This is not DTO documentation and not an OpenAPI replacement.
+
+## Boundary Rules
+
+- New integrations must be explicit here before they appear in implementation.
+- Integration descriptions must stay at architectural boundary level, not code or schema level.
+- Contradictions with product scope must be surfaced instead of normalized silently.