ContextOS Core 3.0.0-rc.1

Core release candidate for testing. This is not stable 3.0.0.

Install the exact candidate (Node.js 22+):

npm install --save-dev --save-exact contextos-agents@3.0.0-rc.1
npx --no-install contextos init

Existing 2.x projects should checkpoint their configuration, upgrade the pinned dependency, run npx --no-install contextos update, and review generated changes. See migration instructions.

Changes

• Projects keep rule sources; the installed package runs the compiler.
• Bundled core skills are opt-in (init --with-core).
• Claude exports native .claude/rules and .claude/skills files.
• Safer update, conflict recovery and uninstall behavior preserves user content and rejects junction/path escapes.
• Stable generated files and lockfiles reduce branch noise.

Local Windows / Node 24 verification passed: 536 core tests, 23 publisher/release-surface tests, a production-only installed consumer, and upgrade/rollback from 2.3.2 restoring all 425 configuration files.

Publication and verification

The Core RC workflow checks the exact reviewed archive on Windows, Linux and macOS before publishing only contextos-agents to npm's next tag, then verifies registry bytes and installed consumers. Publication is complete only when that workflow succeeds. latest stays on stable 2.3.2; MCP stays at 0.4.2.

Archive: contextos-agents-3.0.0-rc.1.tgz

SHA-256: 6f57b0ab5cc179979c4192f1c939e57ba5a764745c6a8593f1f6f42117c6ccfc

File-contract tests do not establish live client loading or model adherence. Fresh client acceptance remains open before stable 3.0.0; see the compatibility matrix.

Verified publication

Publication and registry acceptance completed successfully: Core RC workflow, 7/7 successful jobs. The reviewed archive hash matched on Windows, Linux and macOS; production-only installations of the published registry archive passed on all three platforms. The final PR commit also passed 22/22 CI jobs.

npm distribution tags at verification: next = 3.0.0-rc.1, latest = 2.3.2. The attached release-publish-result.json records the verified archive identity. Source tag: merge commit 33e26a968460d62dfbded609756851e27ef46027.

v2.3.2 - reliable skill metadata and CI (MCP 0.4.2)

Manifestless skill descriptions now survive compilation and native, Cursor and Zed exports. Zed also retains its existing body preview when metadata is absent, fixing the plugin-export regression that failed the root and OCI checks.

• Preserve complete frontmatter boundaries and quote generated Gemini descriptions, including multiline values and punctuation.
• Recognize Russian and English destructive requests with intervening words while retaining mandatory safety guidance under profile exclusions and small budgets.
• Use proportional core workflows, canonical aliases and evidence reports that distinguish completed, partial and unrun checks.
• Validate every required field in the original TypeScript catalog example and distinguish behavioral checks from syntax, structure and simulations.
• Ship companion contextos-mcp@0.4.2 with restored deterministic handler/recovery coverage, a real Git repair/verification/merge scenario and passing Biome formatting. MCP runtime implementation is unchanged; execution and recovery remain experimental.

Acceptance: 542 core tests, 635 MCP tests and 10 publication-recovery tests passed. Candidate CI passed 19/19 jobs; publication and registry acceptance passed 21/21. Published npm archives match the reviewed SHA-256 identities. Production-only installation, upgrade and checkpoint rollback passed on Windows, Linux and macOS, preserving user rules and read-only MCP behavior. Results are recorded in the release evidence.

The first two publication attempts stopped while newly accepted uploads were not yet visible in npm. Retries verified the existing archive hashes before proceeding; no version or tag was overwritten. The subsequent repository-only helper update extends bounded registry probe delays and passes 12 recovery tests without changing the published package archives. Final main CI passed 19/19 jobs at 12b4e3e, including Windows installed-consumer upgrade/rollback; its actual candidate archives retain the published hashes.

npm install --save-dev --save-exact contextos-agents@2.3.2 contextos-mcp@0.4.2
npx --no-install contextos update
npx --no-install contextos compile
npx --no-install contextos export all
npx --no-install contextos export all --check --json

See release acceptance and scope and the changelog. Previous release archive identities are preserved. No new paid model benchmarks were run.

v2.3.1 - maintenance update (MCP 0.4.1)

This maintenance update pairs contextos-agents@2.3.1 with contextos-mcp@0.4.1.

