@slamb2k/mad-skills 2.0.6

package/skills/ship/instructions.md

@@ -0,0 +1,192 @@
+# Ship Instructions
+
+Ship changes through the complete PR lifecycle. Every stage runs in a subagent
+to isolate context from the primary conversation. Prompts for each stage are
+in `references/stage-prompts.md`.
+
+## Flags
+
+Parse optional flags from the request:
+- `--pr-only`: Stop after creating the PR
+- `--no-squash`: Use regular merge instead of squash
+- `--keep-branch`: Don't delete the source branch after merge
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+| gh | cli | `gh --version` | yes | url | https://cli.github.com |
+| ship-analyzer | agent | `~/.claude/agents/ship-analyzer.md` | no | fallback | Uses general-purpose agent |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+Read `default_branch` and `remote` from Stage 1's SYNC_REPORT. These are
+substituted into all stage prompts as `{REMOTE}` and `{DEFAULT_BRANCH}`.
+
+### Platform Detection
+
+After sync, detect the hosting platform from the remote URL:
+
+```bash
+REMOTE_URL=$(git remote get-url {REMOTE} 2>/dev/null)
+if echo "$REMOTE_URL" | grep -qiE 'dev\.azure\.com|visualstudio\.com'; then
+  PLATFORM="azdo"
+elif echo "$REMOTE_URL" | grep -qi 'github\.com'; then
+  PLATFORM="github"
+else
+  PLATFORM="github"   # default fallback
+fi
+```
+
+Pass `{PLATFORM}` into all stage prompts. Each stage uses the appropriate
+CLI tool: `gh` for GitHub, `az repos`/`az pipelines` for Azure DevOps.
+
+> **Azure DevOps prerequisite:** The `az devops` extension must be installed
+> and configured (`az devops configure --defaults organization=... project=...`).
+> If `az repos` commands fail, report the setup requirement to the user.
+
+---
+
+## Stage 1: Sync
+
+Launch **Bash subagent** (haiku — simple git commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Sync with default branch",
+  prompt: "Follow ~/.claude/skills/sync/instructions.md subagent prompt. Return SYNC_REPORT."
+)
+```
+
+Parse SYNC_REPORT. Extract `remote` and `default_branch`. Abort if sync failed.
+
+---
+
+## Stage 2: Commit, Push & Create PR
+
+This stage needs to **read and understand code** to write good commit messages
+and PR descriptions. Use a code-aware subagent.
+
+Launch **ship-analyzer subagent** (reads diffs + source files):
+
+```
+Task(
+  subagent_type: "ship-analyzer",
+  description: "Analyze, commit, push, and create PR",
+  prompt: <read from references/stage-prompts.md#stage-2>
+)
+```
+
+> **Fallback:** If `ship-analyzer` is not available, use `subagent_type: "general-purpose"`.
+
+Substitute `{USER_INTENT}`, `{FILES_TO_INCLUDE}`, `{FILES_TO_EXCLUDE}`,
+`{REMOTE}`, `{DEFAULT_BRANCH}`, `{PLATFORM}` into the prompt.
+
+Parse SHIP_REPORT. Abort if failed.
+
+**Rollback:** If push succeeds but PR creation fails, report the error and
+suggest the manual PR creation command. Do NOT revert the push.
+- GitHub: `gh pr create --head {branch}`
+- Azure DevOps: `az repos pr create --source-branch {branch} --target-branch {DEFAULT_BRANCH}`
+
+**If `--pr-only` flag: Stop here and report PR URL to user.**
+
+---
+
+## Stage 3: Wait for CI
+
+Launch **Bash subagent** in the **background** (haiku — just polling):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  run_in_background: true,
+  description: "Monitor CI checks",
+  prompt: <read from references/stage-prompts.md#stage-3>
+)
+```
+
+Substitute `{PR_NUMBER}` into the prompt.
+
+While CI runs in the background, briefly inform the user:
+```
+CI running for PR #{pr_number}... waiting for checks.
+```
+
+When the background task completes, read the output file and parse CHECKS_REPORT.
+
+---
+
+## Stage 4: Fix Failing Checks (if needed)
+
+If CHECKS_REPORT shows failures, launch **general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Fix CI failures",
+  prompt: <read from references/stage-prompts.md#stage-4>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{BRANCH}`, `{FAILING_CHECKS}` into the prompt.
+
+If fixed, return to Stage 3 (run CI watch again).
+If unable to fix after 2 attempts, report to user and stop.
+
+---
+
+## Stage 5: Merge & Final Sync
+
+Launch **Bash subagent** (haiku — simple git + platform CLI commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Merge PR and sync",
+  prompt: <read from references/stage-prompts.md#stage-5>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{REMOTE}`, `{DEFAULT_BRANCH}`, merge/branch flags.
+
+Parse LAND_REPORT.
+
+---
+
+## Final Report to User
+
+Compile all stage reports into a summary:
+
+```
+Ship complete
+
+  Branch:  {branch}
+  PR:      {pr_url}
+  Merged:  {merge_commit} ({merge_type})
+
+  Commits:
+  {list of commit messages, indented}
+
+  Files:   {count} files changed ({diff_summary})
+```
+
+If any stage failed, report the failure point and suggested resolution.

package/skills/ship/references/stage-prompts.md

@@ -0,0 +1,322 @@
+# Ship Stage Prompts
+
+Subagent prompts for each ship stage. The orchestrator reads these and
+substitutes template variables before launching each subagent.
+
+`{PLATFORM}` is either `github` or `azdo` (detected from remote URL).
+
+---
+
+## Stage 2: Commit, Push & Create PR
+
+**Agent:** ship-analyzer (fallback: general-purpose)
+
+```
+Ship the following changes. Analyze the diffs, create semantic commits,
+push to a feature branch, and create a pull request.
+
+Limit SHIP_REPORT to 15 lines maximum.
+
+PLATFORM: {PLATFORM}
+USER INTENT: {USER_INTENT}
+
+FILES TO INCLUDE: {FILES_TO_INCLUDE}
+
+FILES TO EXCLUDE: {FILES_TO_EXCLUDE}
+
+## Steps
+
+1. **Analyze changes**
+   - Run: git status, git diff, git diff --cached
+   - Read source files where the diff alone doesn't explain intent
+   - Identify logical commit groupings
+
+2. **Create branch** (if on {DEFAULT_BRANCH})
+   git checkout -b <type>/<descriptive-name>
+
+3. **Commit in logical groups**
+   For each logical group:
+     git add <specific-files>
+     git commit -m "$(cat <<'EOF'
+     <type>(<scope>): <description>
+
+     <body if needed>
+     EOF
+     )"
+
+   Rules:
+   - Never add Co-Authored-By or attribution lines
+   - Use HEREDOC for commit messages (ensures proper formatting)
+   - Types: feat, fix, refactor, docs, chore, test, perf
+
+4. **Push**
+   git push -u {REMOTE} $BRANCH
+
+5. **Create PR**
+   - Read: git log {REMOTE}/{DEFAULT_BRANCH}..HEAD --format="%h %s%n%b"
+   - Read: git diff {REMOTE}/{DEFAULT_BRANCH} (skim for PR description context)
+
+   **If PLATFORM == github:**
+     gh pr create --title "<type>: <concise title>" --body "$(cat <<'EOF'
+     ## Summary
+     <1-3 sentences: what and why>
+
+     ## Changes
+     <bullet list of key changes>
+
+     ## Testing
+     - [ ] <verification steps>
+     EOF
+     )"
+
+   **If PLATFORM == azdo:**
+     az repos pr create \
+       --title "<type>: <concise title>" \
+       --description "$(cat <<'EOF'
+     ## Summary
+     <1-3 sentences: what and why>
+
+     ## Changes
+     <bullet list of key changes>
+
+     ## Testing
+     - [ ] <verification steps>
+     EOF
+     )" \
+       --source-branch "$BRANCH" \
+       --target-branch "{DEFAULT_BRANCH}" \
+       --output json
+
+6. **Gather info**
+
+   **If PLATFORM == github:**
+     PR_URL=$(gh pr view --json url -q .url)
+     PR_NUMBER=$(gh pr view --json number -q .number)
+
+   **If PLATFORM == azdo:**
+     # If az repos pr create returned JSON, parse it directly:
+     PR_NUMBER=$(echo "$PR_JSON" | jq -r '.pullRequestId')
+     # Otherwise list to find it:
+     PR_NUMBER=$(az repos pr list --source-branch "$BRANCH" --status active --query '[0].pullRequestId' -o tsv)
+     PR_URL=$(az repos pr show --id $PR_NUMBER --query 'repository.webUrl' -o tsv)/pullrequest/$PR_NUMBER
+
+   COMMITS=$(git log {REMOTE}/{DEFAULT_BRANCH}..HEAD --oneline)
+   DIFF_STAT=$(git diff {REMOTE}/{DEFAULT_BRANCH} --shortstat)
+   FILES_CHANGED=$(git diff {REMOTE}/{DEFAULT_BRANCH} --name-only)
+
+## Output Format
+
+SHIP_REPORT:
+- status: success|failed
+- platform: {PLATFORM}
+- branch: {branch name}
+- pr_url: {url}
+- pr_number: {number}
+- pr_title: {title}
+- commit_count: {number}
+- commits: {list of commit messages}
+- files_changed: {list}
+- diff_summary: {insertions/deletions}
+- errors: {any errors}
+```
+
+---
+
+## Stage 3: Wait for CI
+
+**Agent:** Bash (haiku, background)
+
+```
+Monitor PR/pipeline status checks until complete.
+
+Limit CHECKS_REPORT to 10 lines maximum.
+
+PLATFORM: {PLATFORM}
+PR_NUMBER: {PR_NUMBER}
+BRANCH: {BRANCH}
+
+## Steps
+
+**If PLATFORM == github:**
+
+1. **Wait for checks to complete**
+   gh pr checks {PR_NUMBER} --watch
+
+2. **Report final status**
+   gh pr checks {PR_NUMBER}
+
+**If PLATFORM == azdo:**
+
+1. **Wait for CI to start** (pipelines may take time to trigger after PR creation)
+   Poll until at least one run appears (max 2 minutes, check every 15s):
+   ```
+   RUNS_FOUND=false
+   for i in $(seq 1 8); do
+     RUN_COUNT=$(az pipelines runs list --branch "$BRANCH" --top 5 --query "length(@)" -o tsv 2>/dev/null)
+     if [ -n "$RUN_COUNT" ] && [ "$RUN_COUNT" != "0" ]; then
+       RUNS_FOUND=true
+       break
+     fi
+     sleep 15
+   done
+   ```
+   If no runs appear after 2 minutes, also check PR policy evaluations:
+   ```
+   az repos pr policy list --id {PR_NUMBER} --query "[].{name:configuration.type.displayName, status:status}" -o table
+   ```
+   If no policies exist either, report `no_checks`.
+
+2. **Wait for runs to complete** (max 30 minutes, check every 30s)
+   ```
+   for i in $(seq 1 60); do
+     IN_PROGRESS=$(az pipelines runs list --branch "$BRANCH" --top 5 --query "[?status=='inProgress'] | length(@)" -o tsv)
+     if [ "$IN_PROGRESS" = "0" ] || [ -z "$IN_PROGRESS" ]; then break; fi
+     sleep 30
+   done
+   ```
+
+3. **Report final status**
+   Check both pipeline runs and PR policy evaluations:
+   ```
+   az pipelines runs list --branch "$BRANCH" --top 5 --query "[].{name:definition.name, status:status, result:result}" -o table
+   az repos pr policy list --id {PR_NUMBER} --query "[].{name:configuration.type.displayName, status:status}" -o table
+   ```
+   A policy status of `approved` or `queued` with no `rejected` means passed.
+   A pipeline result of `succeeded` means passed; `failed` means failed.
+
+## Output Format
+
+CHECKS_REPORT:
+- status: all_passed|some_failed|pending|no_checks
+- checks:
+  - name: {check name}
+    status: success|failure|pending
+- failing_checks: {list of failed check names, or "none"}
+```
+
+---
+
+## Stage 4: Fix Failing Checks
+
+**Agent:** general-purpose (default model)
+
+```
+Fix failing CI checks for PR #{PR_NUMBER} on branch {BRANCH}.
+
+Limit FIX_REPORT to 10 lines maximum.
+
+PLATFORM: {PLATFORM}
+FAILING CHECKS: {FAILING_CHECKS}
+
+## Steps
+
+1. **Get failure details**
+
+   **If PLATFORM == github:**
+     gh run list --branch {BRANCH} --status failure --json databaseId --jq '.[0].databaseId'
+     gh run view <run-id> --log-failed
+
+   **If PLATFORM == azdo:**
+     RUN_ID=$(az pipelines runs list --branch {BRANCH} --top 1 --query "[?result=='failed'].id | [0]" -o tsv)
+     az pipelines runs show --id $RUN_ID --output json
+     # Get timeline for detailed step failures:
+     az devops invoke --area build --resource timeline \
+       --route-parameters project=$(az devops configure -l --query '[?name==`project`].value' -o tsv) buildId=$RUN_ID \
+       --api-version 7.0 --query "records[?result=='failed'].{name:name, log:log.url}" -o table
+
+2. **Analyze and fix**
+   Read the relevant source files, understand the failures, fix the code.
+
+3. **Commit and push**
+   git add <fixed-files>
+   git commit -m "$(cat <<'EOF'
+   fix: address CI feedback - {specific issue}
+   EOF
+   )"
+   git push
+
+## Output Format
+
+FIX_REPORT:
+- status: fixed|unable_to_fix
+- changes_made: {description}
+- files_modified: {list}
+- errors: {if unable to fix, why}
+```
+
+---
+
+## Stage 5: Merge & Final Sync
+
+**Agent:** Bash (haiku)
+
+```
+Merge the pull request and sync local {DEFAULT_BRANCH}.
+
+Limit LAND_REPORT to 10 lines maximum.
+
+PLATFORM: {PLATFORM}
+PR_NUMBER: {PR_NUMBER}
+MERGE_FLAGS: {--squash (default) | --merge if --no-squash}
+BRANCH_FLAGS: {--delete-branch (default) | omit if --keep-branch}
+
+## Steps
+
+1. **Merge**
+
+   **If PLATFORM == github:**
+     gh pr merge {PR_NUMBER} {MERGE_FLAGS} {BRANCH_FLAGS}
+
+   **If PLATFORM == azdo:**
+     # 1. Verify all policies pass before attempting merge
+     REJECTED=$(az repos pr policy list --id {PR_NUMBER} --query "[?status=='rejected'] | length(@)" -o tsv 2>/dev/null)
+     if [ -n "$REJECTED" ] && [ "$REJECTED" != "0" ]; then
+       echo "ERROR: $REJECTED PR policies are rejected — cannot merge"
+       az repos pr policy list --id {PR_NUMBER} --query "[?status=='rejected'].{name:configuration.type.displayName, status:status}" -o table
+       # Report failure
+       exit 1
+     fi
+
+     # 2. Complete the PR with merge strategy
+     MERGE_STRATEGY="squash"   # default; use "noFastForward" if --no-squash
+     DELETE_BRANCH="true"      # default; use "false" if --keep-branch
+
+     az repos pr update --id {PR_NUMBER} --status completed \
+       --squash $( [ "$MERGE_STRATEGY" = "squash" ] && echo "true" || echo "false" ) \
+       --delete-source-branch $DELETE_BRANCH
+
+     # 3. If merge fails (e.g. policies still evaluating), wait and retry once
+     if [ $? -ne 0 ]; then
+       echo "Merge failed, waiting 30s for policies to finalize..."
+       sleep 30
+       az repos pr update --id {PR_NUMBER} --status completed \
+         --squash $( [ "$MERGE_STRATEGY" = "squash" ] && echo "true" || echo "false" ) \
+         --delete-source-branch $DELETE_BRANCH
+     fi
+
+2. **Sync local {DEFAULT_BRANCH}**
+   git checkout {DEFAULT_BRANCH}
+   git pull {REMOTE} {DEFAULT_BRANCH}
+
+3. **Restore working state** (if there were stashed changes)
+   git stash pop (only if stash exists from Stage 1)
+
+4. **Cleanup stale branches**
+   git fetch --prune
+   for branch in $(git branch -vv | grep ': gone]' | awk '{print $1}'); do
+     git branch -d "$branch" 2>/dev/null
+   done
+
+5. **Report**
+   MERGE_COMMIT=$(git rev-parse --short HEAD)
+
+## Output Format
+
+LAND_REPORT:
+- status: success|failed
+- merge_commit: {hash}
+- merge_type: squash|merge
+- branch_deleted: true|false
+- branches_cleaned: {list or "none"}
+- errors: {any errors}
+```

package/skills/ship/tests/evals.json

@@ -0,0 +1,30 @@
+[
+  {
+    "name": "banner-and-tagline",
+    "prompt": "Ship my changes",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "(Special delivery|If it compiles|Anchors aweigh|push and pray|faster than Amazon|Yeet the code|merge queue|LGTM)" },
+      { "type": "semantic", "value": "The response begins with an ASCII art banner displayed BEFORE any explanation or workflow steps" }
+    ]
+  },
+  {
+    "name": "pr-lifecycle",
+    "prompt": "Ship the feature I've been working on",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "(commit|push|PR|pull request)", "flags": "i" },
+      { "type": "regex", "value": "(CI|check|merge)", "flags": "i" },
+      { "type": "semantic", "value": "Describes a multi-stage PR lifecycle that includes syncing, committing, pushing, creating a PR, monitoring CI, and merging" }
+    ]
+  },
+  {
+    "name": "subagent-architecture",
+    "prompt": "Ship everything to production",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "ship.analyzer", "flags": "i" },
+      { "type": "semantic", "value": "Mentions using specialized subagents for different stages, including a ship-analyzer agent for code analysis and commit/PR creation" }
+    ]
+  }
+]

