# LockstepAI

Lockstep Dev is a CLI and API-backed workflow for verifying autonomous software execution. It runs local Codex or Claude sessions, applies repo policy and validators, and records verifiable receipts.

Primary URLs:
- Marketing: https://lockstepai.dev/
- Docs: https://docs.lockstepai.dev/
- CLI reference: https://docs.lockstepai.dev/cli
- Quickstart: https://docs.lockstepai.dev/quickstart
- Authentication: https://docs.lockstepai.dev/authentication
- SDK: https://docs.lockstepai.dev/sdk
- Console: https://console.lockstepai.dev/
- Trial request: https://console.lockstepai.dev/trial
- API base: https://api.lockstepai.dev

Install:
```bash
npm install -g @lockstepai/lockstep
lockstep --version
lockstep doctor
```

Directory model:
- `lockstep doctor`, `lockstep templates`, `lockstep setup`, and `lockstep login` can run from any directory.
- `lockstep init`, `lockstep validate`, `lockstep review`, `lockstep policy init`, `lockstep contract init`, and `lockstep run` should run from the target repository root.
- `lockstep setup` stores machine defaults in `~/.locksteprc`.
- `lockstep init` writes `.lockstep.yml` in the current repository.
- `lockstep policy init` writes repo policy in the current repository.

Public CLI commands:
```bash
lockstep --version
lockstep doctor
lockstep templates
lockstep login <api-key>
lockstep setup
lockstep init [template]
lockstep validate [spec-file]
lockstep review [--raw] [spec-file]
lockstep policy init
lockstep contract init [--dry-run] [--output <path>]
lockstep run [spec-file]
lockstep run --runner <codex|claude> --judge <codex|claude>
lockstep run --runner-model <model> --judge-model <model>
lockstep run --execution-mode <standard|yolo>
lockstep run --claude-auth-mode <auto|interactive|api-key|auth-token|oauth-token|bedrock|vertex|foundry>
lockstep run --local --dry-run
lockstep run --local --phase <n>
lockstep run --local --from-phase <n>
lockstep run --local --output <path>
lockstep verify <receipt-file>
```

Recommended first project flow:
```bash
cd /path/to/repo
lockstep doctor
lockstep login ls_test_or_live_key
lockstep setup
lockstep templates
lockstep init blank
lockstep validate
lockstep review
lockstep run
```

Runner and judge:
- Runner is the local provider that performs work.
- Judge is the provider used for review and AI-judge evaluation.
- Supported provider names are `codex` and `claude`.
- Runner and judge can be mixed, for example `lockstep run --runner claude --judge codex`.

Configuration precedence:
1. Command flags, such as `--runner claude`.
2. `.lockstep.yml` in the repo.
3. Machine defaults in `~/.locksteprc`.
4. Built-in defaults: Codex runner, Codex judge, standard autonomy.

Authentication:
- API keys are created in the console.
- Free accounts can create test keys immediately.
- Live keys require a paid plan or an approved manually reviewed trial.
- Manual free trial requests are submitted from https://console.lockstepai.dev/trial.
- Approved manual trials grant 5 live run credits for a limited review window.
- Pro and Team billing through Stripe unlocks live key creation immediately.

Spec skeleton:
```yaml
version: "1"

config:
  agent: "codex"
  judge_mode: "codex"
  execution_mode: "standard"
  max_retries: 3
  step_timeout: 300
  working_directory: "."

context: |
  Shared instructions for every step.

steps:
  - name: "Implement and verify"
    prompt: |
      Describe exactly what the agent should change.
    validate:
      - type: "file_exists"
        target: "package.json"
      - type: "command_passes"
        command: "npm test"
        timeout: 120
```

Validator types:
- `file_exists`: requires `target`.
- `file_not_exists`: requires `target`.
- `file_contains`: requires `path` and `pattern`; optional `is_regex`.
- `file_not_contains`: requires `path` and `pattern`; optional `is_regex`.
- `command_passes`: requires `command`; optional `timeout`.
- `command_output`: requires `command` and `pattern`; optional `is_regex` and `timeout`.
- `api_responds`: requires `url` and `status`; optional `body_contains` and `timeout`.
- `json_valid`: requires `path`; optional `schema`.
- `type_check`: optional `command` and `timeout`.
- `lint_passes`: optional `command` and `timeout`.
- `test_passes`: requires `command`; optional `timeout`.
- `ai_judge`: requires `criteria` and `threshold`; optional `evaluation_targets`, `rubric`, `timeout`. It cannot be the only validator in a step.

Safe command smoke tests:
```bash
lockstep --version
lockstep doctor
lockstep templates
lockstep init blank
lockstep validate
lockstep review
lockstep run --local --dry-run
```

Notes for LLM agents:
- Do not invent commands not listed in the CLI reference.
- Prefer running from the target repo root before using `init`, `review`, or `run`.
- Do not assume a free account has live API access; free accounts need manual trial approval or a paid plan for live keys.
- Do not describe the SDK as the primary product surface. The CLI is primary; the SDK is a thin API client.