From 3b425b6fc8f7d78ccadc0807b505f9df72ebb0ef Mon Sep 17 00:00:00 2001
From: jay <jay@MacBookPro.fritz.box>
Date: Fri, 15 May 2026 02:03:45 +0200
Subject: [PATCH] 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                | 36 ++++++++++++++++++
 scripts/sync-upstream.sh | 82 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+)
 create mode 100644 README.md
 create mode 100755 scripts/sync-upstream.sh

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..83830ae
--- /dev/null
+++ b/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.
diff --git a/scripts/sync-upstream.sh b/scripts/sync-upstream.sh
new file mode 100755
index 0000000..3823ed7
--- /dev/null
+++ b/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")"))'"