# @45ck/prompt-language

A verification-first supervision runtime for coding agents. It wraps supported harnesses such as Claude Code and Codex in a persistent state machine with deterministic control flow, verification gates, and state management.

[![npm](https://img.shields.io/npm/v/@45ck/prompt-language)](https://www.npmjs.com/package/@45ck/prompt-language) [![CI](https://github.com/45ck/prompt-language/actions/workflows/quality.yml/badge.svg)](https://github.com/45ck/prompt-language/actions/workflows/quality.yml) [![license](https://img.shields.io/npm/l/@45ck/prompt-language)](LICENSE) [![node](https://img.shields.io/node/v/@45ck/prompt-language)](package.json) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![npm downloads](https://img.shields.io/npm/dm/@45ck/prompt-language)](https://www.npmjs.com/package/@45ck/prompt-language)

<p align="center">
  <img src="assets/hero-flow.svg" alt="prompt-language flow example" width="720">
</p>

> **In one line.** A thin orchestrator that turns flaky agents into deterministic pipelines by imposing loops, retries, and verification gates the AI cannot self-report past.

## Why it matters

Coding agents are good at producing attempts, but they are unreliable at knowing when
work is actually complete. prompt-language adds a small supervision layer that keeps
state, runs real checks, retries bounded failures, and blocks completion until the
declared gates pass.

Use it when you want:

- repeatable multi-step agent workflows instead of one-off prompts
- real shell-backed completion gates instead of model self-reporting
- resumable state across long runs, compaction, and interruptions
- controlled child-agent orchestration with auditable handoffs

Research results and active experiments live outside this product README. Start with
[What Works Now](docs/evaluation/what-works-now.md), then use
[docs/experiments.md](docs/experiments.md) or [experiments/](experiments/) for
the catalog and raw research tree.

## How it works in three bullets

- **Deterministic execution** -- loops, branches, variables, and retries run without AI involvement. The AI only activates at `prompt` nodes, so the exact deterministic/AI split depends on the flow you write.
- **Verification gates** -- `done when: tests_pass` runs real commands and blocks completion until they pass. The AI cannot self-report "done."
- **Parallel agents** -- `spawn` launches child processes, `await` collects results, `race` picks the fastest. Variables flow between parent and children automatically.

## Install

```bash
npx @45ck/prompt-language
```

Default interactive install requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) and Node.js >= 22. Headless native runners require Node.js >= 22 plus the selected CLI: Codex CLI, OpenCode, Ollama, or aider. Gemini is currently an eval comparison harness, not a native `ci --runner gemini` path. See the [Harness Conformance Matrix](docs/evaluation/harness-conformance-matrix.md) before making runner-support claims.

For the full Claude Code and Codex walkthrough, including install verification, meta-prompt toggles, skill-aware wrapping, and terminal screenshots, see [docs/guides/claude-code-and-codex.md](docs/guides/claude-code-and-codex.md).

## Example

```
agents:
  reviewer:
    model: "opus"
    skills: "code-review", "security-review"

flow:
  let spec = prompt "Write a detailed technical spec for: ${goal}"
  let tasks = prompt "Break this spec into numbered implementation tasks: ${spec}"

  while ask "Are there remaining tasks or unresolved review findings?" grounded-by "npm test" max 10
    foreach task in ${tasks}
      retry max 3
        prompt: Implement ${task}. Follow the spec: ${spec}
        run: npm test
        if command_failed
          prompt: Fix the failing tests for ${task}.
        end
      end
    end

    spawn "review" as reviewer
      prompt: Review all changes against the spec. List any gaps, bugs, or missing edge cases as numbered tasks.
    end
    await "review" timeout 120

    if ${review.findings} != "none"
      let tasks = prompt "Convert these review findings into implementation tasks: ${review.findings}"
    end
  end

done when:
  all(tests_pass, lint_pass)
```

The outer `while ask` loop keeps iterating as long as there are unresolved tasks or review findings. Each iteration implements tasks with retry, then spawns a reviewer -- if the reviewer finds problems, those become the new task list and the loop continues. The flow only exits when the AI judges there's nothing left _and_ real `tests_pass` + `lint_pass` gates confirm it.

Invoke this as a skill from your preferred supported host, or run it headless in CI with `npx @45ck/prompt-language ci`. Native flow runners currently cover Claude, Codex, OpenCode, Ollama, and aider; Gemini remains comparison-only until it has a native runner adapter.

More examples: [docs/examples](docs/examples/index.md) | [examples/public](examples/public/) | DSL cheatsheet: [docs/reference/dsl-cheatsheet.md](docs/reference/dsl-cheatsheet.md)

## Features

| Category          | Highlights                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| **Control flow**  | `if`/`else if`/`else`, `while`, `until`, `retry`, `foreach`, `try`/`catch`/`finally`, `break`, `continue` |
| **Variables**     | `let x = "literal"` / `run "cmd"` / `prompt "..."`, `${x}` interpolation, lists, arithmetic               |
| **Verification**  | `tests_pass`, `lint_pass`, `file_exists`, custom gates, `all()`/`any()` composition                       |
| **Agents**        | Named `agents:` with model/skills/profile, `spawn`/`await`, `race`, `send`/`receive`                      |
| **AI conditions** | `ask "question" grounded-by "command"` for subjective evaluation with real data                           |
| **Resilience**    | Persistent state, compaction survival, `snapshot`/`rollback`, `import`/`include`                          |

## CLI commands

| Command                               | What it does                                 |
| ------------------------------------- | -------------------------------------------- |
| `npx @45ck/prompt-language`           | Install the runtime                          |
| `npx @45ck/prompt-language status`    | Check installation                           |
| `npx @45ck/prompt-language validate`  | Parse, lint, score, and preview a flow       |
| `npx @45ck/prompt-language run`       | Execute a flow via Claude or headless runner |
| `npx @45ck/prompt-language ci`        | Run a flow in headless CI mode               |
| `npx @45ck/prompt-language watch`     | Live TUI flow monitor                        |
| `npx @45ck/prompt-language init`      | Scaffold a starter flow                      |
| `npx @45ck/prompt-language demo`      | Print an annotated example                   |
| `npx @45ck/prompt-language uninstall` | Remove the runtime                           |

Full CLI documentation: [docs/reference/cli-reference.md](docs/reference/cli-reference.md)

## Documentation

| Topic                   | Link                                                                         |
| ----------------------- | ---------------------------------------------------------------------------- |
| Getting started         | [docs/guides/getting-started.md](docs/guides/getting-started.md)             |
| Claude Code and Codex   | [docs/guides/claude-code-and-codex.md](docs/guides/claude-code-and-codex.md) |
| Language reference      | [docs/reference/index.md](docs/reference/index.md)                           |
| DSL cheatsheet          | [docs/reference/dsl-cheatsheet.md](docs/reference/dsl-cheatsheet.md)         |
| How the runtime works   | [docs/guides/guide.md](docs/guides/guide.md)                                 |
| Architecture and design | [docs/architecture.md](docs/architecture.md)                                 |
| Security model          | [docs/security.md](docs/security.md)                                         |
| Examples                | [docs/examples/index.md](docs/examples/index.md)                             |
| Evidence and research   | [docs/evaluation/what-works-now.md](docs/evaluation/what-works-now.md)       |
| Troubleshooting         | [docs/operations/troubleshooting.md](docs/operations/troubleshooting.md)     |
| Roadmap                 | [docs/roadmap.md](docs/roadmap.md)                                           |
| Full doc index          | [docs/index.md](docs/index.md)                                               |

## Tooling

- **VS Code extension** -- syntax highlighting for `.flow`, `.prompt`, and inline flow blocks. Source in `vscode-extension/`.
- **GitHub Actions** -- run flows in CI with [`45ck/prompt-language-action`](https://github.com/45ck/prompt-language-action).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).
