koko-contextos-agents

This is an open-source set of skills and behavioral rules for AI assistants. The package automatically installs an .agents folder into your project, teaching your AI assistant software development best practices (UI Design, Architecture, Security, and more).

Installation

You do not need to clone anything manually. Just open your terminal in the root of your project and run:

npx koko-contextos-agents

The script will automatically detect your project tech stack, create the .agents folder, configure skills, and compile them for your AI agent.

Options

npx koko-contextos-agents --help          # Show all options
npx koko-contextos-agents --version       # Show version
npx koko-contextos-agents --profile mvp   # Install with specific profile (mvp, startup, enterprise, frontend, backend)
npx koko-contextos-agents --auto          # Auto-detect tech stack and apply recommended profile
npx koko-contextos-agents --dry-run       # Preview what will be installed
npx koko-contextos-agents --force         # Overwrite an existing .agents/ folder
npx koko-contextos-agents --skip-compile  # Skip auto-compilation step

Why Use This? (Benefits)

• Save Tokens & Context: ContextOS prevents prompt bloat by generating scoped, modular rules (e.g., .cursor/rules/*.mdc with file-pattern matching), compact index templates, and dynamic skill resolution (node .agents/ctx.js resolve) so assistants load only the relevant domain rules.
• Superior Code Quality: Pre-configured skills guide the AI to follow modern design patterns (DDD, microservices) and professional UI standards (no pure black colors, semantic palettes) rather than generic internet code.
• Save Time: Stop writing massive system prompts or arguing with the AI. The assistant instantly knows your architectural decisions and coding standards from the start.

Project Profiles & Stack Auto-Detection

ContextOS allows you to tailor your AI rules to the project lifecycle and architecture:

Profile Commands

# Auto-detect tech stack in the current project
node .agents/ctx.js detect

# List available profiles and current active profile
node .agents/ctx.js profile list

# Apply a profile
node .agents/ctx.js profile apply mvp

# Recompile all agent exports for the active profile
node .agents/ctx.js export all

What's Inside?

Master Orchestrator

• AGENTS.md — The core ruleset. Automatically routes skills by task type and technology detected in your codebase.

Skills (39 total)

Slash Command Workflows

ContextOS maps development phases directly to slash commands in your AI chat:

Dynamic Skill Resolution & CLI (ctx.js)

The .agents/ctx.js file is the Context Engine — it resolves minimal skills on the fly and compiles exports for AI assistants.

Dynamic Skill Resolution (resolve & index)

To prevent context bloat, ContextOS dynamically resolves the exact 2–4 skills needed for any prompt or file:

# Resolve skills for a task description (English):
node .agents/ctx.js resolve "Build an accessible modal component with React and Tailwind"

# Output:
# [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
# Skills loaded: ponytail-mindset, engineering-workflow, react, ui-ux-pro, web-accessibility

# Multilingual support (Russian):
node .agents/ctx.js resolve "создай модальное окно авторизации и напиши юнит-тесты"

# Output:
# [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
# Skills loaded: ponytail-mindset, engineering-workflow, react, ui-ux-pro, security, testing

# Resolve skills based on active files:
node .agents/ctx.js resolve --files "app/api/auth/route.ts"

# Generate/update progressive lightweight skills index:
node .agents/ctx.js index

# Clean up lingering .swarm-worktrees directories and orphaned swarm/* git branches:
node .agents/ctx.js clean-worktrees

Supported Agents & Compilation

node .agents/ctx.js export all       # Compile for all agents
node .agents/ctx.js export gemini    # Compile for Gemini / Antigravity
node .agents/ctx.js export claude    # Compile for Claude Code
node .agents/ctx.js export cursor    # Compile for Cursor (.cursor/rules/*.mdc)
node .agents/ctx.js export copilot   # Compile for GitHub Copilot
node .agents/ctx.js export aider     # Compile for Aider
node .agents/ctx.js export zed       # Compile for Zed IDE

Pre-Compiled Artifacts & Git Architecture

ContextOS commits generated adapter configurations (.cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md, .aider.conf.yml, CONVENTIONS.md, .zed/rules.md) directly into Git:

• Zero-Build Onboarding: AI assistants (Cursor, Claude Code, GitHub Copilot, Zed, Aider) activate instantly upon repository clone without requiring npm install or separate build steps.
• Git-Native Context: Assistant engines index project rules using native file matchers and git tree walking without depending on background daemon processes.
• Automated Sync & Drift Prevention: CI strictly validates that generated exports match source skills (node .agents/ctx.js validate). Any uncommitted adapter drift fails CI checks via git diff --exit-code.
• Contributor Workflow: Source rules are authored exclusively in .agents/core/skills/<name>/SKILL.md. Running node .agents/ctx.js export all regenerates all assistant configurations deterministically.

Plugin Skills & Validation

You can expand your .agents folder with community plugins or validate your own custom skills using the top-level commands:

# Launch the interactive skill installer to browse and install community skills
npx koko-contextos-agents install-skill

# Or install a specific skill from a GitHub repository automatically
npx koko-contextos-agents install-skill --from-repo kok-o/awesome-skill

# Validate your local skills (checks frontmatter, dependencies, and sync)
npx koko-contextos-agents audit

ContextOS MCP Server & Autonomous Multi-Agent Swarm

ContextOS includes a standalone Model Context Protocol (MCP) execution server located in contextos-mcp/ and bundled as .agents/mcp/server.mjs. It allows orchestrator agents (like Antigravity, Claude Code, or Cursor) to safely delegate coding tasks to parallel subagents running in isolated Git worktrees.

MCP Server Configuration

Add ContextOS to your IDE's MCP settings (e.g. in .agents/mcp_config.json):

{
  "mcpServers": {
    "contextos": {
      "command": "node",
      "args": [
        "./.agents/mcp/server.mjs",
        "--dir",
        "."
      ]
    }
  }
}

Exposed MCP Tools

Enterprise Architecture Guarantees

• Git Worktree Sandboxing: Each subagent operates in a private git worktree (.swarm-worktrees/). The developer's active workspace cannot be corrupted by experimental changes or failing tests.
• Disk-Backed Session Persistence: Active and completed threads are recorded in .swarm-worktrees/session-state.json. If the MCP process is restarted, tasks and diffs can be recovered without losing work.
• Automated In-Worktree Verification (verify_command): Runs test commands (npm test, cargo test, pytest) inside the isolated worktree before marking tasks as successful.
• Context Token Compression: The server extracts essential rules, constraints, and checklists (extractEssentialSkillContent), eliminating verbose samples and reducing prompt overhead.

Testing

Tests use the Node.js built-in test runner for the core framework and Vitest for the MCP engine — zero external test bloat.

1. Root Test Suite (121 tests)

npm test

# tests 121
# suites 27
# pass  121
# fail  0

2. MCP Server Test Suite (428 tests)

cd contextos-mcp && npm test

Test Files  24 passed (24)
     Tests  428 passed (428)

Test coverage:

• tests/install.test.js — installer CLI flags (--help, --dry-run, --force)
• tests/export.test.js — ctx.js export for gemini, claude, cursor (.mdc rules), copilot, aider
• tests/skills.test.js — validates all skill source files and frontmatter
• tests/profile.test.js — profile resolution, stack auto-detection, and skill filtering
• tests/validate.test.js — validator rules, dependency graph, and sync checks
• tests/plugins.test.js — plugin lockfile, registry fetching, and security checks
• tests/resolver.test.js — dynamic skill resolution, progressive index, and bilingual prompt matching
• tests/benchmark.test.js — benchmark scoring engine, static AST checks, runtime sandbox, and reporters
• contextos-mcp/tests/unit/session-persistence.test.ts — session disk persistence, thread state tracking, and orphan purge
• contextos-mcp/tests/unit/contextos-tools.test.ts — all 6 MCP tool handlers and validation

Benchmark: With Skills vs. Without Skills

The repository includes a paired, reproducible code-quality benchmark suite supporting OpenAI (GPT-4o, GPT-5, o1, o3-mini), Google Gemini, Anthropic Claude, and custom gateways (AgentRouter, OpenRouter).

The benchmark evaluates real-world code quality, security vulnerabilities, timing attacks, ARIA accessibility contracts, DDD business invariants, and error isolation between baseline LLMs and ContextOS-assisted agents.

Live Benchmark Execution

# 1. Run live benchmark with OpenAI (GPT-4o, GPT-5, o3-mini):
set OPENAI_API_KEY=sk-...    # PowerShell: $env:OPENAI_API_KEY = "sk-..."
npm run benchmark:live -- --provider openai --model gpt-4o

# 2. Run live benchmark with Google Gemini:
set GEMINI_API_KEY=...       # PowerShell: $env:GEMINI_API_KEY = "..."
npm run benchmark:live -- --provider gemini --model gemini-2.5-flash

# 3. Run live benchmark with Anthropic Claude:
set ANTHROPIC_API_KEY=...    # PowerShell: $env:ANTHROPIC_API_KEY = "..."
npm run benchmark:live -- --provider anthropic --model claude-3-7-sonnet-20250219

# 4. Run with custom OpenAI-compatible router (OpenRouter, AgentRouter, Local vLLM):
node benchmarks/run-live-benchmark.js --base-url "https://agentrouter.org/v1" --api-key "sk-..." --model "gpt-5.6-sol" --open

Execution-Backed Runtime Benchmark (Real Sandbox Test Assertions)

In addition to static checks, ContextOS features an execution-backed runtime benchmark suite. It compiles model-generated code in an isolated Node.js V8 sandbox (node:vm) and runs rigorous behavioral unit assertions (node:assert):

# 1. Run runtime benchmark with OpenRouter (Google Gemini 3.8 Flash):
node benchmarks/run-runtime-benchmark.js --base-url "https://openrouter.ai/api/v1" --api-key "sk-or-v1-..." --model "google/gemini-3.8-flash" --open

# 2. Run runtime benchmark with AgentRouter (GPT-5.6-sol):
node benchmarks/run-runtime-benchmark.js --base-url "https://agentrouter.org/v1" --api-key "sk-..." --model "gpt-5.6-sol" --open

# 3. Run specific scenario (auth-security, ddd-order-invariants, or resilient-api-client):
npm run benchmark:runtime -- --base-url "https://agentrouter.org/v1" --api-key "sk-..." --model "gpt-5.6-sol" --task auth-security

Evaluation Methodology

Submissions are evaluated using a strict, multi-stage verification pipeline:

1. Sandboxed V8 Runtime Execution (Primary Ground Truth): Compiles TypeScript into CommonJS via native AST type stripping (node:module.stripTypeScriptTypes) and executes in an isolated sandbox with timeout and assertion checks (node:assert).
2. Behavioral Invariant Testing: Stress-tests timing attacks (crypto.timingSafeEqual), brute-force IP/Account rate-limiting, error stack redaction, immutable Value Objects, domain event dispatch, and circuit breaker state transitions.
3. Deterministic Static Analysis: AST verification checking for zero ORM/HTTP transport leakage in domain layers and contract compliance.

Production Scenarios Evaluated

The runtime sandbox evaluates model outputs against real-world engineering invariants:

Running Benchmarks Locally

You can run the benchmark suite locally with your own API keys:

# Run runtime sandbox benchmark with Google Gemini:
$env:GEMINI_API_KEY = "your-key"
npm run benchmark:runtime -- --provider gemini --model gemini-2.5-flash

# Run with OpenAI:
$env:OPENAI_API_KEY = "sk-..."
npm run benchmark:runtime -- --provider openai --model gpt-4o

When executed, reports are generated in benchmarks/results/ (.html, .md, .json). These run outputs are kept in your local directory (git-ignored) to keep the repository clean.

Contributing

We are open to pull requests! See CONTRIBUTING.md for a step-by-step guide on how to add a new skill.

Quick start:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingSkill)
3. Add your skill in .agents/core/skills/<name>/SKILL.md
4. Run npm test — all tests must pass
5. Commit your changes (git commit -m 'feat: add AmazingSkill')
6. Push and open a Pull Request

License

Distributed under the MIT License. You can freely use, modify, and distribute this code.