bigpowers 2.8.0 → 2.10.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.8.0",
-  "description": "63 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.10.0",
+  "description": "64 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/develop-tdd.md

@@ -67,6 +67,66 @@ After all tests pass: extract duplication, deepen modules, apply SOLID principle
 
 After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
+### 6a. CI dry-run sub-step (when modifying workflows)
+
+If this cycle modified files in `.github/workflows/`, run a CI dry-run before pushing:
+
+```bash
+# 1. Check for workflow file changes
+CHANGED_WORKFLOWS=$(git diff --name-only HEAD | grep '\.github/workflows/' || true)
+if [ -n "$CHANGED_WORKFLOWS" ]; then
+  echo "==> CI dry-run: workflow files changed"
+  echo "    $CHANGED_WORKFLOWS"
+
+  # 2. Validate YAML syntax
+  if command -v yamllint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      yamllint "$f" && echo "  OK: $f passes YAML lint" || echo "  WARN: $f has YAML issues"
+    done
+  else
+    # Fallback: Python YAML parse
+    for f in $CHANGED_WORKFLOWS; do
+      python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null && \
+        echo "  OK: $f YAML syntax valid" || \
+        echo "  FAIL: $f has YAML syntax errors"
+    done
+  fi
+
+  # 3. Run actionlint if available
+  if command -v actionlint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      actionlint "$f" && echo "  OK: $f passes actionlint" || echo "  WARN: $f has actionlint issues"
+    done
+  fi
+
+  # 4. Check common pitfalls
+  for f in $CHANGED_WORKFLOWS; do
+    # Missing permissions block
+    if ! grep -q 'permissions:' "$f"; then
+      echo "  WARNING: $f missing permissions block — add one for security"
+    fi
+    # npm publish without NPM_TOKEN
+    if grep -q 'npm publish\|npx semantic-release' "$f" && ! grep -q 'NPM_TOKEN' "$f"; then
+      echo "  WARNING: $f has npm publish/semantic-release but no NPM_TOKEN in secrets"
+    fi
+    # Hardcoded Node versions
+    if grep -q 'node-version: [0-9]' "$f"; then
+      echo "  NOTE: $f has hardcoded Node version — consider node-version-file: .nvmrc"
+    fi
+  done
+
+  # 5. Suggest local dry-run
+  if command -v act &>/dev/null; then
+    echo "  SUGGESTION: Run 'act push --dry-run' to test workflows locally"
+  fi
+fi
+```
+
+Checklist:
+- [ ] YAML syntax validated for all changed workflow files
+- [ ] No missing permissions, secrets, or hardcoded versions flagged
+- [ ] Local dry-run suggested if `act` is available
+
 ### 7. Manual Verification Handover
 
 Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.

package/.pi/prompts/publish-package.md