Fixes

• Correct installation/version instructions, resolver examples, and the ContextOS Action default version.
• Remove the TypeScript compiler from MCP production dependencies; verify actual production-only installations outside the source checkout.
• Harden installed MCP path handling and upgrade/checkpoint rollback checks, including bounded Windows dependency-install time.
• Bind publication and recovery to reviewed archive hashes for the current release pair.

Verification

• Candidate CI: 19/19 jobs passed across Windows, Linux, and macOS; core 532 tests passed; MCP 623 passed with seven existing experimental skips.
• Codex CLI live check: negative control, explicit skill invocation, and automatic selection passed in three fresh sessions. The fixture uses skill.yaml routing metadata; this is one run per condition.
• Publication and registry acceptance: CI 37197508427 passed all 21 jobs, verified both archive hashes, and tested installation, upgrade and checkpoint rollback from npm on Windows, Linux and macOS.

Stable scope remains context compilation/selection/export and default read-only MCP inspection. Execution, Python, crash recovery, and concurrent persistence remain experimental. Desktop client checks and the external pilot remain unverified.

Update

npm install --save-dev contextos-agents@2.3.1 contextos-mcp@0.4.1
npx --no-install contextos update
npx --no-install contextos export all

Keep your existing dependency classification if different. Back up project configuration and the lockfile before updating. Install only the core package if you do not use MCP.

See the release checklist and migration/rollback guide.

ContextOS 2.3.0 & contextos-mcp 0.4.0

Overview

ContextOS 2.3.0 and companion package contextos-mcp 0.4.0 shift context management from monolithic instruction manuals to a lean bootstrap with task-proportional selection.

• Core package: contextos-agents 2.2.0 -> 2.3.0
• MCP companion: contextos-mcp 0.4.0 (renamed from @contextos/mcp)
• Runtime execution: Remains opt-in experimental
• Client workflows: External auto-routing in Cursor remains in pilot status

Key Changes

1. Lean Bootstrap: Heavy engineering workflow, roles, and minimalism guidelines are relocated to reference documents. In Cursor, only the bootstrap rules remain permanently active; additional skills attach on demand via ctx.js resolve. Automatic background routing remains under client pilot.
2. Proportional Skills & Security Priority: Simple tasks receive a concise workflow; deep implementation attaches extended guidance. Security instructions survive soft-budget overflow and profile exclusions.
3. Workspace Discovery Fix: Foreign clones and runtime worktrees are excluded from package discovery. On the verification checkout, package count dropped from 502 to 3, eliminating reproduced ENOBUFS buffer errors.
4. Adapter & MCP Alignment: All six adapters honor custom entrypoints and prefer skill.v2.yaml. Manifestless local skills hash and load correctly. MCP context assembly preserves complete instruction bodies and reports sources, hashes, omissions, and budget overflows.
5. Safe Read-Only MCP Inspection: Default status and workspace inspection avoid creating sessions, agents, or worktrees. Execution and filesystem mutations remain opt-in experimental.
6. Verified Upgrade & Rollback: Upgrade from core 2.2.0 / MCP 0.3.1 and checkpoint rollback verified across Windows, Linux, and macOS. On the tested migration fixture, all 325 configuration files restored cleanly while preserving user rules.

Calibration Benchmarks (GPT-6.1 Sol / high reasoning)

• Compact selection was 32.2% cheaper than full instruction injection ($0.76 vs $1.12) with 71.8% fewer input tokens.
• Compact selection was 35.0% more expensive than vanilla prompts without instructions ($0.76 vs $0.56).
• Accuracy: All variants resolved 60/60 test cases with no measured quality advantage (ceiling effect on this regression corpus).

Release Governance & Boundaries

• Already in 2.2.0: 36 catalog skills, stack presets (--preset), CLI and offline distribution.
• Not in 2.3.0: AST graphs and multi-agent swarm orchestration.
• Publication Process: Sequential publication of both packages with automated retry and safe recovery after partial releases. Post-release acceptance verifies clean installation, upgrade, and rollback from the public npm registry across Windows, Linux, and macOS.

v2.2.0 - Terminal Visual Layer, Stack Presets & Offline Catalog Distribution

ContextOS v2.2.0: Terminal Visual Layer, Stack Presets & Offline Catalog Distribution