package/skills/sync/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: sync
+description: >
+  Sync local repository with origin/main. Use before starting new work, after
+  completing a PR, or when needing latest upstream changes. Safely stashes
+  uncommitted changes, fetches and pulls origin/main, restores stash, and cleans
+  up stale local branches (merged or with deleted remotes). Invoke when switching
+  contexts or preparing for new feature work.
+---
+
+# Sync - Repository Synchronization
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time:
+
+```
+{tagline}
+
+    ██╗███████╗██╗   ██╗███╗   ██╗ ██████╗
+   ██╔╝██╔════╝╚██╗ ██╔╝████╗  ██║██╔════╝
+  ██╔╝ ███████╗ ╚████╔╝ ██╔██╗ ██║██║
+ ██╔╝  ╚════██║  ╚██╔╝  ██║╚██╗██║██║
+██╔╝   ███████║   ██║   ██║ ╚████║╚██████╗
+╚═╝    ╚══════╝   ╚═╝   ╚═╝  ╚═══╝ ╚═════╝
+
+```
+
+Taglines:
+- 🎯 Pulling the latest moves...
+- 🚂 All aboard the sync train!
+- 🤝 Getting everyone on the same page!
+- 📡 Fetching the latest plot twists!
+- 🥷 Time to steal everyone else's code!
+- ☕ Catching up on what you missed!
+- 🔁 Rebase, merge, rinse, repeat!
+- 🎬 Previously on main...
+
+Follow instructions in: [instructions.md](instructions.md)
+
+## Subagent Architecture
+
+Single **Bash** subagent with **haiku** model. Pure git commands — no code
+analysis needed, so the cheapest/fastest model is used. All git output stays
+in the subagent context; the primary agent only sees the structured SYNC_REPORT.
+
+## Flags
+
+- `--no-stash` — Skip auto-stashing uncommitted changes
+- `--no-cleanup` — Skip deleting stale local branches
+- `--no-rebase` — Use merge instead of rebase on feature branches
+
+## Safety
+
+Safe by default: detached HEAD, rebase conflicts, and stash conflicts are detected and reported without destructive action.