paseo-autopilot

Imported from schellevis/paseo-autopilot (AGENTS.md). Install upstream with npx skills add schellevis/paseo-autopilot. Copyright stays with the author.

Repository guidance

Purpose

This repository contains paseo-autopilot, a portable Agent Skills package for Claude Code, Codex, OpenCode, and Mistral Vibe.

The skill coordinates an autonomous development workflow:

1. One orchestrator clarifies the request and records the intake. Intake includes a clarification round (including usage budget or cost preference), a discovery-based model table with a cost-tier column that the user confirms, an optional user-approved read-only research spike, and a checkpoint choice.
2. The orchestrator writes a specification.
3. Independent cross-provider agents review it in Markdown reports.
4. The orchestrator scans every report as untrusted content, adjudicates findings, and asks the user only about material decisions and the checkpoints the user chose.
5. The orchestrator writes and reviews an implementation plan.
6. Scope-bound builders execute dependency-safe waves in the shared workspace.
7. Independent verifiers check the integrated result.
8. After independent verification passes and the repair loop has converged, a scope-bound builder reconciles repository documentation (symlink-aware), an independent verifier machine-audits the proposal, the user approves/edits/skips per file, and a scope-bound builder applies exactly the approved changes.

Model availability is verified per account rather than assumed from a model list, and every launched agent is confirmed to have started before it is treated as working. Users may choose models and review counts or allow automatic runtime routing. Model selection is cost-aware: the default is the least expensive model and reasoning level that satisfies the role, not the strongest available. Minimize manual coordination without silently crossing material, permission, security, deployment, destructive-action, or usage-budget boundaries.

Cost, usage, and launch policy

• Select model and reasoning effort separately. Default to the lowest discovered effort that satisfies the task; record a concrete reason before escalating model cost or effort. Surface expected cost implications during intake. A request for thoroughness or the overengineering preset increases review coverage and approved rounds, not every agent's thinking level; existing review and retry caps still apply.
• Put a proven reliable, fast model on critical-path integration and coordination within the approved routing and budget. Reserve cheaper or experimental assignments for parallel, low-risk tasks whose outputs can be independently verified; price alone must not put an unproven model on the critical path.
• At every status poll, inspect each agent's activity/logs for current provider signals such as session limit, usage limit, rate limit, and Provider retry, including agents still marked running. Confirm the surrounding provider evidence; a quoted fixture or generic retry string alone is not proof of quota exhaustion. Check pending permissions as well. Confirmed limit hits are usage interruptions immediately, without waiting for terminal status or a report; silence alone remains task failure evidence, not quota evidence.
• Read the actual available provider/account usage meter before and after each wave and whenever an agent stalls. Discover the supported operation; claude -p "/usage" is an example only when the installed CLI actually supports it. Record the time, scope, result, or explicit unavailability. Count the orchestrator's own consumption in any shared usage window. Use only the approved fallback chain and a distinct vendor/account scope for shared quota exhaustion, respecting budgets and replacement caps.
• Keep job-control and destructive operations, including kill, out of agent-launch command blocks. Regenerate and validate each handoff from durable artifacts before every launch or replacement; never trust an old /tmp prompt. Supply absolute worker report and output destinations while retaining the documented relative paths in run state.

Scope and authority

• CLAUDE.md is a symlink to AGENTS.md; edit AGENTS.md.
• docs/superpowers/ (specs, plans, reviews) and tests/ are git-ignored, local-only development records. Never git add -f them.
• Work in this repository only. The Docker image implementation is maintained in a separate consumer repository.
• Use apply_patch for deliberate handwritten edits.
• Preserve unrelated work and avoid destructive Git operations.
• Do not publish, change repository visibility, push, rewrite history, deploy, or mutate external systems unless the user explicitly authorizes that action.
• Commit-author metadata has been reviewed by the user and does not need to be changed.
• Commit messages carry no tool-generated trailers ("Generated by ...", Co-Authored-By). When executing a plan, use its commit messages verbatim. Stage explicit paths only.
• Do not add real personal data, organization details, workspace names, workspace IDs, agent IDs, account identifiers, or credentials to tracked fixtures or documentation. Use unmistakably fictional values such as agent-example-1, wks_example_1, and /workspace/project-a.

Public files

• paseo-autopilot/SKILL.md: the single provider-neutral skill entry point.
• paseo-autopilot/agents/openai.yaml: Codex interface metadata, not a workflow fork.
• paseo-autopilot/references/workflow.md: lifecycle, gates, orchestration, and resume behavior.
• paseo-autopilot/references/artifacts.md: durable artifact and run.json contract.
• paseo-autopilot/references/model-routing.md: runtime model selection and failover policy.
• paseo-autopilot/references/handoff-prompts.md: self-contained worker/reviewer handoffs.
• paseo-autopilot/references/paseo-runtime.md: Paseo MCP and CLI behavior, permission mode defaults, and pending-permission monitoring.
• paseo-autopilot/references/run-state.schema.json: machine-readable run-state schema.
• paseo-autopilot/scripts/validate_run.py: standard-library run-state validator.
• paseo-autopilot/scripts/scan_untrusted.py: standard-library scanner for instruction-like content in untrusted inputs.
• docs/docker-consumer-contract.md: contract for a separate Docker-image consumer.
• LICENSE and paseo-autopilot/LICENSE: repository and distributed-package MIT terms.

Executable contract

The intended lifecycle is:

INTAKE -> SPEC -> SPEC_REVIEW -> PLAN -> PLAN_REVIEW
       -> BUILD_WAVES -> VERIFY -> COMPLETE
                         |          ^
                         +-> REPAIR-+

