@flancer32/skill-adsm-ctx 0.2.1

package/skill/references/document-projections.md

@@ -0,0 +1,290 @@
+# Documentation Projections
+
+- Path: `skill/references/document-projections.md`
+- Changed: `20260715`
+
+Use this reference whenever an agent initializes, designs, validates, audits, compresses, or upgrades ADSM documentation under `ctx/docs/`.
+
+## Core Model
+
+ADSM documentation is agent-first by default and canonical agent documents are written in English unless a more specific rule applies.
+
+Humans control meaning through optional semantic skins.
+
+Agents maintain detailed operational context documents and keep them aligned with matching skins when those skins exist.
+
+Default file roles under `ctx/docs/**`:
+
+- ordinary `*.md` files are agent-facing operational context documents;
+- `*.skin.<lang>.md` files are human-facing semantic skins in the explicitly named language;
+- `AGENTS.md` files are short local reading, editing, and routing instructions for agents;
+- generated reports and work artifacts outside installed project-facing context are not durable context documents;
+- visual, generated, rendered, or auxiliary artifacts belong under `ctx/assets/**`, not under `ctx/docs/**`.
+
+## Agent Documents
+
+An agent document is an ordinary `*.md` document under `ctx/docs/**`.
+
+Agent documents may be detailed, explicit, dense, and operational.
+
+When relevant, agent documents define:
+
+- entities;
+- relations;
+- invariants;
+- boundaries;
+- allowed changes;
+- forbidden changes;
+- expected behavior;
+- escalation conditions;
+- level boundaries;
+- cross-document consistency rules.
+
+Agent documents are optimized for agent interpretation and execution.
+
+They are not required to have matching skins.
+
+An agent document should reduce ambiguity and statistical guessing by making explicit, when relevant:
+
+- the described object;
+- current truth;
+- scope and boundaries;
+- terms;
+- requirements;
+- forbidden actions;
+- file and directory references;
+- verification methods;
+- authority chain;
+- the relationship to a paired `*.skin.<lang>.md` document when such a document exists.
+
+## Semantic Skins
+
+A skin is a `*.skin.<lang>.md` document in the same directory as its matching agent document.
+
+Pairing rule:
+
+```text
+name.md
+name.skin.en.md
+name.skin.ru.md
+```
+
+Use a lowercase ISO 639-1 language code such as `en`, `ru`, or `es`; use a regional tag only when a real regional distinction is needed. An unmarked `name.skin.md` is invalid.
+
+One agent document and all skins sharing its basename form one document group. A skin represents the same cognitive content for humans, but may reorganize or explain it for its named audience and is not required to be a literal translation.
+
+A skin is not a summary.
+
+A skin is a human-facing semantic layer.
+
+Its job is to help a human quickly restore the correct purpose, mental model, scope, and invariants of the same object described by the paired agent document.
+
+Skins should stay compact and easy to read during supervision.
+
+Recommended skin structure:
+
+```md
+# <Title>
+
+## Purpose
+
+One short sentence.
+
+## Mental Model
+
+One or two short paragraphs.
+
+## Scope
+
+Includes:
+
+- one to three items.
+
+Excludes:
+
+- one to three items.
+
+## Invariants
+
+- normally no more than five to seven items.
+
+## Agent Document
+
+`name.md`
+```
+
+Equivalent section titles are acceptable when the meaning remains clear.
+
+Do not move detailed operational instructions, verification checklists, implementation workflows, or exhaustive inventories into skins.
+
+Skin compactness is guided first by section budgets and only second by total content words.
+
+For validation, content-word counting ignores headings and document metadata where practical, strips fenced code blocks, and counts the remaining prose and list text.
+
+Deterministic validation treats up to 160 content words as normal, 161 through 240 content words as a warning range, and anything above 240 as an error.
+
+Missing skins are acceptable unless the document is a key human-direction document where preserving human intent is especially important.
+
+## Read And Edit Behavior
+
+Before changing an agent document, check whether matching skins exist.
+
+If matching skins exist, read every matching skin before editing the agent document.
+
+Agent document edits must preserve the skin's purpose, mental model, scope, and invariants.
+
+Report a required human decision instead of editing when a requested change would:
+
+- violate a skin invariant;
+- alter the visible meaning controlled by the skin;
+- add or preserve skin requirements that are not tracked in the agent document;
+- turn a bounded concept into a different concept.
+
+If an agent document and skin already conflict, report projection drift.
+
+Do not silently resolve projection drift by changing the skin.
+
+## Projection Drift
+
+Projection drift includes:
+
+- an agent document contradicts any matching skin;
+- a skin exists without a matching agent document;
+- an agent document edit would require weakening skin-controlled meaning;
+- a skin accumulates detailed operational content that belongs in the agent document;
+- an asset introduces meaning not present in agent or skin documents.
+
+Validation should report structural drift such as orphan skins.
+
+Audit, compression, and upgrade work should report semantic drift when it can be evidenced from the documents.
+
+## Documentation Levels And Substructure
+
+ADSM defines only four top-level documentation levels under `ctx/docs/`:
+
+```text
+ctx/docs/product/
+ctx/docs/architecture/
+ctx/docs/environment/
+ctx/docs/code/
+```
+
+Their meanings:
+
+- `product` — product meaning;
+- `architecture` — engineering structure;
+- `environment` — runtime and deployment context;
+- `code` — implementation mapping.
+
+ADSM may provide baseline templates and recommendations, but it must not impose a rigid internal subtree inside those levels.
+
+Project-specific nested subdirectories are allowed and should be used when they improve maintainability.
+
+Valid examples:
+
+```text
+ctx/docs/product/domain/ingress.md
+ctx/docs/product/domain/memory.md
+ctx/docs/architecture/runtime/agent-execution.md
+ctx/docs/environment/deployment/vps.md
+ctx/docs/code/modules/orchestrator.md
+```
+
+Flat files remain allowed when suitable.
+
+Do not require flat prefixed names such as `domain-ingress.md` when nested directories are clearer.
+
+Each of the four documentation levels should contain no more than nine direct subdirectories and no more than nine direct ordinary files. The service-control file `AGENTS.md` and all matching `*.skin.<lang>.md` files are excluded, so an agent document and all of its skins count as one document group. This is a maintainability recommendation, not a reason to collapse meaningful structure.
+
+When a level deliberately exceeds either value, its own `AGENTS.md` must include a `## Documentation Capacity Exception` section that explicitly records the intentional exception and its reason. Deterministic validation warns about the exceeded recommendation and reports an error when this explicit local declaration is absent.
+
+Do not require `README.md` inside `ctx/docs/`.
+
+## Assets
+
+Visual, generated, rendered, or auxiliary artifacts belong under `ctx/assets/**`.
+
+Examples:
+
+```text
+ctx/assets/product/domain/main-map.mmd
+ctx/assets/product/domain/main-map.svg
+ctx/assets/architecture/lifecycle/signal-flow.svg
+```
+
+Assets may be linked from agent or skin documents.
+
+Assets illustrate or render meaning.
+
+Assets must not introduce authoritative project meaning.
+
+If an asset conflicts with agent or skin documents, update the source documents or regenerate the asset.
+
+Do not treat the asset as authoritative over agent or skin documents.
+
+## AGENTS.md Role
+
+`AGENTS.md` files are local agent instruction and routing files.
+
+They should explain:
+
+- what the current directory contains;
+- how agents should read documents in this directory;
+- how agents should edit documents in this directory;
+- which agent/skin rules apply locally;
+- when to escalate to the human;
+- which subdirectories are project-specific and should not be flattened or removed without reason.
+
+Keep `AGENTS.md` files short.
+
+Do not use `AGENTS.md` as a replacement for agent documents or skins.
+
+## Audit Rules
+
+Documentation quality audit should:
+
+- recursively include ordinary `*.md` agent documents under the four top-level documentation levels;
+- classify `*.skin.<lang>.md` files as human-facing semantic skins;
+- detect agent/skin document groups by same basename and directory;
+- report orphan skins;
+- check whether skins are compact human-facing semantic layers rather than operational documents;
+- check whether agent documents preserve matching skin meaning and carry the operational requirements behind them;
+- check whether a missing skin is acceptable or suspicious for key human-direction documents;
+- report projection drift separately from ordinary editorial issues;
+- exclude `ctx/assets/**` from the primary agent-document corpus while checking referenced assets for obvious authority conflicts.
+
+Deterministic validation should:
+
+- require every `*.skin.<lang>.md` file to have a paired non-skin `*.md` document and an explicit valid language marker;
+- require the standard skin sections and the `Agent Document` reference;
+- require both `Includes:` and `Excludes:` blocks inside the skin `Scope` section;
+- verify local markdown document links under `ctx/docs/**`;
+- warn when a documentation level contains more than nine direct directories or more than nine direct ordinary files (excluding `AGENTS.md` and paired `*.skin.<lang>.md` files), and require an explicit `Documentation Capacity Exception` in that level's `AGENTS.md`;
+- measure skin compactness using only the content of `Purpose`, `Mental Model`, `Scope`, and `Invariants`; exclude metadata, headings, and `Agent Document`; count Unicode-aware words and meaningful list items only; warn above 160 words or 12 list items and fail above 240 words or 20 list items;
+- keep ordinary agent-document shape checks minimal instead of imposing a rigid body template.
+
+## Compression Rules
+
+Documentation compression may reduce agent-document size and redundancy.
+
+Compression must not:
+
+- rewrite skin-controlled meaning without a human decision;
+- convert a skin into a full agent document;
+- delete a skin because its matching agent document is detailed;
+- flatten useful nested subdirectories;
+- move authoritative meaning into assets.
+
+When compressing an agent document with a matching skin, preserve the skin's purpose, mental model, scope, and invariants.
+
+When an agent document contains human-facing semantic framing that should be preserved independently for human supervision, recommend extracting a matching skin unless the human has not authorized that migration.
+
+## Upgrade Rules
+
+Upgrades should:
+
+- preserve existing agent documents and project-specific nested subdirectories;
+- add or recommend skins only where human semantic control is clear;
+- report orphan skins and agent/skin conflicts;
+- avoid introducing required `README.md` files inside `ctx/docs/`;
+- keep assets under `ctx/assets/**`.

