cto-legends · module specification · foundation · v0.2.5
cto-legends: Single-Skill Agent Router & Isolated CLI Module Manager
Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.
GitHub Repository (https://github.com/avalonreset/cto-legends) · Handoff: cto-legends capabilities --markdown
cto-legends is the open-source Python 3.11+ standard-library capability router and release manager for the Legends engineering ecosystem. Instead of registering a separate skill or persistent Model Context Protocol (MCP) server for every tool, an operator registers a single unchanging skill (cto_legends/SKILL.md) and connects a content-addressed startup capability index to their coding host (Claude Code, OpenAI Codex, Gemini CLI, Google Antigravity, Cursor, Windsurf, Grok, Aider, or MetaMuse). When a task matches an outcome in the index, the agent resolves only that module's installed Markdown recipe on demand via cto-legends handoff <module>.
Under the hood, cto-legends separates static discovery from isolated runtime execution. Every catalog entry in cto_legends/catalog.json (v1.0.33) binds a public repository, release version, immutable Git commit hash, codeload archive SHA-256 digest, and a closed-vocabulary install/probe/run recipe that never executes arbitrary shell strings from catalog metadata. Managed Python modules are unpacked into dedicated virtual environments under ~/.cto-legends/releases/<module>/<version>-<hash>/ and must pass offline readiness probes before state.json atomically switches the active pointer.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Loading 15+ persistent MCP servers or standalone skill directories into an agent at Turn 0 consumes tens of thousands of context tokens and causes routing collisions across overlapping tool descriptions. Worse, asking a raw LLM in a browser window to install and run arbitrary GitHub tools results in unpinned git clones, global Python dependency pollution, unverified archive downloads, and hallucinated CLI flags.
- Closed-Vocabulary Recipe Engine & SHA-256 Archive Pinning: Every module release in catalog.json is pinned to an immutable commit and verified against a SHA-256 archive checksum before extraction. The manager engine interprets only hardcoded installation and probe primitives (import checks, module-cli doctor runs, file existence, and unittest gates) and rejects unsafe archive members.
- Atomic Per-Module Virtual Environments & Rollback: Each managed Python module receives its own isolated virtual environment at its final release path while holding an exclusive operation.lock. Failed probes leave state.json untouched, and cto-legends rollback <module> --apply swaps back to a retained previous environment after re-probing its health.
- Zero-Latency Local Routing with Bounded Remote Catalog Peek: Local route and handoff queries read the active local catalog first with zero network overhead. Only when a local lookup returns no_match or targets a newly released module does the router perform a read-only, schema-validated peek of the canonical upstream catalog and report whether cto-legends sync will unlock the capability.
CLI Subcommands & Capability Surface
cto-legends capabilities --markdown / cto-legends handoff <module> / cto-legends route "<goal>" — On-Demand Capability Discovery & Recipe Handoff: Outputs the live outcome-based capability index with examples, setup prerequisites, and explicit not_for exclusions so the agent selects by user outcome rather than guessing tool names. Running handoff <module> resolves the active release path, required instruction files, and isolated Python or Node runtime without loading unselected modules into context.cto-legends install <module> [--apply] — Preview-First Isolated Module Installation: Previews the exact catalog version, commit pin, SHA-256 digest, and dependency requirements offline by default. When --apply is explicitly passed, the manager acquires operation.lock, verifies the downloaded archive against its SHA-256 pin, builds an isolated virtual environment under releases/, executes the module's offline probe suite, writes receipt.json, and atomically updates state.json.cto-legends check-updates / cto-legends sync [--apply | --rollback] / cto-legends update [--apply] / cto-legends rollback <module> [--apply] — Catalog Drift Detection, Sync & Environment Rollback: Compares installed module versions, the active local catalog, and upstream releases without modifying disk state. Operators can preview and adopt new catalog pins via sync --apply (preserving catalog.previous.json for sync --rollback), upgrade installed modules via update --apply, or toggle a module back to its retained prior virtual environment via rollback --apply.cto-legends agent-setup <host> [--apply] / cto-legends startup-setup <host> [--apply] / cto-legends agent-audit <host> / cto-legends isolate-skills <host> [--apply] — Host Skill Registration, Startup Wiring & Skill Isolation: Registers the single canonical SKILL.md router across Codex, Gemini, Antigravity, Claude, Cursor, Grok, MetaMuse, Windsurf, and Aider while preserving user edits and appending optional skill-local.md house rules. Connects a reversible content-addressed capability index pointer into host startup instructions with a checked startup-restore manifest, and consolidates legacy standalone module skills into a restorable backup.cto-legends doctor / cto-legends task-readiness [all|research|geogrid|...] / cto-legends report-readiness — Offline Environment Doctor & Task-Readiness Preflight: Executes offline probe recipes across all active module installations and reports optional host binaries (node, pnpm, gh) without making paid provider API calls. Separate task-readiness and report-readiness commands verify downstream task prerequisites such as map browser binaries, PDF report libraries, provider credential presence, and reusable evidence support before live work begins.cto-legends run <module> -- <args> / cto-legends guide <module> / cto-legends register-guide <name> <path> [--apply] — Isolated Module Execution & Guided Native Handoffs: Dispatches CLI arguments directly to a module's isolated Python interpreter or Node runtime while preserving the caller's working directory so generated artifacts stay in the user's workspace. For native desktop applications such as legends-hyperyap, guide <module> returns pinned release assets, platform requirements, and SHA-256 checksums without falsely claiming a managed CLI installation.
Raw Frontier LLM vs. cto-legends Execution Matrix
- Turn-0 Context Footprint & Tool Discovery: Raw LLM (Loads 15+ persistent MCP server schemas or dozens of standalone skill files at startup, burning 30,000+ tokens before the user types a prompt.) vs. Module (Registers one frozen SKILL.md router and a compact content-addressed startup index; loads only the selected module's Markdown recipe on demand via cto-legends handoff.) — cto-legends startup-status <host> and cto-legends agent-audit <host> verify exact startup index hashes and visible skill roots.
- Supply-Chain Pinning & Archive Verification: Raw LLM (Runs unpinned git clone or pip install commands from main branches without commit verification or archive hash checks.) vs. Module (Every catalog.json entry binds an exact version, immutable Git commit, SHA-256 archive hash, and closed-vocabulary probe recipe; byte mismatches fail closed.) — validate_catalog() schema validation plus receipt.json SHA-256 and probe verification inside each release directory.
- Python Dependency & Runtime Isolation: Raw LLM (Installs conflicting packages into the system or workspace Python environment, breaking existing project dependencies.) vs. Module (Builds an independent virtual environment per module and version under ~/.cto-legends/releases/<module>/<version>-<hash>/venv.) — cto-legends status and cto-legends doctor run every module's probe array inside its own isolated interpreter.
- Upgrade Safety & Environment Rollback: Raw LLM (In-place package upgrades overwrite working environments with no atomic state pointer or rollback path when a release breaks.) vs. Module (Retains previous release directories and catalog.previous.json; state.json updates only after all probes pass, and rollback swaps back after re-probing.) — cto-legends rollback <module> and cto-legends sync --rollback preview and restore prior verified states.
- Cost, Credential & Mutation Governance: Raw LLM (Implicitly triggers paid API calls, writes files during setup, or stores API tokens inside prompt files and CLI arguments.) vs. Module (All mutating CLI commands preview by default until --apply is passed; install and doctor never collect credentials or invoke paid provider endpoints.) — Preview JSON payloads ("preview": true) and offline-only probe execution enforced by cto_legends/manager.py.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Do I need to upgrade cto-legends or re-register my agent skill when a new module is released?
- No. The registered skill (cto_legends/SKILL.md) is frozen and names no specific modules. When a new module or version is added to the upstream catalog, cto-legends route and cto-legends handoff detect it via a read-only remote catalog peek and prompt you to run cto-legends sync --apply and cto-legends update --apply.
- Does installing cto-legends download all 18 modules onto my workstation?
- No. Installing cto-legends installs only the standard-library Python router and the bundled catalog seed. Individual modules and their isolated virtual environments are downloaded and built only when you explicitly run cto-legends install <module> --apply.
- How does cto-legends handle native desktop applications versus managed Python/Node CLIs?
- Seventeen catalog modules use managed CLI installations with isolated runtimes and offline readiness probes. Native desktop applications (such as legends-hyperyap) use guided mode: cto-legends guide <module> returns pinned release downloads, platform requirements, and SHA-256 asset checksums without running an OS installer or claiming the app is installed in state.json.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.