ContextOS 2.2.0 delivers a major developer experience (DX) upgrade: a zero-dependency interactive terminal visual layer, stack presets, batch installation, Levenshtein typo suggestions, and autonomous offline distribution of all 36 catalog skills directly within consumer projects.

What's New in v2.2.0

1. Terminal Visual Layer (bin/lib/ui.js)

• ASCII Brand Banner & Status Badges: Clean branded terminal experience for init and installer flows.
• Strictly Aligned 4-Step Stepper: Replaced disjointed log outputs with an aligned progression grid ([1/4] through [4/4]), clear sub-explanations, and uniform indentation.
• Dynamic Progress Bar: Built-in renderProgressBar with automated TTY width detection and ANSI escape stripping for crisp boxed borders.
• Pixel-Perfect Success Card: Replaces unstructured terminal dumps with a single summary card displaying immediate next steps, profile switching, and export commands.

2. Autonomous Offline Catalog Distribution

• Direct Catalog Distribution: Consumer init now packages the 36-skill catalog (.agents/catalog/skills, 326 KB) directly into consumer projects.
• Complete Offline Autonomy: Consumer projects can browse (contextos skill list --available) and install (contextos skill add <name>) domain skills without requiring internet connectivity or global npm caches.

3. Stack Presets & Bulk Installation

• Init Presets (--preset <name>):
  • frontend: react, react-best-practices, nextjs, typescript, ui-ux-pro, impeccable-design, state-management, web-accessibility
  • backend: system-design, api-design, node, fastapi, nestjs, database, ddd
  • devops: docker, ci-cd, terraform, security-audit, performance
  • full: installs all 36 catalog skills
• Bulk Installation Flag (--all):
  • contextos init --all and contextos skill add --all install all catalog skills in a single atomic pass with an interactive progress bar.

4. Levenshtein Typo Suggestions

• Fuzzy matching on misspelled skill names automatically guides developers (e.g. contextos skill add reat -> suggestions: react).
• Built-in skills guide developers toward contextos skill override <name> if they attempt to shadow core skills.

---

Verification & Test Evidence

• Test Suite: 482 passing unit and integration tests across 111 suites.
• Catalog Validation: 36 catalog skills validated with 0 errors and 0 warnings.
• Secrets Audit: 654 files scanned, zero secrets or credentials detected.
• Cross-Platform Compatibility: Validated on Windows (PowerShell/cmd) and POSIX shells.

v2.1.1 - Fail-Closed Governance Hardening & Catalog Distribution

ContextOS v2.1.1 - Fail-Closed Governance Hardening & Catalog Distribution

ContextOS 2.1.1 delivers critical governance hardening, supply chain integrity, full catalog distribution in the npm package, and clean checkout execution.

What's Changed in v2.1.1

Supply Chain & NPM Distribution

• Full Catalog Distribution: Included catalog directory in npm package distribution (package.json files field), allowing consumer projects to install all 36 catalog skills directly from the unpacked package without requiring a repository clone.
• Catalog Source Precedence: Built-in package catalog skills take strict precedence over consumer project files, preventing local workspace files from hijacking catalog installations. Local skills require an explicit local: or path reference.
• Package Size Verification: Total unpacked package size is strictly bounded at 1.30 MB (well below the 2.00 MB budget target), with a compressed tarball size of 396 KB across 303 files.

Security & Fail-Closed Governance

• Strict Exit Code Contract: Standardized exit codes across scan and gate: all reading, git, or configuration failures return code 2 with explicit diagnostics in both enforce and advisory modes; code 0 is returned strictly when verification completes cleanly with no blocking violations; code 1 is returned on blocking violations.
• Literal Git Pathspecs & Diff Isolation: Added --literal-pathspecs, -c core.quotepath=false, --no-ext-diff, and --no-textconv to staged git diff and blob inspections, eliminating filename regex fragility and supporting paths with spaces, Unicode, and glob characters.
• Pre-Commit Hook Safety & Trusted Local Runner:
  • Automatically migrates existing trailing hook blocks from v2.1.0 to execute immediately after the shebang before any user exit 0.
  • Added strict shell shebang validation, rejecting non-shell interpreters (python, node) with exit code 1.
  • Resolves local executable via ./node_modules/.bin/contextos or source repository runner, eliminating unpinned PATH binary fallbacks.
  • Preserves exact scanner exit codes (including code 2 for infrastructure/unverified errors) rather than coercing to code 1.
