Skip to content

WhippleScript Docs

WhippleScript coordinates durable work across agents, humans, packages, queues, timers, scripts, and child workflows. The docs are written for two readers: humans using the website and coding agents reading Markdown directly.

Version scope: the Markdown in this repository documents the current checkout of main. Release users should read the docs from the matching Git tag when exact CLI flags or JSON fields matter. The current published CLI version is 0.1.x; the implementation-stage label printed by whip --help is an internal progress marker, not a separate compatibility version.

If you are a coding agent, start with the local companion skill at skills/whipplescript-author/SKILL.md (web link). It contains the operational route map, feature selection table, canonical patterns, command loop, and links into the deeper pages.

Design records and implementation trackers live in spec/. They are not required for normal authoring.

Reading Paths

Goal Read
Install and run a checked workflow Quickstart
Learn the runtime nouns Concepts
Build a real workflow from an empty file Tutorial
Choose the right authoring pattern Manual
Look up exact syntax Language reference
Pick a known-good example Examples
Run or inspect instances CLI reference
Consume machine-readable output JSON reference
Interpret errors Diagnostics guide
Operate running workflows Runtime & operations
Configure agents, providers, and packages Providers & packages
Fix a failing first run Troubleshooting
Check stability and caveats Current state

Agent Route

Use this route when the task is "write or fix a workflow":

  1. Read skills/whipplescript-author/SKILL.md.
  2. Pick the closest checked example from Examples.
  3. Use the Manual for pattern choice.
  4. Use the Language reference only for exact grammar.
  5. Validate with whip check and fixture-backed whip dev.
  6. Inspect runtime state with status, effects, runs, diagnostics, evidence, and trace --check before changing prompts.

Website

This directory is also a MkDocs site. From the repository root:

python3 -m pip install -r docs/requirements.txt
mkdocs serve

Check the site in strict mode with:

scripts/check-docs-site.sh

The Markdown files remain canonical so agents can navigate them without a site build.

Verification

Docs that present complete workflows or cataloged example commands are checked by scripts:

scripts/check-docs-quickstart.sh
scripts/check-docs-examples.sh
scripts/check-docs-snippets.sh

Code block convention:

  • sh blocks are runnable commands unless they contain placeholders such as <instance>.
  • whip blocks are complete source only when introduced as a full file or covered by one of the scripts above.
  • json and text blocks are output or schema/diagnostic shapes unless the surrounding text says to save them as input.
  • ... and angle-bracket placeholders mark illustrative fragments.

Complete workflow examples should either live in examples/ or be covered by one of the scripts above.