bigpowers 2.12.0 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/.pi/package.json +2 -2
  2. package/.pi/prompts/validate-contracts.md +181 -0
  3. package/.pi/skills/validate-contracts/SKILL.md +183 -0
  4. package/CHANGELOG.md +14 -0
  5. package/SKILL-INDEX.md +36 -35
  6. package/package.json +1 -1
  7. package/scripts/generate-skill-index.sh +1 -0
  8. package/scripts/run-smoke.sh +233 -0
  9. package/skills-lock.json +5 -0
  10. package/validate-contracts/SKILL.md +182 -0
package/.pi/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "bigpowers",
3
- "version": "2.12.0",
4
- "description": "66 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
3
+ "version": "2.13.0",
4
+ "description": "67 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
5
5
  "keywords": [
6
6
  "pi-package"
7
7
  ],
package/.pi/prompts/validate-contracts.md ADDED
@@ -0,0 +1,181 @@
1
+ ---
2
+ 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."
3
+ ---
4
+
5
+
6
+ # Validate Contracts
7
+
8
+ > **HARD GATE** — Do NOT deploy or migrate data without running `validate-contracts` first. Silent data divergence between system boundaries causes the hardest-to-debug production bugs.
9
+ >
10
+ > **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
11
+
12
+ Validate that data structures stay in sync across system boundaries — front-end vs
13
+ back-end, API responses vs expected schemas, config files vs code assumptions,
14
+ migration output vs target shape.
15
+
16
+ ## Contract types
17
+
18
+ Three modes of validation:
19
+
20
+ | Mode | What it catches | When to use |
21
+ |------|----------------|-------------|
22
+ | **Schema** | API response shape mismatches (missing field, wrong type) | Before every deploy, after API changes |
23
+ | **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
24
+ | **Shape** | Column type or format violations in data files | After migrations, before consuming exports |
25
+
26
+ ## Contract file convention
27
+
28
+ All contract files live in `specs/contracts/` and use YAML:
29
+
30
+ ```
31
+ specs/contracts/
32
+ ├── users.schema.yaml # API response schema
33
+ ├── i18n-keys.yaml # Key-set comparison
34
+ ├── migration-output.yaml # Data shape contract
35
+ └── README.md # Local conventions
36
+ ```
37
+
38
+ ### 1. API Response Contracts (`--schema`)
39
+
40
+ Define expected API response shapes and validate live endpoints against them:
41
+
42
+ ```yaml
43
+ # specs/contracts/users.schema.yaml
44
+ endpoint: /api/users
45
+ method: GET
46
+ schema:
47
+ type: object
48
+ required: [id, name, email]
49
+ properties:
50
+ id: { type: number }
51
+ name: { type: string }
52
+ email: { type: string, format: email }
53
+ ```
54
+
55
+ Usage:
56
+
57
+ ```bash
58
+ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.example.com/users
59
+ # → PASS: /api/users matches expected schema (3/3 fields, types ok)
60
+ # → FAIL: /api/users — field 'email' has type null (expected string)
61
+ ```
62
+
63
+ ### 2. Key-Set Contracts (`--key-set`)
64
+
65
+ Assert that two data sources share a consistent set of keys:
66
+
67
+ ```yaml
68
+ # specs/contracts/i18n-keys.yaml
69
+ sources:
70
+ reference: src/frontend/locales/en.json
71
+ target: src/backend/messages/en.json
72
+ mode: subset # all target keys must exist in reference
73
+ ```
74
+
75
+ Usage:
76
+
77
+ ```bash
78
+ validate-contracts --key-set specs/contracts/i18n-keys.yaml
79
+ # → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
80
+ # → added: 1 key in target not in reference: ['deprecated.field']
81
+ # → exit 1 (divergence)
82
+ ```
83
+
84
+ ### 3. Data Shape Contracts (`--shape`)
85
+
86
+ Validate that a data file matches expected column types and constraints:
87
+
88
+ ```yaml
89
+ # specs/contracts/migration-output.yaml
90
+ file: data/users-export.json
91
+ format: json
92
+ fields:
93
+ - name: user_id
94
+ type: number
95
+ required: true
96
+ - name: full_name
97
+ type: string
98
+ required: true
99
+ - name: created_at
100
+ type: string
101
+ format: date-time
102
+ required: false
103
+ ```
104
+
105
+ Usage:
106
+
107
+ ```bash
108
+ validate-contracts --shape specs/contracts/migration-output.yaml
109
+ # → PASS: 3/3 fields validated, 5000 rows OK
110
+ # → WARN: field 'full_name' has 12 null values (0.24%)
111
+ # → FAIL: field 'user_id' has 3 rows with type string (expected number)
112
+ ```
113
+
114
+ ## Process
115
+
116
+ ### 1. Define contract
117
+
118
+ Create a YAML file in `specs/contracts/` following the schema for the mode.
119
+
120
+ ### 2. Run validation
121
+
122
+ ```bash
123
+ bash scripts/validate-contracts.sh <contract-file>
124
+ ```
125
+
126
+ The runner auto-detects the contract type from the file content (presence of `schema:`,
127
+ `sources:`, or `file:` + `fields:` keys).
128
+
129
+ ### 3. Read the report
130
+
131
+ Output is JSON Lines (one event per line) plus a human-readable summary:
132
+
133
+ ```
134
+ {"event":"pass","check":"users.schema","detail":"3/3 fields match types"}
135
+ {"event":"warn","check":"users.schema","detail":"field 'avatar' has format: uri (unexpected)"}
136
+ {"event":"fail","check":"i18n-keys","detail":"missing: 2 keys in target"}
137
+ ```
138
+
139
+ Final summary:
140
+
141
+ ```
142
+ === Validate Contracts Summary ===
143
+ Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
144
+ FAILED: 1 contract has divergence
145
+ ```
146
+
147
+ ### 4. Fix divergence
148
+
149
+ - **Missing keys** → add to target source
150
+ - **Type mismatches** → update schema or fix producer
151
+ - **Shape violations** → fix migration or consumer
152
+
153
+ ### 5. Re-validate
154
+
155
+ ```bash
156
+ bash scripts/validate-contracts.sh <contract-file>
157
+ # → All pass → ready to deploy
158
+ ```
159
+
160
+ ## Integration
161
+
162
+ - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
163
+ - **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
164
+ - **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
165
+
166
+ ## Configuration
167
+
168
+ | Variable | Default | Description |
169
+ |----------|---------|-------------|
170
+ | `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
171
+ | `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
172
+ | `STRICT_MODE` | `false` | Treat warnings as failures |
173
+ | `OUTPUT_FORMAT` | `text` | `text` or `json` |
174
+
175
+ ## Verification
176
+
177
+ → verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
178
+ → verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
179
+ → verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
180
+ → 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"}'`
181
+ → verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
package/.pi/skills/validate-contracts/SKILL.md ADDED
@@ -0,0 +1,183 @@
1
+ ---
2
+ name: validate-contracts
3
+ 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.\""
4
+ model: sonnet
5
+ ---
6
+
7
+
8
+ # Validate Contracts
9
+
10
+ > **HARD GATE** — Do NOT deploy or migrate data without running `validate-contracts` first. Silent data divergence between system boundaries causes the hardest-to-debug production bugs.
11
+ >
12
+ > **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
13
+
14
+ Validate that data structures stay in sync across system boundaries — front-end vs
15
+ back-end, API responses vs expected schemas, config files vs code assumptions,
16
+ migration output vs target shape.
17
+
18
+ ## Contract types
19
+
20
+ Three modes of validation:
21
+
22
+ | Mode | What it catches | When to use |
23
+ |------|----------------|-------------|
24
+ | **Schema** | API response shape mismatches (missing field, wrong type) | Before every deploy, after API changes |
25
+ | **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
26
+ | **Shape** | Column type or format violations in data files | After migrations, before consuming exports |
27
+
28
+ ## Contract file convention
29
+
30
+ All contract files live in `specs/contracts/` and use YAML:
31
+
32
+ ```
33
+ specs/contracts/
34
+ ├── users.schema.yaml # API response schema
35
+ ├── i18n-keys.yaml # Key-set comparison
36
+ ├── migration-output.yaml # Data shape contract
37
+ └── README.md # Local conventions
38
+ ```
39
+
40
+ ### 1. API Response Contracts (`--schema`)
41
+
42
+ Define expected API response shapes and validate live endpoints against them:
43
+
44
+ ```yaml
45
+ # specs/contracts/users.schema.yaml
46
+ endpoint: /api/users
47
+ method: GET
48
+ schema:
49
+ type: object
50
+ required: [id, name, email]
51
+ properties:
52
+ id: { type: number }
53
+ name: { type: string }
54
+ email: { type: string, format: email }
55
+ ```
56
+
57
+ Usage:
58
+
59
+ ```bash
60
+ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.example.com/users
61
+ # → PASS: /api/users matches expected schema (3/3 fields, types ok)
62
+ # → FAIL: /api/users — field 'email' has type null (expected string)
63
+ ```
64
+
65
+ ### 2. Key-Set Contracts (`--key-set`)
66
+
67
+ Assert that two data sources share a consistent set of keys:
68
+
69
+ ```yaml
70
+ # specs/contracts/i18n-keys.yaml
71
+ sources:
72
+ reference: src/frontend/locales/en.json
73
+ target: src/backend/messages/en.json
74
+ mode: subset # all target keys must exist in reference
75
+ ```
76
+
77
+ Usage:
78
+
79
+ ```bash
80
+ validate-contracts --key-set specs/contracts/i18n-keys.yaml
81
+ # → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
82
+ # → added: 1 key in target not in reference: ['deprecated.field']
83
+ # → exit 1 (divergence)
84
+ ```
85
+
86
+ ### 3. Data Shape Contracts (`--shape`)
87
+
88
+ Validate that a data file matches expected column types and constraints:
89
+
90
+ ```yaml
91
+ # specs/contracts/migration-output.yaml
92
+ file: data/users-export.json
93
+ format: json
94
+ fields:
95
+ - name: user_id
96
+ type: number
97
+ required: true
98
+ - name: full_name
99
+ type: string
100
+ required: true
101
+ - name: created_at
102
+ type: string
103
+ format: date-time
104
+ required: false
105
+ ```
106
+
107
+ Usage:
108
+
109
+ ```bash
110
+ validate-contracts --shape specs/contracts/migration-output.yaml
111
+ # → PASS: 3/3 fields validated, 5000 rows OK
112
+ # → WARN: field 'full_name' has 12 null values (0.24%)
113
+ # → FAIL: field 'user_id' has 3 rows with type string (expected number)
114
+ ```
115
+
116
+ ## Process
117
+
118
+ ### 1. Define contract
119
+
120
+ Create a YAML file in `specs/contracts/` following the schema for the mode.
121
+
122
+ ### 2. Run validation
123
+
124
+ ```bash
125
+ bash scripts/validate-contracts.sh <contract-file>
126
+ ```
127
+
128
+ The runner auto-detects the contract type from the file content (presence of `schema:`,
129
+ `sources:`, or `file:` + `fields:` keys).
130
+
131
+ ### 3. Read the report
132
+
133
+ Output is JSON Lines (one event per line) plus a human-readable summary:
134
+
135
+ ```
136
+ {"event":"pass","check":"users.schema","detail":"3/3 fields match types"}
137
+ {"event":"warn","check":"users.schema","detail":"field 'avatar' has format: uri (unexpected)"}
138
+ {"event":"fail","check":"i18n-keys","detail":"missing: 2 keys in target"}
139
+ ```
140
+
141
+ Final summary:
142
+
143
+ ```
144
+ === Validate Contracts Summary ===
145
+ Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
146
+ FAILED: 1 contract has divergence
147
+ ```
148
+
149
+ ### 4. Fix divergence
150
+
151
+ - **Missing keys** → add to target source
152
+ - **Type mismatches** → update schema or fix producer
153
+ - **Shape violations** → fix migration or consumer
154
+
155
+ ### 5. Re-validate
156
+
157
+ ```bash
158
+ bash scripts/validate-contracts.sh <contract-file>
159
+ # → All pass → ready to deploy
160
+ ```
161
+
162
+ ## Integration
163
+
164
+ - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
165
+ - **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
166
+ - **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
167
+
168
+ ## Configuration
169
+
170
+ | Variable | Default | Description |
171
+ |----------|---------|-------------|
172
+ | `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
173
+ | `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
174
+ | `STRICT_MODE` | `false` | Treat warnings as failures |
175
+ | `OUTPUT_FORMAT` | `text` | `text` or `json` |
176
+
177
+ ## Verification
178
+
179
+ → verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
180
+ → verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
181
+ → verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
182
+ → 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"}'`
183
+ → verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
package/CHANGELOG.md CHANGED
@@ -1,3 +1,17 @@
1
+ # [2.13.0](https://github.com/danielvm-git/bigpowers/compare/v2.12.1...v2.13.0) (2026-06-21)
2
+
3
+
4
+ ### Features
5
+
6
+ * **skills:** add validate-contracts — data contract validator ([ec32076](https://github.com/danielvm-git/bigpowers/commit/ec3207617b3d465f8e5223242124cd2366cc2103))
7
+
8
+ ## [2.12.1](https://github.com/danielvm-git/bigpowers/compare/v2.12.0...v2.12.1) (2026-06-20)
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * **skills:** add run-smoke.sh referenced by deploy, smoke-test ([5108891](https://github.com/danielvm-git/bigpowers/commit/51088912084979df38d6bb529297b03a34a6bb66))
14
+
1
15
  # [2.12.0](https://github.com/danielvm-git/bigpowers/compare/v2.11.0...v2.12.0) (2026-06-20)
2
16
 
3
17
 
package/SKILL-INDEX.md CHANGED
@@ -3,8 +3,8 @@
3
3
  > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
4
4
  > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
5
5
 
6
- **Generated:** 2026-06-20T21:50:12Z
7
- **Skills:** 66
6
+ **Generated:** 2026-06-21T18:51:19Z
7
+ **Skills:** 67
8
8
 
9
9
  ---
10
10
 
@@ -15,11 +15,11 @@
15
15
  | Discover | 6 | `elaborate-spec, map-codebase, research-first, search-skills, survey-context, using-bigpowers` |
16
16
  | Design | 7 | `deepen-architecture, define-language, define-success, design-interface, grill-me, grill-with-docs, model-domain` |
17
17
  | Plan | 9 | `assess-impact, change-request, plan-refactor, plan-release, plan-work, run-planning, scope-work, seed-conventions, slice-tasks` |
18
- | Build | 16 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, setup-environment, smoke-test, spike-prototype, wire-ci, wire-observability` |
18
+ | Build | 17 | `align-grid, build-epic, craft-skill, deploy, develop-tdd, execute-plan, guard-git, hook-commits, kickoff-branch, orchestrate-project, publish-package, setup-environment, smoke-test, spike-prototype, validate-contracts, wire-ci, wire-observability` |
19
19
  | 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` |
20
20
  | Release | 2 | `commit-message, release-branch` |
21
21
  | 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` |
22
- | **TOTAL** | **65** | |
22
+ | **TOTAL** | **66** | |
23
23
 
24
24
  ---
25
25
 
@@ -63,37 +63,38 @@
63
63
  | 34 | Build | `setup-environment` | Pre-install dependencies and configure tools before development work begins. Use | ✅ Active |
64
64
  | 35 | Build | `smoke-test` | "Post-deploy health-check against a live URL. Validates HTTP status, response co | ✅ Active |
65
65
  | 36 | Build | `spike-prototype` | Throw-away prototype for unknown problem spaces. Output is learning notes in spe | ✅ Active |
66
- | 37 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
67
- | 38 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
68
- | 39 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
69
- | 40 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
70
- | 41 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
71
- | 42 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains | ✅ Active |
72
- | 43 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
73
- | 44 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
74
- | 45 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after | ✅ Active |
75
- | 46 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
76
- | 47 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
77
- | 48 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
78
- | 49 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
79
- | 50 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
80
- | 51 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and | ✅ Active |
81
- | 52 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
82
- | 53 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
83
- | 54 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
84
- | 55 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
85
- | 56 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
86
- | 57 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose | ✅ Active |
87
- | 58 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
88
- | 59 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build | ✅ Active |
89
- | 60 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
90
- | 61 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
91
- | 62 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
92
- | 63 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
93
- | 64 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping | ✅ Active |
94
- | 65 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
95
-
96
- **Total: 65 active skills.**
66
+ | 37 | Build | `validate-contracts` | "Assert data shape consistency across system boundaries — live API responses a | ✅ Active |
67
+ | 38 | Build | `wire-ci` | "CI pipeline setup with pre-built templates and local validation. Generates GitH | ✅ Active |
68
+ | 39 | Build | `wire-observability` | Add structured JSON logging, observability commands, and idempotent setup script | ✅ Active |
69
+ | 40 | Verify | `audit-code` | Self-review checklist for the coding agent to run before dispatching a reviewer. | ✅ Active |
70
+ | 41 | Verify | `diagnose-root` | Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use | ✅ Active |
71
+ | 42 | Verify | `enforce-first` | Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Val | ✅ Active |
72
+ | 43 | Verify | `fix-bug` | Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains | ✅ Active |
73
+ | 44 | Verify | `inspect-quality` | Interactive QA session where user reports bugs or issues conversationally, and t | ✅ Active |
74
+ | 45 | Verify | `investigate-bug` | Investigate a bug or issue by exploring the codebase to find root cause, then wr | ✅ Active |
75
+ | 46 | Verify | `request-review` | Dispatch a fresh reviewer agent with a clean context to critique the code after | ✅ Active |
76
+ | 47 | Verify | `respond-review` | Act on a reviewer agent's feedback systematically — categorize findings, apply | ✅ Active |
77
+ | 48 | Verify | `run-evals` | Eval-Driven Development — define capability and regression evals before buildi | ✅ Active |
78
+ | 49 | Verify | `trace-requirement` | Link story IDs from specs/release-plan.yaml + epic capsule directories to the im | ✅ Active |
79
+ | 50 | Verify | `validate-fix` | Prove a fix works before declaring done — re-run the failing test, run the ful | ✅ Active |
80
+ | 51 | Verify | `verify-work` | Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-b | ✅ Active |
81
+ | 52 | Release | `commit-message` | Reviews working-tree changes, then drafts a Conventional Commits title/body and | ✅ Active |
82
+ | 53 | Release | `release-branch` | Make the merge/PR/keep/discard decision for a feature branch, verify coverage ga | ✅ Active |
83
+ | 54 | Sustain | `compose-workflow` | Chain multiple bigpowers skills into a custom workflow recipe saved in specs/. U | ✅ Active |
84
+ | 55 | Sustain | `delegate-task` | Delegate one complex task to a single subagent, review its work in two stages be | ✅ Active |
85
+ | 56 | Sustain | `dispatch-agents` | Dispatch multiple subagents in parallel on independent tasks. No waiting between | ✅ Active |
86
+ | 57 | Sustain | `edit-document` | Edit and improve documents by restructuring sections, improving clarity, and tig | ✅ Active |
87
+ | 58 | Sustain | `evolve-skill` | Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose | ✅ Active |
88
+ | 59 | Sustain | `migrate-spec` | Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers Y | ✅ Active |
89
+ | 60 | Sustain | `organize-workspace` | Scans the active workspace for disposable artifacts—logs, caches, stale build | ✅ Active |
90
+ | 61 | Sustain | `reset-baseline` | Restore the project to a known clean state between agent runs or experiments. Us | ✅ Active |
91
+ | 62 | Sustain | `session-state` | Track implementation decisions and progress in specs/state.yaml to prevent conte | ✅ Active |
92
+ | 63 | Sustain | `simulate-agents` | Run Mock User and Auditor agents against a feature in fresh contexts before huma | ✅ Active |
93
+ | 64 | Sustain | `stocktake-skills` | Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (c | ✅ Active |
94
+ | 65 | Sustain | `terse-mode` | Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping | ✅ Active |
95
+ | 66 | Sustain | `write-document` | Write, organize, and sync high-integrity technical documents using the BMAD meth | ✅ Active |
96
+
97
+ **Total: 66 active skills.**
97
98
 
98
99
  ---
99
100
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bigpowers",
3
- "version": "2.12.0",
3
+ "version": "2.13.0",
4
4
  "description": "61 agent skills for spec-driven, test-first software development by solo developers",
5
5
  "main": "index.js",
6
6
  "scripts": {
package/scripts/generate-skill-index.sh CHANGED
@@ -58,6 +58,7 @@ PHASE_MAP=(
58
58
  [hook-commits]="Build"
59
59
  [deploy]="Build"
60
60
  [smoke-test]="Build"
61
+ [validate-contracts]="Build"
61
62
  # Verify
62
63
  [verify-work]="Verify"
63
64
  [validate-fix]="Verify"
package/scripts/run-smoke.sh ADDED
@@ -0,0 +1,233 @@
1
+ #!/usr/bin/env bash
2
+ # run-smoke.sh — Post-deploy health-check runner for smoke-test skill
3
+ # Usage: bash scripts/run-smoke.sh [url] [smoke-checks-file]
4
+ #
5
+ # Reads from smoke-checks.yaml by default. Falls back to single-URL check.
6
+ # Env vars: DEPLOY_URL, SMOKE_CHECKS_FILE, SMOKE_TIMEOUT, SMOKE_RETRIES
7
+ set -euo pipefail
8
+
9
+ SMOKE_CHECKS_FILE="${2:-${SMOKE_CHECKS_FILE:-smoke-checks.yaml}}"
10
+ BASE_URL="${1:-${DEPLOY_URL:-}}"
11
+ SMOKE_TIMEOUT="${SMOKE_TIMEOUT:-30}"
12
+ SMOKE_RETRIES="${SMOKE_RETRIES:-0}"
13
+
14
+ TMPDIR=$(mktemp -d)
15
+ trap 'rm -rf "$TMPDIR"' EXIT
16
+
17
+ checks_passed=0
18
+ checks_failed=0
19
+ failures=""
20
+
21
+ # ── 1. Load checks ──────────────────────────────────────────────────────────
22
+
23
+ run_single_url_check() {
24
+ local url="$1"
25
+ local name="${2:-URL check}"
26
+ local expected_status="${3:-200}"
27
+ local content_signal="${4:-}"
28
+
29
+ echo "[$name]"
30
+ start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
31
+ response=$(curl -s -o "$TMPDIR/body.txt" -w "%{http_code}" --max-time "$SMOKE_TIMEOUT" "$url")
32
+ response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
33
+ status="$response"
34
+ body=$(cat "$TMPDIR/body.txt" 2>/dev/null || echo "")
35
+
36
+ # Assert status
37
+ if [ "$status" -ne "$expected_status" ]; then
38
+ echo " FAIL: HTTP $status (expected $expected_status)"
39
+ checks_failed=$((checks_failed + 1))
40
+ failures="${failures} - $name: HTTP $status (expected $expected_status)\n"
41
+ else
42
+ echo " PASS: HTTP $status"
43
+ checks_passed=$((checks_passed + 1))
44
+ fi
45
+
46
+ # Assert content signal
47
+ if [ -n "$content_signal" ]; then
48
+ if echo "$body" | grep -qiE "$content_signal"; then
49
+ echo " PASS: body matches \"$content_signal\""
50
+ else
51
+ echo " FAIL: body does not match \"$content_signal\""
52
+ checks_failed=$((checks_failed + 1))
53
+ failures="${failures} - $name: missing content signal \"$content_signal\"\n"
54
+ fi
55
+ fi
56
+
57
+ # Assert response time
58
+ if [ "$response_time" -gt 0 ]; then
59
+ echo " Time: ${response_time}ms"
60
+ fi
61
+ echo ""
62
+ }
63
+
64
+ parse_and_run_checks() {
65
+ local file="$1"
66
+ local base_url=""
67
+ local in_checks=false
68
+ local check_name="" check_path="" check_method="" check_status="" check_signal="" check_time=""
69
+
70
+ while IFS= read -r line; do
71
+ # Strip inline comments
72
+ line="${line%%#*}"
73
+ # Trim whitespace
74
+ line="${line#"${line%%[![:space:]]*}"}"
75
+ line="${line%"${line##*[![:space:]]}"}"
76
+ [ -z "$line" ] && continue
77
+
78
+ if [[ "$line" =~ ^base_url: ]]; then
79
+ base_url="${line#base_url:}"
80
+ base_url="${base_url#"${base_url%%[![:space:]]*}"}"
81
+ base_url="${base_url%"${base_url##*[![:space:]]}"}"
82
+ base_url="${base_url%\"}"
83
+ base_url="${base_url#\"}"
84
+ base_url="${base_url%\'}"
85
+ base_url="${base_url#\'}"
86
+ continue
87
+ fi
88
+
89
+ if [[ "$line" == "checks:" ]]; then
90
+ in_checks=true
91
+ check_name=""; check_path=""; check_method="GET"; check_status="200"
92
+ check_signal=""; check_time=""
93
+ continue
94
+ fi
95
+
96
+ if $in_checks; then
97
+ # Detect new check entry (dash at start of list item)
98
+ if [[ "$line" == "- name:"* ]]; then
99
+ # Run previous check if accumulated
100
+ if [ -n "$check_name" ] && [ -n "$base_url" ]; then
101
+ run_parsed_check "$base_url" "$check_name" "$check_path" "$check_status" "$check_signal"
102
+ fi
103
+ check_name="${line#- name:}"
104
+ check_name="${check_name#"${check_name%%[![:space:]]*}"}"
105
+ check_name="${check_name%\"}"; check_name="${check_name#\"}"
106
+ check_name="${check_name%\'}"; check_name="${check_name#\'}"
107
+ check_path=""; check_method="GET"; check_status="200"; check_signal=""; check_time=""
108
+ elif [[ "$line" == "name:"* ]]; then
109
+ check_name="${line#name:}"
110
+ check_name="${check_name#"${check_name%%[![:space:]]*}"}"
111
+ check_name="${check_name%\"}"; check_name="${check_name#\"}"
112
+ check_name="${check_name%\'}"; check_name="${check_name#\'}"
113
+ elif [[ "$line" == "path:"* ]]; then
114
+ check_path="${line#path:}"
115
+ check_path="${check_path#"${check_path%%[![:space:]]*}"}"
116
+ check_path="${check_path%\"}"; check_path="${check_path#\"}"
117
+ check_path="${check_path%\'}"; check_path="${check_path#\'}"
118
+ elif [[ "$line" == "method:"* ]]; then
119
+ check_method="${line#method:}"
120
+ check_method="${check_method#"${check_method%%[![:space:]]*}"}"
121
+ check_method="${check_method%\"}"; check_method="${check_method#\"}"
122
+ check_method="${check_method%\'}"; check_method="${check_method#\'}"
123
+ elif [[ "$line" == "expected_status:"* ]]; then
124
+ check_status="${line#expected_status:}"
125
+ check_status="${check_status#"${check_status%%[![:space:]]*}"}"
126
+ elif [[ "$line" == "content_signal:"* ]]; then
127
+ check_signal="${line#content_signal:}"
128
+ check_signal="${check_signal#"${check_signal%%[![:space:]]*}"}"
129
+ check_signal="${check_signal%\"}"; check_signal="${check_signal#\"}"
130
+ check_signal="${check_signal%\'}"; check_signal="${check_signal#\'}"
131
+ elif [[ "$line" == "max_response_time_ms:"* ]]; then
132
+ check_time="${line#max_response_time_ms:}"
133
+ check_time="${check_time#"${check_time%%[![:space:]]*}"}"
134
+ fi
135
+ fi
136
+ done < "$file"
137
+
138
+ # Run last check
139
+ if [ -n "$check_name" ] && [ -n "$base_url" ]; then
140
+ run_parsed_check "$base_url" "$check_name" "$check_path" "$check_status" "$check_signal"
141
+ fi
142
+ }
143
+
144
+ run_parsed_check() {
145
+ local base_url="$1" name="$2" path="$3" expected_status="$4" content_signal="$5"
146
+ local url="${base_url}${path}"
147
+
148
+ echo "[$name]"
149
+ echo " URL: $url"
150
+ start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
151
+ response=$(curl -s -o "$TMPDIR/body.txt" -w "%{http_code}" --max-time "$SMOKE_TIMEOUT" "$url" 2>/dev/null || echo "000")
152
+ response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
153
+ status="$response"
154
+ body=$(cat "$TMPDIR/body.txt" 2>/dev/null || echo "")
155
+
156
+ # Assert status code
157
+ if [ "$status" -ne "$expected_status" ]; then
158
+ echo " FAIL: HTTP $status (expected $expected_status)"
159
+ checks_failed=$((checks_failed + 1))
160
+ failures="${failures} - $name: HTTP $status (expected $expected_status)\n"
161
+ else
162
+ echo " PASS: HTTP $status"
163
+ fi
164
+
165
+ # Assert content signal
166
+ if [ -n "$content_signal" ]; then
167
+ if echo "$body" | grep -qiE "$content_signal"; then
168
+ echo " PASS: body matches \"$content_signal\""
169
+ checks_passed=$((checks_passed + 1))
170
+ else
171
+ echo " FAIL: body does not match \"$content_signal\""
172
+ checks_failed=$((checks_failed + 1))
173
+ failures="${failures} - $name: missing content signal \"$content_signal\"\n"
174
+ fi
175
+ fi
176
+
177
+ # Assert response time
178
+ if [ -n "${check_time:-}" ] && [ "$check_time" -gt 0 ] 2>/dev/null; then
179
+ if [ "$response_time" -gt "$check_time" ]; then
180
+ echo " FAIL: ${response_time}ms exceeds ${check_time}ms max"
181
+ checks_failed=$((checks_failed + 1))
182
+ failures="${failures} - $name: response time ${response_time}ms (max ${check_time}ms)\n"
183
+ else
184
+ echo " PASS: ${response_time}ms within ${check_time}ms limit"
185
+ fi
186
+ fi
187
+
188
+ if [ "$response_time" -gt 0 ]; then
189
+ echo " Time: ${response_time}ms"
190
+ fi
191
+ echo ""
192
+ }
193
+
194
+ # ── Main dispatch ───────────────────────────────────────────────────────────
195
+
196
+ echo "=== Smoke Test Runner ==="
197
+ echo "Started at: $(date -u '+%Y-%m-%dT%H:%M:%SZ')"
198
+ echo ""
199
+
200
+ if [ -f "$SMOKE_CHECKS_FILE" ]; then
201
+ echo "Checks file: $SMOKE_CHECKS_FILE"
202
+ parse_and_run_checks "$SMOKE_CHECKS_FILE"
203
+ elif [ -n "$BASE_URL" ]; then
204
+ echo "Single URL mode: $BASE_URL"
205
+ run_single_url_check "$BASE_URL" "Baseline"
206
+ else
207
+ echo "ERROR: No smoke-checks.yaml found and no URL provided."
208
+ echo "Usage: bash scripts/run-smoke.sh [url] [smoke-checks-file]"
209
+ echo " DEPLOY_URL=http://example.com bash scripts/run-smoke.sh"
210
+ exit 2
211
+ fi
212
+
213
+ # ── Summary ──────────────────────────────────────────────────────────────────
214
+
215
+ total=$((checks_passed + checks_failed))
216
+ echo "=== Smoke Test Summary ==="
217
+ echo "Total: $total | Passed: $checks_passed | Failed: $checks_failed"
218
+ echo ""
219
+
220
+ if [ "$checks_failed" -gt 0 ]; then
221
+ echo "Failures:"
222
+ echo -e "$failures"
223
+ echo "Smoke test FAILED."
224
+ exit 1
225
+ fi
226
+
227
+ if [ "$total" -eq 0 ]; then
228
+ echo "No checks were executed."
229
+ exit 1
230
+ fi
231
+
232
+ echo "All checks passed."
233
+ exit 0
package/skills-lock.json CHANGED
@@ -301,6 +301,11 @@
301
301
  "sha256": "b150ea218b529f61",
302
302
  "path": "using-bigpowers/SKILL.md"
303
303
  },
304
+ "validate-contracts": {
305
+ "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.\"",
306
+ "sha256": "17653c7ac211c5d8",
307
+ "path": "validate-contracts/SKILL.md"
308
+ },
304
309
  "validate-fix": {
305
310
  "description": "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation.",
306
311
  "sha256": "80fc28e511a501dc",
package/validate-contracts/SKILL.md ADDED
@@ -0,0 +1,182 @@
1
+ ---
2
+ name: validate-contracts
3
+ 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."
4
+ model: sonnet
5
+ ---
6
+
7
+ # Validate Contracts
8
+
9
+ > **HARD GATE** — Do NOT deploy or migrate data without running `validate-contracts` first. Silent data divergence between system boundaries causes the hardest-to-debug production bugs.
10
+ >
11
+ > **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
12
+
13
+ Validate that data structures stay in sync across system boundaries — front-end vs
14
+ back-end, API responses vs expected schemas, config files vs code assumptions,
15
+ migration output vs target shape.
16
+
17
+ ## Contract types
18
+
19
+ Three modes of validation:
20
+
21
+ | Mode | What it catches | When to use |
22
+ |------|----------------|-------------|
23
+ | **Schema** | API response shape mismatches (missing field, wrong type) | Before every deploy, after API changes |
24
+ | **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
25
+ | **Shape** | Column type or format violations in data files | After migrations, before consuming exports |
26
+
27
+ ## Contract file convention
28
+
29
+ All contract files live in `specs/contracts/` and use YAML:
30
+
31
+ ```
32
+ specs/contracts/
33
+ ├── users.schema.yaml # API response schema
34
+ ├── i18n-keys.yaml # Key-set comparison
35
+ ├── migration-output.yaml # Data shape contract
36
+ └── README.md # Local conventions
37
+ ```
38
+
39
+ ### 1. API Response Contracts (`--schema`)
40
+
41
+ Define expected API response shapes and validate live endpoints against them:
42
+
43
+ ```yaml
44
+ # specs/contracts/users.schema.yaml
45
+ endpoint: /api/users
46
+ method: GET
47
+ schema:
48
+ type: object
49
+ required: [id, name, email]
50
+ properties:
51
+ id: { type: number }
52
+ name: { type: string }
53
+ email: { type: string, format: email }
54
+ ```
55
+
56
+ Usage:
57
+
58
+ ```bash
59
+ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.example.com/users
60
+ # → PASS: /api/users matches expected schema (3/3 fields, types ok)
61
+ # → FAIL: /api/users — field 'email' has type null (expected string)
62
+ ```
63
+
64
+ ### 2. Key-Set Contracts (`--key-set`)
65
+
66
+ Assert that two data sources share a consistent set of keys:
67
+
68
+ ```yaml
69
+ # specs/contracts/i18n-keys.yaml
70
+ sources:
71
+ reference: src/frontend/locales/en.json
72
+ target: src/backend/messages/en.json
73
+ mode: subset # all target keys must exist in reference
74
+ ```
75
+
76
+ Usage:
77
+
78
+ ```bash
79
+ validate-contracts --key-set specs/contracts/i18n-keys.yaml
80
+ # → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
81
+ # → added: 1 key in target not in reference: ['deprecated.field']
82
+ # → exit 1 (divergence)
83
+ ```
84
+
85
+ ### 3. Data Shape Contracts (`--shape`)
86
+
87
+ Validate that a data file matches expected column types and constraints:
88
+
89
+ ```yaml
90
+ # specs/contracts/migration-output.yaml
91
+ file: data/users-export.json
92
+ format: json
93
+ fields:
94
+ - name: user_id
95
+ type: number
96
+ required: true
97
+ - name: full_name
98
+ type: string
99
+ required: true
100
+ - name: created_at
101
+ type: string
102
+ format: date-time
103
+ required: false
104
+ ```
105
+
106
+ Usage:
107
+
108
+ ```bash
109
+ validate-contracts --shape specs/contracts/migration-output.yaml
110
+ # → PASS: 3/3 fields validated, 5000 rows OK
111
+ # → WARN: field 'full_name' has 12 null values (0.24%)
112
+ # → FAIL: field 'user_id' has 3 rows with type string (expected number)
113
+ ```
114
+
115
+ ## Process
116
+
117
+ ### 1. Define contract
118
+
119
+ Create a YAML file in `specs/contracts/` following the schema for the mode.
120
+
121
+ ### 2. Run validation
122
+
123
+ ```bash
124
+ bash scripts/validate-contracts.sh <contract-file>
125
+ ```
126
+
127
+ The runner auto-detects the contract type from the file content (presence of `schema:`,
128
+ `sources:`, or `file:` + `fields:` keys).
129
+
130
+ ### 3. Read the report
131
+
132
+ Output is JSON Lines (one event per line) plus a human-readable summary:
133
+
134
+ ```
135
+ {"event":"pass","check":"users.schema","detail":"3/3 fields match types"}
136
+ {"event":"warn","check":"users.schema","detail":"field 'avatar' has format: uri (unexpected)"}
137
+ {"event":"fail","check":"i18n-keys","detail":"missing: 2 keys in target"}
138
+ ```
139
+
140
+ Final summary:
141
+
142
+ ```
143
+ === Validate Contracts Summary ===
144
+ Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
145
+ FAILED: 1 contract has divergence
146
+ ```
147
+
148
+ ### 4. Fix divergence
149
+
150
+ - **Missing keys** → add to target source
151
+ - **Type mismatches** → update schema or fix producer
152
+ - **Shape violations** → fix migration or consumer
153
+
154
+ ### 5. Re-validate
155
+
156
+ ```bash
157
+ bash scripts/validate-contracts.sh <contract-file>
158
+ # → All pass → ready to deploy
159
+ ```
160
+
161
+ ## Integration
162
+
163
+ - **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
164
+ - **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
165
+ - **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
166
+
167
+ ## Configuration
168
+
169
+ | Variable | Default | Description |
170
+ |----------|---------|-------------|
171
+ | `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
172
+ | `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
173
+ | `STRICT_MODE` | `false` | Treat warnings as failures |
174
+ | `OUTPUT_FORMAT` | `text` | `text` or `json` |
175
+
176
+ ## Verification
177
+
178
+ → verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
179
+ → verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
180
+ → verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
181
+ → 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"}'`
182
+ → verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`