stolz-ai

Rational skills for Codex and compatible AI coding agents. No token wasted.

English · Русский · Nederlands · 中文 · עברית

Quick install

Paste this one-line request into Codex or Claude Code on Windows, macOS, or Linux:

Install all STOLZ A.I. skills and their reference files for yourself from https://github.com/Sergey360/stolz-ai/releases/latest. Verify the archive's SHA-256, use your user-level skills directory, preserve existing skills, and verify the installation.

After installation, open a new agent session. Manual installation and team setup.

In v0.15, stolz-quiet-state also covers handing off external work and continuing the original task after verification. Its conditional reference retains the goal, operation and watcher identity; the optional Codex Desktop adapter documents heartbeat fallback and its model overhead. Installation does not create a scheduler or promise automatic resumption.

STOLZ A.I. keeps agent work focused: choose the smallest sufficient route, load context only when needed, reuse verified results, and keep unchanged state outside the model.

It does not make a model think less. It helps it waste less—without replacing correctness, verification, or reliability with a cheaper shortcut.

The package contains five optimization skills, optional instruction-security, source-analysis and browser-workflow skills, profiles, lazy adapters, evidence records, and one opt-in local Codex state entry point. Installing skills does not start a daemon, shared cache, durable state store, or automatic polling controller. Local state exists only after an application explicitly opens it.

Andrei Ivanovich. Artificial intelligence.

The name refers to Andrei Ivanovich Stolz, the rational and active counterpoint to Oblomov in Ivan Goncharov's novel. A.I. carries both meanings: the character's initials and artificial intelligence.

What stays under control

• Nine focused skills. Guard, evidence, browser and MCP are installed separately.
• Verified reuse. Reuse requires matching, fresh identities and prior verification.
• Safe fallbacks. A missing capability never weakens the required outcome or checks.

One task. One route. Verified.

Choose a known concern directly: context, reuse, quiet state, benchmarking, instruction-security review, or source-based analysis. stolz-route helps when that choice is unclear. Ordinary coding needs no STOLZ route. Each selected skill loads its detailed rules only when needed and keeps the required verification before the outcome.

The five core skills

stolz-route — choose a route

Use it when the optimization concern or adapter fallback is unclear.

stolz-context — validate existing context evidence

Use it when an existing STOLZ context manifest or read-ledger entry must be validated for trust, provenance, or invalidation. An ordinary first read does not trigger it.

stolz-reuse — reuse verified results only

Use it only when a prior result or identical in-flight command actually exists. It admits only verified, identity-matched results; otherwise it runs and verifies once.

stolz-quiet-state — report meaningful changes

Use it to suppress duplicate wakes from repeated operation snapshots. Durable cursor, retry and notification decisions keep unchanged state outside the model.

stolz-benchmark — compare equivalent routes

Use it to evaluate a proposed efficiency improvement. It accepts a comparison only after equivalent outcome and verification gates pass.

Optional instruction-security review

Version 0.16.0 adds stolz-guard. Use it to audit a prompt or review a concrete untrusted instruction before acting on it. It checks injection, sensitive disclosure, action authority and persistent-context abuse, with redacted evidence and a scoped continuation. It respects existing user authorization and loads detailed rules only when needed. Ordinary source reads do not trigger it.

The v0.19.0 package contains nine skill directories. Managed optimization profiles still install five skills; install guard separately using the manual instructions. A review does not enforce tool permissions or guarantee attack detection.

Quick start

Clone a tagged or reviewed revision, then validate it before copying the skill you need into your agent runtime's skills directory.

git clone https://github.com/Sergey360/stolz-ai.git
cd stolz-ai
npm ci
npm test

# Example: install the routing skill into a runtime-managed skills directory.
mkdir -p /path/to/agent-skills
cp -R skills/stolz-route /path/to/agent-skills/stolz-route

The v0.13 public archive also provides the stolz-profile CLI for a managed project setup. It creates a reviewed team lock, makes CI fail on drift, reports runtime and lazy-adapter compatibility separately, and supports transactional update, interrupted-update recovery, and rollback. The same archive includes the setup guides and an executable clean-consumer smoke; no private repository is required.

npm install --save-dev /absolute/downloads/stolz-ai-0.19.0.tgz
npx --no-install stolz-profile lock --apply --runtime codex --lockfile /absolute/project/stolz-profile.lock.json
npx --no-install stolz-profile verify-lock --runtime codex --lockfile /absolute/project/stolz-profile.lock.json

The documented validation surface is deliberately small:

npm test

Optional local Codex state