package/skill/references/documentation-compression.md

@@ -0,0 +1,117 @@
+# Documentation Compression
+
+- Path: `skill/references/documentation-compression.md`
+- Changed: `20260708`
+
+Use this reference when an agent must compress an existing ADSM cognitive documentation corpus while preserving accepted project meaning.
+
+Documentation compression is a controlled rewrite mode. It may modify documents, but only to reduce attention cost, improve density, remove duplication, and relocate durable meaning to its authoritative home.
+
+It is not a quality audit, not automatic semantic scoring, and not permission to reinterpret the project.
+
+## Start Prompt
+
+Compress the project cognitive documentation corpus under `ctx/docs/`.
+
+Follow this method:
+
+1. Read the applicable `AGENTS.md` hierarchy from the repository root to the target documentation scope. For the default scope, this means the hierarchy from the repository root to `ctx/docs/`.
+2. Read `skill/references/document-projections.md` for agent/skin classification and projection drift rules.
+3. Use `ctx/docs/` as the default corpus unless the human explicitly provides another scope.
+4. Exclude operational context outside `ctx/docs/` by default, including `ctx/agent/`, workflow configuration, prompt assets, generated reports, runtime materials, and `ctx/assets/**`.
+5. Treat ordinary `*.md` files as agent-facing operational context documents and `*.skin.<lang>.md` files as human-facing semantic skins.
+6. Identify authoritative agent documents, refinement documents, navigation documents, agent/skin pairs, orphan skins, projection drift, and duplicated responsibility areas.
+7. Preserve product intent, domain meaning, architecture boundaries, decisions, constraints, roles, state ownership, environment assumptions, code rules, and skin-controlled meaning.
+8. Remove or reduce only redundant wording, obvious descriptions, repeated definitions, process narration, low-density text, and skill-methodology noise that does not define project meaning.
+9. Move duplicated durable meaning to its authoritative home instead of keeping parallel definitions.
+10. Avoid replacing precise rules with vague summaries.
+11. Avoid inventing, weakening, generalizing, or silently deleting project-specific knowledge.
+12. Update `Changed` attributes for every modified context document.
+13. Report non-editorial uncertainty and skin contradictions as human decisions instead of resolving them by rewrite.
+14. Use `templates/work/report/documentation-compression.md` as the report structure when a file report is requested.
+
+## Corpus Selection
+
+The default corpus is `ctx/docs/`.
+
+Documentation compression is intended for declarative project documentation: product, architecture, environment, code, and other project documentation levels under `ctx/docs/`.
+
+Do not include operational context outside `ctx/docs/` by default, including `ctx/agent/`, generated reports, prompt assets, workflow configuration, runtime materials, `ctx/assets/**`, or other agent-operation artifacts.
+
+When the human gives a narrower scope, compress only that scope and the upstream documents required to preserve its meaning.
+
+When the human explicitly gives a broader non-`ctx/docs/` scope, apply the applicable `AGENTS.md` hierarchy and report that the compression target is outside the default documentation corpus.
+
+When `ctx/docs/filesystem.md` exists, include it in the default corpus as a repository navigation map. Keep it limited to its declared level boundary.
+
+Absence of a matching skin does not make an agent document invalid.
+
+## Authority Mapping
+
+Before rewriting, classify documents and meaning areas:
+
+- authoritative documents define accepted source-of-truth meaning for their level;
+- refinement documents add lower-level precision without redefining upstream meaning;
+- navigation documents orient readers to structure and dependencies;
+- semantic skins govern matching agent documents through short human-controlled meaning;
+- duplicated responsibility areas contain the same durable meaning in more than one place.
+
+Each durable meaning should have one authoritative home. When the same meaning appears in multiple places, keep or move the durable statement to the authoritative home and replace secondary copies with a compact reference only when useful.
+
+Do not move meaning across product, architecture, environment, or code boundaries in a way that changes authority.
+
+## Safe Compression
+
+Safe compression may:
+
+- remove repeated wording that restates the same durable meaning;
+- shorten verbose explanations that add no new fact, rule, boundary, decision, or useful distinction;
+- remove skill-methodology explanation from project-facing documents when that explanation does not define project meaning;
+- replace obvious descriptions with precise project-specific statements;
+- merge duplicated definitions into the authoritative document;
+- remove process narration that does not define accepted project behavior;
+- compress agent documents while preserving matching skin-controlled meaning;
+- keep skins compact and human-readable without turning them into operational agent documents;
+- tighten headings, lists, and navigation text without changing meaning.
+
+Safe compression preserves:
+
+- product intent and scope;
+- domain terms and relationships;
+- role and authority boundaries;
+- architecture boundaries and decisions;
+- state ownership and sources of truth;
+- environment assumptions;
+- code rules and implementation constraints;
+- documented exclusions and non-goals.
+
+## Unsafe Semantic Change
+
+Unsafe semantic change includes:
+
+- inventing missing product facts, requirements, domain entities, architecture boundaries, roles, integrations, state ownership, environment assumptions, or code rules;
+- weakening mandatory language into optional or vague language;
+- generalizing project-specific rules into generic advice;
+- deleting exclusions, constraints, rejected alternatives, or decision rationale because they appear verbose;
+- choosing between contradictory documents without evidence;
+- hiding uncertainty by writing a confident summary;
+- moving meaning to a document whose level is not authoritative for that meaning;
+- changing an agent document in a way that contradicts its matching skin;
+- deleting or weakening a skin-controlled invariant without a human decision;
+- moving authoritative project meaning into `ctx/assets/**`;
+- changing workflow, operational, or runtime semantics outside the requested documentation scope.
+
+When a rewrite would require unsafe semantic change, stop that edit and report the uncertainty as a human decision.
+
+## Reporting
+
+The final report should identify:
+
+- compressed files;
+- preserved authoritative meanings;
+- removed redundancy;
+- moved meanings and their new authoritative homes;
+- human decisions required;
+- unresolved risks.
+
+When no report file is requested, include this information in the final response.

