bigpowers 2.34.1 → 2.34.2

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

@@ -34,6 +34,112 @@ If no manifest is found, prompt the user to specify the type or pass `--type <np
 Before attempting any publish, run all applicable checks:
 
 **npm (`package.json`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**crates.io (`Cargo.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 7. Dry-run mode per registry
+
+See [REFERENCE.md](REFERENCE.md)
+
+## 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"`
+
+---
+
+# Publish Package — Reference
+
+## 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
+```
+
+---
+
+## Reference block 1
+
 ```bash
 # Check auth token exists
 if [ -z "${NPM_TOKEN:-}" ]; then
@@ -71,7 +177,10 @@ if [ -f CHANGELOG.md ]; then
 fi
 ```
 
-**crates.io (`Cargo.toml`):**
+---
+
+## Reference block 2
+
 ```bash
 # Check auth token exists
 if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
@@ -90,7 +199,10 @@ if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_
 fi
 ```
 
-**PyPI (`setup.py` / `pyproject.toml`):**
+---
+
+## Reference block 3
+
 ```bash
 # Check auth token exists
 if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
@@ -106,9 +218,9 @@ if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
 fi
 ```
 
-### 3. Run publish
+---
 
-After all prerequisite checks pass, run the registry-specific command:
+## Reference block 4
 
 ```bash
 # npm