• Cross-Repository Scan Targeting (--project): Added --project <path> support to contextos scan, enabling inspection of external target Git repositories from a central runner.

Core Adapters & Clean Checkout Parity

• Self-Contained MCP Selector Resolution: Resolver parity tests now dynamically compile the TypeScript selector in-memory when gitignored dist is absent, guaranteeing clean checkout compatibility without pre-build requirements.
• CLAUDE.md Demarcation & Idempotency: Claude Code adapter now generates CLAUDE.md with explicit <!-- CONTEXTOS:START --> and <!-- CONTEXTOS:END --> demarcation, preserving user preamble, custom guidelines, and ensuring idempotent re-exports.
• Dual-Root Profile Discovery: Extended dual-root contract to profiles.js (listProfiles and getProfile), enabling consumer projects to define custom profiles that are seamlessly discovered across all CLI and compiler entrypoints.
• Skill Examples Verification Engine: Replaced vm.Script with esbuild.transformSync (for TypeScript/TSX/ESM JavaScript) and Python AST parsing in scripts/verify-skill-examples.js, with syntax validation explicitly separated from behavioral runtime checks.
• CLI Robustness & Documentation Alignment: Restored audit proxy command (as an alias for validate), added rejection with exit code 1 for unknown commands, supported comma-separated --target cursor,claude, updated action examples to v2.1.1, and protected .aider.conf.yml against malformed YAML overwrites.

v2.1.0 - Expanded Catalog, In-Process Quality Gate & Staged Scanner

ContextOS v2.1.0 - Expanded Catalog, In-Process Quality Gate & Staged Scanner

ContextOS 2.1.0 delivers a major expansion to the open skills catalog, full troubleshooting diagnostics, and pre-commit security governance tools.

What's New in v2.1.0

4 New Industry Catalog Skills

• security-audit: In-depth vulnerability scanning, SAST/DAST automation, dependency checking, privilege escalation prevention, and SAIF/CIS benchmark mapping.
• api-design: Deterministic API design guidelines, RESTful contracts, idempotent operations, cursor pagination, rate limiting, and OpenAPI specifications.
• terraform: Infrastructure as Code (IaC) governance, remote state locking, plan review quality gates, least-privilege provider blocks, and OpenTofu compatibility.
• ci-cd: GitHub Actions hardening, matrix test workflows, supply chain artifact signing, branch protection rules, and build caching strategies.

Catalog Hardening & Troubleshooting

• Catalog Diagnostic Guides (TROUBLESHOOTING.md): Added structured troubleshooting guides across all 36 catalog skills covering root causes, concrete code fixes, and verification steps.
• Design Style Code Implementations (EXAMPLES.md): Added production-ready TypeScript/Tailwind component examples to minimalist-design, brutalist-design, and soft-design.
• Playwright End-to-End Testing: Enriched testing skill with comprehensive Playwright E2E testing scenarios, fixtures, mock routes, and cross-browser CI configurations.
• Catalog Sanitation: Removed 13 redundant legacy markdown files across catalog skills to enforce single-source-of-truth standards.

Security & Quality Gate Tooling