package/skill/references/documentation-quality-audit.md

@@ -0,0 +1,199 @@
+# Documentation Quality Audit
+
+- Path: `skill/references/documentation-quality-audit.md`
+- Changed: `20260708`
+
+Use this reference when an agent must audit an existing documentation corpus as an ADSM cognitive context.
+
+The audit checks whether the corpus is usable as operational memory for humans and agents. It is not a structural `validate` pass and it is not an automatic rewrite pass.
+
+Run deterministic `validate` first and fix blocking structural failures before starting this audit.
+
+## Start Prompt
+
+Audit the documentation corpus of this project against the ADSM documentation quality criteria.
+
+Follow this method:
+
+1. Read the applicable `AGENTS.md` hierarchy from the repository root to `ctx/docs/`, unless the user explicitly gives another documentation scope.
+2. Read `skill/references/document-projections.md` for agent/skin classification and projection drift rules.
+3. Identify the audit corpus under `ctx/docs/`, including nested documentation under `product/`, `architecture/`, `environment/`, and `code/`.
+4. Classify ordinary `*.md` files as agent-facing operational context documents, `*.skin.<lang>.md` files as human-facing semantic skins, and `AGENTS.md` files as local agent routing instructions.
+5. Build a compact documentation map that shows source-of-truth agent documents, refinement relationships, agent/skin pairs, orphan skins, projection drift, and duplicated responsibility areas.
+6. Evaluate the corpus against the eight ADSM documentation quality criteria and the projection-specific checks below after deterministic validation is clean or warning-only.
+7. Check whether project-facing documents govern the project rather than explaining ADSM methodology to themselves.
+8. Report only evidence-backed findings, with file references and the violated criterion.
+9. Separate findings that can be fixed editorially from findings that require cross-document synchronization, upstream documentation changes, projection-drift resolution, or human decisions.
+10. Do not invent missing product facts, architecture boundaries, authority rules, workflow semantics, or implementation behavior.
+11. Use `templates/work/report/documentation-quality-audit.md` as the report structure when a file report is requested.
+
+## Corpus Selection
+
+The default corpus is `ctx/docs/`.
+
+Documentation quality audit is intended for the declarative project documentation corpus.
+
+Do not include operational context outside `ctx/docs/` by default, including `ctx/agent/`, generated reports, prompt assets, workflow configuration, or other agent-runtime materials.
+
+When the user gives a narrower scope, audit only that scope and the upstream documents required to interpret it.
+
+When the user explicitly gives a broader non-`ctx/docs/` scope, audit that scope according to its applicable `AGENTS.md` hierarchy and report that the audit target is outside the default documentation corpus.
+
+When `ctx/docs/filesystem.md` exists, include it in the default corpus and use it as the repository navigation map. Do not treat it as a complete description of lower-level documentation structure.
+
+When an `AGENTS.md` file exists inside the scope, apply it as part of the effective instruction hierarchy.
+
+Do not include `ctx/assets/**` in the primary agent-document corpus. Check referenced assets only for obvious conflicts with agent or skin documents.
+
+Absence of a matching skin does not make an agent document invalid.
+
+## Quality Criteria
+
+Apply the criteria according to the document's projection role:
+
+- agent documents are optimized for agent interpretation and execution;
+- skin documents are optimized for human semantic control;
+- `AGENTS.md` files are optimized for local agent routing.
+
+## Projection-Specific Checks
+
+### Skin Documents
+
+Review each `*.skin.<lang>.md` file as a human-facing semantic layer.
+
+Check whether:
+
+- the paired non-skin document exists when required;
+- both documents describe the same object;
+- the skin preserves purpose, mental model, scope, invariants, and a reference to the paired agent document;
+- the skin adds untracked requirements not present in the paired agent document;
+- the skin contradicts the paired agent document;
+- the skin stays compact, human-readable, and free of excessive operational detail.
+
+The review should answer:
+
+- does the document work as a human-facing semantic layer;
+- does it preserve the same meaning as the paired agent document;
+- does it avoid operational overload;
+- does it add untracked requirements;
+- what must be changed.
+
+### Agent Documents
+
+Review each ordinary `*.md` file as an operational context document for LLM agents.
+
+Check whether the document makes explicit, when relevant:
+
+- the described object;
+- current truth;
+- scope and boundaries;
+- terms;
+- requirements;
+- forbidden actions;
+- file and directory references;
+- verification methods;
+- authority chain;
+- the relationship to a paired `*.skin.<lang>.md` document if such a file exists.
+
+The review should answer:
+
+- does the document work as agent-facing operational context;
+- does it reduce guessing;
+- are current facts, future plans, requirements, prohibitions, and verification clear;
+- are file references accurate;
+- whether a missing skin document is acceptable or suspicious.
+
+### Declarativity
+
+Documentation should state stable facts, rules, boundaries, decisions, and invariants.
+
+Report a finding when a document that should define project knowledge instead contains speculation, process narration, hidden TODOs, or unresolved intention phrased as accepted truth.
+
+### Consistency
+
+Documentation should not contain incompatible statements.
+
+Check especially product versus architecture, architecture versus environment or code, glossary versus term usage, source-of-truth declarations, and higher-level boundaries versus lower-level refinements.
+
+### Completeness
+
+Documentation should be complete relative to declared scope.
+
+Report a finding when the corpus names a responsibility, role, lifecycle, state, integration, authority boundary, or constraint but omits the knowledge required for an agent to act without guessing.
+
+### Connectedness
+
+Documentation should form a navigable knowledge model.
+
+Report a finding when documents introduce concepts without upstream anchors, lack navigation to dependent documents, bypass the documented dependency order, or leave related knowledge isolated.
+
+### Density
+
+Documentation should carry project knowledge.
+
+Report a finding when text is verbose but adds no durable fact, rule, boundary, decision, or useful distinction.
+
+Report a finding when a project-facing document spends substantial space explaining ADSM methodology, document contracts, or skill-owned validation behavior instead of governing the project.
+
+### Compactness
+
+Documentation should remain small and well-partitioned enough for regular human and agent use.
+
+Report a finding when a document mixes unrelated concerns, grows beyond its level boundary, lacks an entry map, or makes routine task orientation unnecessarily expensive.
+
+For skin documents, compactness must be judged by human supervision cost first.
+
+Report a finding when a skin becomes a full operational document instead of a short control surface.
+
+Report projection drift when an agent document contradicts its matching skin or when a skin exists without a matching agent document.
+
+### Non-Redundancy
+
+Each durable meaning should have one authoritative home.
+
+Report a finding when the same rule, list, decision, or semantic definition is duplicated across documents in a way that creates synchronization risk.
+
+### Absence Of Obvious Descriptions
+
+Documentation should not spend attention on facts obvious from filenames, common tooling, or directory names unless those facts carry project-specific meaning.
+
+Report a finding when text merely explains that a file or directory exists, restates a heading, describes generic tool behavior, or says what an implementation artifact is without defining its project role.
+
+## Finding Format
+
+Each finding should include:
+
+- criterion;
+- severity;
+- location;
+- issue;
+- evidence;
+- impact;
+- suggested action;
+- decision status.
+
+Severity values:
+
+- `critical` — the corpus can lead agents to perform incorrect work.
+- `high` — project meaning or authority is missing, contradictory, or duplicated in a load-bearing area.
+- `medium` — the corpus remains usable but creates avoidable agent effort or synchronization risk.
+- `low` — localized wording, structure, or density issue.
+
+Decision status values:
+
+- `editorial` — can be fixed without changing meaning.
+- `synchronize` — requires aligning existing statements across documents.
+- `upstream-gap` — requires adding missing meaning to a higher-level document before lower-level correction.
+- `human-decision` — requires the human to decide product meaning, architecture boundary, authority, or workflow semantics.
+
+## Audit Constraints
+
+The audit must not:
+
+- rewrite documentation unless the user explicitly asks for fixes;
+- invent missing product facts or architecture;
+- resolve contradictions by choosing a side without evidence;
+- treat template guidance as project-specific truth;
+- mark a corpus incomplete merely because it does not document out-of-scope concerns.
+
+The audit may propose correction order and candidate edits, but it must distinguish proposals from accepted project knowledge.

