@flancer32/skill-adsm-ctx 0.2.1

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

@@ -0,0 +1,73 @@
+# Architecture Overview
+
+- Path: `ctx/docs/architecture/overview.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+Keep this document short enough for fast supervision.
+
+If the draft grows too large, move detail into `structure.md`, `behavior.md`, `state.md`, `integration.md`, `constraints.md`, `decisions.md`, `checklists.md`, or `supervision.md` and keep only the load-bearing overview here.
+
+## Purpose
+
+Provide a compact entry point to the architecture level.
+
+## Architecture Role
+
+Describe how this level translates product intent into stable engineering structure.
+
+This level should answer briefly:
+
+- what is structurally built;
+- how the system behaves internally;
+- where state is owned;
+- what integrations exist;
+- what constraints must not be violated;
+- why key decisions were made;
+- how human and agents supervise architectural consistency.
+
+## Architectural Style
+
+Describe the stable architectural style or organizing principle of the system.
+
+## Major Areas
+
+List the main architectural areas and explain what each area is responsible for.
+
+Do not list source directories, classes, database tables, or endpoint inventories here.
+
+## Documentation Map
+
+Use this level in the following navigation pattern:
+
+- Read `structure.md` when the question is "what are the main architectural areas and boundaries?"
+- Read `behavior.md` when the question is "how do those areas work together through major internal flows?"
+- Read `checklists.md` when the question is "which fast human checks should I run before concluding that agent work drifted?"
+- Read `state.md` when the question is "where is authoritative state owned, persisted, changed, and derived?"
+- Read `integration.md` when the question is "which external systems and internal contract boundaries matter?"
+- Read `constraints.md` when the question is "which architectural options are forbidden or non-negotiable?"
+- Read `decisions.md` when the question is "why was this architecture chosen over other durable alternatives?"
+- Read `supervision.md` when the question is "what may agents change, what requires approval, and what signals drift?"
+
+## Product Dependency
+
+State explicitly that architecture depends on product documentation.
+
+Product documentation defines what the product is.
+
+Architecture documentation defines how that product is realized structurally.
+
+The expected dependency is:
+
+```text
+product
+  → architecture
+  → environment
+  → code
+```
+
+Architecture must not redefine product meaning, invent missing product behavior, or normalize product contradictions silently.
+
+## Collaboration
+
+Describe how one human and many agents use this architecture level as an operational interface.

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

@@ -0,0 +1,52 @@
+# Architecture State
+
+- Path: `ctx/docs/architecture/state.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe state ownership and sources of truth.
+
+## Sources Of Truth
+
+List the durable sources of truth that matter architecturally.
+
+## State Categories
+
+Separate state into categories such as:
+
+- authoritative durable state;
+- temporary state;
+- derived state.
+
+Make clear which category is the source of truth and which categories are downstream reflections of it.
+
+## Ownership Boundaries
+
+Describe the boundaries around:
+
+- which state is authoritative;
+- where persistence responsibility lives;
+- where derived state comes from;
+- which state areas must not be re-owned implicitly.
+
+## Ownership Rules
+
+Describe:
+
+- who owns each important state area;
+- who may change it;
+- who may authorize new state creation.
+
+## State Authority
+
+Describe:
+
+- who has authority to commit durable state change;
+- how derived state stays traceable to authoritative state;
+- how persistence responsibility is kept explicit.
+
+## Change Discipline
+
+Make clear that agents must not introduce new persistent state owners or categories without updating architecture documents and obtaining human approval.

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

@@ -0,0 +1,32 @@
+# Architecture Structure
+
+- Path: `ctx/docs/architecture/structure.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe the major architectural blocks, runtime areas, and responsibility boundaries.
+
+## Architectural Blocks
+
+List the main architectural parts and the responsibility of each part.
+
+This is not code structure.
+
+Do not list:
+
+- classes or modules;
+- source directories as if they were architecture;
+- database tables;
+- endpoint inventories.
+
+## Responsibility Boundaries
+
+Describe the stable boundaries between architectural areas and the authority each area holds.
+
+## Optional Expansion
+
+If the project grows, deeper structure documents may be created under `structure/`.
+
+Do not create those subdocuments unless they are justified by project scale.

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

@@ -0,0 +1,61 @@
+# Architecture Supervision
+
+- Path: `ctx/docs/architecture/supervision.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe how one human and many agents supervise architecture-level consistency.
+
+Use this document for durable supervision rules and approval boundaries.
+
+Use `checklists.md` for short recurring human checks.
+
+## Human-Agent Supervision Principle
+
+State that:
+
+- humans own architectural direction and guardrails;
+- agents operate within documented architectural boundaries;
+- architecture documentation is the authoritative medium through which the human direction-setting loop and the agent refinement and execution-support loop coordinate at the architecture level;
+- agents must surface architectural drift instead of silently resolving it;
+- major architectural boundary changes require human approval.
+
+## Human Responsibilities
+
+Describe the human role in setting direction, approving guardrails, and resolving architectural uncertainty.
+
+## Agent Responsibilities
+
+Describe what agents may refine autonomously inside existing architecture boundaries.
+
+State that agents should prefer updating documentation before code when a new architectural concept appears.
+
+## Mandatory Approval Cases
+
+State which changes require human approval.
+
+At minimum, cover:
+
+- new architectural owners;
+- new persistent state;
+- new external integrations;
+- new system boundaries.
+
+## Drift Signals
+
+Describe the signals that indicate architecture and implementation are diverging.
+
+## Pre-Code Check Order
+
+State which documents agents must check before code-oriented work.
+
+The expected dependency is:
+
+```text
+product
+  -> architecture
+  -> environment
+  -> code
+```

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

