Project Description

piste is a small glue layer you install into a project you're already working on. It doesn't replace how you do anything, it just adds a handful of commands, agents, and skills to opencode so you and your agents can work on tickets, review PRs and write them without the usual mess.

I built it for ongoing group projects: tickets coming in, PRs going out, more than one person touching the code.

Why

When you're the only one on a repo, you can keep the whole process in your head. In a group project you can't, and neither can an agent. Everyone needs the same rhythm: plan before writing code, review before merge, and PRs that explain themselves.

I wanted that rhythm available without adopting some heavy framework, so piste stays deliberately small:
- Installs by copying files in, and never overwrites what already exists
- No ticket files, no worktrees, no JSON config
- Permissions live in each agent's own frontmatter
- The AGENTS.md skeleton is filled in by /setup on the first run

If I end up missing something, I'll add it then, not before.

What's In It

Commands:
- /setup: explores the repo (stack, real test/lint/build commands, folder layout) and fills in AGENTS.md. Safe to re-run, it refines instead of clobbering your edits.
- /work "<ticket>": always runs in plan mode. Proposes a phased plan and stops. It doesn't touch a file until you switch to build.
- /review-pr: reviews a diff using the checklist. Depth is calibrated to risk: a fast pass on the mechanical stuff, a real deep look at anything touching auth, payments, migrations, or anything it isn't confident about. Any Blocker gets verified by a second, context-free agent before it reaches you, so a false positive doesn't show up labeled as fact.
- /write-review: drafts the actual review in my voice, shows it, and only posts it once I say so.
- /describe-pr: drafts a PR description from the real diff (Problem → What this does → Verification → Reviewer notes). Doesn't open the PR on its own.

Agents:
- reviewer: read-only by design. It can report a problem but never fix it, because a silent fix hides a disagreement someone should see.
- verifier: the fresh-eyes check on Blockers. It gets the diff and one claim, no reasoning attached, and decides whether it's actually real.

Skills: plan-quality, git-workflow, pr-review (with a reference checklist), and pr-writing-style.

Notes

• No stack-specific skills on purpose. /setup covers how a repo actually works, and anything deeper is better sourced per project than baked in here.
• .opencode/skills/ and .claude/skills/ are interchangeable, so community skills drop in without changes.

Install

./install.sh /path/to/your-project
cd /path/to/your-project
opencode

Then run /setup inside opencode and give it a one-line description of the project if it asks. From there, new work starts with /work, and PRs go through /review-pr before merge.