Skip to content

Queen Shell CLI reference

paseka is the Queen Shell — a single binary for colony setup, one-shot bee runs, interactive sessions, NATS runtime, and housekeeping.

Build from the repo root:

go build -o paseka ./cmd/paseka

Conventions

Resolving the colony

Most commands resolve the git repository and colony config from the current working directory. Use --path / -C to start resolution from another directory inside the repo:

paseka bee run scout --body "survey" --path /path/to/repo

Resolution requires:

  • A git repository with .paseka/colony.yaml (run paseka init first)
  • Machine-local config at ~/.config/paseka/<slug>/ (created by paseka init)

Identifiers

Flag / field Name in docs Description
--trace traceId Flight trail — groups runs, worktrees, and bus events for one feature chain
--body (bee run / chat) task body Free-text nectar passed into the prompt template ({{.Task}})
--task (task / proposal) taskId Structured subtask id in the task ledger (e.g. task-1)
agent id agentId Unique id per adapter invocation (auto-generated for bee run)

NATS dependency

Command NATS required?
paseka init, bee run --no-bus, bee chat, session, colony topology, nuc, console, purge (filesystem only), export, inspect usage No
paseka purge --bus Yes — requires nats.url and --trace
paseka bee run (default) Optional — publishes domain events when nats.url is configured
paseka run, doctor, replay, signal, cue, proposal, energy, task create, task start, task retry, gate telegram Yes
paseka task list, paseka task show, export Optional — prefers JetStream KV, falls back to filesystem projection

Default NATS URL after paseka init: nats://127.0.0.1:4222 (see docker-compose.yml).

Non-empty PASEKA_NATS_URL overrides nats.url in home config.yaml (useful for containers and shared NATS hosts). Homelab / server container setup: Homelab deployment.

Command tree

paseka
├── init
├── bee
│   ├── run <role>
│   └── chat <role> [prompt]
├── session
│   ├── list
│   ├── attach <sessionId>
│   ├── stop <sessionId>
│   └── run <role>          (hidden — Ghostty launcher)
├── run
├── task
│   ├── create
│   ├── list
│   ├── show
│   └── start
├── doctor
├── event
│   ├── emit
│   ├── validate
│   ├── pending
│   └── flush
├── inspect
│   └── usage
├── replay <traceId>
├── cue
│   ├── list
│   └── run <id> <text>
├── signal
├── proposal
│   ├── approve
│   └── reject
├── energy
│   ├── show
│   └── add
├── colony
│   └── topology
├── nuc
│   ├── export
│   └── import <file|url|->
├── console
├── gate
│   └── telegram
├── export
└── purge

paseka init

Bootstrap .paseka/ in the current git repository and machine-local home config under ~/.config/paseka/<slug>/.

Flag Short Default Description
--path -C cwd Directory inside the git repository
--adapter cursor Scaffold bees and home config for this adapter (cursor or pi; unknown values use cursor)

Creates (if missing):

  • .paseka/colony.yaml, bees/, prompts/, scout and builder bee definitions (using the selected adapter)
  • ~/.config/paseka/<slug>/config.yaml (includes nats.url; non-empty PASEKA_NATS_URL overrides it)
  • ~/.config/paseka/<slug>/adapters/cursor.yaml (default adapter)
  • ~/.config/paseka/<slug>/adapters/pi.yaml (when --adapter pi)
  • ~/.config/paseka/<slug>/adapters/claude.yaml (optional Claude adapter config)

Idempotent — existing files are skipped.

paseka init
paseka init --adapter pi
paseka init -C /path/to/repo

paseka bee

Run colony bees via adapters (Cursor Agent CLI by default; Pi CLI when adapter: pi; shell/python when adapter: script).

paseka bee run <role>

Dispatch one bee — a single non-interactive adapter invocation (AFK run).

Arguments: role — bee name matching .paseka/bees/<role>.yaml (e.g. scout, builder).

Flag Short Required Description
--body -b * Task body rendered into the prompt template
--prompt * Inline prompt override (skips template file)
--trace Flight trail id; generated if omitted
--intent Task intent for the bee role (vocabulary from bee intents or <role>-intent-* partials; default from bee config or discovered vocabulary)
--path -C Colony resolution start directory
--no-bus Skip NATS publish (file-only run)