@@ -0,0 +1,35 @@
+# Code Documentation
+
+- Path: `ctx/docs/code/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Defines the code documentation level.
+
+Documents at this level map architecture into implementation constraints, source organization expectations, tests, and code-level invariants.
+
+## Level Map
+
+- `AGENTS.md` — level definition for `ctx/docs/code/`.
+- `overview.md` — product code boundary, code responsibilities, and code invariants.
+- `testing.md` — test strategy, required checks, and validation expectations.
+
+## Level Boundary
+
+Defines:
+
+- Implementation mapping from architecture to code.
+- Code-level invariants and source constraints.
+- Test and validation expectations for implementation work.
+
+Does NOT define:
+
+- Product meaning, architecture ownership, or deployment environment facts.
+- Runtime operations outside code-level constraints.
+- Agent workflow behavior outside this documentation level.
+
+## Local Rules
+
+- Preserve project-specific nested code subdirectories such as modules, packages, or test areas when they improve maintainability.

package/skill/templates/ctx/docs/code/overview.md

@@ -0,0 +1,21 @@
+# Code Overview
+
+- Path: `ctx/docs/code/overview.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe the implementation boundary of the product at code level.
+
+## Code Structure
+
+Summarize the major source branches and their responsibilities.
+
+## Engineering Constraints
+
+Record stable code-level constraints, conventions, or layering rules.
+
+## Test Boundary
+
+Describe where implementation verification lives and what kinds of tests exist.

package/skill/templates/ctx/docs/code/testing.md

@@ -0,0 +1,13 @@
+# Testing Overview
+
+- Path: `ctx/docs/code/testing.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe the test boundary for the project.
+
+## Test Structure
+
+List the main test layers, directories, and intended verification scope.

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

@@ -0,0 +1,34 @@
+# Environment Documentation
+
+- Path: `ctx/docs/environment/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Defines the environment documentation level.
+
+Documents at this level describe runtime assumptions, deployment context, infrastructural prerequisites, and operational constraints.
+
+## Level Map
+
+- `AGENTS.md` — level definition for `ctx/docs/environment/`.
+- `overview.md` — runtime assumptions, execution surfaces, external prerequisites, and operational constraints.
+
+## Level Boundary
+
+Defines:
+
+- Runtime and deployment context required for system operation.
+- Environment assumptions and external prerequisites.
+- Operational constraints that implementation and deployment must respect.
+
+Does NOT define:
+
+- Product meaning or architecture ownership.
+- Source-level implementation details.
+- Project-local agent workflow behavior.
+
+## Local Rules
+
+- Preserve project-specific nested environment subdirectories such as deployment, runtime, or operations areas when they improve maintainability.

package/skill/templates/ctx/docs/environment/overview.md

@@ -0,0 +1,21 @@
+# Environment Overview
+
+- Path: `ctx/docs/environment/overview.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe the runtime and operational environment required by the system.
+
+## Runtime Model
+
+Identify the main execution environments, hosts, runtimes, or operational domains.
+
+## External Dependencies
+
+List required external systems or platform prerequisites.
+
+## Environment Constraints
+
+Record stable environment-level constraints that the implementation must respect.

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

@@ -0,0 +1,39 @@
+# Filesystem Structure
+
+- Path: `ctx/docs/filesystem.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Defines the declarative structure of the project repository at the top level only, listing root-level directories and root-level files and establishing repository boundaries as a navigation model.
+
+This starter is not a completed repository map.
+
+During context design, replace placeholder entries with the actual top-level repository directories and root-level files.
+
+Do not keep optional examples or inferred technology directories unless they exist and carry project-specific meaning.
+
+## Root Structure
+
+- `ctx/` — cognitive context containing project documentation, assets, and project-local agent materials.
+- `{{top-level-directory}}/` — replace with an actual project directory and its project role.
+
+## Root Files
+
+- `AGENTS.md` — root-level agent instructions.
+- `{{root-file}}` — replace with an actual root-level file and its project role.
+
+## Scope Rule
+
+This document must describe only top-level directories and root-level files of the repository.
+
+Subdirectories must not be described here.
+
+Lower-level structure must be described only by the corresponding `AGENTS.md` files within those directories.
+
+## Boundary Definition
+
+- `ctx/` defines the system model and governs interpretation of the repository.
+- Product implementation directories must be named here only after the project structure is known.
+- Generated, dependency, cache, secret, and local tool directories must be omitted unless the project context explicitly governs them.

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