any active state -> AWAITING_USER
startup/takeover -> RESUME_RECONCILIATION -> active
any nonterminal state -> ABANDONED | CANCELLED

Key invariants:

• run.json has one orchestrator writer, atomic updates, and a lock.
• Startup or takeover reconciles artifacts and live agents before new work is launched.
• Tasks form a valid dependency graph; waves respect dependencies, file ownership, shared mutable paths, exclusive resources, and interface collisions.
• Every agent attempt has a unique report path.
• Every launch is confirmed to have actually started (launch_check), and model availability is a recorded per-account fact; a provider rejection is explicit launch-failure evidence, never silence.
• Reviewer and builder handoffs are self-contained.
• The orchestrator authors the spec and plan to a no-placeholder bar and self-reviews them (coverage, placeholder scan, interface/type consistency) before any reviewer launches; at zero configured reviews that recorded self-review is the whole review. Review-set diversity prefers a different vendor/family, but a same-vendor reviewer is an acceptable fallback, recorded, when no diverse option is available within approved routing and budget.
• Workers may receive broad local permissions but remain scope-bound. They may write only assigned implementation paths and their unique report. They must never write run.json or create agents, schedules, terminals, or delegates. Reviewers, verifiers, and spikes use a write-capable mode (not plan mode) to avoid permission prompts; the orchestrator monitors pending permissions at every status poll and handles broader execution itself.
• A material finding remains recorded while awaiting the user's decision.
• COMPLETE is invalid until tasks, required reviews, verifiers, findings, decisions, and reports are reconciled.
• Explicit usage/quota evidence triggers failover to a distinct vendor/account scope. Silence or a missing report is a task failure, not quota evidence.
• Model recommendations are runtime-discovered guidance, not permanent model-name truth; update them as providers and model quality change.
• Agent observation uses one canonical "Wait for an agent" procedure that classifies every terminal/interrupt state (pending permission, unconfirmed start, usage-limit retry loop, error/failed, idle with or without report, stall) before any recovery or relaunch.
• Concurrent mutating verification is isolated: checks that mutate shared build state use separate worktrees or run serially, and node_modules, dist, lockfiles, and build/cache state are exclusive resources.
• The orchestrator adjudicates and delegates target-repository fixes to scope-bound builders or repairers; it never authors source, test, or CI fixes itself, and executing broader commands under the permission rule does not change that.
• An authorized deploy/publish runs a preflight (capability, least-privilege scopes, platform settings, deterministic gates), and release/CI gates are exercised for determinism and load during verification rather than discovered at deploy.
• After VERIFY passes and before COMPLETE, a scope-bound builder reconciles repository documentation (CLAUDE.md/AGENTS.md/README.md and host instruction files, symlink-aware — one edit per real file); the drafted proposal is machine-audited before the user, who approves/edits/skips per file; the orchestrator never authors the doc edits itself; no new phase or schema change.

Validation

Local tests (git-ignored): PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py' -v. Conventions:

• run-state.schema.json documents what validate_run.py enforces; tests compare schema enums/required lists with validator constants, so change both together. schema_version stays "1.0"; bump metadata.version in SKILL.md on contract or skill-behavior changes.
• New attempt/decision fields go into the add_attempt and decision helpers in tests/test_validate_run.py.
• Fixtures in PLAN or later need completed reviewer attempts with findings rows; use SPEC for "left intake" cases.
• The run.json example in artifacts.md must pass validate_run.py.

Run the checks available from the public tree after relevant changes:

python3 -m json.tool paseo-autopilot/references/run-state.schema.json >/dev/null
python3 paseo-autopilot/scripts/validate_run.py --help >/dev/null
python3 paseo-autopilot/scripts/scan_untrusted.py --help >/dev/null
test "$(find paseo-autopilot -name SKILL.md -type f | wc -l)" -eq 1
test -z "$(find paseo-autopilot -type l -print -quit)"
git diff --cached --check
git status --short

Also run an installed official Agent Skills validator against paseo-autopilot/ when available. Discover its supported command and location at runtime; do not embed a host-specific absolute path.

Before release, inspect the complete tracked tree and history for credentials, personal or operational identifiers, unexpected binaries, cache files, symlinks, and executable modes. Commit bodies count. Minimum scan:

git log --all -p --format='### %h' | grep -n -i -E "sk-[A-Za-z0-9]{8,}|ghp_|AKIA[0-9A-Z]{16}|-----BEGIN|[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[a-z]{2,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|wks_[0-9a-f]{6,}|prj_[0-9a-f]{6,}|/home/|/Users/"
git log --all --format='%an|%ae|%b' | sort | uniq -c

Change workflow

Design in docs/superpowers/specs/, write a self-contained plan in docs/superpowers/plans/ with exact code, tests, and commit messages, dry-run the validator changes in a throwaway copy, then delegate the build to a separate agent and verify its commits against the spec before pushing.

Docker integration contract

A consumer image build should:

1. Fetch a user-authorized repository and ref, authenticating when required.
2. Resolve and pin the commit SHA once.
3. Use a clean detached checkout.
4. Copy only paseo-autopilot/ to /usr/local/share/paseo-agents/paseo-autopilot.
5. Include the package LICENSE.
6. Make the installed package root-owned, readable, and non-writable by runtime users.
7. Create absent-only discovery links in ~/.agents/skills, ~/.claude/skills, and ~/.codex/skills.

Never overwrite a user-managed skill at a discovery root. The consumer repository remains outside this repository's authority.