Fan Solo

Fan Solo

Treat Solo as a native workspace around existing CLI agents, terminals, and project commands—not as an IDE, agent provider, container manager, or proof that work completed.

Enforce process authority first

Before any input, stop, restart, close, rename, output clear, UI selection, or timer delivery, prove target is current process or a recorded descendant spawned by current actor. Project membership, process name, idle/stopped/completed state, and cleanup intent never prove ownership. For parent, sibling, unrelated, YAML-backed shared process, or another actor's descendant, require explicit user or runbook authority naming exact target and action.

Establish live context

Use sources in this order before acting:

1. Call Solo whoami; confirm actor, Solo process, and effective project.
2. Call help() for current overview, then help(topic=...) for relevant workflow. Use help(topic="docs") when documentation lookup is needed.
3. Consult live Solo Docs MCP or current official docs when behavior, schema, availability, or version matters.
4. Use bundled references for routing and house style, never as fresher authority than live runtime or docs.

Do not assume every documented tool is enabled. Discover current surface.

Route intent

For ambiguous or multi-surface requests, read capability map before selecting skills. Use fewest skills that fully cover task.

Choose agent mode

Default to one agent for sequential work, shared-state edits, or one coherent judgment loop. Use $solo-work-with-agents for that lifecycle.

Use $solo-orchestrate-agents only when at least two lanes are independent enough to own separately. Lead owns decomposition, boundaries, integration, and final verification. Workers own bounded lanes—not whole goal. A parenting agent writes coordination state, final synthesis, and at most mechanical integration-seam glue—a no-code lead delegates even that: assign every separable artifact change—including rework—to a worker lane, and take back concise evidence and artifact paths, not whole pasted output.

Evidence-gathering lanes are ordinary orchestration: $solo-orchestrate-agents supplies the worker mechanics, timers, and handoffs. Provider selection, citation discipline, and research synthesis are not Solo capabilities—they come from whatever research method or skill the session already carries.

Load routing-agent-work through the current host when installed and a lane needs model selection. Use house style for Solo mechanics.

Choose durable state

• Scratchpad: plans, findings, decisions, evidence, handoff context.
• Todo: actionable owned lane, acceptance criteria, blockers, status, comments.
• Todo comment: task-local progress and final handoff.
• KV: small temporary/discoverable JSON, never prose or completion proof.
• Lock: short-lived collision signal, never authorization or permanent ownership.
• Timer: wake-up/resumption, never proof worker or service finished. Prefer Solo timers over shell sleep or ad-hoc polling loops whenever Solo is available.
• Prompt template: reusable dispatch text, never current project truth.
• Repository docs: reconciled durable project behavior and decisions.

Keep the live set ephemeral. Complete or backlog todos, promote durable conclusions as evidence lands, and cancel obsolete timers and locks; archive a scratchpad or delete a record only after its recorded consumers have consumed it at the current revision. An unconsumed handoff outlives its producing lane, though stale todos and orphaned scratchpads remain noise once safe to retire. When a whole run ends with residue across several surfaces, route reconciliation to $solo-close-out-work—it promotes durable content first, then retires the ephemeral copy without losing incomplete work.

Read house style before spawning agents, mutating shared state, or controlling processes.

Protect ownership and safety

• Manage only current process and descendants it spawned. Never infer authority over parent, sibling, unrelated, or shared YAML-backed process from idleness, stopped state, or cleanup intent.
• Use explicit project and process IDs when scope is ambiguous. Record returned child IDs.
• Treat command trust, locks, and identity as separate gates. Never bypass trust or treat lock as permission.
• Ask before destructive or externally visible action unless user already authorized exact target and effect.
• Preserve unrelated files, processes, todos, scratchpads, and concurrent work.

Complete with evidence

Verify at task's real boundary: process output/status, bound port or service readiness, changed artifact or diff, relevant tests/checks, and durable todo/scratchpad handoff as applicable. Idle, prompt delivery, agent summary, successful tool call, or lock ownership alone is insufficient.

Before closing owned descendants: capture useful output, update todo/comment or scratchpad, cancel stale timers, release owned locks, and confirm acceptance checks. Close only when requested or clearly part of authorized workflow.

Use sources when resolving provenance, product boundaries, or changing behavior.