@@ -124,9 +236,9 @@ python -m twine upload dist/*  # or: poetry publish
 brew bump-formula-pr --url=<tarball-url> <formula-name>
 ```
 
-### 4. Verify publish success
+---
 
-After publish, confirm the version appears on the registry:
+## Reference block 5
 
 ```bash
 # npm
@@ -139,9 +251,9 @@ cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER
 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:
+## Reference block 6
 
 ```bash
 # Generic failure handler
@@ -174,9 +286,9 @@ if [ $? -ne 0 ]; then
 fi
 ```
 
-### 6. Dry-run mode (`--dry-run`)
+---
 
-Run `--dry-run` to verify all prerequisites without actually publishing:
+## Reference block 7
 
 ```bash
 # Example output
@@ -192,7 +304,9 @@ $ publish-package --dry-run
 [DRY-RUN] Exiting without publishing.
 ```
 
-### 7. Dry-run mode per registry
+---
+
+## Reference block 8
 
 ```bash
 # npm dry-run
@@ -204,59 +318,3 @@ 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

@@ -64,29 +64,7 @@ bash scripts/land-branch.sh <task-slug> "feat(scope): description"
 ```
 
 **Path B — `scripts/land-branch.sh` missing (fallback):**
-```bash
-# Fallback: manual squash-merge when land-branch.sh is absent
-FEATURE_BRANCH=<task-slug>
-DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
-
-# Ensure we're on the feature branch
-if [ "$(git branch --show-current)" != "$FEATURE_BRANCH" ]; then
-  git checkout "$FEATURE_BRANCH"
-fi
-
-# Checkout default branch and update
-git checkout "$DEFAULT_BRANCH"
-git pull --rebase origin "$DEFAULT_BRANCH" 2>/dev/null || git pull origin "$DEFAULT_BRANCH"
-
-# Squash-merge the feature branch
-git merge --no-ff "$FEATURE_BRANCH" -m "<conventional-commit-message>"
-
-# Push
-git push origin "$DEFAULT_BRANCH"
-
-# Clean up local feature branch
-git branch -d "$FEATURE_BRANCH"
-```
+See [REFERENCE.md](REFERENCE.md)
 
 **Report which path was taken.** Print exactly:
 - `"used land-branch.sh"` if Path A
@@ -118,41 +96,7 @@ mv specs/epics/eNN-slug specs/epics/archive/
 
 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
-```
+See [REFERENCE.md](REFERENCE.md)
 
 - [ ] CI workflow passes after push
 - [ ] `release.ci_verified: true` documented in state.yaml
@@ -178,21 +122,12 @@ git checkout main && git status && pwd
 
 Report: "Branch released. Integrate mode: <solo-local|team-pr>. cwd: $(pwd) on $(git branch --show-current)."
 
-## Solo-local fallback detail
-
-The fallback sequence (Path B above) handles the "remote has moved" case with `git pull --rebase`. Use when `scripts/land-branch.sh` is absent.
-
-**Acceptance:** When fallback runs, main is updated, feature branch is deleted locally, and output states `"used fallback merge (land-branch.sh not found)"`.
-
-## Handoff
-
-Gate: READY -> next: survey-context
-Writes: state.yaml handoff.next_skill = survey-context
-
 ---
 
 # Release Branch — Reference
 
+# Release Branch — Reference
+
 ## PR body template (team-pr mode)
 
 ```bash
@@ -246,3 +181,84 @@ After landing the branch, record delivery metrics for this story:
   cycle_minutes: 90
   bcp_per_hour: 2.0
 ```
+
+---
+
+## Solo-local fallback detail
+
+The fallback sequence (Path B above) handles the "remote has moved" case with `git pull --rebase`. Use when `scripts/land-branch.sh` is absent.
+
+**Acceptance:** When fallback runs, main is updated, feature branch is deleted locally, and output states `"used fallback merge (land-branch.sh not found)"`.
+
+## Handoff
+
+Gate: READY -> next: survey-context
+Writes: state.yaml handoff.next_skill = survey-context
+
+---
+
+## Reference block 1
+
+```bash
+# Fallback: manual squash-merge when land-branch.sh is absent
+FEATURE_BRANCH=<task-slug>
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
+
+# Ensure we're on the feature branch
+if [ "$(git branch --show-current)" != "$FEATURE_BRANCH" ]; then
+  git checkout "$FEATURE_BRANCH"
+fi
+
+# Checkout default branch and update
+git checkout "$DEFAULT_BRANCH"
+git pull --rebase origin "$DEFAULT_BRANCH" 2>/dev/null || git pull origin "$DEFAULT_BRANCH"
+
+# Squash-merge the feature branch
+git merge --no-ff "$FEATURE_BRANCH" -m "<conventional-commit-message>"
+
+# Push
+git push origin "$DEFAULT_BRANCH"
+
+# Clean up local feature branch
+git branch -d "$FEATURE_BRANCH"
+```
+
+---
+
+## Reference block 2
+
+```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
+```

package/.pi/skills/smoke-test/SKILL.md

@@ -22,6 +22,94 @@ Can be run standalone for quick health checks or chained as the final step of th
 
 Smoke checks are defined in `smoke-checks.yaml` at the project root:
 
+See [REFERENCE.md](REFERENCE.md)
+
+Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use.
+
+### Check Schema
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Human-readable check name (used in report) |
+| `path` | Yes | `/` | URL path relative to base_url |
+| `method` | No | `GET` | HTTP method |
+| `expected_status` | No | `200` | Expected HTTP status code |
+| `content_signal` | No | — | Regex or string to find in response body |
+| `max_response_time_ms` | No | — | Fail if response slower than this threshold (ms) |
+
+## Process
+
+### 1. Load smoke checks
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 2. Run each check
+
+For each check in the configuration, perform an HTTP request:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 3. Assert results
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 4. Generate report
+
+See [REFERENCE.md](REFERENCE.md)
+
+## Integration with deploy skill
+
+The `deploy` skill references `smoke-test` as its final verification step:
+
+```bash
+# In deploy workflow — after successful deploy
+DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
+```
+
+---
+
+# Smoke Test — Reference
+
+## Runner script
+
+A ready-to-use runner is provided for standalone operation:
+
+```bash
+bash scripts/run-smoke.sh [url] [smoke-checks-file]
+```
+
+The runner:
+1. Uses `$DEPLOY_URL`, `$SMOKE_CHECKS_FILE`, or CLI arguments
+2. Runs all defined checks
+3. Prints a pass/fail summary
+4. Exits 0 on all pass, non-zero on any failure
+
+
+---
+
+## Configuration reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SMOKE_CHECKS_FILE` | `smoke-checks.yaml` | Path to smoke checks YAML |
+| `DEPLOY_URL` / `BASE_URL` | *(required)* | Base URL for all checks |
+| `SMOKE_TIMEOUT` | `30` | Per-check timeout (seconds) |
+| `SMOKE_RETRIES` | `0` | Number of retries on failure |
+
+
+---
+
+## Verification
+
+→ verify: `test -f smoke-test/SKILL.md && grep -q 'name: smoke-test' smoke-test/SKILL.md && echo OK`
+→ verify: `grep -qi 'smoke.checks.yaml\|checklist\|expected_status\|content_signal' smoke-test/SKILL.md && echo OK`
+→ verify: `grep -ci 'pass\|fail\|summary\|report' smoke-test/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'smoke-test' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
 ```yaml
 # smoke-checks.yaml — auto-loaded if present at project root
 base_url: "https://example.com"
@@ -52,22 +140,9 @@ checks:
     content_signal: "not found|404"
 ```
 
-Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use.
-
-### Check Schema
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `name` | Yes | — | Human-readable check name (used in report) |
-| `path` | Yes | `/` | URL path relative to base_url |
-| `method` | No | `GET` | HTTP method |
-| `expected_status` | No | `200` | Expected HTTP status code |
-| `content_signal` | No | — | Regex or string to find in response body |
-| `max_response_time_ms` | No | — | Fail if response slower than this threshold (ms) |
-
-## Process
+---
 
-### 1. Load smoke checks
+## Reference block 2
 
 ```bash
 SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
@@ -83,9 +158,9 @@ else
 fi
 ```
 
-### 2. Run each check
+---
 
-For each check in the configuration, perform an HTTP request:
+## Reference block 3
 
 ```bash
 url="${BASE_URL}${path}"
@@ -98,7 +173,9 @@ status=$response
 body=$(cat /tmp/smoke_body.txt)
 ```
 
-### 3. Assert results
+---
+
+## Reference block 4
 
 ```bash
 checks_passed=0
@@ -133,7 +210,9 @@ if [ -n "$max_response_time_ms" ] && [ "$response_time" -gt "$max_response_time_
 fi
 ```
 
-### 4. Generate report
+---
+
+## Reference block 5
 
 ```bash
 total=$((checks_passed + checks_failed))
@@ -151,42 +230,3 @@ else
   exit 0
 fi
 ```
-
-## Runner script
-
-A ready-to-use runner is provided for standalone operation:
-
-```bash
-bash scripts/run-smoke.sh [url] [smoke-checks-file]
-```
-
-The runner:
-1. Uses `$DEPLOY_URL`, `$SMOKE_CHECKS_FILE`, or CLI arguments
-2. Runs all defined checks
-3. Prints a pass/fail summary
-4. Exits 0 on all pass, non-zero on any failure
-
-## Integration with deploy skill
-
-The `deploy` skill references `smoke-test` as its final verification step:
-
-```bash
-# In deploy workflow — after successful deploy
-DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
-```
-
-## Configuration reference
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SMOKE_CHECKS_FILE` | `smoke-checks.yaml` | Path to smoke checks YAML |
-| `DEPLOY_URL` / `BASE_URL` | *(required)* | Base URL for all checks |
-| `SMOKE_TIMEOUT` | `30` | Per-check timeout (seconds) |
-| `SMOKE_RETRIES` | `0` | Number of retries on failure |
-
-## Verification
-
-→ verify: `test -f smoke-test/SKILL.md && grep -q 'name: smoke-test' smoke-test/SKILL.md && echo OK`
-→ verify: `grep -qi 'smoke.checks.yaml\|checklist\|expected_status\|content_signal' smoke-test/SKILL.md && echo OK`
-→ verify: `grep -ci 'pass\|fail\|summary\|report' smoke-test/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
-→ verify: `grep -q 'smoke-test' SKILL-INDEX.md && echo OK`

package/.pi/skills/using-bigpowers/SKILL.md

@@ -9,7 +9,7 @@ model: sonnet
 > **HARD GATE** — **HARD GATE** — This skill is the entry point. Do NOT skip it when onboarding new users or starting a new session. It establishes the bigpowers methodology, lifecycle phases, and conventions.
 
 
-Welcome to **bigpowers** — a lifecycle of **61** agent skills for production-ready, TDD-driven software by solo developers.
+Welcome to **bigpowers** — a lifecycle of **70** agent skills for production-ready, TDD-driven software by solo developers.
 
 ## Install
 
@@ -100,7 +100,7 @@ Start the HTTP dashboard with `visual-dashboard` → `GET /api/status?projectDir
 - **Integrate:** team default is `gh pr` (team-pr); solo profile uses `land-branch.sh`. Never create GitHub issues from skills — use local Markdown files instead.
 - **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
 - **verify: every step.** Every epic task must have `verify: <runnable command>`. Evidence over claims.
-- **61 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
+- **70 skills.** See `SKILL-INDEX.md`; find skills with `search-skills`.
 
 ## After this