vaos-ai

Verified Agent Operating System. Plan, execute, verify — deterministic done-gates for coding agents.

Your AI agent says the task is done — vaos proves it. Zero dependencies. One command. Auditable evidence.

Why

75% of agentic AI tasks fail in production. Agents hallucinate completion, skip tests, and claim success without proof. Other tools let agents self-grade their work. VAOS adds an external, absolute deterministic constraint layer — no LLM-as-judge, just mathematical proofs that pass or fail.

🚀 What's New in v5.0: Dual-Agent Architecture & Biometrics

• Biometric OS-Level Handoff (vaos audit-agent): True Zero-Trust Asymmetry. The Executor Agent writes code; the Auditor Agent audits it. To prevent the Executor from forging a signature, vaos audit-agent physically halts the terminal process and forces a native macOS TouchID / Password prompt before the private.pem cryptography key is unlocked.

v4.0 Core Features

• True Zero-Trust Cryptography: Completely eliminates "Agent Omnipotence". The Human Architect mathematically signs plan constraints using asymmetric .pem keys.
• Air-Gapped Auditing (vaos audit): Agents are stripped of the ability to finalize tasks. Humans (or CI pipelines) run vaos audit to cryptographically prove requirements haven't been tampered with before execution.

v3.0 Core Features

• Constraint Locking: Agents are physically prevented from editing test requirements to hack a passing grade. Verification cryptographically links back to the original spawned plan.
• Deep LSP Validation (--lsp): Natively enforces abstract syntax checks (tsc --noEmit) to hard-block hallucinated imports or type corruption.
• Cross-Agent Standardization: Generates strictly formatted .cursorrules and CLAUDE.md to force all native IDE agents to adhere strictly to the VAOS verification protocols.

A task is only DONE when all verification gates pass:

1. Constraint Hash Matching: Workspace constraints must violently match the orchestrated plan.
2. LSP/AST Validation: (If --lsp) All types and syntax must compile flawlessly.
3. All verification commands succeed (exit code 0)
4. All required artifacts exist
5. All validators pass
6. All acceptance criteria are checked

No exceptions. No "it should work." Prove it.

Quickstart

npx vaos-ai init
vaos plan --goal "add user authentication"
# Edit requirements.yml and phases.yml
vaos plan --spawn 2026-03-01__add-user-auth
vaos verify 2026-03-01__api__setup-auth --human

Install

# As project devDependency (recommended)
npm install --save-dev vaos-ai

# Or run directly with npx
npx vaos-ai init

How It Works

Plan → Spawn → Execute → Verify → Done

Plans decompose goals into verified tasks

vaos/plans/<plan-id>/
├── PLAN.md              # Goal, context, constraints
├── requirements.yml     # Each requirement has a verify field
└── phases.yml           # Tasks with dependencies (blocked_by)

Tasks are self-contained workspaces

vaos/tasks/<task-id>/
├── TASK.md              # Objective, plan, claims
├── acceptance.md        # Verifiable criteria (checkboxes)
├── config.yml           # Commands, artifacts, validators
├── runbook.md           # Human-readable command guide
├── evidence/
│   ├── verify.json      # Deterministic PASS/FAIL report
│   └── artifacts_manifest.json
└── logs/
    └── verify-*.log     # Command execution logs

CLI Reference

vaos init

Initialize VAOS in your project. Creates vaos/ directory with config, templates, and optionally installs Claude Code slash commands.

vaos init                           # Interactive setup
vaos init --yes                     # Non-interactive with defaults
vaos init --channel myapp           # Set default channel
vaos init --no-slash-commands       # Skip Claude Code slash commands

vaos plan

Create and manage plans. Plans decompose a goal into phases with task dependencies. Every requirement specifies how it will be verified — plans are verification contracts.

vaos plan --goal "add user auth"    # Create a new plan
vaos plan --list                    # List all plans
vaos plan --show <plan-id>          # Show plan with task statuses
vaos plan --spawn <plan-id>         # Create tasks from plan phases (idempotent)
vaos plan --spawn <plan-id> --force # Re-create all tasks
vaos plan --reset <plan-id>         # Clear task-map and logs
vaos plan --reset <plan-id> --delete-tasks  # Also delete task directories

vaos add-requirement --plan <id> --desc "Auth test" --cmd "npm test"
vaos add-task --plan <id> --phase "Foundation" --name "Setup" --reqs R1

