@runtypelabs/cli 1.9.4 → 2.0.1

package/README.md

@@ -1,4 +1,5 @@
 <p align="center" style="background:white;border-radius:4px;padding: 12px;margin-bottom:16px;">
+  <br>
   <img
     src="https://www.runtype.com/runtype-text-only.svg"
     alt="Runtype: The Intelligent Product Company"
@@ -6,6 +7,10 @@
   />
 </p>
 
+👋 Hey there! We're here to help you build intelligent products.
+
+You are looking at...
+
 # The Runtype CLI
 
 This is our command-line interface for the platform, which includes _Marathon_, our harness for long-running tasks and deep workflow analysis.
@@ -120,6 +125,144 @@ runtype marathon "Code Builder" --goal "Build it" --no-runner --no-finish
 | `--no-runner`          |         | Hide the runner emoji from the header border      |
 | `--no-finish`          |         | Hide the finish line emoji from the header border |
 
+#### Custom Playbooks
+
+Playbooks let you define custom workflows with milestones, model overrides, verification settings, and rules in a single YAML file.
+
+```bash
+# Run with a custom playbook
+runtype marathon "Minimal design library" \
+  --playbook design-library \
+  --goal "Create a clean, modern component library with a blue/slate palette" \
+  --sandbox daytona
+
+# Playbooks are loaded from .runtype/marathons/playbooks/ (first checks folder CLI is ran from, then ~/.runtype/)
+```
+
+From the folder where you want to run the CLI, create the playbook with:
+
+```bash
+mkdir -p .runtype/marathons/playbooks
+
+cat > .runtype/marathons/playbooks/design-library.yaml <<'EOF'
+name: design-library
+description: Generate a styled component library (headers, buttons, forms) and deploy a live preview
+
+rules: |
+  IMPORTANT: Before doing anything else, create a new directory for this project
+  (e.g. "design-library/" or a name derived from the goal). All files must be
+  created inside that directory — do NOT write files in the current working directory.
+  Use vanilla HTML + CSS only — no frameworks, no build tools.
+  Every component must be responsive and accessible (aria labels, focus states).
+  Use CSS custom properties for all colors, spacing, and typography so the
+  entire theme can be changed by editing a single :root block.
+  The final index.html should be a showcase page displaying every component variant.
+
+milestones:
+  - name: research
+    description: Analyze the style direction and plan the component set
+    model: gpt-5-mini
+    instructions: |
+      FIRST: Create a new project directory (e.g. "design-library/" or a name
+      derived from the goal). All files for this project go inside that directory.
+      Do NOT look at or use any existing files in the current working directory.
+
+      Then, read the goal to understand the desired visual style.
+      Decide on a color palette, typography scale, and spacing system.
+      List the exact components to build:
+        - Header: full-width navbar with logo area, nav links, and mobile menu
+        - Buttons: primary, secondary, outline, ghost, destructive — in sm/md/lg sizes
+        - Forms: text input, textarea, select, checkbox, radio, toggle — with labels and validation states
+      Write design-tokens.md inside the project directory capturing your decisions.
+    completionCriteria:
+      type: evidence
+      minReadFiles: 1
+
+  - name: build
+    description: Create the HTML, CSS, and showcase page
+    model: claude-sonnet-4-6
+    instructions: |
+      Create the project files:
+        1. styles/tokens.css — CSS custom properties for the entire theme
+        2. styles/components.css — all component styles using the tokens
+        3. index.html — showcase page that renders every component and variant
+      Make sure:
+        - The showcase page has sections for Headers, Buttons, and Forms
+        - Each section shows all variants side by side
+        - The page looks good at mobile (375px) and desktop (1200px) widths
+        - All interactive elements have hover/focus/active states
+      If a sandbox is available, use `deploy_sandbox` to deploy the showcase
+      as a live preview so the user can see it in their browser.
+    completionCriteria:
+      type: sessions
+      minSessions: 1
+
+  - name: polish
+    description: Refine details, test responsiveness, and deploy
+    model: gemini-3-flash
+    instructions: |
+      Review the showcase page in the browser preview.
+      Fix any visual issues, alignment problems, or missing states.
+      Ensure the page title and meta description reflect the library name.
+      Verify the deployed preview URL is accessible.
+    completionCriteria:
+      type: never
+    canAcceptCompletion: true
+EOF
+```
+
+**Search order**: Exact path → `.runtype/marathons/playbooks/<name>.yaml|yml|json` (repo) → `~/.runtype/marathons/playbooks/<name>.yaml|yml|json` (user).
+
+**Completion criteria types**:
+
+- `evidence` — advances when enough files have been read (`minReadFiles`)
+- `sessions` — advances after N sessions (`minSessions`)
+- `planWritten` — advances when the agent writes its plan artifact
+- `never` — only the agent's `TASK_COMPLETE` signal can advance (if `canAcceptCompletion: true`)
+
+#### Marathon Anatomy
+
+```
+┌─ marathon ──────────────────────────────────────────────────────┐
+│                                                                 │
+│  ┌─ playbook (optional) ─────────────────────────────┐          │
+│  │  Defines milestones, models, verification, rules  │          │
+│  │  .runtype/marathons/playbooks/tdd.yaml            │          │
+│  └───────────────────────────────────────────────────┘          │
+│           │                                                     │
+│           ▼                                                     │
+│  ┌─ milestone 1 ──┐  ┌─ milestone 2 ──┐  ┌─ milestone 3 ─────┐  |
+│  │ research        │  │ test-design     │  │ execution       │  |
+│  │                 │  │                 │  │                 │  |
+│  │  run 1          │  │  run 3          │  │  run 5          │  |
+│  │    checkpoint ──┤  │    checkpoint ──┤  │    checkpoint ──┤  |
+│  │  run 2          │  │  run 4          │  │  run 6          │  |
+│  │    checkpoint ──┤  │    checkpoint ──┘  │    checkpoint ──┘  |
+│  │  (advances) ────┘  │                 |  │                 │  |
+│  └─────────────────┘  └─────────────────┘  └──── finish ─────┘  |
+│                                                                 |
+│  ┌─ rules (optional) ────────────────────────────────┐          |
+│  │  Repo-wide standards applied to ALL milestones    │          │
+│  │  .runtype/marathons/rules/*.md                    │          │
+│  └───────────────────────────────────────────────────┘          │
+└─────────────────────────────────────────────────────────────────┘
+
+Vocabulary:
+  marathon     The overall autonomous task runner
+  playbook     Custom workflow definition
+                (optional, default: research→planning→execution)
+  milestones   Behavioral phases the agent works through
+  runs         Individual agent sessions within a milestone
+  checkpoint   Pause between runs for human review/steering
+  finish       Task completion
+
+What's optional:
+  ✓ Playbook    Without one, uses default workflow (research→planning→execution)
+  ✓ Rules       Without them, agent follows only playbook/milestone instructions
+  ✓ Models      Without overrides, uses CLI --model flag or default
+  ✓ Verification Without it, no verification gate between milestones
+```
+
 #### Tool Context Modes
 
 When a marathon runs multiple sessions, tool call/result pairs from previous sessions are preserved in the conversation history. The `--tool-context` flag controls how older tool results are stored to balance cost and re-readability: