Add README and upstream sync script

- Document included skills and their purpose
- Add sync-upstream.sh to pull changes from obra/superpowers upstream

README.md

@@ -0,0 +1,36 @@
+# pi-superpowers-skills
+
+Superpowers skills for the pi agent. Forked from [obra/superpowers](https://github.com/obra/superpowers).
+
+## Skills included
+
+| Skill | Description |
+|-------|-------------|
+| `systematic-debugging` | 4-phase root-cause process before any fix |
+| `test-driven-development` | RED-GREEN-REFACTOR. No production code without a failing test |
+| `verification-before-completion` | Verify before claiming "done" — evidence before assertions |
+| `writing-plans` | Write implementation plans before touching code |
+| `requesting-code-review` | Self-review checklist before merge |
+| `receiving-code-review` | Rigorously process feedback, don't blindly apply |
+| `finishing-a-development-branch` | Merge/PR/cleanup workflow when done |
+
+## Upstream sync
+
+This repo tracks a subset of the upstream [obra/superpowers](https://github.com/obra/superpowers) skills.
+
+### Check for updates (dry-run)
+
+```bash
+./scripts/sync-upstream.sh --dry-run
+```
+
+### Apply updates
+
+```bash
+./scripts/sync-upstream.sh
+# Review staged changes, then:
+git commit -m "Sync skills from upstream"
+git push
+```
+
+The script fetches `upstream/main`, compares the selected `skills/*` directories, and merges any changes.

scripts/sync-upstream.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Sync selected skills from upstream (github.com/obra/superpowers)
+# Usage: ./scripts/sync-upstream.sh [--dry-run]
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+DRY_RUN=${DRY_RUN:-false}
+if [[ "${1:-}" == "--dry-run" ]]; then
+  DRY_RUN=true
+fi
+
+SKILLS=(
+  systematic-debugging
+  test-driven-development
+  verification-before-completion
+  writing-plans
+  requesting-code-review
+  receiving-code-review
+  finishing-a-development-branch
+)
+
+echo "Fetching upstream..."
+git fetch upstream --depth=1
+
+UPSTREAM_REF="upstream/main"
+CURRENT_REF="HEAD"
+
+CHANGED=false
+for skill in "${SKILLS[@]}"; do
+  echo ""
+  echo "=== Checking skills/$skill ==="
+
+  # Get list of files that differ
+  diff_files=$(git diff --name-only "$CURRENT_REF" "$UPSTREAM_REF" -- "skills/$skill" 2>/dev/null || true)
+
+  if [[ -z "$diff_files" ]]; then
+    echo "  Up to date"
+    continue
+  fi
+
+  echo "  Changes detected:"
+  echo "$diff_files" | sed 's/^/    /'
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo "  (dry-run, skipping copy)"
+    CHANGED=true
+    continue
+  fi
+
+  # Checkout the entire skill directory from upstream
+  git checkout "$UPSTREAM_REF" -- "skills/$skill"
+  echo "  Merged from upstream"
+  CHANGED=true
+done
+
+if [[ "$CHANGED" == false ]]; then
+  echo ""
+  echo "All skills up to date. Nothing to do."
+  exit 0
+fi
+
+if [[ "$DRY_RUN" == true ]]; then
+  echo ""
+  echo "Dry run complete. Run without --dry-run to apply changes."
+  exit 0
+fi
+
+# Stage everything in skills/
+git add -A skills/
+
+if git diff --cached --quiet; then
+  echo ""
+  echo "No changes to commit after merge."
+  exit 0
+fi
+
+echo ""
+echo "Changes staged. Commit with:"
+echo "  git commit -m 'Sync skills from obra/superpowers upstream (v$(git describe --tags "$UPSTREAM_REF" 2>/dev/null || echo "$(git rev-parse --short "$UPSTREAM_REF")"))'"