### `vaos keygen`, `vaos sign`, `vaos audit`, `vaos audit-agent`
Generate Zero-Trust Asymmetric Keys to mathematically prevent agent hallucination loops.

```bash
vaos keygen                           # Generate RSA keys (private in ~/.vaos, public in project)
vaos sign <plan-id>                   # Cryptographically sign a plan's requirements.yml
vaos audit <task-id>                  # Human/CI gate: Mathematically prove completion
vaos audit-agent <plan-id>            # Dual-Agent Sub-Agent Protocol: Request biometric OS signature

Requirements format (requirements.yml):

requirements:
  - id: R1
    description: Auth endpoint returns JWT
    verify:
      command: npm test -- --grep "auth"
      artifact: src/auth/handler.js

Phases format (phases.yml):

phases:
  - id: phase-1
    name: Foundation
    tasks:
      - id: setup-auth
        name: Set up authentication
        channel: api
        requirements: [R1]
        blocked_by: []
      - id: add-tests
        name: Add integration tests
        channel: api
        requirements: [R1]
        blocked_by: [setup-auth]

vaos new-task

Create a standalone task workspace from template.

vaos new-task --channel api --name "add user authentication"

Task ID format: YYYY-MM-DD__channel__slugified-name

vaos execute

Execute a plan by dispatching tasks to a configurable agent command and verifying each one. Tasks run in dependency order (waves).

vaos execute <plan-id>              # Execute all unblocked tasks
vaos execute <plan-id> --wave 1     # Execute specific wave only
vaos execute <plan-id> --dry-run    # Preview execution plan
vaos execute <plan-id> --parallel 3 # Run up to 3 tasks per wave in parallel

Webhooks

VAOS supports execution webhooks natively across any verification run. Add these to your project's vaos/config.yml:

webhooks:
  on_verify_pass: 'curl -X POST https://api.example.com/webhook -d "task_id={task_id}"'
  on_verify_fail: 'npm run notify-slack -- "{task_id}"'

VAOS will automatically execute these commands whenever an agent deterministically passes or fails verification.

Configure the agent command in vaos/config.yml:

execute:
  command: "claude -p '{task_summary}' --allowedTools Edit,Write,Bash"
  parallel: 3  # Max concurrent tasks per wave (default: 1)

Template variables: {task_id}, {task_dir}, {task_summary}, {context_pack}

vaos accept

Toggle acceptance criteria checkboxes programmatically. No more manual markdown editing.

vaos accept <task-id> 1             # Check criterion #1
vaos accept <task-id> 1 2 3         # Check multiple criteria
vaos accept <task-id> --all         # Check all criteria
vaos accept <task-id> 1 --uncheck   # Uncheck criterion #1
vaos accept <task-id> --all --uncheck  # Uncheck all

vaos verify

Run deterministic verification. Executes commands, checks artifacts, validates acceptance.

vaos verify <task-id>               # JSON output
vaos verify <task-id> --human       # Human-readable checklist
vaos verify <task-id> --agent       # LLM-optimized JSON output with stderr and structural context
vaos verify <task-id> --retry 3     # Retry up to 3 times on failure
vaos verify <task-id> --retry 3 --fix-cmd "claude -p 'Fix: {failure_report}'"
vaos verify <task-id> --watch       # Re-verify on file changes

Exit code: 0 = PASS, 1 = FAIL.

Retry mode generates a structured failure report (evidence/failure-report.md) and optionally feeds it to an agent for automatic fixing.

Watch mode continuously re-verifies when task files change — useful during development.

vaos status

Show all tasks with their verification status.

vaos status                         # All tasks
vaos status --channel api           # Filter by channel
vaos status --json                  # JSON output for CI/CD

vaos pack-context

Generate a compact context summary for agent consumption.

vaos pack-context <task-id>

Configuration

Project config (vaos/config.yml)

channel: my-project
execute:
  command: "claude -p '{task_summary}'"

Task config (vaos/tasks/<id>/config.yml)

channel: api
artifacts:
  - path: evidence/artifacts_manifest.json
  - path: dist/index.js
validators:
  - type: file-size
    path: dist/index.js
    min_size: 1
  - type: contains
    path: dist/index.js
    text: "export default"
verify:
  commands:
    - npm test
    - npm run build

Validators

Built-in validator types:

| Type | Checks | Config keys | |------|--------|-------------| | file-size | File size bounds | path, min_size, max_size | | contains | File contains text | path, text | | json-schema | Valid JSON | path | | regex | Content matches pattern | path, pattern, flags | | exit-code | Command exit code | command, expect | | ffprobe | Video/audio properties | path, min_duration, max_duration, has_audio, has_video, codec, min_width, min_height |

Custom validators

const vaos = require('vaos-ai');

vaos.validators.register('lighthouse', (validator, taskDir) => {
  const report = JSON.parse(fs.readFileSync(path.join(taskDir, validator.path), 'utf8'));
  const score = report.categories.performance.score * 100;
  return {
    type: 'lighthouse',
    ok: score >= (validator.min_score || 90),
    checks: [{ check: 'performance', ok: score >= validator.min_score, expected: validator.min_score, actual: score }],
  };
});

Programmatic API

const vaos = require('vaos-ai');

// Plan
const { planId } = vaos.plan({ goal: 'add auth' });
const spawned = vaos.spawnTasks(planId);       // Idempotent
vaos.resetPlan(planId, { deleteTasks: true }); // Start over

// Execute (async, parallel)
const results = await vaos.execute(planId, { parallel: 3 });

// Accept
vaos.accept('2026-03-01__api__add-auth', { all: true });

// Verify
const report = vaos.verify('2026-03-01__api__add-auth', { silent: true });
console.log(report.status); // 'PASS' or 'FAIL'

// Verify with retry
const retryReport = vaos.verifyWithRetry('task-id', { maxRetries: 3 });

// Graph
const { buildGraph, computeWaves } = vaos.graph;
const graph = buildGraph(phases);
const waves = computeWaves(graph);

// Status
const tasks = vaos.status({ json: true });

// Init
await vaos.init({ yes: true, channel: 'myapp' });

Claude Code & Cursor Integration

When you run vaos init, it installs slash commands to .claude/commands/ and generates .cursor/rules/vaos.mdc.

Agentic Test-Driven Development (TDD): VAOS v2.2.7 enforces a shift-left strategy for AI agents. Rather than coding blindly and checking VAOS at the end, the generated prompts instruct the agent to run vaos verify <task-id> --watch in the background while it codes. This forces Cursor and Claude to strategize iteratively against strict validation barriers.

Agentic API (v2.3.0): VAOS v2.3.0 is built natively for AI agents. Rather than relying on LLMs to generate and edit fragile YAML syntax, they can use deterministic CLI commands like vaos add-requirement and vaos add-task. When agents verify their tasks using vaos verify <task-id> --agent, VAOS produces structured JSON containing:

1. Truncated subsets of stderr logs.
2. Contextual "Shift-Left" file outlines mapping out structural classes and functions when validation fails.
3. Smart validation warnings explicitly alerting the LLM if the underlying plan constraints changed since spawning a workspace loop.

• /vaos:plan — Create/show/spawn plans
• /vaos:execute — Execute plan with agent dispatch
• /vaos:verify — Verify task with retry and analysis
• /vaos:status — Show all tasks and plans

Templates

Task templates

Create channel-specific templates in vaos/templates/<channel>/:

vaos/templates/
├── default/          # Fallback for all channels
└── frontend/         # Used when --channel frontend
    ├── TASK.md
    ├── acceptance.md
    ├── config.yml
    └── runbook.md

Plan templates

VAOS ships with a default plan template. Plans are created in vaos/plans/.

Global Options

vaos --verbose <command>  # Show debug output (or set VAOS_VERBOSE=1)
vaos --version            # Show version
vaos --help               # Show help

CI/CD Integration

# .github/workflows/verify.yml
name: VAOS Verify
on: [push]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx vaos-ai status --json

Philosophy

Agent orchestration frameworks tell agents what to do. VAOS verifies what they did — and governs how they do it.

• Deterministic: Commands execute, files get checked, criteria get validated. No LLM-as-judge.
• Auditable: Every PASS has a verify.json with timestamps, command outputs, and artifact manifests.
• Governed: Plans enforce dependency order. Agents can't skip ahead. Failed tasks block dependents.
• Agent-agnostic: Works with Claude Code, Cursor, Windsurf, Devin, or shell scripts.
• Minimal dependencies: One dependency (js-yaml). Installs in under a second.

Package Name

The npm package is published as vaos-ai. After installation, the CLI command is vaos.

License

MIT