@@ -0,0 +1,260 @@
+---
+description: "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure."
+---
+
+
+# Publish Package
+
+> **HARD GATE** — Do not attempt to publish without verifying prerequisites. Missing auth tokens, stale builds, or duplicate versions cause CI failures that are hard to debug post-push.
+>
+> **HARD GATE** — Always run `--dry-run` first. Package registries are append-only — a bad publish cannot be fully undone on most registries.
+
+Publish packages to language-specific registries. Detects package type from manifest files, verifies publish prerequisites, runs the registry-specific publish command, and confirms the version appears on the registry.
+
+## Process
+
+### 1. Detect package type
+
+Read the project root for manifest files to determine the package type:
+
+| Manifest | Registry | Publish command |
+|----------|----------|----------------|
+| `package.json` | npm | `npm publish --access public` |
+| `Cargo.toml` | crates.io | `cargo publish` |
+| `setup.py` / `pyproject.toml` | PyPI | `twine upload dist/*` or `flit publish` |
+| `Formula/<name>.rb` | Homebrew | `brew bump-formula-pr` |
+| Multiple detected | Polyglot | Error: specify registry with `--registry <npm|crates.io|pypi|brew>` |
+
+If no manifest is found, prompt the user to specify the type or pass `--type <npm|crates.io|pypi|brew>`.
+
+### 2. Verify prerequisites
+
+Before attempting any publish, run all applicable checks:
+
+**npm (`package.json`):**
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+**crates.io (`Cargo.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+### 7. Dry-run mode per registry
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+## Verify
+
+→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/.pi/prompts/release-branch.md

@@ -107,6 +107,52 @@ gh pr merge --squash --delete-branch
 mv specs/epics/eNN-slug specs/epics/archive/
 ```
 
+### 7b. CI verification (solo-local and team-pr)
+
+> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
+
+After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+
+```bash
+echo "==> Polling CI for main branch..."
+TIMEOUT=600   # 10 minutes
+INTERVAL=30   # poll every 30 seconds
+ELAPSED=0
+
+while [ $ELAPSED -lt $TIMEOUT ]; do
+  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
+  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
+  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
+  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
+  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
+    echo "OK: CI passed for $(git rev-parse --short HEAD)"
+    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
+      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
+    break
+  fi
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
+    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
+    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
+    echo "  Handoff to fix-bug with the failure URL above."
+    return 1
+  fi
+
+  sleep $INTERVAL
+  ELAPSED=$((ELAPSED + INTERVAL))
+  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
+done
+
+echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
+return 1
+```
+
+- [ ] CI workflow passes after push
+- [ ] `release.ci_verified: true` documented in state.yaml
+- On failure: `handoff.next_skill = fix-bug` with the CI failure URL
+
 ### 8. Clean up worktree
 
 ```bash

package/.pi/skills/develop-tdd/SKILL.md

@@ -69,6 +69,66 @@ After all tests pass: extract duplication, deepen modules, apply SOLID principle
 
 After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
+### 6a. CI dry-run sub-step (when modifying workflows)
+
+If this cycle modified files in `.github/workflows/`, run a CI dry-run before pushing:
+
+```bash
+# 1. Check for workflow file changes
+CHANGED_WORKFLOWS=$(git diff --name-only HEAD | grep '\.github/workflows/' || true)
+if [ -n "$CHANGED_WORKFLOWS" ]; then
+  echo "==> CI dry-run: workflow files changed"
+  echo "    $CHANGED_WORKFLOWS"
+
+  # 2. Validate YAML syntax
+  if command -v yamllint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      yamllint "$f" && echo "  OK: $f passes YAML lint" || echo "  WARN: $f has YAML issues"
+    done
+  else
+    # Fallback: Python YAML parse
+    for f in $CHANGED_WORKFLOWS; do
+      python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null && \
+        echo "  OK: $f YAML syntax valid" || \
+        echo "  FAIL: $f has YAML syntax errors"
+    done
+  fi
+
+  # 3. Run actionlint if available
+  if command -v actionlint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      actionlint "$f" && echo "  OK: $f passes actionlint" || echo "  WARN: $f has actionlint issues"
+    done
+  fi
+
+  # 4. Check common pitfalls
+  for f in $CHANGED_WORKFLOWS; do
+    # Missing permissions block
+    if ! grep -q 'permissions:' "$f"; then
+      echo "  WARNING: $f missing permissions block — add one for security"
+    fi
+    # npm publish without NPM_TOKEN
+    if grep -q 'npm publish\|npx semantic-release' "$f" && ! grep -q 'NPM_TOKEN' "$f"; then
+      echo "  WARNING: $f has npm publish/semantic-release but no NPM_TOKEN in secrets"
+    fi
+    # Hardcoded Node versions
+    if grep -q 'node-version: [0-9]' "$f"; then
+      echo "  NOTE: $f has hardcoded Node version — consider node-version-file: .nvmrc"
+    fi
+  done
+
+  # 5. Suggest local dry-run
+  if command -v act &>/dev/null; then
+    echo "  SUGGESTION: Run 'act push --dry-run' to test workflows locally"
+  fi
+fi
+```
+
+Checklist:
+- [ ] YAML syntax validated for all changed workflow files
+- [ ] No missing permissions, secrets, or hardcoded versions flagged
+- [ ] Local dry-run suggested if `act` is available
+
 ### 7. Manual Verification Handover
 
 Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.

package/.pi/skills/publish-package/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: publish-package
+description: "\"Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure.\""
+model: sonnet
+---
+
+
+# Publish Package
+
+> **HARD GATE** — Do not attempt to publish without verifying prerequisites. Missing auth tokens, stale builds, or duplicate versions cause CI failures that are hard to debug post-push.
+>
+> **HARD GATE** — Always run `--dry-run` first. Package registries are append-only — a bad publish cannot be fully undone on most registries.
+
+Publish packages to language-specific registries. Detects package type from manifest files, verifies publish prerequisites, runs the registry-specific publish command, and confirms the version appears on the registry.
+
+## Process
+
+### 1. Detect package type
+
+Read the project root for manifest files to determine the package type:
+
+| Manifest | Registry | Publish command |
+|----------|----------|----------------|
+| `package.json` | npm | `npm publish --access public` |
+| `Cargo.toml` | crates.io | `cargo publish` |
+| `setup.py` / `pyproject.toml` | PyPI | `twine upload dist/*` or `flit publish` |
+| `Formula/<name>.rb` | Homebrew | `brew bump-formula-pr` |
+| Multiple detected | Polyglot | Error: specify registry with `--registry <npm|crates.io|pypi|brew>` |
+
+If no manifest is found, prompt the user to specify the type or pass `--type <npm|crates.io|pypi|brew>`.
+
+### 2. Verify prerequisites
+
+Before attempting any publish, run all applicable checks:
+
+**npm (`package.json`):**
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+**crates.io (`Cargo.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+### 7. Dry-run mode per registry
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+## Verify
+
+→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/.pi/skills/release-branch/SKILL.md

@@ -109,6 +109,52 @@ gh pr merge --squash --delete-branch
 mv specs/epics/eNN-slug specs/epics/archive/
 ```
 
+### 7b. CI verification (solo-local and team-pr)
+
+> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
+
+After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+
+```bash
+echo "==> Polling CI for main branch..."
+TIMEOUT=600   # 10 minutes
+INTERVAL=30   # poll every 30 seconds
+ELAPSED=0
+
+while [ $ELAPSED -lt $TIMEOUT ]; do
+  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
+  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
+  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
+  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
+  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
+    echo "OK: CI passed for $(git rev-parse --short HEAD)"
+    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
+      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
+    break
+  fi
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
+    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
+    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
+    echo "  Handoff to fix-bug with the failure URL above."
+    return 1
+  fi
+
+  sleep $INTERVAL
+  ELAPSED=$((ELAPSED + INTERVAL))
+  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
+done
+
+echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
+return 1
+```
+
+- [ ] CI workflow passes after push
+- [ ] `release.ci_verified: true` documented in state.yaml
+- On failure: `handoff.next_skill = fix-bug` with the CI failure URL
+
 ### 8. Clean up worktree
 
 ```bash

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.10.0](https://github.com/danielvm-git/bigpowers/compare/v2.9.0...v2.10.0) (2026-06-20)
+
+
+### Features
+
+* **skills:** add CI verify and dry-run to skills ([e751564](https://github.com/danielvm-git/bigpowers/commit/e75156478b7c23f4e32ed78eec644916f14dd3c4))
+
+# [2.9.0](https://github.com/danielvm-git/bigpowers/compare/v2.8.0...v2.9.0) (2026-06-20)
+
+
+### Features
+
+* **skills:** add publish-package skill for multi-registry publishing ([945a481](https://github.com/danielvm-git/bigpowers/commit/945a481cef07335c59277c82137e4a6bec78655a))
+
 # [2.8.0](https://github.com/danielvm-git/bigpowers/compare/v2.7.5...v2.8.0) (2026-06-20)
 
 

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-20T21:22:23Z
-**Skills:** 63
+**Generated:** 2026-06-20T21:31:11Z
+**Skills:** 64
 
 ---
 
@@ -15,11 +15,11 @@
 | Discover | 6 | `elaborate-spec, map-codebase, research-first, search-skills, survey-context, using-bigpowers` |
 | Design | 7 | `deepen-architecture, define-language, define-success, design-interface, grill-me, grill-with-docs, model-domain` |
 | Plan | 9 | `assess-impact, change-request, plan-refactor, plan-release, plan-work, run-planning, scope-work, seed-conventions, slice-tasks` |
-| Build | 13 | `align-grid, build-epic, craft-skill, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, setup-environment, spike-prototype, wire-ci, wire-observability` |
+| Build | 14 | `align-grid, build-epic, craft-skill, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, setup-environment, spike-prototype, wire-ci, wire-observability` |
 | Verify | 12 | `audit-code, diagnose-root, enforce-first, fix-bug, inspect-quality, investigate-bug, request-review, respond-review, run-evals, trace-requirement, validate-fix, verify-work` |
 | Release | 2 | `commit-message, release-branch` |
 | Sustain | 13 | `compose-workflow, delegate-task, dispatch-agents, edit-document, evolve-skill, migrate-spec, organize-workspace, reset-baseline, session-state, simulate-agents, stocktake-skills, terse-mode, write-document` |
-| **TOTAL** | **62** | |
+| **TOTAL** | **63** | |
 
 ---
 
@@ -58,39 +58,40 @@
 | 29 | Build | `hook-commits` | Set up pre-commit hooks with lint-staged (Prettier), type checking, and tests in | ✅ Active |
 | 30 | Build | `kickoff-branch` | Create a git worktree and feature branch, then verify a clean test baseline befo | ✅ Active |
 | 31 | Build | `orchestrate-project` | Meta-skill that enforces the 6-phase core loop (discover → elaborate → plan  | ✅ Active |
-| 32 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
-| 33 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
-| 34 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
-| 35 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
-| 36 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
-| 37 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
-| 38 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
-| 39 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
-| 40 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
-| 41 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
-| 42 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
-| 43 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
-| 44 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
-| 45 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
-| 46 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
-| 47 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
-| 48 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
-| 49 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
-| 50 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
-| 51 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
-| 52 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
-| 53 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
-| 54 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
-| 55 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
-| 56 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
-| 57 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
-| 58 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
-| 59 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
-| 60 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
-| 61 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
-| 62 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
-
-**Total: 62 active skills.**
+| 32 | Build | `publish-package` | "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies pr | ✅ Active |
+| 33 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
+| 34 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
+| 35 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
+| 36 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
+| 37 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
+| 38 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
+| 39 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
+| 40 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains  | ✅ Active |
+| 41 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
+| 42 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
+| 43 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after  | ✅ Active |
+| 44 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
+| 45 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
+| 46 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
+| 47 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
+| 48 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
+| 49 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and  | ✅ Active |
+| 50 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
+| 51 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
+| 52 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
+| 53 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
+| 54 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
+| 55 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose  | ✅ Active |
+| 56 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
+| 57 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build  | ✅ Active |
+| 58 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
+| 59 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
+| 60 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
+| 61 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
+| 62 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping  | ✅ Active |
+| 63 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
+
+**Total: 63 active skills.**
 
 ---
 

package/develop-tdd/SKILL.md

@@ -68,6 +68,66 @@ After all tests pass: extract duplication, deepen modules, apply SOLID principle
 
 After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
+### 6a. CI dry-run sub-step (when modifying workflows)
+
+If this cycle modified files in `.github/workflows/`, run a CI dry-run before pushing:
+
+```bash
+# 1. Check for workflow file changes
+CHANGED_WORKFLOWS=$(git diff --name-only HEAD | grep '\.github/workflows/' || true)
+if [ -n "$CHANGED_WORKFLOWS" ]; then
+  echo "==> CI dry-run: workflow files changed"
+  echo "    $CHANGED_WORKFLOWS"
+
+  # 2. Validate YAML syntax
+  if command -v yamllint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      yamllint "$f" && echo "  OK: $f passes YAML lint" || echo "  WARN: $f has YAML issues"
+    done
+  else
+    # Fallback: Python YAML parse
+    for f in $CHANGED_WORKFLOWS; do
+      python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null && \
+        echo "  OK: $f YAML syntax valid" || \
+        echo "  FAIL: $f has YAML syntax errors"
+    done
+  fi
+
+  # 3. Run actionlint if available
+  if command -v actionlint &>/dev/null; then
+    for f in $CHANGED_WORKFLOWS; do
+      actionlint "$f" && echo "  OK: $f passes actionlint" || echo "  WARN: $f has actionlint issues"
+    done
+  fi
+
+  # 4. Check common pitfalls
+  for f in $CHANGED_WORKFLOWS; do
+    # Missing permissions block
+    if ! grep -q 'permissions:' "$f"; then
+      echo "  WARNING: $f missing permissions block — add one for security"
+    fi
+    # npm publish without NPM_TOKEN
+    if grep -q 'npm publish\|npx semantic-release' "$f" && ! grep -q 'NPM_TOKEN' "$f"; then
+      echo "  WARNING: $f has npm publish/semantic-release but no NPM_TOKEN in secrets"
+    fi
+    # Hardcoded Node versions
+    if grep -q 'node-version: [0-9]' "$f"; then
+      echo "  NOTE: $f has hardcoded Node version — consider node-version-file: .nvmrc"
+    fi
+  done
+
+  # 5. Suggest local dry-run
+  if command -v act &>/dev/null; then
+    echo "  SUGGESTION: Run 'act push --dry-run' to test workflows locally"
+  fi
+fi
+```
+
+Checklist:
+- [ ] YAML syntax validated for all changed workflow files
+- [ ] No missing permissions, secrets, or hardcoded versions flagged
+- [ ] Local dry-run suggested if `act` is available
+
 ### 7. Manual Verification Handover
 
 Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/publish-package/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: publish-package
+description: "Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure."
+model: sonnet
+---
+
+# Publish Package
+
+> **HARD GATE** — Do not attempt to publish without verifying prerequisites. Missing auth tokens, stale builds, or duplicate versions cause CI failures that are hard to debug post-push.
+>
+> **HARD GATE** — Always run `--dry-run` first. Package registries are append-only — a bad publish cannot be fully undone on most registries.
+
+Publish packages to language-specific registries. Detects package type from manifest files, verifies publish prerequisites, runs the registry-specific publish command, and confirms the version appears on the registry.
+
+## Process
+
+### 1. Detect package type
+
+Read the project root for manifest files to determine the package type:
+
+| Manifest | Registry | Publish command |
+|----------|----------|----------------|
+| `package.json` | npm | `npm publish --access public` |
+| `Cargo.toml` | crates.io | `cargo publish` |
+| `setup.py` / `pyproject.toml` | PyPI | `twine upload dist/*` or `flit publish` |
+| `Formula/<name>.rb` | Homebrew | `brew bump-formula-pr` |
+| Multiple detected | Polyglot | Error: specify registry with `--registry <npm|crates.io|pypi|brew>` |
+
+If no manifest is found, prompt the user to specify the type or pass `--type <npm|crates.io|pypi|brew>`.
+
+### 2. Verify prerequisites
+
+Before attempting any publish, run all applicable checks:
+
+**npm (`package.json`):**
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+**crates.io (`Cargo.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+### 7. Dry-run mode per registry
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+## Verify
+
+→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/release-branch/SKILL.md

@@ -108,6 +108,52 @@ gh pr merge --squash --delete-branch
 mv specs/epics/eNN-slug specs/epics/archive/
 ```
 
+### 7b. CI verification (solo-local and team-pr)
+
+> **HARD GATE** — Do NOT declare success until CI completes. A push that fails CI is a regression, not a release.
+
+After push (solo-local step 5 or team-pr step 7), verify the CI workflow completes successfully:
+
+```bash
+echo "==> Polling CI for main branch..."
+TIMEOUT=600   # 10 minutes
+INTERVAL=30   # poll every 30 seconds
+ELAPSED=0
+
+while [ $ELAPSED -lt $TIMEOUT ]; do
+  CI_JSON=$(gh run list --limit 1 --branch main --workflow CI --json status,conclusion,headSha,databaseId 2>/dev/null)
+  CI_STATUS=$(echo "$CI_JSON" | jq -r '.[0].status // "unknown"')
+  CI_CONCLUSION=$(echo "$CI_JSON" | jq -r '.[0].conclusion // ""')
+  CI_SHA=$(echo "$CI_JSON" | jq -r '.[0].headSha // ""')
+  CI_ID=$(echo "$CI_JSON" | jq -r '.[0].databaseId // ""')
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "success" ]; then
+    echo "OK: CI passed for $(git rev-parse --short HEAD)"
+    bp-yaml-set.sh specs/state.yaml release.ci_verified true 2>/dev/null || \
+      echo "  (bp-yaml-set not available — manually set release.ci_verified: true in state.yaml)"
+    break
+  fi
+
+  if [ "$CI_STATUS" = "completed" ] && [ "$CI_CONCLUSION" = "failure" ]; then
+    echo "FAIL: CI failed for $(git rev-parse --short HEAD)"
+    echo "  Run URL: https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/actions/runs/$CI_ID"
+    echo "  Handoff to fix-bug with the failure URL above."
+    return 1
+  fi
+
+  sleep $INTERVAL
+  ELAPSED=$((ELAPSED + INTERVAL))
+  echo "  Waiting... (${ELAPSED}s / ${TIMEOUT}s)"
+done
+
+echo "FAIL: CI did not complete within ${TIMEOUT}s timeout"
+return 1
+```
+
+- [ ] CI workflow passes after push
+- [ ] `release.ci_verified: true` documented in state.yaml
+- On failure: `handoff.next_skill = fix-bug` with the CI failure URL
+
 ### 8. Clean up worktree
 
 ```bash

package/scripts/generate-skill-index.sh

@@ -51,6 +51,7 @@ PHASE_MAP=(
   [setup-environment]="Build"
   [wire-observability]="Build"
   [wire-ci]="Build"
+  [publish-package]="Build"
   [align-grid]="Build"
   [orchestrate-project]="Build"
   [guard-git]="Build"

package/skills-lock.json

@@ -68,7 +68,7 @@
     },
     "develop-tdd": {
       "description": "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).",
-      "sha256": "af45529ecb20d449",
+      "sha256": "4002d960b18436cd",
       "path": "develop-tdd/SKILL.md"
     },
     "diagnose-root": {
@@ -186,9 +186,14 @@
       "sha256": "12d45efb07a36e94",
       "path": "plan-work/SKILL.md"
     },
+    "publish-package": {
+      "description": "\"Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure.\"",
+      "sha256": "25ead1dd4d174d54",
+      "path": "publish-package/SKILL.md"
+    },
     "release-branch": {
       "description": "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says \"release\", \"merge\", or \"open a PR\".",
-      "sha256": "70fc37ac4e22143d",
+      "sha256": "6b2df2c92230d098",
       "path": "release-branch/SKILL.md"
     },
     "request-review": {