* Provide --body or --prompt for LLM bees. Script bees (adapter: script) do not require a prompt; they run the bee's command: and receive runtime context via PASEKA_* env vars (see architecture overview § Script adapter).

Behavior:

  • Renders prompt from .paseka/prompts/ (see prompt templates)
  • Writes run artifacts to .paseka/runs/<traceId>/<agentId>/
  • Builder bees with worktree: true run in .paseka/worktrees/<traceId>/
  • Publishes domain events (SIGNAL, INSIGHT, MUTATION, VERIFICATION) to NATS when configured
  • Prints status, trace, agent id, workspace, run dir, output, and diff summary
paseka bee run scout --body "Plan auth for the API"
paseka bee run builder --body "Implement login" --trace trace-abc123 --intent feature
paseka bee run scout --prompt "Quick spike: {{.Task}}" --body "rate limiting"
paseka bee run builder --body "hotfix" --no-bus

paseka bee chat <role> [prompt]

Start an interactive human-in-the-loop session in a long-lived agent process.

Arguments:

  • role — bee name
  • prompt (optional) — initial prompt text; equivalent to --prompt
Flag Short Required Description
--body -b * Task body for the prompt template
--prompt * Inline prompt override
--trace Flight trail id; generated if omitted
--intent Task intent for the bee role (vocabulary from bee intents or <role>-intent-* partials)
--path -C Colony resolution start directory
--terminal default or ghostty (overrides ~/.config/paseka/<slug>/terminal.yaml)

* Provide a positional prompt, --body, or --prompt.

See interactive sessions for session architecture and Ghostty attach.

paseka bee chat scout "Discuss the auth design"
paseka bee chat builder --body "Walk through the login flow"
paseka bee chat scout "review PR" --terminal ghostty

paseka session

Manage interactive agent sessions registered in ~/.config/paseka/<slug>/state.json.

paseka session list

List active sessions for the colony.

Flag Short Description
--path -C Colony resolution start directory

paseka session attach <sessionId>

Attach to a session running in the current paseka process (in-process PTY relay). No flags.

paseka session stop <sessionId>

Stop a session by id. Tries the in-process manager first, then signals a remote PID from state.json.

Flag Short Description
--path -C Colony resolution start directory (for remote stop)

paseka session run <role> (hidden)

Internal entry point used when bee chat --terminal ghostty launches a new terminal window. Same flags as bee chat (--path, --body, --trace, --prompt).

paseka run

Start the long-running Hive Runtime — a NATS reactor that subscribes to colony events, updates the task ledger, and dispatches ready tasks to bees.

Flag Short Description
--path -C Colony resolution start directory

Requires: NATS with JetStream (nats.url in home config, or PASEKA_NATS_URL).

Runs until interrupted (Ctrl+C). On SIGNAL / task.ready events, dispatches the configured bee and publishes resulting domain events. See task ledger.

# Terminal 1
docker compose up -d
paseka run

# Terminal 2 — inject a ready task
paseka signal --type SIGNAL --trace trace-1 \
  --payload '{"kind":"task.ready","taskId":"task-1","title":"Add endpoint","bee":"builder"}'

paseka task

Inspect and enqueue tasks for a trace. Task execution still requires the long-running paseka run reactor.

paseka task create

Create a new task by publishing task.plan. Generates traceId and taskId when omitted.

Flag Short Required Description
--title * Task title
--body * Inline task body
--stdin * Read task body from stdin
--file * Read task body from file
--trace Flight trail id (generated when omitted)
--task Task id (generated when omitted)
--bee Bee role (default: defaults.default_bee from colony.yaml, fallback builder)
--intent Task intent for the bee role (vocabulary from bee intents or <role>-intent-* partials)
--depends-on Task dependencies (repeatable or comma-separated)
--review Review policy: none, required, final
--autorun Publish task.ready immediately after task.plan
--path -C Colony resolution start directory

* Provide --title and/or one body source (--body, --stdin, or --file).

paseka task create --title "Add health check" --body "Implement /healthz endpoint" --bee builder --intent feature
cat task.md | paseka task create --title "Implement auth" --stdin --autorun
paseka task create --file task.md --bee builder --autorun