@@ -0,0 +1,38 @@
+# Product Documentation
+
+- Path: `ctx/docs/product/AGENTS.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Defines the product documentation level.
+
+Documents at this level describe the system as a product: its meaning, purpose, scope, domain language, user roles, product boundaries, and product-level invariants.
+
+## Level Map
+
+- `AGENTS.md` — level definition for `ctx/docs/product/`.
+- `domain.md` — product domain model; describes the product world, domain areas, business entities, ownership, and semantic relations, not storage structure.
+- `glossary.md` — product terminology; defines stable product terms and prevents terminology drift.
+- `overview.md` — entry point; defines product identity, scope, boundaries, and navigation, not a compressed full specification.
+- `roles.md` — user role model; describes role categories, authority, permissions, ownership boundaries, and responsibility boundaries.
+- `use-cases.md` — product use cases; describes user goals and expected outcomes, not UI, API, or implementation flows.
+
+## Level Boundary
+
+Defines:
+
+- Product identity, scope, and explicit exclusions.
+- Product language, roles, and authority boundaries.
+- Product-level user goals, expected outcomes, and durable invariants.
+
+Does NOT define:
+
+- Architectural structure, system decomposition, or integration boundaries.
+- Execution environment, deployment topology, or code-level implementation constraints.
+- Agent workflow behavior, repository operations, or methodological rules above this level.
+
+## Local Rules
+
+- Preserve project-specific nested product subdirectories such as domain, roles, glossary, or use-case areas when they improve maintainability.

package/skill/templates/ctx/docs/product/domain.md

@@ -0,0 +1,77 @@
+# Product Domain Model
+
+- Path: `ctx/docs/product/domain.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Describe the product world at the overview level.
+
+This document defines product-world semantics only: what exists in the product world, why it matters, who owns it, and how major concepts relate to each other.
+
+Detailed domain areas may be described in `ctx/docs/product/domain/`.
+
+## Level Boundary
+
+Defines:
+
+- major domain areas;
+- core domain entities;
+- ownership principles for domain objects;
+- semantic relations between domain areas and entities;
+- domain-level invariants.
+
+Does NOT define:
+
+- database tables, DTO fields, indexes, migrations, or persistence structure;
+- API routes, request and response contracts, or transport protocols;
+- UI screens, widgets, components, or user interaction mechanics;
+- source code structure, modules, services, classes, or implementation algorithms;
+- detailed role permissions and authority rules.
+
+## Domain Areas
+
+List the major areas of the product world.
+
+For each area, describe:
+
+- purpose;
+- ownership;
+- primary entities;
+- relation to other areas;
+- detailed document, if it exists.
+
+## Core Domain Entities
+
+List only the entities required for first-level understanding of the product world.
+
+Do not describe all entities here.
+
+Detailed entity models belong to dedicated domain-area documents.
+
+## Ownership Principles
+
+Describe product-level ownership principles for domain objects.
+
+Detailed authority and role permissions belong to `roles.md`.
+
+## Semantic Relations
+
+Describe the most important relations between domain areas and core entities.
+
+Focus on product meaning, not implementation structure.
+
+## Domain Invariants
+
+List product-world rules that must remain true regardless of architecture, storage, UI, or code.
+
+## Domain Documentation Map
+
+List detailed domain documents.
+
+Example:
+
+- `domain/identity.md` — identity and access domain.
+- `domain/content.md` — content and publication domain.
+- `domain/billing.md` — billing and credit domain.

package/skill/templates/ctx/docs/product/glossary.md

