bigpowers 2.34.1 → 2.34.2

package/skills-lock.json

@@ -68,7 +68,7 @@
     },
     "deploy": {
       "description": "\"Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production.\"",
-      "sha256": "260894aa4f869093",
+      "sha256": "304967c4f7d0ea13",
       "path": "deploy/SKILL.md"
     },
     "design-interface": {
@@ -78,7 +78,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": "e050f400da14eff3",
+      "sha256": "8a232210dc2c11d3",
       "path": "develop-tdd/SKILL.md"
     },
     "diagnose-root": {
@@ -163,7 +163,7 @@
     },
     "migrate-spec": {
       "description": "Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs.",
-      "sha256": "7636756cd3421b20",
+      "sha256": "84077c1eaa2ec40d",
       "path": "migrate-spec/SKILL.md"
     },
     "model-domain": {
@@ -198,7 +198,7 @@
     },
     "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",
+      "sha256": "39f5ba9b115cca6b",
       "path": "publish-package/SKILL.md"
     },
     "quick-fix": {
@@ -208,7 +208,7 @@
     },
     "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": "5d1e07e58d1aff44",
+      "sha256": "fd5e968246ce07bd",
       "path": "release-branch/SKILL.md"
     },
     "request-review": {
@@ -283,7 +283,7 @@
     },
     "smoke-test": {
       "description": "\"Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill.\"",
-      "sha256": "402c89c31ac4fd4c",
+      "sha256": "85d2de9e87e141f7",
       "path": "smoke-test/SKILL.md"
     },
     "spike-prototype": {
@@ -313,12 +313,12 @@
     },
     "using-bigpowers": {
       "description": "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained.",
-      "sha256": "b150ea218b529f61",
+      "sha256": "3e73bdd359b49743",
       "path": "using-bigpowers/SKILL.md"
     },
     "validate-contracts": {
       "description": "\"Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy.\"",
-      "sha256": "17653c7ac211c5d8",
+      "sha256": "59cf618f642fa10c",
       "path": "validate-contracts/SKILL.md"
     },
     "validate-fix": {
@@ -338,7 +338,7 @@
     },
     "wire-ci": {
       "description": "\"CI pipeline setup with pre-built templates and local validation. Generates GitHub Actions workflows, validates YAML syntax and permissions, supports dry-run via act/gh. The CI equivalent of wire-observability.\"",
-      "sha256": "dcbf6e1516f6b355",
+      "sha256": "cc3fd8faf2686be1",
       "path": "wire-ci/SKILL.md"
     },
     "wire-observability": {

package/smoke-test/REFERENCE.md

@@ -0,0 +1,162 @@
+# 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"
+checks:
+  - name: "Homepage"
+    path: "/"
+    method: GET
+    expected_status: 200
+    content_signal: "bigpowers"
+    max_response_time_ms: 3000
+
+  - name: "API Health"
+    path: "/api/health"
+    method: GET
+    expected_status: 200
+    content_signal: "ok|healthy"
+
+  - name: "API Jogos"
+    path: "/api/jogos"
+    method: GET
+    expected_status: 200
+    content_signal: "jogos|games"
+
+  - name: "Not Found handling"
+    path: "/nonexistent"
+    method: GET
+    expected_status: 404
+    content_signal: "not found|404"
+```
+
+---
+
+## Reference block 2
+
+```bash
+SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+BASE_URL="${DEPLOY_URL:-$BASE_URL}"
+
+if [ -f "$SMOKE_CHECKS_FILE" ]; then
+  echo "Loaded smoke checks from $SMOKE_CHECKS_FILE"
+elif [ -n "$BASE_URL" ]; then
+  echo "No smoke-checks.yaml found. Using single URL check against $BASE_URL"
+else
+  echo "ERROR: No smoke-checks.yaml found and no DEPLOY_URL/BASE_URL set."
+  exit 1
+fi
+```
+
+---
+
+## Reference block 3
+
+```bash
+url="${BASE_URL}${path}"
+start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
+
+# Perform the HTTP request
+response=$(curl -s -o /tmp/smoke_body.txt -w "%{http_code}" "$url")
+response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
+status=$response
+body=$(cat /tmp/smoke_body.txt)
+```
+
+---
+
+## Reference block 4
+
+```bash
+checks_passed=0
+checks_failed=0
+failures=""
+
+# Assert status code
+if [ "$status" -ne "${expected_status:-200}" ]; then
+  echo "  FAIL: expected status ${expected_status} but got $status"
+  checks_failed=$((checks_failed + 1))
+  failures="${failures}  - $name: HTTP $status (expected ${expected_status})\n"
+else
+  echo "  PASS: HTTP $status"
+fi
+
+# Assert content signal
+if [ -n "$content_signal" ]; then
+  if echo "$body" | grep -qiE "$content_signal"; then
+    echo "  PASS: body contains \"$content_signal\""
+  else
+    echo "  FAIL: body does not contain \"$content_signal\""
+    checks_failed=$((checks_failed + 1))
+    failures="${failures}  - $name: missing content signal \"$content_signal\"\n"
+  fi
+fi
+
+# Assert response time
+if [ -n "$max_response_time_ms" ] && [ "$response_time" -gt "$max_response_time_ms" ]; then
+  echo "  FAIL: response time ${response_time}ms exceeds ${max_response_time_ms}ms"
+  checks_failed=$((checks_failed + 1))
+  failures="${failures}  - $name: response time ${response_time}ms (max ${max_response_time_ms}ms)\n"
+fi
+```
+
+---
+
+## Reference block 5
+
+```bash
+total=$((checks_passed + checks_failed))
+echo ""
+echo "=== Smoke Test Summary ==="
+echo "Total: $total | Passed: $checks_passed | Failed: $checks_failed"
+
+if [ "$checks_failed" -gt 0 ]; then
+  echo ""
+  echo "Failures:"
+  echo -e "$failures"
+  exit 1
+else
+  echo "All checks passed."
+  exit 0
+fi
+```

package/smoke-test/SKILL.md

@@ -21,35 +21,7 @@ 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:
 
-```yaml
-# smoke-checks.yaml — auto-loaded if present at project root
-base_url: "https://example.com"
-checks:
-  - name: "Homepage"
-    path: "/"
-    method: GET
-    expected_status: 200
-    content_signal: "bigpowers"
-    max_response_time_ms: 3000
-
-  - name: "API Health"
-    path: "/api/health"
-    method: GET
-    expected_status: 200
-    content_signal: "ok|healthy"
-
-  - name: "API Jogos"
-    path: "/api/jogos"
-    method: GET
-    expected_status: 200
-    content_signal: "jogos|games"
-
-  - name: "Not Found handling"
-    path: "/nonexistent"
-    method: GET
-    expected_status: 404
-    content_signal: "not found|404"
-```
+See [REFERENCE.md](REFERENCE.md)
 
 Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use.
 
@@ -68,102 +40,21 @@ Checks can also be specified inline via environment variables or CLI arguments f
 
 ### 1. Load smoke checks
 
-```bash
-SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
-BASE_URL="${DEPLOY_URL:-$BASE_URL}"
-
-if [ -f "$SMOKE_CHECKS_FILE" ]; then
-  echo "Loaded smoke checks from $SMOKE_CHECKS_FILE"
-elif [ -n "$BASE_URL" ]; then
-  echo "No smoke-checks.yaml found. Using single URL check against $BASE_URL"
-else
-  echo "ERROR: No smoke-checks.yaml found and no DEPLOY_URL/BASE_URL set."
-  exit 1
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 2. Run each check
 
 For each check in the configuration, perform an HTTP request:
 
-```bash
-url="${BASE_URL}${path}"
-start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
-
-# Perform the HTTP request
-response=$(curl -s -o /tmp/smoke_body.txt -w "%{http_code}" "$url")
-response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
-status=$response
-body=$(cat /tmp/smoke_body.txt)
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 3. Assert results
 
-```bash
-checks_passed=0
-checks_failed=0
-failures=""
-
-# Assert status code
-if [ "$status" -ne "${expected_status:-200}" ]; then
-  echo "  FAIL: expected status ${expected_status} but got $status"
-  checks_failed=$((checks_failed + 1))
-  failures="${failures}  - $name: HTTP $status (expected ${expected_status})\n"
-else
-  echo "  PASS: HTTP $status"
-fi
-
-# Assert content signal
-if [ -n "$content_signal" ]; then
-  if echo "$body" | grep -qiE "$content_signal"; then
-    echo "  PASS: body contains \"$content_signal\""
-  else
-    echo "  FAIL: body does not contain \"$content_signal\""
-    checks_failed=$((checks_failed + 1))
-    failures="${failures}  - $name: missing content signal \"$content_signal\"\n"
-  fi
-fi
-
-# Assert response time
-if [ -n "$max_response_time_ms" ] && [ "$response_time" -gt "$max_response_time_ms" ]; then
-  echo "  FAIL: response time ${response_time}ms exceeds ${max_response_time_ms}ms"
-  checks_failed=$((checks_failed + 1))
-  failures="${failures}  - $name: response time ${response_time}ms (max ${max_response_time_ms}ms)\n"
-fi
-```
+See [REFERENCE.md](REFERENCE.md)
 
 ### 4. Generate report
 
-```bash
-total=$((checks_passed + checks_failed))
-echo ""
-echo "=== Smoke Test Summary ==="
-echo "Total: $total | Passed: $checks_passed | Failed: $checks_failed"
-
-if [ "$checks_failed" -gt 0 ]; then
-  echo ""
-  echo "Failures:"
-  echo -e "$failures"
-  exit 1
-else
-  echo "All checks passed."
-  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
+See [REFERENCE.md](REFERENCE.md)
 
 ## Integration with deploy skill
 
@@ -173,19 +64,3 @@ The `deploy` skill references `smoke-test` as its final verification step:
 # 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/using-bigpowers/SKILL.md

@@ -8,7 +8,7 @@ description: One-time bootstrap that introduces the bigpowers skills system, the
 > **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
 
@@ -99,7 +99,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
 

package/validate-contracts/REFERENCE.md

@@ -0,0 +1,183 @@
+# Validate Contracts — Reference
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 1
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+---
+
+## Example 2
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Example 3
+
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/frontend/locales/en.json
+  target: src/backend/messages/en.json
+mode: subset      # all target keys must exist in reference
+```
+
+---
+
+## Example 4
+
+```bash
+validate-contracts --key-set specs/contracts/i18n-keys.yaml
+# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
+# → added: 1 key in target not in reference: ['deprecated.field']
+# → exit 1 (divergence)
+```
+
+---
+
+## Example 5
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 6
+
+```bash
+validate-contracts --shape specs/contracts/migration-output.yaml
+# → PASS: 3/3 fields validated, 5000 rows OK
+# → WARN: field 'full_name' has 12 null values (0.24%)
+# → FAIL: field 'user_id' has 3 rows with type string (expected number)
+```
+
+---
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`