For one explicit, workspace-local path, an application can connect bounded context fragments, verified reuse, and quiet state. It has no provider client, background timer, or automatic model invocation. The caller supplies the identities, policy, verification, and each snapshot; a miss or unavailable component selects the normal verified route.

import { openCodexLocalState } from 'stolz-ai/codex-local-state';

const state = openCodexLocalState({
  enabled: true,
  workspace: '/absolute/path/to/workspace',
  max_storage_bytes: 8 * 1024 * 1024,
});
await state.initialize();

Read Installation and compatibility before integrating it. The state directory is local to the selected workspace; it stores private evidence locally and returns compact identities rather than raw logs or prompts.

For deterministic profile selection, dry-run/install commands, lazy-loading rules, lock verification, recovery, rollback, and removal, read Installation and compatibility.

Compatibility without overclaiming

The core skills are provider-neutral, but portability is not certification. The same five skills can be selected for Codex, Claude Code, and Qwen Code; profile resolution, adapter availability, runtime evidence, and provider evidence are separate claims.

STOLZ v0.7 contains exact-version C2 sanitized runtime-telemetry evidence for Claude Code 2.1.251 and Qwen Code 0.22.3. It does not transfer to a newer runtime version. Codex CLI 0.153.4 was exercised in four installed-local runs on the v0.7 release contour, but Codex has no v0.7 C2 row. C3 pair admission is implemented fail-closed; every current provider pair remains withheld because no complete comparable provider-export pair has been admitted.

Read the exact capability matrix before describing support. A missing or insufficient capability must select a safe fallback; it must never lower the required outcome or verification.

The v0.12 installed-skill diagnostic used Codex CLI 0.153.4 with gpt-5.6-sol at xhigh reasoning. Its untouched replacement held-out gate passed 23/24 strict routes, 24/24 required outcomes, and 24/24 permission decisions. The full 68-attempt report includes every failure and correction. This small diagnostic is not a universal accuracy, provider-token, cost, or savings claim.

v0.14 adds 40 bounded attempts against the byte-identical v0.13.0 archive on Codex CLI 0.154.0-alpha.6.2. All 20 pairs had equal outcomes and verification, but every tested Sol and Astra cohort used more comparable input-plus-output tokens and more wall time on the STOLZ route. The v0.14 summary publishes the exact tuples, overhead, unavailable fields, and claim boundary.

Evidence boundary

STOLZ A.I. documents mechanisms that can reduce waste, not a numerical saving claim. A published token-saving statement needs reproducible paired baseline/optimized evidence on the same versioned fixture, equivalent required outcomes, and passing verification for both routes. A lower-token run with a weaker outcome or failed verification is rejected—not counted as a saving.

The benchmarking guide separates fixture_only, runtime_measured, and provider-native evidence. It also records the mixed historical v0.4.1 result and the negative bounded v0.14 result. Neither proves a general saving or predicts larger real projects. See skills/stolz-benchmark/ for the admission rules.

Documentation

• Installation and compatibility
• Architecture and exact capability matrix
• Benchmarking and evidence interpretation
• Русский README
• Nederlands README
• 中文 README
• עברית README
• Contributing
• Security policy
• Release notes
• License and project notice

Contributing

npm test
npm run benchmark:check

Read Contributing before opening a change. License and legal notices are in LICENSE and NOTICE.

Evidence workflow in v0.17.0

Version 0.17.0 includes seven skills: five managed optimization skills, optional guard and optional stolz-evidence. Evidence separates actual reading scope, supported findings and unmet requirements, including corrections and handoffs. It uses existing context and reuse identities. It does not enforce truthfulness or guarantee activation. Install it separately; the optional project rule can retain the short procedure when the detailed skill is not selected.

Controlled browser workflow in v0.18.0

Optional stolz-browser guides tab reuse, ownership, sequential lifecycle operations and recovery decisions. It preserves the selected browser and necessary UI checks. Ordinary web search needs no browser workflow. The initial scope is Codex Desktop guidance; it adds no browser controller, crash-prevention guarantee or savings claim. Install the complete directory separately using the browser instructions.

MCP catalogs and code execution in v0.19.0

Optional stolz-mcp helps choose native deferred discovery or code execution for a concrete MCP optimization. The offline stolz-mcp CLI audits exact source bytes and builds a small index with individual definitions. stolz-ai/mcp-code wraps an existing authorized client, preserving exact tool names, explicit nulls and complete MCP results. Projection rejects errors and oversized summaries. It changes no MCP settings and makes no provider-token savings claim. Installation.