bigpowers 2.34.1 → 2.35.0

package/.pi/prompts/validate-contracts.md

@@ -27,30 +27,13 @@ Three modes of validation:
 
 All contract files live in `specs/contracts/` and use YAML:
 
-```
-specs/contracts/
-├── users.schema.yaml        # API response schema
-├── i18n-keys.yaml           # Key-set comparison
-├── migration-output.yaml    # Data shape contract
-└── README.md                # Local conventions
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ### 1. API Response Contracts (`--schema`)
 
 Define expected API response shapes and validate live endpoints against them:
 
-```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 }
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
@@ -64,52 +47,21 @@ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.
 
 Assert that two data sources share a consistent set of keys:
 
-```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
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
-```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)
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ### 3. Data Shape Contracts (`--shape`)
 
 Validate that a data file matches expected column types and constraints:
 
-```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
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
-```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)
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ## Process
 
@@ -157,12 +109,172 @@ bash scripts/validate-contracts.sh <contract-file>
 # → All pass → ready to deploy
 ```
 
+---
+
+# 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 |
@@ -172,6 +284,9 @@ bash scripts/validate-contracts.sh <contract-file>
 | `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`

package/.pi/prompts/wire-ci.md

@@ -41,6 +41,131 @@ If no manifest is found, prompt the user to specify the type or pass `--type <ru
 Create `.github/workflows/ci.yaml` with standard steps derived from the project type and its manifest:
 
 **Rust template (`Cargo.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**Node template (`package.json`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**Python template (`setup.py` / `pyproject.toml`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**Go template (`go.mod`):**
+See [REFERENCE.md](REFERENCE.md)
+
+**C/C++ template (`CMakeLists.txt`):**
+See [REFERENCE.md](REFERENCE.md)
+
+### 3. Generate release workflow (if semantic-release detected)
+
+If the project has semantic-release configured (in `package.json`, `.releaserc`, or `release.config.js`), also generate `.github/workflows/release.yaml`:
+
+See [REFERENCE.md](REFERENCE.md)
+
+> **NPM_TOKEN is required** for publishing to npm. Without it, semantic-release will fail at the publish step. See `--validate` to check this.
+
+### 4. Validate workflows (`--validate`)
+
+Run `wire-ci --validate` to check all generated workflow files:
+
+See [REFERENCE.md](REFERENCE.md)
+
+**Exit codes:**
+- `0` — all checks pass (no errors)
+- `1` — YAML syntax errors found
+- `2` — validation warnings only (missing permissions, secrets, etc.)
+
+### 5. Dry-run workflows (`--dry-run`)
+
+Attempt to run the generated workflows locally to catch errors before push:
+
+See [REFERENCE.md](REFERENCE.md)
+
+> **act** runs workflows in a local Docker environment — the most accurate pre-push validation.
+> **gh workflow run** sends the workflow to GitHub but doesn't execute locally — useful for checking YAML parsing but not for testing the actual steps.
+
+### 6. Document common CI failure patterns
+
+Add the following to the project's documentation or CLAUDE.md after setup:
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| `npm publish` fails | `NPM_TOKEN` not set as repo secret | Add `NPM_TOKEN` to GitHub repo secrets |
+| `semantic-release` fails on push | Missing `permissions: contents: write` | Add `permissions: contents: write` to release job |
+| `cargo publish` auth fail | `CARGO_REGISTRY_TOKEN` not set | Add token to `~/.cargo/config.toml` or env |
+| `go vet` fails | Go version mismatch | Match `go.mod` `go` directive with setup-go version |
+| `cargo clippy` errors | New lints in Rust nightly | `cargo clippy --fix` or allow specific lints |
+| `act` not found | Docker not running or act not installed | `brew install act` / `docker ps` to verify Docker |
+| Hardcoded Node version stale | `.nvmrc` exists but workflow uses hardcoded version | Use `node-version-file: .nvmrc` instead |
+
+## Verify
+
+→ verify: `test -f wire-ci/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: wire-ci" wire-ci/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "template\|workflow\|validate\|dry.run" wire-ci/SKILL.md | awk '{if($1>=3) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "wire-ci" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`
+
+---
+
+# Wire Ci — Reference
+
+## Examples
+
+### Create CI for a Rust project
+
+```bash
+# Detect from Cargo.toml, generate workflows
+wire-ci
+
+# Validate generated workflows
+wire-ci --validate
+
+# Run locally with act
+wire-ci --dry-run
+```
+
+### Create CI for a Node project with semantic-release
+
+```bash
+wire-ci
+wire-ci --validate
+# Expect warning: "npm publish step found but no NPM_TOKEN in secrets"
+# Fix: add NPM_TOKEN to repo secrets
+```
+
+### Validate existing workflows (no generation)
+
+```bash
+wire-ci --validate --check-only
+```
+
+
+---
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--validate` | Check YAML syntax, permissions, secrets, common pitfalls |
+| `--dry-run` | Run workflows locally via `act` or dispatch via `gh` |
+| `--check-only` | Only validate, do not generate new files |
+| `--type <type>` | Force project type (skip auto-detection) |
+| `--force` | Overwrite existing workflow files |
+| `--no-release` | Skip release workflow generation even if semantic-release detected |
+
+
+---
+
+## Integration with build-epic
+
+When `wire-ci` is used as part of `build-epic`:
+
+1. **During develop-tdd**: If the task modifies `.github/workflows/`, run `wire-ci --validate` as a CI dry-run sub-step
+2. **During release-branch**: After push, run `gh run list --limit 1 --branch main --json status,conclusion` to verify CI passes
+
+---
+
+## Reference block 1
+
 ```yaml
 name: CI
 on: [push, pull_request]
@@ -59,7 +184,10 @@ jobs:
       - run: cargo build --release
 ```
 
-**Node template (`package.json`):**
+---
+
+## Reference block 2
+
 ```yaml
 name: CI
 on: [push, pull_request]
@@ -79,7 +207,10 @@ jobs:
       - run: npm run build 2>/dev/null || true
 ```
 
-**Python template (`setup.py` / `pyproject.toml`):**
+---
+
+## Reference block 3
+
 ```yaml
 name: CI
 on: [push, pull_request]
@@ -99,7 +230,10 @@ jobs:
       - run: pytest
 ```
 
-**Go template (`go.mod`):**
+---
+
+## Reference block 4
+
 ```yaml
 name: CI
 on: [push, pull_request]
@@ -117,7 +251,10 @@ jobs:
       - run: go build ./...
 ```
 
-**C/C++ template (`CMakeLists.txt`):**
+---
+
+## Reference block 5
+
 ```yaml
 name: CI
 on: [push, pull_request]
@@ -131,9 +268,9 @@ jobs:
       - run: ctest --test-dir build
 ```
 
-### 3. Generate release workflow (if semantic-release detected)
+---
 
-If the project has semantic-release configured (in `package.json`, `.releaserc`, or `release.config.js`), also generate `.github/workflows/release.yaml`:
+## Reference block 6
 
 ```yaml
 name: Release
@@ -164,11 +301,9 @@ jobs:
           NPM_TOKEN: \${{ secrets.NPM_TOKEN }}
 ```
 
-> **NPM_TOKEN is required** for publishing to npm. Without it, semantic-release will fail at the publish step. See `--validate` to check this.
+---
 
-### 4. Validate workflows (`--validate`)
-
-Run `wire-ci --validate` to check all generated workflow files:
+## Reference block 7
 
 ```bash
 # Validate YAML syntax
@@ -210,14 +345,9 @@ for f in .github/workflows/*.yaml; do
 done
 ```
 
-**Exit codes:**
-- `0` — all checks pass (no errors)
-- `1` — YAML syntax errors found
-- `2` — validation warnings only (missing permissions, secrets, etc.)
-
-### 5. Dry-run workflows (`--dry-run`)
+---
 
-Attempt to run the generated workflows locally to catch errors before push:
+## Reference block 8
 
 ```bash
 # Option A: Use act (recommended)
@@ -233,75 +363,3 @@ else
   echo "      Install gh CLI for remote dry-run"
 fi
 ```
-
-> **act** runs workflows in a local Docker environment — the most accurate pre-push validation.
-> **gh workflow run** sends the workflow to GitHub but doesn't execute locally — useful for checking YAML parsing but not for testing the actual steps.
-
-### 6. Document common CI failure patterns
-
-Add the following to the project's documentation or CLAUDE.md after setup:
-
-| Failure | Cause | Fix |
-|---------|-------|-----|
-| `npm publish` fails | `NPM_TOKEN` not set as repo secret | Add `NPM_TOKEN` to GitHub repo secrets |
-| `semantic-release` fails on push | Missing `permissions: contents: write` | Add `permissions: contents: write` to release job |
-| `cargo publish` auth fail | `CARGO_REGISTRY_TOKEN` not set | Add token to `~/.cargo/config.toml` or env |
-| `go vet` fails | Go version mismatch | Match `go.mod` `go` directive with setup-go version |
-| `cargo clippy` errors | New lints in Rust nightly | `cargo clippy --fix` or allow specific lints |
-| `act` not found | Docker not running or act not installed | `brew install act` / `docker ps` to verify Docker |
-| Hardcoded Node version stale | `.nvmrc` exists but workflow uses hardcoded version | Use `node-version-file: .nvmrc` instead |
-
-## Examples
-
-### Create CI for a Rust project
-
-```bash
-# Detect from Cargo.toml, generate workflows
-wire-ci
-
-# Validate generated workflows
-wire-ci --validate
-
-# Run locally with act
-wire-ci --dry-run
-```
-
-### Create CI for a Node project with semantic-release
-
-```bash
-wire-ci
-wire-ci --validate
-# Expect warning: "npm publish step found but no NPM_TOKEN in secrets"
-# Fix: add NPM_TOKEN to repo secrets
-```
-
-### Validate existing workflows (no generation)
-
-```bash
-wire-ci --validate --check-only
-```
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--validate` | Check YAML syntax, permissions, secrets, common pitfalls |
-| `--dry-run` | Run workflows locally via `act` or dispatch via `gh` |
-| `--check-only` | Only validate, do not generate new files |
-| `--type <type>` | Force project type (skip auto-detection) |
-| `--force` | Overwrite existing workflow files |
-| `--no-release` | Skip release workflow generation even if semantic-release detected |
-
-## Integration with build-epic
-
-When `wire-ci` is used as part of `build-epic`:
-
-1. **During develop-tdd**: If the task modifies `.github/workflows/`, run `wire-ci --validate` as a CI dry-run sub-step
-2. **During release-branch**: After push, run `gh run list --limit 1 --branch main --json status,conclusion` to verify CI passes
-
-## Verify
-
-→ verify: `test -f wire-ci/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
-→ verify: `grep -q "name: wire-ci" wire-ci/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
-→ verify: `grep -ci "template\|workflow\|validate\|dry.run" wire-ci/SKILL.md | awk '{if($1>=3) print "OK: semantics"; else print "FAIL: missing"}'`
-→ verify: `grep -q "wire-ci" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/.pi/skills/deploy/SKILL.md

@@ -88,6 +88,53 @@ exit 1
 
 After invoking the deploy command, poll for completion:
 
+See [REFERENCE.md](REFERENCE.md)
+
+Use exponential backoff for retries on transient failures:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 6. Baseline smoke test
+
+See [REFERENCE.md](REFERENCE.md)
+
+For comprehensive health-checking, chain to the `smoke-test` skill:
+
+```bash
+# After deploy success
+bash scripts/run-smoke.sh "$DEPLOY_URL"
+```
+
+---
+
+# Deploy — Reference
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ARTIFACT_DIR` | `dist` | Build output directory |
+| `DEPLOY_URL` | *(required)* | Live URL for smoke test |
+| `DEPLOY_TIMEOUT` | `300` | Max wait for deploy completion (seconds) |
+| `DEPLOY_POLL_INTERVAL` | `30` | Polling interval (seconds) |
+| `RETRY_MAX` | `3` | Max deploy retry attempts |
+| `BUILD_COMMAND` | *(auto-detect)* | Override build command |
+
+
+---
+
+## Verification
+
+→ verify: `test -f deploy/SKILL.md && grep -q 'name: deploy' deploy/SKILL.md && echo OK`
+→ verify: `grep -qi 'build\|artifact\|deploy\|smoke' deploy/SKILL.md && echo OK`
+→ verify: `grep -ci 'package.json\|Cargo.toml\|Makefile\|manifest' deploy/SKILL.md | awk '{if($1>=1) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'timeout\|poll\|status\|retry\|backoff' deploy/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'curl.*DEPLOY_URL\|smoke\|health' deploy/SKILL.md && echo OK`
+
+---
+
+## Reference block 1
+
 ```bash
 DEPLOY_TIMEOUT="${DEPLOY_TIMEOUT:-300}"   # seconds (default 5 minutes)
 DEPLOY_POLL_INTERVAL="${DEPLOY_POLL_INTERVAL:-30}"  # seconds
@@ -110,7 +157,9 @@ while true; do
 done
 ```
 
-Use exponential backoff for retries on transient failures:
+---
+
+## Reference block 2
 
 ```bash
 RETRY_MAX="${RETRY_MAX:-3}"
@@ -127,7 +176,9 @@ for attempt in $(seq 1 "$RETRY_MAX"); do
 done
 ```
 
-### 6. Baseline smoke test
+---
+
+## Reference block 3
 
 ```bash
 DEPLOY_URL="${DEPLOY_URL:?DEPLOY_URL must be set}"
@@ -138,29 +189,3 @@ else
   exit 1
 fi
 ```
-
-For comprehensive health-checking, chain to the `smoke-test` skill:
-
-```bash
-# After deploy success
-bash scripts/run-smoke.sh "$DEPLOY_URL"
-```
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ARTIFACT_DIR` | `dist` | Build output directory |
-| `DEPLOY_URL` | *(required)* | Live URL for smoke test |
-| `DEPLOY_TIMEOUT` | `300` | Max wait for deploy completion (seconds) |
-| `DEPLOY_POLL_INTERVAL` | `30` | Polling interval (seconds) |
-| `RETRY_MAX` | `3` | Max deploy retry attempts |
-| `BUILD_COMMAND` | *(auto-detect)* | Override build command |
-
-## Verification
-
-→ verify: `test -f deploy/SKILL.md && grep -q 'name: deploy' deploy/SKILL.md && echo OK`
-→ verify: `grep -qi 'build\|artifact\|deploy\|smoke' deploy/SKILL.md && echo OK`
-→ verify: `grep -ci 'package.json\|Cargo.toml\|Makefile\|manifest' deploy/SKILL.md | awk '{if($1>=1) print "OK"; else print "FAIL"}'`
-→ verify: `grep -ci 'timeout\|poll\|status\|retry\|backoff' deploy/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
-→ verify: `grep -q 'curl.*DEPLOY_URL\|smoke\|health' deploy/SKILL.md && echo OK`