puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-10-14 13:22:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: reformat codebase with oxfmt

Browse Source 
Apply prettier-compatible formatting across the repo to match the
incoming oxfmt configuration. Mechanical reformat only — no logic
changes. Covers YAML quote normalization, package.json key sorting,
Markdown/TOML formatting, and minor TS whitespace tweaks.
This commit is contained in:
Mohamed Boudra
2026-04-23 21:44:48 +07:00
parent 9b25f8fc36
commit ce4b0d54c7
81 changed files with 1171 additions and 1009 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/paseo-chat/SKILL.md
+5
View File
@@ -19,6 +19,7 @@ Load the **Paseo skill** first if you need CLI guidance for launching or messagi
## Rules
When using chat:
- create a room with `paseo chat create` if you need a new room
- inspect available rooms with `paseo chat ls` and `paseo chat inspect`
- post with `paseo chat post`
@@ -27,6 +28,7 @@ When using chat:
- check chat often while working
Mentions are active:
- write mentions inline in the message body as `@<agent-id>` to notify a specific agent immediately
- use `@everyone` to notify all non-archived, non-internal agents
- notifications are sent to the target agent without blocking the chat post
@@ -99,10 +101,12 @@ paseo chat wait issue-456 --timeout 60s
## Defaults
When creating a room:
- choose a short slug: `issue-456`, `pr-143-review`, `relay-cleanup`
- give it a clear purpose
When using a room:
- read only a bounded window before acting
- post updates when they would help another agent or your future self
- use `--reply-to` when responding to a specific message
@@ -112,6 +116,7 @@ When using a room:
- your own agent ID is available via `$PASEO_AGENT_ID`
Typical things to post:
- status updates
- blockers
- handoffs
skills/paseo-handoff/SKILL.md
+7 -7
View File
@@ -30,13 +30,13 @@ Parse `$ARGUMENTS` to determine:
### Provider Resolution
| User says | --provider | Mode |
|---|---|---|
| *(nothing)* | `codex/gpt-5.4` | `full-access` |
| `codex` | `codex/gpt-5.4` | `full-access` |
| `claude` | `claude/opus` | `bypass` |
| `opus` | `claude/opus` | `bypass` |
| `sonnet` | `claude/sonnet` | `bypass` |
| User says | --provider | Mode |
| ----------- | --------------- | ------------- |
| _(nothing)_ | `codex/gpt-5.4` | `full-access` |
| `codex` | `codex/gpt-5.4` | `full-access` |
| `claude` | `claude/opus` | `bypass` |
| `opus` | `claude/opus` | `bypass` |
| `sonnet` | `claude/sonnet` | `bypass` |
Default is **Codex** with `gpt-5.4`.
skills/paseo-loop/SKILL.md
+2
View File
@@ -108,6 +108,7 @@ paseo loop stop <id> # Stop a running loop
### Worker prompt
The worker prompt must be:
- self-contained
- concrete about commands, files, branches, tests, PRs, or systems to inspect
- explicit about what counts as progress this iteration
@@ -115,6 +116,7 @@ The worker prompt must be:
### Verifier prompt
The verifier prompt should:
- check facts, not offer fixes
- cite commands, outputs, or file evidence
- be specific about what "done" means
skills/paseo-orchestrate/SKILL.md
+59 -50
View File
@@ -17,6 +17,7 @@ You are an end-to-end implementation orchestrator. You take a task from understa
## Prerequisites
Load these skills before proceeding:
1. **e2e-playwright** — if the task involves frontend/UI work
## Guard
@@ -46,13 +47,13 @@ Merge with defaults for any missing fields. The file maps role categories to `<a
- The part before `/` is the `agentType` (e.g., `codex`, `claude`, `opencode`)
- The part after `/` is the `model` (e.g., `gpt-5.4`, `opus`)
| Category | Roles covered | Default |
|----------|--------------|---------|
| `impl` | impl, tester, refactorer | `codex/gpt-5.4` |
| `ui` | impl agents doing UI/styling work | `claude/opus` |
| `research` | researcher | `codex/gpt-5.4` |
| `planning` | planner, plan-reviewer | `codex/gpt-5.4` |
| `audit` | auditor, qa | `codex/gpt-5.4` |
| Category | Roles covered | Default |
| ---------- | --------------------------------- | --------------- |
| `impl` | impl, tester, refactorer | `codex/gpt-5.4` |
| `ui` | impl agents doing UI/styling work | `claude/opus` |
| `research` | researcher | `codex/gpt-5.4` |
| `planning` | planner, plan-reviewer | `codex/gpt-5.4` |
| `audit` | auditor, qa | `codex/gpt-5.4` |
The file also has a `preferences` array of freeform natural language strings. Read these at startup and weave them into your behavior contextually. When the user says "store my preference: X", update the file.
@@ -90,11 +91,13 @@ To archive: Paseo **archive agent**.
### How to Write Agent Prompts
**Describe the problem, not the solution.** Your prompt should tell the agent:
- What's wrong or what needs to be built (the goal)
- How it currently fails (error output, test output, user-visible behavior)
- The acceptance criteria (what "done" looks like)
**Do NOT tell the agent:**
- Which specific lines to change
- What code to write
- Which functions to call or which patterns to use
@@ -141,43 +144,43 @@ State the order and briefly why: "Order 3 — touches server session management
**Order 1 — Single file, single concern.** A contained change: fix a bug in one function, add a field to one type, update one component.
| Phase | Agents |
|-------|--------|
| Research | 1 researcher |
| Planning | 0 — orchestrator plans inline |
| Implement | 1 impl |
| Verify | 1-2 auditors |
| Cleanup | 0-1 refactorer |
| Phase | Agents |
| --------- | ----------------------------- |
| Research | 1 researcher |
| Planning | 0 — orchestrator plans inline |
| Implement | 1 impl |
| Verify | 1-2 auditors |
| Cleanup | 0-1 refactorer |
**Order 2 — Single module, few files.** A feature or fix within one package that touches 3-8 files.
| Phase | Agents |
|-------|--------|
| Research | 2 researchers |
| Planning | 1 planner |
| Phase | Agents |
| --------- | ---------------- |
| Research | 2 researchers |
| Planning | 1 planner |
| Implement | 1 impl per phase |
| Verify | 2-3 auditors |
| Cleanup | 1 refactorer |
| Verify | 2-3 auditors |
| Cleanup | 1 refactorer |
**Order 3 — Cross-module, multiple packages.** A feature that spans packages.
| Phase | Agents |
|-------|--------|
| Research | 3-4 researchers |
| Planning | 2 planners + 1 plan-reviewer |
| Implement | 1-2 impl agents per phase |
| Verify | 3-4 auditors |
| Cleanup | 1-2 refactorers |
| Phase | Agents |
| --------- | ---------------------------- |
| Research | 3-4 researchers |
| Planning | 2 planners + 1 plan-reviewer |
| Implement | 1-2 impl agents per phase |
| Verify | 3-4 auditors |
| Cleanup | 1-2 refactorers |
**Order 4 — Architectural, system-wide.** A new subsystem, major refactor, or system-wide change.
| Phase | Agents |
|-------|--------|
| Research | 5+ researchers |
| Planning | 2+ planners + 2 plan-reviewers |
| Implement | 2+ impl agents per phase |
| Verify | Full auditor suite per phase |
| Cleanup | 2+ refactorers |
| Phase | Agents |
| --------- | ------------------------------ |
| Research | 5+ researchers |
| Planning | 2+ planners + 2 plan-reviewers |
| Implement | 2+ impl agents per phase |
| Verify | Full auditor suite per phase |
| Cleanup | 2+ refactorers |
---
@@ -250,6 +253,7 @@ Deploy planners to create an implementation plan informed by research findings.
Every planner prompt must emphasize this: the default agent instinct is to bolt new code on top of existing code. Resist this.
The right approach:
1. Study the existing code — understand why it's shaped the way it is
2. Design the target shape — what would the code look like if this feature had always existed?
3. Identify the refactoring gap — what needs to change so the new feature slots in cleanly?
@@ -344,6 +348,7 @@ Present the plan to the user. Wait for explicit confirmation before proceeding.
Persist the plan to disk and set up the heartbeat:
Use the Paseo **create schedule** tool with:
- `name`: `"heartbeat-<task-slug>"`
- `target`: `"self"`
- `every`: `"5m"`
@@ -394,6 +399,7 @@ Do the following steps in order:
## Phase 7: Implement
Execute phases from the plan sequentially. For each phase:
1. Launch impl agent(s) with `background: true, notifyOnFinish: true`
2. Wait for notification
3. Verify (Phase 8)
@@ -406,6 +412,7 @@ UI passes use `providers.ui` from preferences. All other impl work uses `provide
### TDD — Not Optional
Every impl agent works TDD:
1. Write a failing test that defines the expected behavior
2. Make it pass
3. Refactor if needed
@@ -462,6 +469,7 @@ Run typecheck when done. Do NOT commit."
### Handling Blockers
If an impl agent reports a blocker:
- Do NOT ask the user (in either mode)
- Spin up a researcher to investigate
- Spin up an impl agent to fix it
@@ -477,13 +485,13 @@ After every implementation phase, deploy auditors to verify the work. Auditors a
### Which Auditors to Deploy
| Phase type | Auditors |
|-----------|----------|
| Refactor | `parity`, `regression`, `types` |
| Feature (backend) | `overeng`, `tests`, `regression`, `types` |
| Phase type | Auditors |
| ------------------ | ------------------------------------------------------ |
| Refactor | `parity`, `regression`, `types` |
| Feature (backend) | `overeng`, `tests`, `regression`, `types` |
| Feature (frontend) | `overeng`, `tests`, `types`, `browser` (if applicable) |
| UI pass | `overeng`, `browser` (if applicable) |
| Test-only | `regression` |
| UI pass | `overeng`, `browser` (if applicable) |
| Test-only | `regression` |
Deploy all relevant auditors in parallel — they're read-only so they don't conflict.
@@ -622,6 +630,7 @@ Do NOT edit files."
### Interpreting Findings
If any auditor reports issues:
1. Check the auditor's activity with Paseo **get agent activity** for details
2. Direct the impl agent to fix them via Paseo **send agent prompt**, or launch a new impl agent if the old one is stale
3. Re-deploy the same auditor after fixes
@@ -841,16 +850,16 @@ Every agent has exactly one role. The role determines what the agent does, wheth
**Naming:** `<role>-<scope>[-<specialization>]` in kebab-case.
| Role | Job | Edits? | Prompt emphasis |
|------|-----|--------|----------------|
| `researcher` | Gathers info: codebase, docs, web, scripts | No | "Report what you find. Do not suggest solutions. Do not edit files." |
| `planner` | Creates implementation plan from research | No | "Think refactor-first. Design the target shape, not the steps." |
| `plan-reviewer` | Adversarially challenges a plan | No | "Challenge the plan. Find what's wrong, missing, or over-engineered." |
| `impl` | Writes code, works TDD | Yes | "Work TDD. Reshape existing code. Run typecheck AND run any tests you modified. Both must pass. Do NOT commit." |
| `tester` | Writes/fixes tests | Yes | "Verify behavior, not implementation. Run every test you modified and confirm it passes. A test change without running the test is not done." |
| `auditor` | Read-only verification | No | "Check [specialization]. Report YES/NO with evidence. Do NOT edit files." |
| `refactorer` | Targeted cleanup | Yes | "Fix [specialization] only. Run typecheck and any tests you touch. Do NOT commit." |
| `qa` | End-to-end QA, browser testing | No | "Test the actual user experience. Report with evidence." |
| Role | Job | Edits? | Prompt emphasis |
| --------------- | ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `researcher` | Gathers info: codebase, docs, web, scripts | No | "Report what you find. Do not suggest solutions. Do not edit files." |
| `planner` | Creates implementation plan from research | No | "Think refactor-first. Design the target shape, not the steps." |
| `plan-reviewer` | Adversarially challenges a plan | No | "Challenge the plan. Find what's wrong, missing, or over-engineered." |
| `impl` | Writes code, works TDD | Yes | "Work TDD. Reshape existing code. Run typecheck AND run any tests you modified. Both must pass. Do NOT commit." |
| `tester` | Writes/fixes tests | Yes | "Verify behavior, not implementation. Run every test you modified and confirm it passes. A test change without running the test is not done." |
| `auditor` | Read-only verification | No | "Check [specialization]. Report YES/NO with evidence. Do NOT edit files." |
| `refactorer` | Targeted cleanup | Yes | "Fix [specialization] only. Run typecheck and any tests you touch. Do NOT commit." |
| `qa` | End-to-end QA, browser testing | No | "Test the actual user experience. Report with evidence." |
Auditor specializations: `overeng`, `dry`, `tests`, `regression`, `types`, `browser`, `parity`
Refactorer specializations: `dry`, `dead-code`, `naming`
skills/paseo-orchestrate/references/final-qa.md
+1
View File
@@ -81,6 +81,7 @@ Do NOT edit files."
## If Issues Are Found
If any final QA agent reports issues:
1. Launch an impl or refactorer agent to fix them
2. Re-run the specific QA check that failed
3. Repeat until all checks pass
skills/paseo-orchestrate/references/impl-phase.md
+5
View File
@@ -5,6 +5,7 @@ Deploy impl agents to execute the plan phase by phase. Each phase is independent
## TDD — Not Optional
Every impl agent works TDD:
1. Write a failing test that defines the expected behavior
2. Make it pass
3. Refactor if needed
@@ -17,6 +18,7 @@ If an impl agent finds a broken test, it fixes it. No "pre-existing failures." N
Execute phases sequentially from the plan. Refactoring phases first, then feature phases, then UI passes.
After each phase:
1. Verify (see verification.md)
2. Fix any issues found
3. Re-verify
@@ -29,11 +31,13 @@ Use the Paseo **create agent** tool with `background: true` and `notifyOnFinish:
### How to describe the work
**Describe the problem, not the solution.** Your prompt should tell the agent:
- What's wrong or what needs to be built (the goal)
- How it currently fails (error output, test output, user-visible behavior)
- The acceptance criteria (what "done" looks like)
**Do NOT tell the agent:**
- Which specific lines to change
- What code to write
- Which functions to call or which patterns to use
@@ -95,6 +99,7 @@ Run typecheck when done. Do NOT commit."
## Handling Blockers
If an impl agent reports a blocker:
- Do NOT ask the user (in either mode)
- Spin up a researcher to investigate
- Spin up an impl agent to fix it
skills/paseo-orchestrate/references/planning-phase.md
+3
View File
@@ -7,6 +7,7 @@ Deploy planners to create an implementation plan informed by research findings.
Every planner prompt must emphasize this: the default agent instinct is to bolt new code on top of existing code. Resist this.
The right approach:
1. Study the existing code — understand why it's shaped the way it is
2. Design the target shape — what would the code look like if this feature had always existed?
3. Identify the refactoring gap — what needs to change so the new feature slots in cleanly?
@@ -65,6 +66,7 @@ Challenge the plan:
## Multiple Planners (Order 3+)
For cross-module tasks, deploy planners focusing on different slices:
- One for backend phases
- One for frontend phases
- One for test strategy
@@ -74,6 +76,7 @@ Then deploy a plan-reviewer to challenge the combined plan.
## Iteration
If the plan-reviewer finds significant issues, either:
1. Send follow-up instructions via the Paseo **send agent prompt** tool to the planner
2. Launch a new planner if the original is stale
skills/paseo-orchestrate/references/preferences.md
+9 -7
View File
@@ -24,15 +24,16 @@ Maps role categories to `<agent-type>/<model>` strings. These map directly to th
- The part before `/` is the `agentType` (e.g., `codex`, `claude`, `opencode`)
- The part after `/` is the `model` (e.g., `gpt-5.4`, `opus`)
| Category | Roles covered |
|----------|--------------|
| `impl` | impl, tester, refactorer |
| `ui` | impl agents doing UI/styling work |
| `research` | researcher |
| `planning` | planner, plan-reviewer |
| `audit` | auditor, qa |
| Category | Roles covered |
| ---------- | --------------------------------- |
| `impl` | impl, tester, refactorer |
| `ui` | impl agents doing UI/styling work |
| `research` | researcher |
| `planning` | planner, plan-reviewer |
| `audit` | auditor, qa |
If a category is missing, use these defaults:
- `impl` -> `codex/gpt-5.4`
- `ui` -> `claude/opus`
- `research` -> `codex/gpt-5.4`
@@ -44,6 +45,7 @@ If a category is missing, use these defaults:
Freeform array of natural language strings. The user states preferences and the orchestrator appends them here. Read these at startup and weave them into your behavior contextually.
Examples:
- "Prefer small, focused PRs over large bundled ones"
- "Run E2E tests with Maestro, not Playwright"
- "Always check mobile responsiveness"
skills/paseo-orchestrate/references/triage.md
+27 -27
View File
@@ -18,46 +18,46 @@ State the order and briefly why: "Order 3 — touches server session management
A contained change: fix a bug in one function, add a field to one type, update one component.
| Phase | Agents |
|-------|--------|
| Research | 1 researcher |
| Planning | 0 — orchestrator plans inline |
| Implement | 1 impl |
| Verify | 1-2 auditors |
| Cleanup | 0-1 refactorer |
| Phase | Agents |
| --------- | ----------------------------- |
| Research | 1 researcher |
| Planning | 0 — orchestrator plans inline |
| Implement | 1 impl |
| Verify | 1-2 auditors |
| Cleanup | 0-1 refactorer |
### Order 2 — Single module, few files
A feature or fix within one package that touches 3-8 files. Might involve new types, new tests, a few component changes.
| Phase | Agents |
|-------|--------|
| Research | 2 researchers |
| Planning | 1 planner |
| Phase | Agents |
| --------- | ---------------- |
| Research | 2 researchers |
| Planning | 1 planner |
| Implement | 1 impl per phase |
| Verify | 2-3 auditors |
| Cleanup | 1 refactorer |
| Verify | 2-3 auditors |
| Cleanup | 1 refactorer |
### Order 3 — Cross-module, multiple packages
A feature that spans packages (e.g., server + app, or CLI + server). Multiple concerns, multiple file groups, likely needs interface changes between layers.
| Phase | Agents |
|-------|--------|
| Research | 3-4 researchers (one per area: backend, frontend, tests, external docs) |
| Planning | 2 planners + 1 plan-reviewer |
| Implement | 1-2 impl agents per phase |
| Verify | 3-4 auditors (overeng, tests, regression, types) |
| Cleanup | 1-2 refactorers |
| Phase | Agents |
| --------- | ----------------------------------------------------------------------- |
| Research | 3-4 researchers (one per area: backend, frontend, tests, external docs) |
| Planning | 2 planners + 1 plan-reviewer |
| Implement | 1-2 impl agents per phase |
| Verify | 3-4 auditors (overeng, tests, regression, types) |
| Cleanup | 1-2 refactorers |
### Order 4 — Architectural, system-wide
A new subsystem, major refactor, or change that touches most of the codebase. New abstractions, new patterns, potentially breaking changes that need migration.
| Phase | Agents |
|-------|--------|
| Research | 5+ researchers across all relevant areas |
| Planning | 2+ planners (one per major area) + 2 plan-reviewers |
| Implement | 2+ impl agents per phase, sequenced carefully |
| Verify | Full auditor suite per phase |
| Cleanup | 2+ refactorers with different specializations |
| Phase | Agents |
| --------- | --------------------------------------------------- |
| Research | 5+ researchers across all relevant areas |
| Planning | 2+ planners (one per major area) + 2 plan-reviewers |
| Implement | 2+ impl agents per phase, sequenced carefully |
| Verify | Full auditor suite per phase |
| Cleanup | 2+ refactorers with different specializations |
skills/paseo-orchestrate/references/verification.md
+7 -6
View File
@@ -6,13 +6,13 @@ After every implementation phase, deploy auditors to verify the work. Auditors a
Not every phase needs every auditor. Match auditors to the work:
| Phase type | Auditors |
|-----------|----------|
| Refactor | `parity`, `regression`, `types` |
| Feature (backend) | `overeng`, `tests`, `regression`, `types` |
| Phase type | Auditors |
| ------------------ | ------------------------------------------------------ |
| Refactor | `parity`, `regression`, `types` |
| Feature (backend) | `overeng`, `tests`, `regression`, `types` |
| Feature (frontend) | `overeng`, `tests`, `types`, `browser` (if applicable) |
| UI pass | `overeng`, `browser` (if applicable) |
| Test-only | `regression` |
| UI pass | `overeng`, `browser` (if applicable) |
| Test-only | `regression` |
Deploy all relevant auditors in parallel — they're read-only so they don't conflict.
@@ -151,6 +151,7 @@ Do NOT edit files."
## Interpreting Findings
If any auditor reports issues:
1. Check the auditor's activity with the Paseo **get agent activity** tool for details
2. Direct the impl agent to fix them via the Paseo **send agent prompt** tool, or launch a new impl agent if the old one is stale
3. Re-deploy the same auditor after fixes
skills/paseo/SKILL.md
+4
View File
@@ -193,6 +193,7 @@ paseo terminal send-keys <terminal-id> --literal "raw text" # No special token
`Enter`, `Tab`, `Escape`, `Space`, `BSpace`, `C-c`, `C-d`, `C-z`, `C-l`, `C-a`, `C-e`
**Common pattern — launch a process and interact with it:**
```bash
id=$(paseo terminal create --name "my-shell" -q)
paseo terminal send-keys "$id" "claude" Enter
@@ -208,11 +209,13 @@ paseo terminal kill "$id"
## Available Models
**Claude (default provider):**
- `--provider claude/haiku` — Fast/cheap, ONLY for tests (not for real work)
- `--provider claude/sonnet` — Good for most tasks
- `--provider claude/opus` — For harder reasoning, complex debugging
**Codex:**
- `--provider codex/gpt-5.4` — Latest frontier agentic coding model (preferred for all engineering tasks)
- `--provider codex/gpt-5.4-mini` — Cheaper, faster, but less capable
@@ -236,6 +239,7 @@ Both `paseo run` and `paseo wait` block until the agent completes. Trust them.
`paseo run` blocks by default and `--output-schema` returns structured JSON, making it easy to compose agents in bash loops and pipelines.
**Detach + wait pattern for parallel work:**
```bash
api_id=$(paseo run -d --name "impl-api" "implement the API" -q)
ui_id=$(paseo run -d --name "impl-ui" "implement the UI" -q)