puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(skills): strip orchestrator concerns from paseo skill

Browse Source 
Paseo skill is now a pure CLI reference — commands, models,
permissions, waiting guidelines, and bash composition patterns.
Orchestrator-specific guidance (agent interrogation, investigation
vs implementation, management principles, committee patterns) moved
to the new paseo-orchestrator skill.
This commit is contained in:
Mohamed Boudra
2026-03-23 21:52:36 +07:00
parent 27be8c3b1e
commit 2da56634a1
1 changed files with 15 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
skills/paseo/SKILL.md
View File

@@ -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 <id>`
- **Trace the implementation**: Ask them to walk through the code flow step by step
- **Uncover gaps**: Send follow-up prompts with `paseo send <id> "<question>"`
- "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 <id>`** — 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 <id> # timed out? just run it again:
paseo wait <id> # still going? keep waiting:
paseo wait <id> --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 '...' "<prompt>"
# Wrong: anxious polling loop
paseo wait <id> # timed out
paseo ls # is it still running??
paseo inspect <id> # what's it doing??
paseo logs <id> # 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 <id> "<prompt>"` to guide them
- **Monitor progress** - Use `paseo logs <id> -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."
```