package/skill/references/orchestration-model.md

@@ -0,0 +1,41 @@
+# Orchestration Model
+
+- Path: `skill/references/orchestration-model.md`
+- Changed: `20260715`
+
+This skill is a router and baseline manager.
+
+It is responsible for:
+
+- generic ADSM context structure;
+- the agent/skin documentation projection model;
+- lifecycle guidance;
+- baseline validation;
+- migration entry points;
+- the reserved boundary definition for `ctx/agent/`.
+
+It is not responsible for inventing specialized technical or domain documentation.
+
+For `ctx/agent/`, this skill may:
+
+- install only `ctx/agent/AGENTS.md` as the boundary file;
+- state that project-local subdirectories there are outside ADSM methodology;
+- preserve project-local materials that humans or agents maintain there for concrete tools or relationships.
+
+For `ctx/agent/`, this skill must not:
+
+- define or require a template-managed subdirectory structure;
+- invent tool-specific instructions, workflow semantics, or executable profiles;
+- define a GitHub-based workflow on its own.
+
+When specialization is needed, the agent should use a matching available skill after the generic baseline is in place.
+
+Concrete tool-facing materials belong to project-local documentation, explicit human instruction, or an external specialized skill when one is available and relevant.
+
+Specialized skills may add project-specific nested documentation under the four top-level `ctx/docs` levels, but they must preserve agent/skin pairing rules and keep artifacts under `ctx/assets/**`.
+
+## Template Boundary
+
+`templates/ctx/` is the reusable initialization baseline. It may establish generic structure, starter documents, and the `ctx/agent/AGENTS.md` boundary, but it must not add project-specific facts or detailed ADSM methodology to project-facing documents.
+
+Keep only the minimal bootstrap signal needed to identify an ADSM context and route methodology work to this skill. Use `templates/work/` only as working material for agent operations; do not install those reports or optional semantic-skin patterns into project context by default.

