diff --git a/README.md b/README.md index 60e3ce21c0f63217485c6b8c17565149d197a81e..a8c8cb239d4f6f4717864cd4e5a1e64709bd3c0c 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,10 @@ token count, plus overall metadata usage. I've used and tested them most with - [authoring-skills](skills/authoring-skills/SKILL.md): Creates and reviews Agent Skills following best practices. Covers skill structure, frontmatter, and progressive disclosure patterns. +- [collaborating-through-pr-pico-sh](skills/collaborating-through-pr-pico-sh/SKILL.md): + Collaborates on git patches via [pr.pico.sh], a minimal patchbin service. + Covers both contributing and reviewing patch requests using `git format-patch` + and `git am`. - [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md): Creates tasks and handoffs in [Lunatask] via [lune]. Tasks are just tasks. Handoffs capture work to resume later across sessions without filling context @@ -250,6 +254,18 @@ Token breakdown: ─────────────────────────────────────────────── Total: 10050 tokens +=== collaborating-through-pr-pico-sh === + +Token breakdown: + Name: 30 tokens + Description: 120 tokens + Body: 1260 tokens (42 lines) + References: + contributing.md 435 tokens + reviewing.md 1080 tokens + ─────────────────────────────────────────────── + Total: 2925 tokens + === creating-tasks-through-lunatask === Token breakdown: @@ -355,9 +371,9 @@ Token breakdown: Token breakdown: Name: 25 tokens Description: 159 tokens - Body: 3133 tokens (111 lines) + Body: 3082 tokens (111 lines) ─────────────────────────────────────────────── - Total: 3317 tokens + Total: 3266 tokens === resuming-work-through-lunatask === @@ -376,9 +392,9 @@ Token breakdown: Token breakdown: Name: 18 tokens Description: 132 tokens - Body: 972 tokens (46 lines) + Body: 970 tokens (48 lines) ─────────────────────────────────────────────── - Total: 1122 tokens + Total: 1120 tokens === scripting-with-go === @@ -437,10 +453,10 @@ Token breakdown: SUMMARY ============================================================ -Skills: 21 -Metadata: 3067 tokens -Combined bodies: 57651 tokens -Overall: 182834 tokens +Skills: 22 +Metadata: 3217 tokens +Combined bodies: 58858 tokens +Overall: 185706 tokens Validation errors: 0 Largest skills (by total tokens): diff --git a/skills/collaborating-through-pr-pico-sh/SKILL.md b/skills/collaborating-through-pr-pico-sh/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..42fa9fa2a4e7a2e361306a8382b7ebd2eb2001b3 --- /dev/null +++ b/skills/collaborating-through-pr-pico-sh/SKILL.md @@ -0,0 +1,50 @@ +--- +name: collaborating-through-pr-pico-sh +description: Collaborates on git patches via pr.pico.sh, a minimal patchbin service. Use when submitting, reviewing, or managing patch requests, or when the user mentions pr.pico.sh, patchbin, or patch requests. +license: AGPL-3.0-or-later +metadata: + author: Amolith +--- + +pr.pico.sh is a patchbin where collaboration happens through `git format-patch` and `git am`. Whether you are submitting code changes or reviewing them, it all happens in code — both contributor and reviewer create commits, optionally with comments in code, and exchange them as patches rather than commenting in a web UI. + +## Registration + +If `ssh pr.pico.sh` returns a "not registered" error, stop and ask the user what they would like to register as, or if they're already registered. If they're not and provide a username, register their key with `ssh {username}@pr.pico.sh register`. + +## Common commands + +```console +ssh pr.pico.sh pr ls --mine {repo} # also --open, --closed, --accepted +# Display metadata for a specific PR +ssh pr.pico.sh pr summary {id} +ssh pr.pico.sh logs --pr {id} # also --repo {id} or your own --pubkey + +# Apply all patches from a PR +ssh pr.pico.sh pr print {id} | git am -3 + +# Print a specific patchset (rather than the whole PR) +ssh pr.pico.sh print ps-{id} +``` + +The project's README.md or AGENTS.md likely mention whether the project uses pr.pico.sh and which pr.pico.sh repo it uses. If you don't already know its ID, grep for `pr.pico.sh` in the README.md, first falling back to an AGENTS.md, then a broader in-cwd search if still not found, and read surrounding lines to identify the repo ID. + +## Admin commands + +```console +# Create a repo on pr.pico.sh +ssh pr.pico.sh repo create {repoName} + +# Delete a repo and all its PRs (requires --write confirmation) +ssh pr.pico.sh repo rm --write {repoName} + +# Remove a specific patchset +ssh pr.pico.sh ps rm {patchsetID} +``` + +## Flows + +You will often be _either_ reviewing or sending patches, and the user will have made it clear which. Be sure to read the right one. + +- For sending patches, opening a PR, contributing upstream, or similar requests when the project uses pr.pico.sh, see [contributing.md](references/contributing.md) +- For reviewing patches/PRs, accepting a contributor's PR, or similar, see [reviewing.md](references/reviewing.md) diff --git a/skills/collaborating-through-pr-pico-sh/references/contributing.md b/skills/collaborating-through-pr-pico-sh/references/contributing.md new file mode 100644 index 0000000000000000000000000000000000000000..3986fda3f811d5e5dd32e298ba996a33879963da --- /dev/null +++ b/skills/collaborating-through-pr-pico-sh/references/contributing.md @@ -0,0 +1,20 @@ +1. Clone the repo and make changes via commits +2. Create a new patch request +3. If revisions are requested, apply reviewer patches, address feedback, and submit revised patches + +```console +# Create a new patch request +git format-patch origin/main --stdout | ssh pr.pico.sh pr create {repo} + +# Apply reviewer feedback +ssh pr.pico.sh pr print {id} | git am -3 + +# Submit a revision to an existing PR +git format-patch origin/main --stdout | ssh pr.pico.sh pr add {id} + +# Submit a revision with a comment +git format-patch origin/main --stdout | ssh pr.pico.sh pr add --comment "addressed feedback" {id} + +# Edit a PR's title +ssh pr.pico.sh pr edit {id} {title} +``` diff --git a/skills/collaborating-through-pr-pico-sh/references/reviewing.md b/skills/collaborating-through-pr-pico-sh/references/reviewing.md new file mode 100644 index 0000000000000000000000000000000000000000..4e237ae107960dcad9d5224115191d300d20a5ca --- /dev/null +++ b/skills/collaborating-through-pr-pico-sh/references/reviewing.md @@ -0,0 +1,46 @@ +1. Apply the contributor's patches locally +2. Make review comments or code changes directly in code, then commit +3. Submit the review as a patch +4. Once satisfied, accept the PR and push to upstream + +```console +# Apply patches from a PR +ssh pr.pico.sh pr print {id} | git am -3 + +# Submit a review (comments/changes as commits) +git format-patch origin/main --stdout | ssh pr.pico.sh pr add --review {id} + +# Submit a review with a comment +git format-patch origin/main --stdout | ssh pr.pico.sh pr add --review --comment "Thank you for the contribution! Just left a couple inline notes" {id} + +# Accept a PR (accepts multiple IDs) +ssh pr.pico.sh pr accept {id} + +# Accept with a comment piped via stdin +echo "looks good, merging!" | ssh pr.pico.sh pr accept --comment {id} + +# Submit final patchset and accept in one step +git format-patch origin/main --stdout | ssh pr.pico.sh pr add --accept {id} + +# Close/reject a PR (accepts multiple IDs) +ssh pr.pico.sh pr close {id} + +# Close with a comment piped via stdin +echo "won't fix because ..." | ssh pr.pico.sh pr close --comment {id} + +# Submit patchset and close in one step +git format-patch origin/main --stdout | ssh pr.pico.sh pr add --close {id} + +# Reopen a previously closed PR +ssh pr.pico.sh pr reopen {id} + +# Reopen with a comment piped via stdin +echo "reconsidered, reopening because ..." | ssh pr.pico.sh pr reopen --comment {id} + +# Edit a PR's title +ssh pr.pico.sh pr edit {id} {title} + +# Prep and push to upstream +git rebase -i origin/main # or whatever the correct `remote/canonical-branch` are +git push origin main # or whatever the correct `remote canonical-branch` are +```