{"id":"91bd3e82-6f76-4bb0-9105-9459bea00414","slug":"paseo-matt-workloop","kind":"skill","name":"paseo-matt-workloop","summary":"Paseo 多 Agent workloop：整合 Matt Pocock skills，支持 npx 安装与更新。","owner":"suntianc","repoUrl":"https://github.com/suntianc/paseo-matt-workloop","license":"MIT","licenseTier":"permissive","trust":"community","stars":10,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-10-26T02:18:38.000Z","addedAt":"2026-11-01T02:19:26.560Z","logoUrl":"https://avatars.githubusercontent.com/u/53503872?u=3ecea5ba5471bf22e60e070400fdeab12ced50d9&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["matt-pocock","paseo","workloop","agent"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-01T02:19:34.631Z","sample":false,"url":"https://conduits.dev/tools/paseo-matt-workloop","language":"JavaScript","transports":["stdio"],"install":{"npm":"paseo-matt-workloop"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# paseo-matt-workloop\n\n**English** · [简体中文](README.zh-CN.md)\n\nTurn a development request into reviewed code on a local integration branch. Matt Pocock skills guide the work; Paseo runs the executors and reviewers.\n\nFor release history and upgrade notes, see the [changelog](CHANGELOG.md).\n\n## 1. Skills\n\nStart with **`paseo-workloop`** for orchestration, or use a supporting skill on its own. The collection includes 17 upstream skill sources, with local `paseo-workloop`, `requirement-ledger`, `workloop-audit`, `codegraph` and a suggestion-only `retro` entry point.\n\n| Skill | Use it to… |\n| --- | --- |\n| [retro](skills/retro/SKILL.md) | Review recurring problems and suggest improvements for the user to decide, without applying them. |\n| [writing-for-agents](skills/writing-for-agents/SKILL.md) | Write clear, selectively loaded instructions and references for agents. |\n| [paseo-workloop](skills/paseo-workloop/SKILL.md) | Coordinate tickets, isolated worktrees, independent review, rework, and serial integration through Paseo. |\n| [requirement-ledger](skills/requirement-ledger/SKILL.md) | Find which long-lived requirement a request belongs to, and point at the runs, specs, ADRs and deliveries behind it. |\n| [workloop-audit](skills/workloop-audit/SKILL.md) | Audit past Workloop runs read-only: count what their records show and flag what the workflow's rules expect but the records contradict. |\n| [grill-me](skills/grill-me/SKILL.md) | Clarify a request's goal, boundaries, and design choices with the user. |\n| [grill-with-docs](skills/grill-with-docs/SKILL.md) | Clarify a request while capturing domain vocabulary and architectural decisions. |\n| [grilling](skills/grilling/SKILL.md) | Interview in rounds, asking each question after its prerequisite decisions are settled. |\n| [domain-modeling](skills/domain-modeling/SKILL.md) | Establish shared terminology and record decisions in a glossary and ADRs. |\n| [to-spec](skills/to-spec/SKILL.md) | Turn an agreed discussion into a spec with implementation and testing decisions. |\n| [to-tickets](skills/to-tickets/SKILL.md) | Split a spec into vertical slices with explicit blocking dependencies. |\n| [implement](skills/implement/SKILL.md) | Implement and verify a spec or ticket using the project's conventions. |\n| [tdd](skills/tdd/SKILL.md) | Develop through red → green → refactor, testing observable behavior. |\n| [code-review](skills/code-review/SKILL.md) | Review changes from a fixed baseline against repository standards and the originating spec. |\n| [diagnosing-bugs](skills/diagnosing-bugs/SKILL.md) | Reproduce and measure a bug or performance regression before choosing a fix. |\n| [codegraph](skills/codegraph/SKILL.md) | Navigate symbols, call paths, and change impact in an indexed repository. |\n| [codebase-design](skills/codebase-design/SKILL.md) | Design module boundaries that keep interfaces small and encapsulate complexity. |\n| [improve-codebase-architecture](skills/improve-codebase-architecture/SKILL.md) | Find architecture improvements, inspect an HTML report, and explore a selected proposal. |\n| [handoff](skills/handoff/SKILL.md) | Prepare a handoff containing the goal, decisions, evidence, and unfinished work. |\n| [wait-what](skills/wait-what/SKILL.md) | Ask the agent to explain its previous message again. |\n| [setup-matt-pocock-skills](skills/setup-matt-pocock-skills/SKILL.md) | Configure issue tracking and domain documents for standalone use of the upstream engineering skills. |\n\n## 2. Workflow\n\n![Quick, Direct and Full routes; user confirmation, bounded rework, integrate, an independent final review with its bounded repair loop, finish, retro assessment and archive, plus an optional requirement ledger](docs/assets/workloop.en.svg)\n\n[Editable Excalidraw source](docs/assets/workloop.en.excalidraw) — download and open it in Excalidraw.\n\nChoose enough process for the task. Existing authorization carries forward; clarify material gaps rather than asking the same questions at each stage.\n\n| Route | Choose it when… | Work |\n| --- | --- | --- |\n| **Quick** | The goal is clear, the change is local and reversible, and verification is straightforward. | Execute in the current session, verify and deliver. No ticket or Paseo daemon required. |\n| **Direct** | A bounded task benefits from delegation and independent review. | One scoped ticket; follow-up repairs may be imported after integration. |\n| **Full** | Design choices, dependencies or parallel work need coordination. | A spec, dependent tickets whose numbered criteria the user confirms, and an independent final review before `finish`. |\n\nDirect and Full use this lifecycle:\n\n| Stage | Result |\n| --- | --- |\n| **Execute and review** | The executor commits and reports evidence; an independent reviewer checks the frozen candidate against the ticket's confirmed, numbered criteria (`AC1`, `AC2`, …) or one of four floor classes — `Regression`, `Data loss`, `Security`, `ADR`. Anything else is a suggestion for the user, not a blocker. Rework continues in the original executor session and worktree. |\n| **Integrate** | Merge the reviewed candidate, then run the checks, this ticket's acceptance commands and the regression set — the acceptance commands of every ticket integrated so far. Unlock dependent tickets while retaining child sessions and worktrees. Failed merges, checks or acceptance commands return to the original executor. |\n| **Finish** | Re-run the checks and the whole regression set. Full also requires an independent final reviewer's pass for the current integration tip, or a `changes_requested` whose blocking findings are all waived; the orchestrator's `final-review.md` maps the acceptance evidence and carries no verdict. `finish` lists every waived finding for the user to review and writes the reviews' out-of-scope suggestions, by ticket, to one file in the run directory. Keep sessions for retrospective assessment. |\n| **Retro** | Assess the whole run for recurring failures, business pitfalls, repeated wrong behavior or repeated exploration. Present findings and suggested destinations, or record a brief no-retro reason. Suggestions are not applied automatically. Findings that are project traps are proposed as [pitfall](skills/paseo-workloop/reference/pitfalls.md) entries in `docs/pitfalls/`, written only after the user agrees. When the `workloop-audit` skill is installed, start from its read-only check of the run's records. |\n| **Archive** | Save CLI activity transcripts and the agent/attempt index, then archive sessions together. Integrated trees and each agent's `scratch/` folder (other commits' trees, installs, caches) are removed; unmerged or dirty cancelled/replaced work is retained. User decisions on retro suggestions do not delay archival. |\n\nEvery check has a time limit — 30 minutes by default, at most 1440 — and `integrate` and `finish` run theirs as a background check phase outside the run lock. The user confirms each ticket's numbered criteria before the run starts — each names the command that proves it, or why none can — and from then on they are frozen; a re-review — of a ticket after rework, and of a later final review round after one has reported — confirms the previous in-boundary blocking findings, re-runs the acceptance commands and looks for floor-class problems in the change since, and raises nothing else. A rework message carries the matching method: reproduce each finding, fix its cause, then check the change since the review. Rework rounds and final repair cycles are capped at two each by default, and every finding the run lets through is recorded, with its reason, in a waiver ledger that `finish` prints; the [run reference](skills/paseo-workloop/reference/run.md) holds each gate's rules.\n\nRecoverable errors continue in the same session. If the executor session is lost, `retry` replaces it in the existing worktree; `--new-worktree` explicitly starts a fresh tree. A defect found **after integration** is a new repair ticket with a new session and worktree from the latest integration tip.\n\nUse `retro` whenever useful, during a run or after archival. Mid-run retro leaves execution running and does not replace the assessment after `finish`. For agent-facing documentation, use `writing-for-agents`; `tidy-docs` handles organization and placement.\n\nTicketed runs deliver the local `workloop/<feature>` branch. Publishing, opening a PR, or merging into the main branch remains the user's decision.\n\n## 3. Installation\n\nUse **Node.js 20+, npm, and Git** on the machine where Paseo runs the agents. For a remote Paseo host, install on that host.\n\nChoose the directory your agent reads. The commands below work in macOS/Linux shells and Windows PowerShell.\n\n### Claude-compatible agents\n\nFor Claude Code and agents that read `~/.claude/skills`:\n\n```sh\n# Install\nnpx --yes github:suntianc/paseo-matt-workloop#main install --target \"$HOME/.claude/skills\"\n\n# Update the same directory\nnpx --yes github:suntianc/paseo-matt-workloop#main update --target \"$HOME/.claude/skills\"\n```\n\n### General agents\n\nFor agents that read the default `~/.agents/skills` directory:\n\n```sh\n# Install\nnpx --yes github:suntianc/paseo-matt-workloop#main install\n\n# Update\nnpx --yes github:suntianc/paseo-matt-workloop#main update\n```\n\nFor another skills directory, add `--target \"path/to/skills\"` to both commands. Keep the whole collection together: workloop resolves its supporting skills and resources through sibling paths.\n\nInstallation is complete when the command succeeds and your agent discovers `paseo-workloop` after restarting or refreshing its skills. Installed files persist outside the npx cache; `update` fetches the current GitHub `main` and prints its commit.\n\n**If installation or update reports a conflict**, back up the named local content, then restore the managed copy or install into an empty directory. The installer tracks ownership in `.paseo-matt-workloop.json` and preserves unrelated skills. Add `--dry-run` to check a target before writing; use `--help` for the available installer options.\n\n## 4. Runtime requirements and usage\n\n### Prepare the runtime\n\nBefore starting a Direct or Full run, establish these conditions (Quick does not need Paseo):\n\n| Requirement | Ready when… |\n| --- | --- |\n| **Paseo daemon** | `paseo agent ls -g --json` returns JSON from the intended host. |\n| **Agent session** | The orchestrator runs inside Paseo with `PASEO_AGENT_ID`, agent-scoped `create_agent` and `send_agent_prompt` tools, and heartbeat support. |\n| **Role profiles** | `wl-executor` and `wl-reviewer`, or explicitly selected alternatives, resolve to the user's chosen provider, model, and mode. Configure them in Paseo. |\n| **Project baseline** | The target is a Git repository and the checks chosen for the run already pass on its base. |\n\nFor version-dependent behavior or a failed prerequisite, consult the [Paseo compatibility notes](skills/paseo-workloop/reference/paseo-compat.md) before starting workers. The other skills can be used independently of this runtime; `codegraph` applies when the project already has an index.\n\n### Start a run\n\nOpen the project in Paseo with an agent that has loaded the collection. Describe the goal and acceptance expectations:\n\n```text\nUse paseo-workloop to add CSV export to this project.\nAgree with me on scope and acceptance checks before starting the run.\n```\n\n**To orchestrate the run**, read and follow [paseo-workloop](skills/paseo-workloop/SKILL.md). It selects a route and links the relevant execution, recovery and archival procedure. Workloop keeps its tracker in the run directory, so it can start directly with its supporting skills.\n\nSpecs, tickets, briefs, reports, retrospectives, captured activity and state live in `~/.workloop/<project>/<feature>/` by default (`WORKLOOP_ROOT` overrides the root). Finish active runs before updating their scripts.\n\nUse the reference matching the situation:\n\n- **Before pausing while workers run:** follow [async supervision](skills/paseo-workloop/reference/async-supervision.md) to arm notifications and the fallback heartbeat.\n- **After a session or operation is interrupted:** follow [recovery](skills/paseo-workloop/reference/recovery.md) to reconcile current state before taking another action.\n- **To organize a project's documentation:** follow [tidy-docs](skills/paseo-workloop/reference/tidy-docs.md) for per-machine registration and the document workflow.\n- **To maintain or sync this collection:** follow the [collection guide](skills/README.md); check commands are defined in [package.json](package.json).\n\n## 5. Acknowledgments\n\n- **[Matt Pocock / skills](https://github.com/mattpocock/skills)** — the upstream engineering and productivity skills that guide this workflow. Upstream sources remain unchanged; workloop adaptations live in local skills and role briefs. The local retro entry point keeps the original under `retro/reference/upstream.md` as reference.\n- **[Paseo](https://github.com/getpaseo/paseo)** — the runtime for coordinating independent coding agents, workspaces, and completion notifications.\n\nLocal code uses the [MIT License](LICENSE). Upstream notices are preserved in [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES); source versions and diagram attribution are recorded in [NOTICE.md](NOTICE.md).\n"}