package/skill/references/specialized-skills.md

@@ -0,0 +1,31 @@
+# Specialized Skills
+
+- Path: `skill/references/specialized-skills.md`
+- Changed: `20260708`
+
+Use specialized skills when the project context requires knowledge that should not live in this generic lifecycle skill.
+
+Examples of specialization signals:
+
+- browser-side web application structure;
+- backend application architecture;
+- data or persistence modeling;
+- deployment and runtime environment design;
+- tool-specific agent instructions or workflow design for a concrete execution engine or host platform.
+
+Tool-specific specialization signals include:
+
+- concrete GitHub events, labels, Pull Request lifecycle rules, prompts, or profile fragments;
+- engine-specific routing schemas or executable workflow configuration;
+- project-specific agent role definitions tied to one automation engine.
+
+GitHub-based workflow design, including GitHub events, labels, Pull Request lifecycle, prompts, profiles, and executable routing configuration, should use an external specialized skill when available.
+
+If no specialized skill is available, preserve the project-local structure already in use under `ctx/agent/`, keep any accepted tool semantics already defined by the project or the human, and record the missing specialization area explicitly instead of inventing unsupported details.
+
+Specialized skills must preserve ADSM's documentation projection model:
+
+- ordinary `*.md` files under `ctx/docs/**` are agent-facing operational context documents;
+- `*.skin.<lang>.md` files are human-facing semantic skins for matching agent documents;
+- nested subdirectories inside the four top-level documentation levels are allowed;
+- visual, generated, rendered, and auxiliary artifacts belong under `ctx/assets/**`.