diff --git a/skills/paseo/SKILL.md b/skills/paseo/SKILL.md index 700d61bcf..d4f458c2e 100644 --- a/skills/paseo/SKILL.md +++ b/skills/paseo/SKILL.md @@ -1,11 +1,9 @@ --- name: paseo -description: Use when entering orchestrator mode to manage agents via Paseo CLI +description: Paseo CLI reference for managing agents. Load this skill whenever you need to use paseo commands. --- -### Paseo CLI Commands - -Use these CLI commands to manage agents: +## CLI Commands ```bash # List agents (directory-scoped by default) @@ -78,86 +76,31 @@ paseo ls --json # JSON output paseo ls -q # IDs only (quiet mode, useful for scripting) ``` -### Available Models +## Available Models -**Claude (default provider)** - use aliases, CLI resolves to latest version: -- `--model haiku` - Fast/cheap, ONLY for tests (not for real work) -- `--model sonnet` - Default, good for most tasks -- `--model opus` - For harder reasoning, complex debugging +**Claude (default provider)** — use aliases, CLI resolves to latest version: +- `--model haiku` — Fast/cheap, ONLY for tests (not for real work) +- `--model sonnet` — Default, good for most tasks +- `--model opus` — For harder reasoning, complex debugging **Codex** (`--provider codex`): -- `--model gpt-5.4` - Latest frontier agentic coding model (default, preferred for all engineering tasks) -- `--model gpt-5.1-codex-mini` - Cheaper, faster, but less capable +- `--model gpt-5.4` — Latest frontier agentic coding model (default, preferred for all engineering tasks) +- `--model gpt-5.1-codex-mini` — Cheaper, faster, but less capable -### Permissions +## Permissions Always launch agents fully permissioned. Use `--mode bypass` for Claude and `--mode full-access` for Codex. Control behavior through **strict prompting**, not permission modes. -### Agent Use Cases +## Waiting for Agents -You can run agents to: -- **Implement a task** - Spawn an agent to write code and implement features -- **Have a design discussion** - Use Codex for architecture discussions -- **Test some feature** - Run tests and verify functionality -- **Do investigation** - Research and explore the codebase -- **Review changes** - Use Codex for thorough code reviews - -### Clarifying Ambiguous Requests - -**CRITICAL:** When user requests are ambiguous or unclear: - -1. **Research first** - Spawn an investigation agent to understand the current state -2. **Ask clarifying questions** - After research, ask the user specific questions about what they want -3. **Present options** - Offer multiple approaches with trade-offs -4. **Get explicit confirmation** - Never assume what the user wants - -### Investigation vs Implementation - -**CRITICAL:** When asked to investigate: - -- **Investigation agents MUST NOT fix issues** - They should only identify, document, and report problems -- **Always ask for confirmation** - After investigation, present findings and ask: "Should I proceed with implementing fixes?" -- **Only implement if explicitly requested** - Don't auto-fix without user approval - -### Rigorous Agent Interrogation - -**CRITICAL:** Agents start with ZERO context about your task. You must always provide complete context in your initial prompt. - -When working with agents, you must dig deep and challenge them rigorously: - -#### For Implementation Agents - -- **Don't accept surface-level completion**: Check their logs with `paseo logs ` -- **Trace the implementation**: Ask them to walk through the code flow step by step -- **Uncover gaps**: Send follow-up prompts with `paseo send ""` - - "Show me exactly where you handle error case X" - - "What happens if the user does Y before Z?" - - "Walk me through the data flow from input to output" - -#### For Investigation/Debugging Agents - -- **Don't stop at the first answer**: Keep digging deeper -- **Explore different angles**: "What are 3 other possible causes?" -- **Request proof**: "Show me the specific code that proves this hypothesis" -- **Challenge assumptions**: "How do you know that's the root cause?" - -#### For Review Agents (prefer Codex) - -- **Security review**: "What are the security implications? Any OWASP vulnerabilities?" -- **Edge cases**: "What edge cases are not handled?" -- **Performance**: "Where are the performance bottlenecks?" -- **Maintainability**: "How maintainable is this code?" - -### Waiting for Agents - -**CRITICAL:** Both `paseo run` and `paseo wait` block until the agent completes. Trust them. +Both `paseo run` and `paseo wait` block until the agent completes. Trust them. - `paseo run` waits **forever** by default (no timeout). Use `--wait-timeout` to set a limit. - `paseo wait` also waits forever by default. Use `--timeout` to set a limit. - Agent tasks can legitimately take 10, 20, or even 30+ minutes. This is normal. - When a wait times out, **just re-run `paseo wait `** — don't panic, don't start checking logs, don't inspect status. The agent is still working. -- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent. This wastes your context window and accomplishes nothing. -- Only check logs/inspect if you have a **specific reason** to believe something is wrong (e.g., you sent a prompt and got an unexpected error back). +- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent. +- Only check logs/inspect if you have a **specific reason** to believe something is wrong. - **Never launch a duplicate agent** because a wait timed out. The original is still running. ```bash @@ -166,35 +109,14 @@ paseo wait # timed out? just run it again: paseo wait # still going? keep waiting: paseo wait --timeout 300 # or use a longer timeout -# For long-running tasks, set a generous timeout on run itself: -paseo run --wait-timeout 1h --output-schema '...' "" - # Wrong: anxious polling loop paseo wait # timed out paseo ls # is it still running?? paseo inspect # what's it doing?? paseo logs # let me check the logs!! -# ^ Don't do this. Trust the wait. ``` -### Agent Management Principles - -- **Keep agents focused** - Each agent should have a clear, specific responsibility -- **You can talk to them** - Use `paseo send ""` to guide them -- **Monitor progress** - Use `paseo logs -f` to stream output -- **Always provide context** - Remember: agents start with zero knowledge of your task -- **Verify work rigorously** - Don't trust, verify. Ask agents to prove their work -- **Commit frequently** - Ensure each agent commits their changes before moving on -- **Plan for quality gates** - Use Codex review agents as checkpoints -- **Run in parallel when possible** - Use `-d` flag to run multiple agents concurrently - -### Common Patterns - -#### Committee - -When stuck or planning something hard, use the `/committee` skill. It launches two high-reasoning agents (Opus 4.6 + GPT 5.4) in parallel to do root cause analysis and produce a plan, then stays alive to review the implementation afterward. - -### Composing Agents in Bash Scripts +## Composing Agents in Bash `paseo run` blocks by default and `--output-schema` returns structured JSON, making it easy to compose agents in bash loops and pipelines. @@ -220,7 +142,4 @@ ui_id=$(paseo run -d --name "UI impl" "implement the UI" -q) # Wait for both to finish paseo wait "$api_id" paseo wait "$ui_id" - -# Review the combined result -paseo run --provider codex "review the API and UI implementations. DO NOT edit." ```