skill-adsm-ctx

Build and evolve project cognitive context for Agent-Driven Software Management (ADSM).

Overview

@flancer32/skill-adsm-ctx is an ADSM skill package for initializing, designing, validating, auditing, compressing, and upgrading project cognitive context.

It manages the lifecycle of project context as its primary object. It does not define business requirements, backend architecture, browser architecture, deployment logic, or domain-specific documentation on its own.

This package is developed according to the ADSM methodology.

The package includes:

• the adsm-ctx CLI for lifecycle operations;
• the adsm-ctx skill payload for AI agents;
• reusable ctx/ templates for bootstrapping ADSM-compatible projects.
• working templates for agent-produced reports.

Purpose

Use this package when you need to:

• initialize a new ADSM-compatible project context;
• design the context structure for a concrete project;
• validate whether an existing context follows expected ADSM structure;
• audit a documentation corpus against ADSM documentation quality criteria;
• compress a documentation corpus while preserving accepted project meaning;
• upgrade a context when ADSM conventions evolve.

This package acts as an orchestration layer. It provides generic structure, lifecycle guidance, validation, documentation quality audit guidance, documentation compression guidance, and upgrade entry points. When project-specific context is required, it should direct the agent to use specialized skills when they are available.

The bundled baseline now covers both:

• product-level context, which defines what the system is;
• architecture-level context, which defines how product intent is realized through structure, behavior, state ownership, integrations, constraints, decisions, and supervision.

Non-Goals

This package does not:

• invent project requirements or business rules;
• replace specialized documentation skills;
• write domain-specific architecture content as if it knew the project;
• perform automatic semantic scoring or correction of documentation quality;
• change project meaning during documentation compression;
• perform destructive upgrades without explicit review.

Requirements

• Node.js with npm.
• An agent skills root, normally ~/.agents/skills.

Installation And Update

Install the package globally once for the current user:

npm install --global @flancer32/skill-adsm-ctx

Install its matching agent payload into the selected skills root:

adsm-ctx install-skill "$HOME/.agents/skills"

The command replaces only $HOME/.agents/skills/adsm-ctx; it does not modify other installed skills.

Verify the runtime and payload:

adsm-ctx --help
test -f "$HOME/.agents/skills/adsm-ctx/SKILL.md"

To update, update the global npm package and reinstall its payload:

npm update --global @flancer32/skill-adsm-ctx
adsm-ctx install-skill "$HOME/.agents/skills"

The npm package is the canonical distribution of both artifacts. Its public adsm-ctx launcher runs the package as an explicit TeqFW host; the install-skill command copies the version-matched skill/ bundle. Do not copy only SKILL.md manually: the payload also needs its references and templates.

For a project-pinned CI or team workflow, install the package locally and invoke the same public launcher with npm:

npm install --save-dev @flancer32/skill-adsm-ctx
npm exec -- adsm-ctx validate .

CLI Usage

Show help:

adsm-ctx --help

Initialize a context in the current directory:

adsm-ctx init

Design guidance for a project context:

adsm-ctx design

Validate an existing project context:

adsm-ctx validate

Validate a specific path:

adsm-ctx validate <project-root>

Run the upgrade entry point:

adsm-ctx upgrade

Install the bundled skill payload:

adsm-ctx install-skill <skills-root>

Advanced TeqFW users may invoke the metadata-declared commands directly when teq is installed:

teq --host @flancer32/skill-adsm-ctx adsm-ctx:validate .

Lifecycle Modes

init

Creates the minimal ADSM-compatible context structure, starter documents, and ctx/adsm.json metadata.

design

Provides guidance for classifying the project, choosing relevant documentation branches, and identifying when specialized ADSM skills should be used.

validate

Checks baseline paths, required documentation levels, required AGENTS.md files, metadata, body/skin pairing, localized skin names, local markdown document links, and structural projection checks. When the repository provides a deterministic validator, run it and report errors and warnings separately. Validation reports findings without modifying project content.