On success prints trace, task, suggested paseka task start / paseka task show commands, and whether task.ready was published.

paseka task list

List tasks for one flight trail.

Flag Short Required Description
--trace yes Flight trail id
--path -C Colony resolution start directory

Reads JetStream KV when NATS is configured; otherwise falls back to .paseka/runs/<traceId>/tasks/*/task.md.

paseka task list --trace trace-1

paseka task show

Show one task, its markdown description, and linked agent runs.

Flag Short Required Description
--trace yes Flight trail id
--task yes Task id
--path -C Colony resolution start directory 
paseka task show --trace trace-1 --task task-1

paseka task start

Publish task.ready for eligible planned tasks. Requires NATS.

Flag Short Required Description
--trace yes Flight trail id
--task Task id; when omitted, starts all eligible planned tasks
--path -C Colony resolution start directory 
# Terminal 1
paseka run

# Terminal 2 — enqueue one task or all eligible tasks
paseka task start --trace trace-1 --task task-1
paseka task start --trace trace-1

paseka task retry

Re-publish task.ready for a failed or stuck running task using the same bee, intent, and body from the task ledger. Requires NATS.

Flag Short Required Description
--trace yes Flight trail id
--task yes Task id
--path -C Colony resolution start directory 
# Terminal 1
paseka run

# Terminal 2 — retry after a failed adapter run
paseka task retry --trace trace-1 --task task-1

paseka doctor

Check NATS connectivity, JetStream resources, and colony bee wiring for the colony.

Flag Short Description
--path -C Colony resolution start directory

Reports: connection, JetStream, event stream, task-ledger KV bucket, object store bucket; code proposal wiring (worktree ↔ kind mismatches as errors, bare code.proposal alias as warnings, missing subscribers / verification publishes as advisories).

Exits with an error if any check fails.

paseka doctor

paseka replay <traceId>

List domain events for a flight trail replayed from JetStream.

Arguments: traceId — flight trail to replay.

Flag Short Description
--path -C Colony resolution start directory

Prints event type, payload.kind, and agent id per event. Does not re-execute bees.

paseka replay trace-abc123

paseka cue

Run colony Forage Cue shortcuts from .paseka/cues/<id>.yaml. Publishes signal or task ingress immediately (no confirm). Full authoring, Console, Telegram, and honey rules: Forage Cues.

Requires NATS (same as paseka signal / task create).

paseka cue list

Flag Short Description
--path -C Colony resolution start directory

Lists cues sorted by id (id + optional description).

paseka cue run

Flag Short Required Description
<id> yes Cue id (filename without .yaml)
<text> yes Operator text (Text / Title / Body in templates)
--trace Attach to existing flight trail (new trace when omitted; cue energy_budget ignored when trail already seeded)
--set Template override key=val (repeatable; unused keys ignored)
--path -C Colony resolution start directory 
paseka cue list
paseka cue run feature "OAuth callback returns 500 on refresh"
paseka cue run hotfix "Fix nil deref in token refresh"
paseka cue run feature "Follow-up" --trace trace-abc123

paseka signal

Publish a domain event directly to the NATS bus (manual choreography / testing).

Flag Short Required Default Description
--type yes SIGNAL, INSIGHT, MUTATION, or VERIFICATION
--payload yes JSON object (include kind for task lifecycle events)
--trace auto Flight trail id
--agent cli Agent id on the event envelope
--path -C Colony resolution start directory 
# Plan tasks (scout output shape)
paseka signal --type INSIGHT --trace trace-1 \
  --payload '{"kind":"task.plan","tasks":[{"taskId":"task-1","title":"Add endpoint","bee":"builder"}]}'

# Mark task ready for the reactor
paseka signal --type SIGNAL --trace trace-1 \
  --payload '{"kind":"task.ready","taskId":"task-1","bee":"builder"}'

Event contracts: task ledger, .paseka/prompts/_partials/emit-howto.md and type-scoped emit partials.

paseka event

Validate and publish bus events with machine-readable feedback. This is the intended agent publish path.

By default, emit publishes to JetStream immediately. With --defer, the event is validated and appended to a per-run pending queue (.paseka/runs/<traceId>/<agentId>/pending.ndjson); runtime flushes FIFO on successful AFK or interactive session completion. Failed or cancelled runs leave pending on disk for inspect / manual flush. --defer requires an existing run directory for the event's traceId and agentId — missing run dir fails closed.

Trail comb artifacts (014) use runtime scan flush on success and do not depend on this buffer. See 015 for the general deferred-emit contract.

Live-only kinds (CLI rejects --defer): system.kill, energy.add, energy.consume, session.invite, beekeeper.ready, task.status.

paseka event emit

Flag Short Required Default Description
--stdin yes Read one JSON event object from stdin
--defer false Queue for flush on successful run/session completion instead of publishing now
--agent agent Default agent id when omitted from JSON
--path -C Colony resolution start directory 
paseka event emit --stdin <<'EOF'
{"traceId":"trace-1","agentId":"agent-1","type":"VERIFICATION","payload":{"kind":"verification.success","summary":"All requirements met"}}
EOF

End-of-run handoff (deferred until successful exit):

paseka event emit --defer --stdin <<'EOF'
{"traceId":"trace-1","agentId":"agent-1","type":"INSIGHT","payload":{"kind":"task.plan","tasks":[{"taskId":"task-1","title":"Add endpoint","bee":"builder"}]}}
EOF

Live success response:

{"ok":true,"traceId":"trace-1","type":"VERIFICATION","kind":"verification.success","subject":"paseka.events.VERIFICATION.verification.success","eventLogPath":"/path/to/.paseka/runs/trace-1/agent-1/events.ndjson"}

Deferred success response:

{"ok":true,"deferred":true,"traceId":"trace-1","type":"INSIGHT","kind":"task.plan","pendingPath":"/path/to/.paseka/runs/trace-1/agent-1/pending.ndjson"}

Validation failure:

{"ok":false,"error":"schema_validation_failed","details":[{"path":"payload.summary","message":"required"}]}

Defer denied (live-only kind):

{"ok":false,"error":"defer_denied","details":[{"path":"payload.kind","message":"kind \"session.invite\" cannot be deferred; use live emit"}]}

paseka event validate

Same stdin input as emit, but validates only and does not publish.

paseka event validate --stdin <<'EOF'
{"traceId":"trace-1","type":"INSIGHT","payload":{"kind":"task.plan","tasks":[{"taskId":"task-1","title":"Add endpoint"}]}}
EOF

paseka event pending

Show deferred event count and kinds for a run (does not read raw pending.ndjson by hand).

Flag Short Required Description
--trace yes Flight trail id
--agent yes Agent run id
--path -C Colony resolution start directory 
paseka event pending --trace trace-1 --agent agent-1

paseka event flush

Publish pending events FIFO, or discard without publishing. Uses the same flush path as runtime on successful completion. Mid-flush publish errors stop at the first failure; already-published events stay on the bus and remaining items stay queued for retry.

Flag Short Required Description
--trace yes Flight trail id
--agent yes Agent run id
--discard Clear pending queue without publishing
--path -C Colony resolution start directory 
paseka event flush --trace trace-1 --agent agent-1
paseka event flush --trace trace-1 --agent agent-1 --discard

paseka inspect

Filesystem projections for flight trails and runs (no NATS).

paseka inspect usage

Show LLM token usage from result.json projections — trace aggregate by default, or one run with --agent. Mirrors Queen Console trace/run usage fields (inputTokens, outputTokens, cache read/write). Only Cursor AFK runs report usage today; others print usage: (none).

Flag Short Required Description
--trace yes Flight trail id
--agent Agent id (single run; omit for trace aggregate)
--path -C Colony resolution start directory 
paseka inspect usage --trace trace-1
paseka inspect usage --trace trace-1 --agent agent-abc

paseka energy

Manage per-trace honey reserve (energyToken).

paseka energy show

Flag Short Required Description
--trace yes Flight trail id
--path -C Colony resolution start directory

paseka energy add

Inject honey into a trace (SIGNAL / energy.add). When paseka run is active, the command publishes only and the reactor projects the ledger update (avoids double-counting). When the reactor is stopped, the CLI applies the event locally after publish so energy show reflects the top-up immediately.

Blocked tasks with exhausted reserve are unblocked when the reactor is running.

Flag Short Required Description
--trace yes Flight trail id
--amount yes Positive number of tokens to add
--path -C Colony resolution start directory 
paseka energy show --trace trace-1
paseka energy add --trace trace-1 --amount 5

paseka kill

Hard-kill a trace (SIGNAL / system.kill). Cancels non-terminal tasks, stops new AFK dispatch, and cancels in-flight adapter processes for that traceId. Does not stop interactive sessions — use paseka session stop for those.

When paseka run is active, the command publishes and waits for the ledger projection. When the reactor is stopped, the CLI applies the event locally after publish.

Flag Short Required Description
--trace yes Flight trail id
--reason Optional summary recorded on cancelled tasks
--path -C Colony resolution start directory 
paseka kill --trace trace-1
paseka kill --trace trace-1 --reason "dispute avalanche"

paseka colony

Colony configuration projections (filesystem only — no NATS).

paseka colony topology

Print the colony EDA topology as a Mermaid flowchart derived from .paseka/bees/*.yaml and .paseka/colony.yaml auto_invites. Emits the same Mermaid string as Queen Console GET /api/colony/topology for the same colony root. Useful for docs, PRs, and offline inspection when paseka run is stopped.

Flag Short Description
--path -C Colony resolution start directory
--out Write Mermaid to file instead of stdout 
paseka colony topology
paseka colony topology --out docs/colony-topology.mmd
paseka colony topology -C /path/to/repo

See specs/007-colony-eda-topology.md for graph semantics (subscribe/publish/invite edges, implicit task.ready, intent annotations).

paseka nuc

Export and import portable Nuc packs (bee YAML + prompts) between Colonies. Full format and conflict policy: nuc.

paseka nuc export

Flag Short Default Description
--output -o stdout Write nuc file; prints path when set
--bees all roles Comma-separated bee roles to export
--name colony slug metadata.name in the nuc file
--description Optional metadata.description
--path -C cwd Colony resolution start directory 
paseka nuc export -o minimal.nuc.yaml
paseka nuc export --bees scout,builder -o scout-builder.nuc.yaml

paseka nuc import <file|url|->

Flag Default Description
--force off Overwrite existing bee and prompt files
--dry-run off Show import plan without writing
--verbose / -v off List created, skipped, and overwritten paths
--path / -C cwd Colony resolution start directory

Default conflict policy is skip (same as paseka init for existing files). Use --force to replace whole files. No field-level merge — use git to review imports.

paseka nuc import ./minimal.nuc.yaml
paseka nuc import https://example.com/nucs/dev.nuc.yaml --dry-run -v
paseka nuc import ./dev.nuc.yaml --force

paseka gate

Human Gateway surfaces outside Queen Console. MVP: Telegram only.

paseka gate telegram

Long-poll Telegram Bot API for one colony: push notifications, /status /energy /task /invites /help, optional commands.custom emit: signal slash commands, invite and proposal buttons. Separate process from paseka run. Requires machine-local ~/.config/paseka/<slug>/telegram.yaml and NATS.

Flag Short Default Description
--path -C cwd Directory inside the git repository 
paseka gate telegram
paseka gate telegram -C /path/to/repo

Setup, allowlist, and command reference: Telegram gateway. Design: specs/010-telegram-human-gateway.md.

paseka console

Start the local Queen Console web UI (embedded SPA + JSON API).

Flag Short Required Default Description
--addr 127.0.0.1:8787 Listen address (keep on localhost unless you understand the exposure risk)
--path -C Colony resolution start directory 
paseka console
paseka console --addr 127.0.0.1:8787

Open the printed URL in a browser. Queen Console does not enforce authentication yet.

Useful surfaces for HITL: Reviews tab lists waiting_review tasks; for final merge gates (review: final / _review) it shows a side-by-side worktree merge preview before approve. Prefer previewing there, then approve via the UI or paseka proposal approve. Full baseline: specs/002-queen-console-mvp.md.

paseka proposal

Human-in-the-loop actions for code proposals (MUTATION with kind: code.proposal.isolated, code.proposal.root, or legacy alias code.proposal).

paseka proposal approve

Approve a review-gated task and publish VERIFICATION / task.completed. Behavior branches on proposal workspace:

Task context Merge trace worktree? Auto-commit?
Isolated final gate (review: final / _review, proposalWorkspace: isolated) Yes, when worktree exists Yes (merge commit)
Root soft gate (proposalWorkspace: root, review: required) No (R1 ack) No
Isolated review: required mid-task No (unless final gate) No

For isolated final merge gates, preview the accumulated worktree diff in Queen Console Reviews first (paseka console). Root approve advances the ledger only — beekeeper commits .paseka/ / docs/ changes on colony root manually.

Flag Short Required Default Description
--trace yes Flight trail id
--task yes Review task id (e.g. task-1, _review, or a review: final task)
--summary approved by human VERIFICATION/task.completed completion note (not INSIGHT/trace.summary)
--merge-message Merge commit subject for isolated final gate (optional HITL body); distinct from INSIGHT/trace.summary, which supplies the default merge body
--path -C Colony resolution start directory

paseka proposal reject

Reject a review-gated task — publishes human INSIGHT / human.feedback. Tasks with review: required return to ready for another AFK pass when paseka run is active.

Flag Short Required Default Description
--trace yes Flight trail id
--task yes Task id
--feedback Please revise the proposal. Message for the bee
--path -C Colony resolution start directory 
# Isolated final gate — may print merge commit SHA
paseka proposal approve --trace trace-1 --task _review --summary "LGTM, merged"
# Root soft ack — no merge commit line
paseka proposal approve --trace trace-1 --task task-cfg-1 --summary "Config changes acknowledged"
paseka proposal reject --trace trace-1 --task task-1 --feedback "Use the existing auth middleware"

paseka export

Write a self-contained HTML report for one flight trail to the current working directory. The file includes trace overview, tasks, runs (oldest first), and the full event timeline (oldest first) with expandable raw JSON per event. Styling matches Queen Console (dark theme, JetBrains Mono from CDN with system fallbacks).

Flag Short Required Description
--trace yes Flight trail id
--path -C Colony resolution start directory

Output file: paseka-export-<slug>-<traceId>.html in the current working directory.

Data is read from .paseka/runs/ (same as Queen Console). Task and energy fields prefer JetStream KV when NATS is configured; otherwise filesystem projections are used.

paseka export --trace trace-abc123
paseka export --trace trace-abc123 -C /path/to/repo

paseka purge

Remove ephemeral colony artifacts. Without --yes, shows a plan and asks for confirmation.

Flag Short Description
--runs Remove .paseka/runs/ trace directories
--worktrees Remove .paseka/worktrees/ and associated git worktrees
--cache Remove .paseka/cache/
--state Reset ~/.config/paseka/<slug>/state.json worktree registry
--bus Remove JetStream task-ledger KV, stream events, and object-store artifacts for --trace (requires NATS)
--trace Flight trail id (required with --bus)
--reseed-energy After --bus purge, seed honey to colony defaults.energy_budget (requires --bus and --trace)
--all Purge runs, worktrees, cache, and state (does not include --bus)
--yes -y Skip confirmation prompt
--path -C Colony resolution start directory

At least one target flag (--runs, --worktrees, --cache, --state, --all, or --bus) is required.

--bus behavior: Deletes the task-ledger KV entry for the trace (tasks, energy reserve), domain events for that traceId from the JetStream event stream, and trace-scoped object-store artifacts (<traceId>-*.diff). Requires a configured nats.url and --trace. Not included in --all — pass --bus explicitly when resetting bus state.

Stop the reactor first: Stop paseka run before purge --bus so the reactor is not reading or writing task-ledger KV while keys and stream messages are deleted. Running bus purge against an active reactor can cause races and stale in-memory state.

--reseed-energy: Operator hygiene for retrying work on a fixed trace — after a successful --bus purge, seeds the trace honey reserve (budget and remaining) to the colony defaults.energy_budget (same source as reactor first seed). Works with the reactor stopped; verify with paseka energy show --trace <id>. Not an eval harness command.

paseka purge --runs --yes
paseka purge --all

# Reset bus state and reseed honey for a fixed trace (retry after failed run)
paseka purge --bus --trace my-trace --reseed-energy --yes

# Eval case reset (filesystem + bus for one fixed trace)
paseka purge --runs --worktrees --state --bus --trace eval-01-add-function --yes

Typical workflows

First-time setup

paseka init                    # Cursor adapter (default)
paseka init --adapter pi       # Pi adapter
agent login                    # or export CURSOR_API_KEY (cursor init)
docker compose up -d           # local NATS + JetStream
paseka doctor

One-shot scout → builder (no reactor)

TRACE=$(paseka bee run scout --body "Plan user settings page" | awk '/trace:/ {print $2}')
paseka bee run builder --trace "$TRACE" --body "Implement settings form"

Choreographed run with reactor

paseka run &                   # background reactor
paseka task create --title "Add health check" --body "Implement /healthz" --bee builder --autorun
paseka task list --trace <printed-trace>
paseka replay <printed-trace>

Manual plan + start

paseka run &                   # background reactor
paseka signal --type INSIGHT --trace trace-1 \
  --payload '{"kind":"task.plan","tasks":[{"taskId":"task-1","title":"Add health check","bee":"builder"}]}'
paseka task start --trace trace-1
paseka task list --trace trace-1
paseka replay trace-1

Interactive design session

paseka bee chat scout "Let's design the notification system"
paseka session list
paseka session stop <sessionId>

Feature ideation (soft path)

Manual Phase 0 flow for raw ideas → spec → task ledger. See specs/005-feature-ideation-flow.md.

Ideation SIGNAL kinds (feature.requested, feature.classified, spec.ready) are colony choreography contracts — field shapes are defined in the ideation spec and bee emit partials, not enforced by internal/protocol. Platform HITL kinds (session.invite, beekeeper.ready) are documented in specs/006-human-gateway-invites.md.

TRACE=trace-$(date +%s)
paseka signal --type SIGNAL --trace "$TRACE" \
  --payload '{"kind":"feature.requested","title":"…","body":"…"}'
paseka bee run scout --intent intake --trace "$TRACE" \
  --body "Intake the feature.requested on this trail"
# With paseka run up and default auto_invites: invite list shows pending grilling invite
paseka invite accept <inviteId>
# Or manual path before accept:
# paseka bee chat drone --intent grilling --trace "$TRACE" "Grill: …"
# After grilling writes docs/specs/… and emits spec.ready:
paseka bee chat drone --intent breakdown --trace "$TRACE" "Break down docs/specs/…"

Session invites (Human Gateway)

paseka invite list [--trace <id>] [--status pending|accepted|completed|incomplete]
paseka invite record --trace "$TRACE" --bee drone --intent grilling --body "Grill: …"
paseka invite accept <inviteId>          # detached session; costs 1 honey; attach with session attach
paseka invite accept <inviteId> --attach # attach terminal immediately
paseka invite reject <inviteId>
paseka invite reject <inviteId> --defer  # mark deferred

Accept consumes 1 honey from the trace reserve. If exhausted, invite stays pending — run paseka energy add --trace "$TRACE" --amount 1 (or more) and retry. Ad-hoc bee chat does not consume honey.

Invite statuses: pending, accepted, completed, incomplete, cancelled, deferred. Accepted invites become completed when a bus event matches the invite's persisted done_when contract (optional file-at-ref check); incomplete when the session ends without a valid artifact.

Seed offline with invite record, or configure auto_invites in .paseka/colony.yaml so paseka run auto-publishes when a matching bus event arrives. With empty auto_invites, no auto-invite runs. Accept publishes beekeeper.ready and starts an interactive session on the same traceId.

See specs/006-human-gateway-invites.md and bee routing §7–8.

Doc Topic
Brief Product vision, EDA, NATS role
architecture overview Colony layout, adapters, runs IPC
prompt templates Prompt template resolution
task ledger Task lifecycle events on the bus
interactive sessions bee chat, sessions, Ghostty
Telegram gateway Setup and run paseka gate telegram
specs/005-feature-ideation-flow.md Feature ideation soft path (intake → grill → breakdown)
specs/006-human-gateway-invites.md Session invites, auto_invites, done_when
specs/010-telegram-human-gateway.md Telegram Human Gateway design