@@ -0,0 +1,110 @@
+# Product Glossary
+
+- Path: `ctx/docs/product/glossary.md`
+- Template Version: `20260605`
+- Changed: `YYYYMMDD`
+
+## Purpose
+
+Define stable product terminology.
+
+This document defines product-language semantics only: what terms mean inside the product, which terms are preferred, which terms are prohibited or deprecated, and how terms relate to product domain, roles, and use cases.
+
+Detailed glossary groups may be described in `ctx/docs/product/glossary/`.
+
+## Level Boundary
+
+Defines:
+
+- stable product terms;
+- preferred names for product concepts;
+- prohibited, deprecated, or ambiguous terms;
+- synonym and naming rules;
+- relations between terms;
+- terminology-level invariants.
+
+Does NOT define:
+
+- database table names, column names, DTO names, or persistence naming rules;
+- API route names, request fields, response fields, or transport naming rules;
+- UI labels, button texts, menu names, or copywriting;
+- source code identifiers, class names, service names, or module names;
+- implementation-specific naming conventions.
+
+## Term Groups
+
+List the major groups of product terminology.
+
+Small projects may keep this structure light at first and use a compact list of core terms before splitting terminology into groups.
+
+For each group, describe:
+
+- purpose;
+- related domain area;
+- related roles or use cases;
+- detailed document, if it exists.
+
+## Core Terms
+
+List only the terms required for first-level understanding of the product language.
+
+Do not describe the complete terminology catalog here when the product has many terms.
+
+This document may start as a compact list of core terms and evolve into grouped terminology only when the product language grows.
+
+Detailed term groups belong to dedicated glossary documents.
+
+## Term Format
+
+When a term is defined in this document or in a detailed glossary document, use product-level language.
+
+Recommended fields:
+
+- preferred term;
+- definition;
+- context of use;
+- related domain concepts;
+- related roles;
+- related use cases;
+- allowed synonyms;
+- prohibited synonyms;
+- deprecated terms.
+
+Do not include implementation identifiers unless the implementation identifier is intentionally the same product term.
+
+## Naming Principles
+
+Describe product-level naming principles.
+
+Clarify:
+
+- how product terms are selected;
+- when a term becomes stable;
+- how ambiguous terms are resolved;
+- how deprecated terms are handled;
+- how terms should remain consistent across product documentation.
+
+## Terminology Relations
+
+Describe important relations between terms.
+
+Examples:
+
+- broader and narrower terms;
+- preferred term and synonym;
+- current term and deprecated term;
+- product term and external/common term.
+
+## Terminology Invariants
+
+List terminology-level rules that must remain true regardless of architecture, storage, UI, or code.
+
+## Glossary Documentation Map
+
+List detailed glossary documents.
+
+Example:
+
+- `glossary/domain.md` — domain terminology.
+- `glossary/roles.md` — role terminology.
+- `glossary/ai.md` — AI-related terminology.

package/skill/templates/ctx/docs/product/overview.md

@@ -0,0 +1,74 @@
+# Product Overview
+
+- Path: `ctx/docs/product/overview.md`
+- Template Version: `20260702`
+- Changed: `YYYYMMDD`
+
+Keep this document short enough for fast orientation.
+
+If the draft grows too large, move detail into `domain.md`, `roles.md`, `use-cases.md`, or `glossary.md` and keep only the load-bearing overview here.
+
+## Product Identity
+
+Describe what kind of product this is, who it serves, and what durable user problem it solves.
+
+This section defines the product as a whole, not its implementation or feature inventory.
+
+## Product Mission
+
+Describe why the product exists and what stable product intention guides its development.
+
+This section should express the product purpose, not the current backlog.
+
+## Product Scope
+
+Define what the product is responsible for at the product level.
+
+This section defines the product boundary, not a complete feature list.
+
+## Product Areas
+
+Describe the major product knowledge areas.
+
+This section should help the reader understand where detailed product knowledge belongs before reading `domain.md`, `roles.md`, `use-cases.md`, and `glossary.md`.
+
+Do not treat this section as a compressed replacement for those documents.
+
+## Core Lifecycle
+
+Describe the main lifecycle of product use from entry to useful result.
+
+This section should provide orientation through the product, not a complete use-case catalog.
+
+## Product Boundaries
+
+### In Scope
+
+List product-level responsibilities.
+
+### Out of Scope
+
+List explicit exclusions and anti-goals.
+
+This section is normative. It prevents agents from expanding the product in invalid directions.
+
+## MVP Boundary
+
+Summarize the functional boundary of the current product version.
+
+This section defines the current committed product shape, but must not replace detailed use cases or domain definitions.
+
+## Product Invariants
+
+List product-level rules that must remain true across architecture, environment, code, and future product changes.
+
+Use this section only for stable product constraints.
+
+## Documentation Map
+
+Use this section as a navigation index for product knowledge.
+
+- Read `domain.md` to understand the product world, domain areas, business entities, ownership, and semantic relations.
+- Read `roles.md` to understand product participants, authority, permissions, ownership boundaries, and responsibility boundaries.
+- Read `use-cases.md` to understand user goals, expected outcomes, and product-level usage scenarios.
+- Read `glossary.md` to understand stable product terminology.