prompt-language

@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.

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, then use docs/experiments.md or 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

npx @45ck/prompt-language

Default interactive install requires Claude Code 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 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.

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.