Add detached agents and heartbeat scheduling (#1266)

skills/paseo-advisor/SKILL.md

@@ -13,7 +13,7 @@ Single agent. Reads the situation you're in. Gives a judgment. You decide what t
 
 ## Prerequisites
 
-Read the **paseo** skill — provider for the advisor comes from orchestration preferences unless the user names one.
+Read the **paseo** skill. Before choosing a provider, read `~/.paseo/orchestration-preferences.json` unless the user explicitly named a provider in this request. Do not create the advisor until you have read it.
 
 ## Picking the advisor
 

skills/paseo-committee/SKILL.md

@@ -14,14 +14,16 @@ The purpose is to step back, not double down. The committee may propose a comple
 
 ## Prerequisites
 
-Read the **paseo** skill. Contrast is the point of a committee, so pick across providers deliberately rather than using whatever the default category would resolve to.
+Read the **paseo** skill. Before choosing committee members, read `~/.paseo/orchestration-preferences.json` unless the user explicitly named providers in this request. Do not create committee agents until you have read it.
+
+Contrast is the point of a committee, so pick across providers deliberately using the configured preferences rather than hardcoded defaults.
 
 ## Composition
 
-Two members with different reasoning styles:
+Two members with different reasoning styles, selected from orchestration preferences:
 
-- **Claude Opus** with extended thinking on
-- **Codex GPT-5.4** with thinking on
+- one planning/research-strength provider
+- one contrasting high-reasoning provider
 
 Override only when the user explicitly asks for different members.
 

skills/paseo-epic/SKILL.md

@@ -17,6 +17,8 @@ This usually runs for hours, often overnight. By the time agents are working, yo
 
 This is a Paseo skill. Load the **paseo** skill first — it carries the surface (worktrees, agents, waiting, scheduling, preferences). Every agent you spawn reads it too.
 
+Before choosing any provider, read `~/.paseo/orchestration-preferences.json`. Do not create planner, reviewer, researcher, implementer, or auditor agents until you have read it.
+
 **Do not use your own subagents.** All agents in this skill are Paseo agents, spawned through the Paseo MCP. Your harness's native subagent stack is not in play here.
 
 The role and phase-type vocabulary lives in the roles reference shipped with this skill (`references/roles.md`).

skills/paseo-handoff/SKILL.md

@@ -12,7 +12,7 @@ Transfer the current task — context, decisions, failed attempts, constraints
 
 ## Prerequisites
 
-Read the **paseo** skill — provider for the receiving agent comes from orchestration preferences unless the user names one.
+Read the **paseo** skill. Before choosing a provider, read `~/.paseo/orchestration-preferences.json` unless the user explicitly named a provider in this request. Do not create the receiving agent until you have read it.
 
 ## Parsing arguments
 
@@ -29,7 +29,7 @@ The receiving agent has zero context. Include:
 [Imperative description.]
 
 ## Context
-[Why this task exists, background needed.]
+[Why this task exists, required context.]
 
 ## Relevant files
 - `path/to/file.ts` — [what it is and why it matters]
@@ -54,6 +54,8 @@ The receiving agent has zero context. Include:
 
 ## Launch
 
-Create the agent via Paseo with a `[Handoff] <task>` title, the briefing as initial prompt, and cwd set to the worktree path if `--worktree`.
+Create the agent via Paseo with a `[Handoff] <task>` title, the briefing as initial prompt, `detached: true`, and cwd set to the worktree path if `--worktree`. Leave `notifyOnFinish` omitted unless the user explicitly wants no callback.
+
+Handoff agents are siblings/root agents, not your subagents. They must survive you being archived and must not appear in your subagent track.
 
 Don't wait by default — the user decides whether to follow along or move on. Tell them the agent ID and how to follow along (the paseo skill explains).

skills/paseo-loop/SKILL.md

@@ -12,7 +12,7 @@ A loop is a worker/verifier cycle: launch a worker → check verification → re
 
 ## Prerequisites
 
-Read the **paseo** skill for orchestration preferences — worker and verifier providers come from preferences unless the user names them.
+Read the **paseo** skill. Before choosing worker or verifier providers, read `~/.paseo/orchestration-preferences.json` unless the user explicitly named providers in this request. Do not start the loop until you have read it.
 
 Loops are a CLI primitive: `paseo loop run`. Manage with `paseo loop ls`, `paseo loop inspect <id>`, `paseo loop logs <id>`, `paseo loop stop <id>`.
 

skills/paseo/SKILL.md

@@ -20,13 +20,21 @@ Returns `{ branchName, worktreePath }`. Pass `cwd` to target a specific repo.
 
 ## Agents
 
-**`create_agent`** — required: `title`, `provider` (`claude/opus`, `codex/gpt-5.4`, …), `initialPrompt`. Common: `cwd` (often a `worktreePath`), `background` (default `false` — blocks until completion or permission), `notifyOnFinish`, `settings`. Returns `{ agentId, … }`.
+**`create_agent`** — required: `title`, `provider` (`claude/opus`, `codex/gpt-5.4`, …), `initialPrompt`. Common: `cwd` (often a `worktreePath`), `notifyOnFinish`, `settings`, `detached`. Returns `{ agentId, … }`.
 
 Initial runtime settings live under `settings`: `modeId`, `thinkingOptionId`, and provider-specific `features`. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }` when creating the agent.
 
 Compose: call `create_worktree` first, then `create_agent` with `cwd` set to the returned `worktreePath`.
 
-**`send_agent_prompt`** — `{ agentId, prompt }`. Blocks by default; pass `background: true` to fire-and-forget.
+### Agent relationships
+
+Agents you create default to **your subagents**: omit `detached` or pass `detached: false`. Use this for advisors, committee members, planners, implementers, auditors, loop workers, and any agent whose lifetime belongs to your task. Subagents appear under you and are archived with you.
+
+Pass `detached: true` only when the agent you create should stand on its own, not help you finish your task. Use this for handoffs and fire-and-forget delegations the user may continue after you are archived. Detached agents do not appear in your subagent track and are not archived with you.
+
+For subagents, leave `notifyOnFinish` omitted or set it to `true`. You will get notified when the created agent finishes, errors, or needs permission. Set `notifyOnFinish: false` only when the created agent is truly fire-and-forget and you do not need to follow up.
+
+**`send_agent_prompt`** — `{ agentId, prompt }`. Use for follow-ups to an existing agent.
 
 **`update_agent`** — `{ agentId, name?, labels?, settings? }`. Use `settings` for runtime changes on an existing agent: `modeId`, `model`, `thinkingOptionId`, and provider-specific `features`. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }`.
 
