Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,4 @@ hack/*
.codegraph/
/assets/brand/captain-formation/presentation/
/.new
pkg/adapters/resources/anthropic.json
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Save as `review.prompt`, preview the effective request, then execute:
captain lint promptfile review.prompt
captain prompt render review.prompt -V target=pkg/promptrun --json
captain prompt run review.prompt -V target=pkg/promptrun
captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.1-sol
captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.2-sol
```

Render performs no model call or setup. Files are templates; inline `-p` and piped text are literal unless variables or `{{input}}` opt into templating. Piped input binds to `input`, a named `-V key=-`, or is appended when unused. Use `--attach` for files/URLs, `--preset` for reusable runtime layers and `--no-stream --json` for a buffered structured result.
Expand All @@ -70,7 +70,7 @@ captain prompt --schema
| Isolation | `container`, `sandbox`, `sandbox credentials`, `sandbox git-agent` | [Sandboxes](docs/src/pages/sandboxes/index.mdx) |
| Gavel integration | `gavel todos` embeds Captain | [TODO lifecycle](docs/src/pages/todos/index.mdx) |

`captain ai prompt` aliases `captain prompt run`. Other AI utilities include `ai agent` for explicit generate/verify workflows, `ai models`, `ai test`, `ai tokens` and `ai mock`. Use each command's help for its current flags. A runtime is `(model, mode)`; mode is `api`, `agent`, `cli` or `cmux`, with provider derived from the model. Configure provider defaults with `captain configure openai --mode agent --model gpt-6.1-sol --effort high --active`.
`captain ai prompt` aliases `captain prompt run`. Other AI utilities include `ai agent` for explicit generate/verify workflows, `ai models`, `ai test`, `ai tokens` and `ai mock`. Use each command's help for its current flags. A runtime is `(model, mode)`; mode is `api`, `agent`, `cli` or `cmux`, with provider derived from the model. Configure provider defaults with `captain configure openai --mode agent --model gpt-6.2-sol --effort high --active`.

## Verification and embedding

Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/configuration/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Captain reads saved defaults from `~/.captain.yaml`. Run `captain configure` for

```sh
captain configure
captain configure openai --mode agent --model gpt-6.1-sol --effort high --active
captain configure openai --mode agent --model gpt-6.2-sol --effort high --active
captain configure anthropic --mode agent --model sonnet --effort default
captain whoami --models=false
```
Expand All @@ -27,7 +27,7 @@ ai:
providers:
openai:
mode: agent
model: gpt-6.1-sol
model: gpt-6.2-sol
reasoningEffort: high
timeout: 20m
prompts:
Expand Down
2 changes: 1 addition & 1 deletion docs/src/pages/fixtures/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ These proxies capture real traffic; they do not turn a mutating tool into a read

```sh
captain prompt observe --runtime agent:sonnet -p 'Explain this repository' > .tmp/observation.json
captain prompt observe review.prompt --runtime api:gpt-6.1-sol -V target=pkg/cli
captain prompt observe review.prompt --runtime api:gpt-6.2-sol -V target=pkg/cli
```

`observe` is CLI-only and emits one `captain.observation/v1` JSON document. `--runtime` is required and cannot be combined with `--model` or `--mode`. Fallback chains, parallel matrices and workflow-backed prompts are rejected. `--mcp-config` and `--capture-kubernetes` request external capture; availability and capture coverage are recorded explicitly rather than treating missing measurements as zero.
Expand Down
13 changes: 12 additions & 1 deletion docs/src/pages/prompts/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,23 @@ Arguments after the prompt are input files; the shell expands globs. Each must b

Without a batch, every input file goes to one run. `--batch=N` splits them into runs of N files, so `--batch=1` processes files one at a time; under a batch the `--attach` files are split too, each run attaching only its own. `--batch-concurrency=M` runs M batches at once (default 1). The flags override the prompt's `batch` field. Each batch is its own recorded run, and its input hooks may skip it. The result lists one row per batch with its inputs, status and answer, skip reason or error. The totals count succeeded, failed and skipped runs; tokens and cost are summed over the runs that executed. When any batch fails, the others still run and the command exits non-zero. A batch cannot be combined with a multi-runtime run (`runtimes:` or `-M`).

## Command fan-out

Save the [fan-out example](/prompts/format/#command-fan-out) as `classify.prompt`. Preview it with one sample object, then run the script and inspect the sessions it starts.

```sh
captain prompt render ./classify.prompt --vars '{"item":{"name":"docs"}}' --json
captain prompt run ./classify.prompt --json
```

`render` uses the sample without executing `fanout.exec`. Omit the sample when running so the script can supply each item. Run output includes `batchId` and an ordered `runs` list with each item's one-based `fanOutIndex` and `sessionId`. If the script returns `[]`, the run completes without starting any sessions.

## Runtime and output

```sh
captain prompt run review.prompt --preset Plan
captain prompt render review.prompt --no-presets --json
captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.1-sol
captain prompt run review.prompt -M agent:sonnet -M agent:gpt-6.2-sol
captain prompt run review.prompt --no-stream --json
captain prompt observe --runtime agent:sonnet -p 'Explain this repository'
```
Expand Down
23 changes: 22 additions & 1 deletion docs/src/pages/prompts/format.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,27 @@ batch: {size: 1, concurrency: 4}
Classify {{file}}.
```

### Command fan-out

Use `fanout.exec` to run a script once before launching sessions. It runs on the Captain host in the prompt's resolved working directory, before any per-session sandbox setup. As with inline tools, a shebang selects the interpreter. The script receives the caller's template variables as a JSON object on stdin. Write exactly one JSON array to stdout and send diagnostics to stderr. Captain renders the same prompt once per array element and runs each in a fresh session. Use `{{item.name}}` to read a field or `{{{itemJSON}}}` to insert the complete element, including scalars and arrays.

```yaml
---
model: api:sonnet
fanout:
exec: |
printf '%s\n' '[{"name":"docs"},{"name":"tests"}]'
concurrency: 2
---
List three ways to improve the project's {{item.name}}.
```

Save the example as `classify.prompt` and run `captain prompt run ./classify.prompt`. The default concurrency is one. Results follow the array's order even when sessions finish out of order. An empty array starts no sessions. If the command fails or prints invalid JSON, Captain starts no sessions. If a session fails after launch, the other sessions still run and the CLI reports the result of each one.

Rendering or previewing a prompt never runs the command. For a preview, supply a sample `item` or `itemJSON` as a template variable. Fan-out runs use their own sessions with a single runtime. File batching, chat, and session resumption are unavailable for these runs.

In the prompt workbench, open the **Fan-out** tab to edit the script and optional concurrency limit. **Apply to draft** updates the YAML in **Source**. Select **Save** to persist the draft, or open **Run** to try the draft first. **Remove from draft** deletes the `fanout` block.

## Inline tools

`tools` declares tools the model can call, keyed by tool name. Each tool runs its `exec` script and returns the result to the model. Inline tools are caller tools: API runtimes call them in-process and agent runtimes reach them through Captain's caller-tool MCP endpoint. A runtime that cannot expose caller tools (for example `google cli`) refuses the run before the first model call. Jev is the exception: it ignores tools and leaves them to hooks (see [Jev typed decisions](#jev-typed-decisions)).
Expand Down Expand Up @@ -468,7 +489,7 @@ Human output shows the number of files checked and separate error and warning co

The two website prompts check every command, flag, version and example against the tool's source (`source`, default the working directory) and share four families. `ia/` covers information architecture: navigation grouped by reader goals rather than code layout, one purpose per page, labels that predict their content, a clean heading outline, cross-links, and orphaned, dead-end or broken links. `ux/` covers reading and interaction: link and call-to-action labels, conditions placed before the step they govern, callouts, a recommended default among options, and text alternatives for images and recordings. `dx/` covers developer experience: prerequisites, time to the first working result, commands that paste and run, complete examples and option reference, configuration precedence, version drift and unsafe steps. `density/` covers information density: walls of text, buried ledes, filler, content in the wrong shape, repetition and fragmentation. The numeric thresholds in these rules are reporting triggers, not targets. The marketing prompt adds `web/` for the landing page's message and `oss/` for open-source essentials: license, repository, the open-core boundary, ungated access, community, security contact, maintenance and telemetry.

Each review prompt declares `permissions: {access: read-only}` rather than a tool list. The same file therefore runs read-only on claude, where it compiles to Edit, Write, Bash and sub-agent denies, and on codex, where it compiles to a read-only sandbox that never asks. Web tools stay available on both. `captain permissions explain examples/proposal-review.prompt --model agent:sonnet --model agent:gpt-6.1-sol` shows both postures; see [Portable access](/prompts/runtime/#portable-access).
Each review prompt declares `permissions: {access: read-only}` rather than a tool list. The same file therefore runs read-only on claude, where it compiles to Edit, Write, Bash and sub-agent denies, and on codex, where it compiles to a read-only sandbox that never asks. Web tools stay available on both. `captain permissions explain examples/proposal-review.prompt --model agent:sonnet --model agent:gpt-6.2-sol` shows both postures; see [Portable access](/prompts/runtime/#portable-access).

To use an example by name from any directory, copy it from `examples/` into `~/.config/captain/prompts/`, or into a repository's `.captain/prompts/` for project use. These examples are not embedded in the binary.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/pages/prompts/runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ A converted intent is applied only on runtimes that speak another dialect, so a
The built-in presets themselves are unchanged. To see what a prompt becomes on each runtime, or to rewrite a block into the portable form, use:

<CodeExample client:load language="bash" title="Explain and convert" source={`
captain permissions explain proposal-review --model agent:sonnet --model agent:gpt-6.1-sol
captain permissions explain proposal-review --model agent:sonnet --model agent:gpt-6.2-sol
captain permissions convert .captain/presets/read-only.yaml # prints the diff
captain permissions convert .captain/presets/read-only.yaml --write # rewrites the file
`} />
Expand Down
4 changes: 4 additions & 0 deletions docs/src/pages/prompts/sources-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,10 @@ Rendering accepts template variables and an optional runtime `spec` overlay. It

The `run` action renders synchronously, creates a prompt run id, then streams session entries through `/api/captain/prompt/runs/{runId}/stream`. A snapshot endpoint at `/api/captain/prompt/runs/{runId}` lets the UI recover entries, completion state, summary, and error text.

For a [fan-out prompt](/prompts/format/#command-fan-out), send `chat: false` or omit `chat`. The run action executes `fanout.exec` once and returns `batchId` plus an ordered `runs` array. Each entry includes `fanOutIndex`, `sessionId`, and the child `runId` to use with the stream endpoint. An empty array produces `{"status":"completed"}` without a run or batch ID. The render action can accept a sample in `variables.item` and leaves the script untouched.

In the workbench, **Render** previews the current draft and **Run fan-out** starts its sessions. A **Command fan-out** group in the **Run** tab lets you inspect each child session. The workbench reports when an empty array starts no sessions.

Send `chat: true` in the run request to keep a managed chat available for follow-up messages. Each chat runs as a supervisor, so starting another chat does not wait for an existing chat to finish or leave its idle period. This applies to single runs and multi-runtime chat batches. `POST /api/captain/prompt/runs/{runId}/stop` also cancels a chat that has not started: its stream becomes terminal and its queued task cannot later launch a provider.

A workflow that declares `workflow.verify` also publishes its own `verify` SSE event: `{"report": <VerifyReport>, "done": boolean}`. Only the newest snapshot is kept — a late subscriber gets the run's current verification state on connect, the same way it gets `run` and `state` — and it stops updating once the run is done. See [Verification](/agents/verification/) for the report shape and how it is persisted.
36 changes: 36 additions & 0 deletions examples/security-updates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# GitHub security updates

Use [security-updates.prompt](security-updates.prompt) to run a separate Captain session for each repository in a GitHub organization that has an exact topic. The GitHub token determines which repositories the fan-out can see. Captain runs up to three repository sessions at a time.

## Prerequisites

Install a Captain build that supports `fanout.exec`, Python 3, and Gavel. Apply and publish modes also need Git, Worktrunk (`wt`), Repomap with `deps update --security`, and the package managers and test tools used by the repositories.

Configure GitHub credentials on the Captain host. The fan-out uses `GITHUB_TOKEN` or `GH_TOKEN` if Captain passes it to the shell, or the credential saved by Gavel in `~/.config/gavel/auth.json`. Give the token access to the repositories and alert endpoints you want to audit. Configure `GITHUB_TOKEN` or `GH_TOKEN` in the per-repository session environment for Repomap, plus credentials for Git fetches in write modes. Publish mode needs permission to push branches, open PRs, and enable auto-merge in repositories that allow it. Keep tokens out of prompt inputs.

## Run

From the Captain repository root, start with an audit. Replace `example-org` and `platform` with your organization and topic.

```sh
captain prompt run examples/security-updates.prompt \
--var org=example-org --var topic=platform --json
```

In the prompt workbench, open **Run**, enter **org** and **topic**, and choose an **action**.

| Action | Result |
| --- | --- |
| `audit` | Reports Dependabot alerts, CodeQL findings, and PR health from Gavel. |
| `apply` | Applies and verifies supported Dependabot fixes in an isolated Worktrunk worktree, then returns its path. |
| `publish` | Applies and verifies eligible fixes, then opens PRs with `gavel commit -p --auto-merge`. With `rebase: true`, also rebases eligible security PRs owned by the authenticated user. |

To publish fixes with auto-merge and rebase eligible PRs:

```sh
captain prompt run examples/security-updates.prompt \
--var org=example-org --var topic=platform \
--var action=publish --var rebase:=true --json
```

Each session reports its audit coverage, verification results, PR URLs or worktree paths, and any findings that require a maintainer. Archived, disabled, and forked repositories receive an audit only. GitHub auto-merge waits for the repository's required checks and reviews.
Loading
Loading