• Staged Git Index Security Scanner (contextos scan): Fast, in-memory scanner inspecting git diff --cached for leaked API secrets, credential patterns, unfinished lazy stubs (// TODO), and task write-scope containment.
• Isolated Pre-Commit Git Hooks (contextos hook install): Safe hook manager installing isolated ContextOS pre-commit verification blocks without overwriting or interfering with existing user hooks.
• Quality Gate Engine (contextos gate): Deterministic, in-process drift verification engine checking managed outputs against source skills without disk mutation.
• GitHub Composite Action (.github/actions/contextos-gate): Security-hardened CI action running from a pinned package version without executing consumer build scripts or npm test.
• Adapter Compatibility Contracts: Comprehensive specifications and verified test contracts for Cursor, Claude Code, GitHub Copilot, Gemini CLI, Aider, and Zed.
• Self-Documenting CLI: Updated contextos --help command registry to include scan, hook, recover, and explain.

v2.0.0 — Stable Core Context Compiler

ContextOS v2.0.0

Changed (Breaking)

• Minimum supported Node.js version is now 22. Node.js 18 and 20 have reached end of life.
• Product Repositioning: ContextOS is now explicitly positioned as an Agent Context Governance tool (a deterministic context compiler), shifting away from 'Autonomous AI Swarm' messaging.
• Distribution Boundary: The ContextOS MCP server and execution runtime are no longer bundled within the core \contextos-agents\ package. They will be distributed separately via the @contextos/mcp\ package.
• CLI Deprecation: The --with-mcp\ and \setup-mcp\ flags in the \contextos init\ command are deprecated and now serve only as a warning/redirect to the new package.
• Catalog Boundary: The default installation profile has been reduced to a 'Neutral Bootstrap' (core workflow, context management, security).

Added

• Migration Commands: Added \contextos profile prune\ to safely remove optional skills that are no longer part of the default profile.
• Boundary Documentation: Added \docs/PRODUCT_BOUNDARIES.md\ and \docs/MIGRATION.md.

Removed

• Unverified benchmark marketing claims regarding token reduction percentages have been removed until the reproducible Benchmark v2 suite is finalized.

v2.0.0-beta.2

Full Changelog: v2.0.0-beta.1...v2.0.0-beta.2

v2.0.0-beta.3 — Stabilization Release

ContextOS v2.0.0-beta.3 — Stabilization and Packaging Hardening

This release focuses on packaging integrity, runtime stability, and production-readiness ahead of the stable v2.0.0 launch. It resolves tarball distribution gaps, hardens CLI diagnostics, synchronizes skill manifests, and refines customization workflows.

---

Key Highlights and Improvements

1. Production Packaging and Tarball Integrity

• Complete distribution bundle: Added .agents/resolver and .agents/rules to package.json package manifest, preventing MODULE_NOT_FOUND errors when installing fresh from npm or tarball.
• Automated Tarball Smoke Testing: Introduced end-to-end integration tests (tests/tarball-smoke.test.js) verifying the entire cycle: npm pack -> unpack -> project initialization -> context resolution, compilation, and validation.

2. Runtime and Doctor Hardening

• Isolated CLI diagnostics (contextos doctor): Removed fallback to host app versions, ensuring strict dependency checking. Added runtime execution gates for CanonicalResolver, RuleCatalog, and ManifestCompiler with non-zero exit codes on module failure.
• Graceful Thread handling: Replaced direct runtime dependency crash in contextos thread with an informative guide pointing to @contextos/mcp.
• Modern MCP setup guide: Deprecated contextos setup-mcp hint replaced with direct npm package guidance (npm i -D @contextos/mcp).

3. Core Manifest and Skill Sync

• Clean Skill Index: Pruned phantom catalog entries in skills-index.json, leaving exactly the 7 bundled core skills available out-of-the-box.
• Deterministic Stats: Removed hardcoded fallbacks in stats.js to report strictly verifiable, on-disk skill counts.
• AGENTS.md Availability Guards: Clear architectural separation between Core (7 bundled) and Extended Catalog skills with automatic routing guards.

4. Customization DX and Plugin Security

• Smart Security Filter: Fine-tuned plugin linter regexes to prevent false-positive security warnings on documentation examples, persona definitions, and harmless base64 strings.
• Dynamic Cursor Adapter: Cursor configuration exports now dynamically extract file glob patterns directly from skill.yaml.
• Customization CLI Tools: First-class support for contextos customize subcommands: override, eject, and diff.

---

Verification and Quality Gates

All automated verification pipelines are passing:

• Unit and Integration Tests: 369/369 tests passed across 90 suites
• Rule and Skill Validation: 0 errors, 0 warnings (node .agents/ctx.js validate)
• Documentation and Linting: 0 markdown violations (npm run lint:md)
• Secret Scanner: 0 findings across 659 repository files (check:secrets)
• ContextOS Benchmark v2: 30 benchmark tasks across 4 arms executed with 100% completion rate

---

Quick Install / Upgrade

# Global installation
npm install -g contextos-agents@2.0.0-beta.3

# Local project installation
npm install --save-dev contextos-agents@2.0.0-beta.3

# Run health check
npx contextos-agents doctor