@codersbrew/pi-tools 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,10 @@
 # @codersbrew/pi-tools
 
-A publishable [pi](https://github.com/badlogic/pi-mono) package that bundles CodersBrew's custom pi extensions.
+A publishable [pi](https://github.com/badlogic/pi-mono) package that bundles CodersBrew's custom pi extensions and skills.
 
-## Included extensions
+## Included resources
+
+### Extensions
 
 ### `security`
 Protects common dangerous tool operations by:
@@ -16,6 +18,17 @@ Adds an interactive TUI for analyzing pi session history from `~/.pi/agent/sessi
 - model, cwd, day-of-week, and time-of-day breakdowns
 - contribution-style heatmap visualizations
 
+### Skill: `github-workflow`
+An opinionated GitHub workflow skill for branch creation, commits, pushes, PR creation, review, and merge work.
+
+It prefers `gh` for GitHub-aware actions and uses plain `git` where local source-control operations are the better tool.
+
+Invoke it in pi with:
+
+```bash
+/skill:github-workflow
+```
+
 ## Install
 
 Global install:
@@ -43,13 +56,15 @@ You can also add it manually to pi settings:
 This package uses pi's standard package manifest:
 - `extensions/security.ts`
 - `extensions/session-breakdown.ts`
+- `skills/github-workflow/SKILL.md`
 
 The root `package.json` exposes them through:
 
 ```json
 {
   "pi": {
-    "extensions": ["./extensions"]
+    "extensions": ["./extensions"],
+    "skills": ["./skills"]
   }
 }
 ```
@@ -86,8 +101,8 @@ Bootstrap steps for `@codersbrew/pi-tools`:
 
 1. Create an npm access token with publish rights
 2. Add it to the GitHub repo as `NPM_TOKEN`
-3. Confirm `package.json` has the intended version, currently `0.1.0`
-4. Push a version tag such as `v0.1.0`
+3. Confirm `package.json` has the intended version
+4. Push a matching version tag such as `v0.2.0`
 5. GitHub Actions will verify the package, publish it, and create a GitHub release
 
 ### Switch to trusted publishing after first release
@@ -106,7 +121,7 @@ After trusted publishing is configured, remove the `NPM_TOKEN` secret if you wan
 
 1. Update the package version in `package.json`
 2. Commit and push the change
-3. Create and push a matching version tag such as `v0.1.1`
+3. Create and push a matching version tag such as `v0.2.0`
 4. GitHub Actions will run verification, publish to npm, and create a GitHub release
 
 The workflow uses Node 24 so the npm CLI is new enough for trusted publishing and provenance support.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codersbrew/pi-tools",
-  "version": "0.1.1",
-  "description": "A pi package bundling CodersBrew pi extensions.",
+  "version": "0.2.0",
+  "description": "A pi package bundling CodersBrew pi extensions and skills.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -22,6 +22,7 @@
   },
   "files": [
     "extensions",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -50,6 +51,9 @@
   "pi": {
     "extensions": [
       "./extensions"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/github-workflow/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: github-workflow
+description: Use when working in a git repository hosted on GitHub and handling branch creation, commits, pushes, pull requests, reviews, or merges with gh CLI available.
+---
+
+# GitHub Workflow
+
+## Overview
+
+Use a hybrid workflow: prefer `gh` for GitHub-aware tasks, and use `git` for local history editing, staging, and branch mechanics.
+
+**Opinionated defaults:**
+- inspect repo state before making changes
+- keep branches focused and short-lived
+- use conventional-commit-style messages when possible
+- open PRs with clear titles and summaries
+- merge with explicit intent, not guesswork
+
+## Quick Start Checks
+
+Run these before branching or opening a PR:
+
+```bash
+gh auth status
+git remote -v
+gh repo view --json nameWithOwner,defaultBranchRef
+```
+
+Confirm:
+- `gh` is authenticated
+- the repo remote points to the expected GitHub repository
+- you know the default branch, usually `main` or `master`
+
+If `gh repo view` fails because the current repo is not connected to GitHub, fall back to plain `git` and ask before attempting GitHub-specific actions.
+
+## Tool Choice Rules
+
+| Use `gh` for | Use `git` for |
+|---|---|
+| auth and repo checks | staging files |
+| PR create/view/checkout/review/merge | commit creation/amend/rebase |
+| PR status and checks | switching branches |
+| opening web pages for repo or PR context | inspecting local diffs and history |
+
+**Fallback rule:** if `gh` has a clean command for the task, prefer it. If the task is fundamentally local source control, use `git`.
+
+## Branch Workflow
+
+1. Sync and inspect the default branch.
+2. Create a focused branch from the default branch.
+3. Keep the branch name descriptive.
+
+Example:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feat/add-github-workflow-skill
+```
+
+Recommended prefixes:
+- `feat/`
+- `fix/`
+- `docs/`
+- `chore/`
+- `refactor/`
+- `test/`
+
+Avoid vague names like `updates`, `stuff`, or `misc-fixes`.
+
+## Commit Workflow
+
+Use `git` for staging and committing. Keep commits small and readable.
+
+```bash
+git status
+git add <paths>
+git commit -m "feat: add github workflow skill"
+```
+
+Prefer conventional-commit-style summaries:
+- `feat: add github workflow skill`
+- `fix: correct PR base branch detection`
+- `docs: document packaged skills`
+- `chore: clean up release notes`
+
+Before pushing, review what changed:
+
+```bash
+git diff --staged
+```
+
+If a commit needs cleanup, use `git commit --amend` or interactive rebase deliberately. Do not use `gh` for local history surgery.
+
+## Push and PR Workflow
+
+Push with `git`, then use `gh` to work with the PR.
+
+```bash
+git push -u origin HEAD
+gh pr create --fill --base main
+```
+
+Useful `gh` commands:
+
+```bash
+gh pr status
+gh pr view --web
+gh pr checks
+gh pr create --fill --base <default-branch>
+gh pr checkout <number>
+```
+
+PR hygiene:
+- make sure the base branch is correct
+- use a title that matches the change
+- include a short summary of what changed and any risk areas
+- mention tests run when relevant
+
+If `--fill` produces a weak title/body, replace it instead of accepting low-quality PR text.
+
+## Review Workflow
+
+Use `gh` to inspect and respond to review state.
+
+```bash
+gh pr view <number>
+gh pr diff <number>
+gh pr checks <number>
+gh pr review <number> --comment -b "Looks good overall; left one suggestion."
+gh pr review <number> --approve
+gh pr review <number> --request-changes -b "Please address the failing tests and rename the branch."
+```
+
+When reviewing your own work, check:
+- PR targets the correct base branch
+- branch is up to date enough for the repo's workflow
+- checks are green or known failures are explained
+- description matches the actual diff
+
+## Merge Workflow
+
+Prefer `gh pr merge` so the merge action is tied to GitHub PR state.
+
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+
+Common variants:
+- `--squash` for small or iterative branches
+- `--merge` when the repo prefers merge commits
+- `--rebase` when the repo explicitly prefers rebased history
+
+Before merging, confirm:
+- approvals or review requirements are satisfied
+- required checks passed
+- the chosen merge strategy matches repo norms
+
+After merge, sync local state:
+
+```bash
+git switch main
+git pull --ff-only
+```
+
+## Common Mistakes
+
+- using `gh` for tasks that are really local `git` operations
+- forgetting to verify the default branch before creating the PR
+- pushing a branch without `-u` and then losing the upstream link
+- opening a PR with an unhelpful auto-filled title/body
+- merging without checking CI or review status
+- mixing unrelated changes into one branch or one commit
+
+## Red Flags
+
+Stop and re-check before acting if you see any of these:
+- `gh auth status` is not healthy
+- the remote is not the repo you expected
+- you do not know the correct base branch
+- the branch name does not describe the change
+- the PR title says one thing but the diff shows another
+- checks are failing and no reason is documented
+
+When unsure, inspect first, then act.