@slamb2k/mad-skills 2.0.39 → 2.0.41

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.39",
+  "version": "2.0.41",
   "author": {
     "name": "slamb2k",
     "url": "https://github.com/slamb2k"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.39",
+  "version": "2.0.41",
   "description": "Claude Code skills collection — full lifecycle development tools",
   "type": "module",
   "repository": {

package/skills/brace/SKILL.md

@@ -249,6 +249,21 @@ Before sending the prompt, substitute these variables:
 
 Parse SCAFFOLD_REPORT. If status is "failed", report to user and stop.
 
+### Branch Discipline Injection
+
+When updating an existing project CLAUDE.md (not creating from template):
+
+1. Check if `## Branch Discipline` already exists:
+   ```bash
+   grep -q "## Branch Discipline" CLAUDE.md
+   ```
+2. If NOT found, inject the Branch Discipline section before `## Guardrails`:
+   - Read the file content
+   - Find the line containing `## Guardrails`
+   - Insert the Branch Discipline section (from the template) immediately before it
+   - If no `## Guardrails` section exists, append the section at the end of the file
+3. If already present, skip (idempotent)
+
 ---
 
 ## Phase 5: Verification & Report

package/skills/brace/references/claude-md-template.md

@@ -51,6 +51,20 @@ handles curated facts.
 
 {UNIVERSAL_PRINCIPLES}
 
+## Branch Discipline
+
+- **Always sync to main before starting new work** — run `/sync` or
+  `git checkout main && git pull` before creating a feature branch
+- **Never branch from a feature branch** — always branch from an up-to-date `main`
+- **One feature per branch** — don't stack unrelated changes on the same branch
+- **After shipping a PR, sync immediately** — checkout main and pull before
+  starting the next task
+- **If a PR is pending review**, switch to main before starting unrelated work —
+  don't build on top of an unmerged branch
+
+These rules prevent divergent branches that require complex rebases with risk
+of silent conflict resolution.
+
 ## Guardrails
 
 - Verify tool output format before chaining into another tool

package/skills/build/SKILL.md

@@ -141,6 +141,39 @@ Before Stage 1, resolve the PLAN argument into content:
    - File: `Plan: {file path} ({line count} lines)`
    - Text: `Plan: inline ({word count} words)`
 
+## Pre-Build Branch Check
+
+Before starting Stage 1, verify the working tree is suitable for building:
+
+1. **Detect current branch and default branch:**
+   ```bash
+   CURRENT=$(git branch --show-current)
+   DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+   DEFAULT_BRANCH="${DEFAULT_BRANCH:-main}"
+   git fetch origin "$DEFAULT_BRANCH" --quiet 2>/dev/null
+   ```
+
+2. **If on a feature branch** (not `main`/`master`/default):
+   ```bash
+   BEHIND=$(git rev-list --count HEAD..origin/"$DEFAULT_BRANCH" 2>/dev/null || echo 0)
+   ```
+   If `BEHIND > 0`, warn the user via `AskUserQuestion`:
+   ```
+   "You're on branch '{CURRENT}' which is {BEHIND} commits behind {DEFAULT_BRANCH}.
+   Starting a new feature here risks divergent branches and complex rebases."
+   ```
+   Options:
+   - "Switch to main first (Recommended)" — run `/sync`, then create a new branch
+   - "Continue on this branch" — proceed (user accepts the risk)
+   - "Cancel" — stop
+
+3. **If on the default branch** and not up to date:
+   ```bash
+   LOCAL=$(git rev-parse "$DEFAULT_BRANCH")
+   REMOTE=$(git rev-parse "origin/$DEFAULT_BRANCH")
+   ```
+   If `LOCAL != REMOTE`, run `/sync` automatically before proceeding.
+
 ---
 
 ## Stage 1: Explore

package/skills/manifest.json

@@ -1,12 +1,12 @@
 {
-  "generated": "2026-03-17T23:37:17.477Z",
+  "generated": "2026-03-22T07:57:16.501Z",
   "count": 10,
   "skills": [
     {
       "name": "brace",
       "directory": "brace",
       "description": "'Initialize any project directory with a standard scaffold for AI-assisted development. Creates specs/ and context/ directories, a project CLAUDE.md with development workflow and guardrails, .gitignore, and branch protection. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: \"init project\", \"setup brace\", \"brace\", \"initialize\", \"bootstrap\", \"scaffold\".'",
-      "lines": 445,
+      "lines": 460,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -16,7 +16,7 @@
       "name": "build",
       "directory": "build",
       "description": "Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.",
-      "lines": 378,
+      "lines": 411,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -66,7 +66,7 @@
       "name": "rig",
       "directory": "rig",
       "description": "'Idempotently bootstrap any repository with standard development tools, hooks, and workflows. Use when starting work on a new repo, onboarding to an existing project, or ensuring a repo has proper CI/CD setup. Configures: git hooks (lefthook), commit message templates, PR templates, and GitHub Actions for lint/format/type-check/build. Prompts for user confirmation before changes. Triggers: \"bootstrap repo\", \"setup hooks\", \"configure CI\", \"rig\", \"standardize repo\".'",
-      "lines": 343,
+      "lines": 363,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": true,
@@ -76,7 +76,7 @@
       "name": "ship",
       "directory": "ship",
       "description": "\"Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship.\"",
-      "lines": 418,
+      "lines": 495,
       "hasScripts": true,
       "hasReferences": true,
       "hasAssets": false,
@@ -86,7 +86,7 @@
       "name": "speccy",
       "directory": "speccy",
       "description": "Deep-dive interview skill for creating comprehensive specifications. Reviews existing code and docs, then interviews the user through multiple rounds of targeted questions covering technical implementation, UI/UX, concerns, and tradeoffs. Produces a structured spec in specs/. Use when starting a new feature, system, or major change that needs a spec.",
-      "lines": 253,
+      "lines": 272,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,

package/skills/rig/SKILL.md

@@ -293,6 +293,26 @@ If "Let me choose", present individual options as multi-select.
 For each approved item, follow the procedures in
 `references/configuration-steps.md`.
 
+### Branch Discipline in CLAUDE.md
+
+If the project has an existing `CLAUDE.md`:
+
+1. Check if `## Branch Discipline` already exists:
+   ```bash
+   grep -q "## Branch Discipline" CLAUDE.md
+   ```
+2. If NOT found, inject the Branch Discipline section before `## Guardrails`:
+   - Read the file content
+   - Find the line containing `## Guardrails`
+   - Insert the Branch Discipline section immediately before it
+   - If no `## Guardrails` section exists, append at the end of the file
+3. If already present, skip (idempotent)
+
+The Branch Discipline content to inject is the `## Branch Discipline` section
+from `skills/brace/references/claude-md-template.md`. Read that file to get
+the exact content — this avoids duplication and ensures both /brace and /rig
+inject identical text.
+
 ---
 
 ## Phase 5: Verification

package/skills/ship/SKILL.md

@@ -318,16 +318,51 @@ The fix subagent MUST commit and push before returning. Once it returns,
 attempt = 0
 while attempt < 2:
   CHECKS = run_watch()
-  if CHECKS.status == "all_passed" or CHECKS.status == "no_checks":
+  if CHECKS.status == "all_passed":
     break  → proceed immediately to Stage 5 (do NOT ask user to confirm merge)
+  if CHECKS.status == "no_checks":
+    → prompt user via AskUserQuestion:
+      "No CI checks found for PR #{PR_NUMBER} after waiting 30 seconds.
+       The repository may not have CI configured, or checks may still be registering."
+      Options:
+      - "Merge without checks (Recommended)" → break to Stage 5
+      - "Wait another 30 seconds" → re-run the watch (do not increment attempt)
+      - "Cancel" → stop /ship and display failure banner
+    break (if user chose merge or after re-wait resolves)
   attempt += 1
   run_fix(CHECKS.failing_checks)
   → loop back to watch
 
 if attempt == 2 and still failing:
-  report failures to user, stop
+  → display failure banner and stop (see Failure Handling below)
 ```
 
+### Failure Handling
+
+When /ship fails at ANY point (CI exhausts fix attempts, merge fails, post-merge
+verification fails), display the failure banner and STOP:
+
+```
+┌─ Ship · FAILED ──────────────────────────────────
+│
+│  ❌ PR #{PR_NUMBER} was NOT merged
+│
+│  Reason: {specific failure reason}
+│  Branch: {BRANCH} (still active)
+│
+│  ⚠️  You are still on branch '{BRANCH}'.
+│     Run /sync to return to main before starting new work.
+│
+└───────────────────────────────────────────────────
+```
+
+**Critical rules on failure:**
+- Do NOT proceed to "What's Next?"
+- Do NOT suggest next tasks or follow-up work
+- Do NOT invoke `/sync` or any other skill
+- Do NOT use language like "will be auto-merged" or "PR is pending"
+- The failure banner is the LAST output — nothing follows it
+
 ---
 
 ## Stage 5: Merge & Final Sync
@@ -352,6 +387,34 @@ bash "$SKILL_ROOT/skills/ship/scripts/merge.sh" \
 
 Parse LAND_REPORT from output markers. Exit code 0=merged, 1=failed.
 
+### 5a-verify. Verify merge completed
+
+After merge.sh reports success, verify the PR actually merged:
+
+**GitHub:**
+```bash
+PR_STATE=$(gh pr view "$PR_NUMBER" --json state --jq '.state')
+```
+Expected: `"MERGED"`
+
+**AzDO CLI:**
+```bash
+PR_STATE=$(az repos pr show --id "$PR_NUMBER" --query status -o tsv)
+```
+Expected: `"completed"`
+
+**AzDO REST:**
+```bash
+PR_RESP=$(curl -s -H "$AUTH" "${AZDO_ORG_URL}/${AZDO_PROJECT_URL_SAFE}/_apis/git/repositories/${REPO_ID}/pullRequests/${PR_NUMBER}?api-version=7.1")
+PR_STATE=$(echo "$PR_RESP" | jq -r '.status')
+```
+Expected: `"completed"`
+
+If the PR is NOT in the expected merged/completed state, treat as a failure —
+display the failure banner (see Failure Handling) with reason "PR merge was
+accepted but PR is still in '{PR_STATE}' state. The merge may be queued or
+deferred." and stop.
+
 ### 5b. Sync local repo
 
 After the merge script succeeds, run the sync script to checkout the default
@@ -361,10 +424,23 @@ branch, pull the merge commit, and **clean up stale branches**:
 bash "$SKILL_ROOT/skills/sync/scripts/sync.sh" "{REMOTE}" "{DEFAULT_BRANCH}"
 ```
 
+After sync completes, verify the working tree is on the default branch:
+
+```bash
+CURRENT=$(git branch --show-current)
+if [ "$CURRENT" != "{DEFAULT_BRANCH}" ]; then
+  git checkout {DEFAULT_BRANCH}
+  git pull {REMOTE} {DEFAULT_BRANCH}
+fi
+```
+
 ---
 
 ## What's Next?
 
+**Only run this section if /ship succeeded (PR is merged).** If any failure
+occurred, the failure banner was already displayed and nothing should follow it.
+
 After a successful merge, determine what work comes next by checking these
 sources (in priority order):
 
@@ -393,6 +469,7 @@ Compile all stage reports into a summary:
 │  🌿 Branch:  {branch}
 │  🔗 PR:      {pr_url}
 │  🔀 Merged:  {merge_commit} ({merge_type})
+│  🌿 Now on: {DEFAULT_BRANCH} (up to date)
 │
 │  📝 Commits
 │     • {commit message 1}

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

@@ -258,6 +258,12 @@ FAILING CHECKS: {FAILING_CHECKS}
    )"
    git push
 
+CRITICAL — after pushing, your job is DONE. Return immediately.
+- Do NOT manually trigger, queue, or run any CI builds or pipelines
+- Do NOT use `az pipelines run`, `gh workflow run`, or any build-triggering command
+- The PR build policy will trigger automatically on push
+- The orchestrator will poll for the new build via ci-watch.sh
+
 ## Output Format
 
 FIX_REPORT:

package/skills/ship/scripts/ci-watch.sh

@@ -22,12 +22,14 @@ for arg in "$@"; do
 done
 
 STATUS="" CHECKS="" FAILING=""
+GRACE_POLLS=0
 
 emit_report() {
   echo "CHECKS_REPORT_BEGIN"
   echo "status=$STATUS"
   echo "checks=$CHECKS"
   echo "failing_checks=${FAILING:-none}"
+  echo "grace_period_polls=$GRACE_POLLS"
   echo "CHECKS_REPORT_END"
 }
 
@@ -38,15 +40,29 @@ if [ "$PLATFORM" = "github" ]; then
     emit_report; exit 3
   fi
 
+  # Grace period: wait for checks to register (CI may not trigger immediately)
+  GRACE_POLLS=0
+  GRACE_JSON="[]"
+  for _ in $(seq 1 3); do
+    GRACE_POLLS=$((GRACE_POLLS + 1))
+    GRACE_JSON=$(gh pr checks "$PR_NUMBER" --json name,state 2>/dev/null || echo "[]")
+    if [ "$GRACE_JSON" != "[]" ]; then
+      break
+    fi
+    sleep 10
+  done
+
+  # If no checks found after grace period, report and exit
+  if [ "$GRACE_JSON" = "[]" ]; then
+    STATUS="no_checks"; CHECKS=""; FAILING="none"
+    emit_report; exit 0
+  fi
+
   # gh pr checks --watch blocks until done; --fail-fast stops on first failure
   gh pr checks "$PR_NUMBER" --watch --fail-fast 2>/dev/null || true
 
   # Parse final status
   CHECKS_JSON=$(gh pr checks "$PR_NUMBER" --json name,state 2>/dev/null || echo "[]")
-  if [ "$CHECKS_JSON" = "[]" ]; then
-    STATUS="no_checks"; CHECKS=""; FAILING="none"
-    emit_report; exit 0
-  fi
 
   FAIL_COUNT=$(echo "$CHECKS_JSON" | jq '[.[] | select(.state=="FAILURE")] | length')
   CHECKS=$(echo "$CHECKS_JSON" | jq -r '.[] | "\(.name):\(.state | ascii_downcase)"' | paste -sd, -)
@@ -77,9 +93,11 @@ fi
 
 # ── AzDO CLI mode ──────────────────────────────────────
 if [ "$AZDO_MODE" = "cli" ]; then
-  # Wait for CI to start (max 2 min)
+  # Grace period: wait for CI to start (max 2 min)
   RUNS_FOUND=false
+  GRACE_POLLS=0
   for _ in $(seq 1 8); do
+    GRACE_POLLS=$((GRACE_POLLS + 1))
     RUN_COUNT=$(az pipelines runs list --branch "$BRANCH" --top 5 \
       --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" \
       --query "length(@)" -o tsv 2>/dev/null)
@@ -147,9 +165,11 @@ fi
 if [ "$AZDO_MODE" = "rest" ]; then
   BUILDS_URL="$AZDO_ORG_URL/$AZDO_PROJECT_URL_SAFE/_apis/build/builds?branchName=refs/heads/$BRANCH&\$top=5&api-version=7.0"
 
-  # Wait for CI to start (max 2 min)
+  # Grace period: wait for CI to start (max 2 min)
   RUNS_FOUND=false
+  GRACE_POLLS=0
   for _ in $(seq 1 8); do
+    GRACE_POLLS=$((GRACE_POLLS + 1))
     RUN_COUNT=$(curl -s -H "$AUTH" "$BUILDS_URL" | jq '.value | length')
     if [ -n "$RUN_COUNT" ] && [ "$RUN_COUNT" != "0" ]; then
       RUNS_FOUND=true; break

package/skills/ship/scripts/merge.sh

@@ -65,16 +65,34 @@ DELETE_FLAG=$( [ "$DELETE_BRANCH" = true ] && echo "true" || echo "false" )
 
 # ── AzDO CLI mode ──────────────────────────────────────
 if [ "$AZDO_MODE" = "cli" ]; then
-  # Check for rejected policies
-  REJECTED=$(az repos pr policy list --id "$PR_NUMBER" \
-    --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" \
-    --query "[?status=='rejected'] | length(@)" -o tsv 2>/dev/null)
-  if [ -n "$REJECTED" ] && [ "$REJECTED" != "0" ]; then
-    STATUS="failed"
-    ERRORS="$REJECTED PR policies are rejected"
-    MERGE_COMMIT=""; BRANCH_DELETED=false
-    emit_report; exit 1
-  fi
+  # Wait for all policies to reach terminal state (approved/rejected/notApplicable)
+  POLICY_TIMEOUT=20  # 20 iterations × 15 seconds = 5 minutes
+  for POLICY_ITER in $(seq 1 $POLICY_TIMEOUT); do
+    POLICY_JSON=$(az repos pr policy list --id "$PR_NUMBER" --org "$AZDO_ORG_URL" --project "$AZDO_PROJECT" -o json 2>/dev/null || echo "[]")
+
+    REJECTED=$(echo "$POLICY_JSON" | jq '[.[] | select(.status=="rejected")] | length')
+    PENDING=$(echo "$POLICY_JSON" | jq '[.[] | select(.status=="running" or .status=="queued" or .status=="pending")] | length')
+
+    if [ "${REJECTED:-0}" -gt 0 ]; then
+      STATUS="failed"
+      ERRORS="policies rejected"
+      MERGE_COMMIT=""; BRANCH_DELETED=false
+      emit_report; exit 1
+    fi
+
+    if [ "${PENDING:-0}" -eq 0 ]; then
+      break  # All policies terminal
+    fi
+
+    if [ "$POLICY_ITER" -eq "$POLICY_TIMEOUT" ]; then
+      STATUS="failed"
+      ERRORS="policies not evaluated after 5 minutes"
+      MERGE_COMMIT=""; BRANCH_DELETED=false
+      emit_report; exit 1
+    fi
+
+    sleep 15
+  done
 
   # Complete the PR
   if az repos pr update --id "$PR_NUMBER" --status completed \
@@ -111,16 +129,35 @@ if [ "$AZDO_MODE" = "rest" ]; then
   REPO_NAME=$(basename -s .git "$(git remote get-url origin)")
   PR_API="$AZDO_ORG_URL/$AZDO_PROJECT_URL_SAFE/_apis/git/repositories/$REPO_NAME/pullrequests/$PR_NUMBER"
 
-  # Check for rejected policies
-  EVALS=$(curl -s -H "$AUTH" \
-    "$AZDO_ORG_URL/$AZDO_PROJECT_URL_SAFE/_apis/policy/evaluations?artifactId=vstfs:///CodeReview/CodeReviewId/$AZDO_PROJECT_URL_SAFE/$PR_NUMBER&api-version=7.0")
-  REJECTED=$(echo "$EVALS" | jq '[.value[] | select(.status=="rejected")] | length')
-  if [ "$REJECTED" != "0" ]; then
-    STATUS="failed"
-    ERRORS="PR has rejected policy evaluations"
-    MERGE_COMMIT=""; BRANCH_DELETED=false
-    emit_report; exit 1
-  fi
+  # Wait for all policy evaluations to reach terminal state
+  POLICY_TIMEOUT=20
+  for POLICY_ITER in $(seq 1 $POLICY_TIMEOUT); do
+    EVALS=$(curl -s -H "$AUTH" \
+      "$AZDO_ORG_URL/$AZDO_PROJECT_URL_SAFE/_apis/policy/evaluations?artifactId=vstfs:///CodeReview/CodeReviewId/$AZDO_PROJECT_URL_SAFE/$PR_NUMBER&api-version=7.0" 2>/dev/null || echo '{"value":[]}')
+
+    REJECTED=$(echo "$EVALS" | jq '[.value[] | select(.status=="rejected")] | length')
+    PENDING=$(echo "$EVALS" | jq '[.value[] | select(.status=="running" or .status=="queued" or .status=="pending")] | length')
+
+    if [ "${REJECTED:-0}" -gt 0 ]; then
+      STATUS="failed"
+      ERRORS="PR has rejected policy evaluations"
+      MERGE_COMMIT=""; BRANCH_DELETED=false
+      emit_report; exit 1
+    fi
+
+    if [ "${PENDING:-0}" -eq 0 ]; then
+      break
+    fi
+
+    if [ "$POLICY_ITER" -eq "$POLICY_TIMEOUT" ]; then
+      STATUS="failed"
+      ERRORS="policies not evaluated after 5 minutes"
+      MERGE_COMMIT=""; BRANCH_DELETED=false
+      emit_report; exit 1
+    fi
+
+    sleep 15
+  done
 
   # Resolve merge strategy
   MERGE_STRATEGY=$( [ "$SQUASH" = true ] && echo "squash" || echo "noFastForward" )

package/skills/speccy/SKILL.md

@@ -84,6 +84,25 @@ For each row, in order:
 
 ## Stage 1: Context Gathering
 
+### Pre-Spec Branch Check
+
+Before gathering context, check if the user is on a stale branch:
+
+```bash
+CURRENT=$(git branch --show-current)
+if [ "$CURRENT" != "main" ] && [ "$CURRENT" != "master" ]; then
+  git fetch origin main --quiet 2>/dev/null
+  BEHIND=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo 0)
+  if [ "$BEHIND" -gt 5 ]; then
+    echo "⚠️ Branch '$CURRENT' is $BEHIND commits behind main."
+    echo "   Consider running /sync before building from this spec."
+  fi
+fi
+```
+
+This is advisory only (specs don't modify code) — do not block, continue
+regardless of the result.
+
 Before asking any questions, build a thorough understanding of the project:
 
 1. **Capture GOAL** — the user's argument describing what needs to be specified