@@ -44,9 +52,11 @@ Compose: call `create_worktree` first, then `create_agent` with `cwd` set to the
 
 Only set feature IDs returned by `inspect_provider`. For Codex fast mode, look for `fast_mode` and pass `settings: { features: { "fast_mode": true } }` to `create_agent` or `update_agent`.
 
-## Heartbeats
+## Schedules and heartbeats
 
-**`create_schedule`** — required: `prompt`. Pick one of `cron` or `every` (`"5m"`, `"1h"`). Optional: `name`, `target` (`self` | `new-agent`), `provider`, `maxRuns`, `expiresIn`. Use for periodic checks on long-running work or recurring maintenance.
+**`create_schedule`** — starts a new agent on a cron cadence. Required: `prompt`, `cron`, `provider`. Optional: `timezone`, `name`, `cwd`, `maxRuns`, `expiresIn`. Use when the recurring work should live in fresh agents.
+
+**`create_heartbeat`** — sends you a prompt on a cron cadence. Required: `prompt`, `cron`. Optional: `timezone`, `name`, `maxRuns`, `expiresIn`. Use for reminders, PR/build babysitting, and status checks that should return to this conversation.
 
 ## Models
 
@@ -54,7 +64,7 @@ Only set feature IDs returned by `inspect_provider`. For Codex fast mode, look f
 
 ## Orchestration preferences
 
-User-specific configuration at `~/.paseo/orchestration-preferences.json`. **Any paseo skill that picks an agent reads this file.** Never hardcode a provider string in another skill — resolve through this file.
+User-specific configuration at `~/.paseo/orchestration-preferences.json`. **Before any Paseo skill chooses a provider or creates an agent, it must read this file.** Reading means an actual file read, not relying on these examples or defaults. Never hardcode a provider string in another skill — resolve through this file.
 
 Two parts:
 
@@ -84,7 +94,7 @@ If the file is missing, use sensible defaults and tell the user once.
 
 Agents take time — 10–30+ minutes is routine. Favor asynchronous workflows.
 
-For every `create_agent` or `send_agent_prompt`, pass `background: true` and `notifyOnFinish: true`. Paseo delivers a notification to your conversation when the agent finishes, errors, or needs permission. **You must not call `wait_for_agent` on a notify-on-finish agent.** Move on to other work. The notification arrives on its own.
+For `create_agent`, leave `notifyOnFinish` omitted or set it to `true` unless the created agent is truly fire-and-forget. You will get notified when the created agent finishes, errors, or needs permission. **You must not call `wait_for_agent` on a notify-on-finish agent.** Move on to other work. The notification arrives on its own.
 
 Don't poll `list_agents` or `get_agent_status` to "check on" a running agent. The notification will tell you.
 
@@ -97,7 +107,7 @@ paseo run --provider codex/gpt-5.4 --mode full-access --worktree feat/x "<prompt
 paseo send <agent-id> "<follow-up>"
 paseo ls
 paseo worktree ls
-paseo schedule create --every 5m "ping main build"
+paseo schedule create --cron "*/15 * * * *" "ping main build"
 ```
 
 Discover with `paseo --help` and `paseo <cmd> --help`.