quality-audit

Guides an agent through evidence-backed review of a documentation corpus against ADSM documentation quality criteria. This is a skill mode, not a CLI command.

The default audit corpus is ctx/docs/. Operational context such as ctx/agent/, workflow configuration, prompt assets, and generated reports is outside the default corpus unless explicitly requested.

documentation-compression

Guides an agent through controlled rewrite of a documentation corpus to reduce size, improve density, and remove duplication without changing accepted project meaning. This is a skill mode, not a CLI command.

The default compression corpus is ctx/docs/. Operational context such as ctx/agent/, workflow configuration, prompt assets, generated reports, and runtime materials is outside the default corpus unless explicitly requested.

upgrade

Reads context metadata and reports or applies non-destructive migrations when available. The initial implementation provides the migration mechanism and reports when no migrations apply.

Workflow

Recommended sequence:

1. Run adsm-ctx init in a new project repository.
2. Run adsm-ctx design to shape the context for the actual project.
3. Use specialized skills where the project needs domain-specific documentation.
4. Run adsm-ctx validate as the deterministic preflight as the context evolves.
5. Use the skill's quality-audit mode only after structural validation passes or leaves warnings only.
6. Use the skill's documentation-compression mode when accepted documentation meaning is stable but the corpus has high attention cost.
7. Run adsm-ctx upgrade when template conventions or schema versions change.

Documentation Levels

The recommended documentation dependency is:

product
  -> architecture
  -> environment
  -> code

Use the architecture level once product meaning is clear enough to define stable engineering guardrails.

The bundled architecture templates expect these top-level documents:

• overview.md
• structure.md
• behavior.md
• state.md
• integration.md
• constraints.md
• decisions.md
• supervision.md

They are designed for one human plus many agents: body documents stay precise for agentic implementation work, and optional skins stay concise for human semantic control.

Semantic Skin Languages

Canonical agent-facing documents use ordinary names such as overview.md and are written in English unless a project rule says otherwise. Human-facing skins use an explicit language suffix:

overview.md
overview.skin.en.md
overview.skin.ru.md

Use lowercase ISO 639-1 codes (en, ru, es); add a regional tag only for a genuine regional distinction. overview.skin.md is invalid. All skins with the same basename form one group with the canonical document, and may adapt the presentation for people rather than be literal translations. A skin uses a compact structure appropriate to its document type; its paired base is derived from the filename, so it does not need an Agent Document link.

For AGENTS.md authoring, Level Boundary sections should stay compact and guardrail-oriented. They are intended to prevent likely scope drift, not to become exhaustive specifications.

Skill And CLI Relationship

The CLI performs local filesystem operations and structural validation.

The skill in skill/SKILL.md instructs an AI agent how to use the lifecycle modes, how to avoid inventing project content, how to audit documentation quality, how to compress documentation without changing meaning, and how to route documentation work toward specialized skills when needed.

Documentation quality audit uses skill/references/documentation-quality-audit.md and the working report template at skill/templates/work/report/documentation-quality-audit.md.

Documentation compression uses skill/references/documentation-compression.md and the working report template at skill/templates/work/report/documentation-compression.md.

The skill does not directly invoke other skills. It instructs the agent to select and use them when relevant.

Specialized Skill Orchestration

adsm-ctx is intentionally generic. Its design mode should recognize when a project needs specialization such as browser-side web documentation, backend service documentation, data-model documentation, or deployment context.

When a specialized ADSM skill is available, the agent should use it for that area after the generic context baseline is in place.

When no specialized skill is available, this package should create only generic structure and record the specialization gap instead of inventing domain-specific content.

Local Development

Run the CLI directly from the repository:

npm exec -- adsm-ctx --help

Run the tests:

npm test

Changelog

See CHANGELOG.md for the prepared, unpublished 0.3.0 release notes.

Status

This repository contains a working skeleton intended as a foundation for future ADSM context lifecycle tooling.

License

Apache-2.0