@teevee98/synapse-hub 4.1.4 → 4.2.1

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 (133) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: api-network-mocking-interception
3
3
  description: "Intercept HTTP/GraphQL traffic, stub routes, and simulate chaos network failures. Use when stubbing, mocking, or intercepting network calls during UI or API tests."
4
+ category: verification_and_resilience
5
+ version: "2.0.0"
6
+ policies:
7
+ network: localhost-only
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # API Network Mocking, Interception & Resilience Skill
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Intercept HTTP/GraphQL traffic, stub routes, and simulate chaos network failures. Use when stubbing, mocking, or intercepting network calls during UI or API tests.
20
+ - **Activation Scope:** Domain workflows for `03-api-and-contracts` involving `api-network-mocking-interception`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT mock endpoints that are the primary subject under test (do not mock what you are verifying).
28
+ - Do NOT leave unhandled route wildcards that silently swallow unrelated network traffic.
29
+ - Do NOT use outdated static JSON payloads when live schemas have evolved.
30
+ - **Sibling Skill Boundaries:**
31
+ - consumer-driven-contract-testing validates microservice contracts; api-network-mocking-interception stubs routes and injects chaos faults in browser harnesses.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  > **Target:** Eliminate flaky tests caused by backend dependencies, slow microservices, or inconsistent staging data by intercepting browser-level network requests, and verify frontend resilience against network faults and degradations.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Core Principles
41
+ ### Core Principles
13
42
 
14
43
  1. **Deterministic State over Staging Data:**
15
44
  - UI tests should verify front-end state rendering and user interactions, not whether the backend DB is seeded.
@@ -24,9 +53,10 @@ description: "Intercept HTTP/GraphQL traffic, stub routes, and simulate chaos ne
24
53
 
25
54
  ---
26
55
 
27
- ## 2. Playwright Route Interception Standard Patterns
56
+ ### Playwright Route Interception Standard Patterns
28
57
 
29
58
  ### Pattern A: Static JSON Response Stubbing
59
+ <!-- classification: illustrative -->
30
60
  ```typescript
31
61
  // Stub user profile API
32
62
  await page.route('**/api/v1/user/profile', async (route) => {
@@ -44,6 +74,7 @@ await page.route('**/api/v1/user/profile', async (route) => {
44
74
  ```
45
75
 
46
76
  ### Pattern B: Modifying Live Responses (HAR / Passthrough Mutation)
77
+ <!-- classification: illustrative -->
47
78
  ```typescript
48
79
  // Intercept real response and inject edge-case field
49
80
  await page.route('**/api/v1/reports', async (route) => {
@@ -55,6 +86,7 @@ await page.route('**/api/v1/reports', async (route) => {
55
86
  ```
56
87
 
57
88
  ### Pattern C: Simulating Network Failures & Delays
89
+ <!-- classification: illustrative -->
58
90
  ```typescript
59
91
  // Simulate 500 Internal Server Error
60
92
  await page.route('**/api/v1/checkout', async (route) => {
@@ -74,9 +106,10 @@ await page.route('**/api/v1/heavy-list', async (route) => {
74
106
 
75
107
  ---
76
108
 
77
- ## 3. Chaos & Network Degradation Patterns
109
+ ### Chaos & Network Degradation Patterns
78
110
 
79
111
  ### Pattern D: Emulating Extreme Latency & Jitter via CDP
112
+ <!-- classification: illustrative -->
80
113
  ```typescript
81
114
  const client = await page.context().newCDPSession(page);
82
115
  await client.send('Network.emulateNetworkConditions', {
@@ -96,6 +129,7 @@ if (await submitBtn.isVisible()) {
96
129
  ```
97
130
 
98
131
  ### Pattern E: Simulating Gateway Drops (502/503/504) & Circuit Breaker Recovery
132
+ <!-- classification: illustrative -->
99
133
  ```typescript
100
134
  let attemptCount = 0;
101
135
  await page.route('**/api/v1/orders/submit', async (route) => {
@@ -117,6 +151,7 @@ await page.route('**/api/v1/orders/submit', async (route) => {
117
151
  ```
118
152
 
119
153
  ### Pattern F: Sudden Offline Disconnection & Reconnection
154
+ <!-- classification: illustrative -->
120
155
  ```typescript
121
156
  // 1. Cut network abruptly
122
157
  await context.setOffline(true);
@@ -134,9 +169,25 @@ await expect(page.locator('h1')).toBeVisible();
134
169
 
135
170
  ---
136
171
 
137
- ## 4. Best Practices Checklist
172
+ ### Best Practices Checklist
138
173
  - [ ] Always declare routes **before** calling `page.goto()`.
139
174
  - [ ] Use regex or glob patterns with caution; avoid intercepting Vite/Webpack bundling scripts.
140
175
  - [ ] Critical forms must disable submit buttons during in-flight network transit to prevent duplicate requests.
141
176
  - [ ] HTTP 502/503/504 errors must trigger user-friendly notifications, never raw JSON dumps or blank screens.
142
177
  - [ ] For teardown, unroute specific patterns or reset context per test.
178
+
179
+ ---
180
+
181
+ ## 4. Verification Points & DoD
182
+
183
+ 1. Mock routes match exact URL patterns, HTTP methods, and status codes.
184
+ 2. Chaos fault injection (latencies, 500 errors, rate limits) verifies UI graceful degradation.
185
+ 3. Network route handlers clean up upon test fixture teardown.
186
+
187
+ ---
188
+
189
+ ## 5. Handoff Protocol
190
+
191
+ - **Deliverables:** Route interception handlers, mock fixture payloads, and network chaos test cases.
192
+ - **Next Subagent:** api-engineer / test-runner
193
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: api-spec-to-e2e-matrix
3
3
  description: "Generate automated positive, boundary, and negative test matrices from OpenAPI specifications. Use when converting an OpenAPI/Swagger spec into an end-to-end test matrix."
4
+ category: architecture_and_analysis
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: none
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # API Spec to E2E Matrix — Contract-Based Test Generator
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Generate automated positive, boundary, and negative test matrices from OpenAPI specifications. Use when converting an OpenAPI/Swagger spec into an end-to-end test matrix.
20
+ - **Activation Scope:** Domain workflows for `03-api-and-contracts` involving `api-spec-to-e2e-matrix`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT generate positive-only test matrices; boundary and negative status codes must be fully mapped.
28
+ - Do NOT generate tests against outdated OpenAPI specifications without running schema diffing.
29
+ - Do NOT hardcode unauthenticated test credentials in generated matrices.
30
+ - **Sibling Skill Boundaries:**
31
+ - consumer-driven-contract-testing verifies CDC contracts; api-spec-to-e2e-matrix compiles exhaustive test matrices from OpenAPI specs.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  This skill converts OpenAPI / Swagger specifications, JSON Schemas, or REST endpoint contracts into a structured, executable End-to-End (E2E) testing matrix covering happy path, boundary values, and negative error scenarios.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Test Generation Matrix Taxonomy
41
+ ### Test Generation Matrix Taxonomy
13
42
 
14
43
  ```mermaid
15
44
  flowchart TD
@@ -23,7 +52,7 @@ flowchart TD
23
52
 
24
53
  ---
25
54
 
26
- ## 2. Boundary Value Generation Rules
55
+ ### Boundary Value Generation Rules
27
56
 
28
57
  For every field defined in the endpoint schema, generate targeted edge cases:
29
58
 
@@ -37,7 +66,7 @@ For every field defined in the endpoint schema, generate targeted edge cases:
37
66
 
38
67
  ---
39
68
 
40
- ## 3. Negative Scenario Validation Checklist
69
+ ### Negative Scenario Validation Checklist
41
70
 
42
71
  Every negative test case must assert two distinct layers:
43
72
  1. **API Layer Assertion:**
@@ -49,17 +78,18 @@ Every negative test case must assert two distinct layers:
49
78
 
50
79
  ---
51
80
 
52
- ## 4. Automation Output Standards
81
+ ### Automation Output Standards
53
82
 
54
83
  - Generated test cases must adhere to the project's **Clean POM** structure.
55
84
  - All requests should utilize dynamic test data with unique timestamp prefixes to ensure idempotency.
56
85
 
57
86
  ---
58
87
 
59
- ## 5. Automated Execution via Tooling
88
+ ### Automated Execution via Tooling
60
89
 
61
90
  Agent can automatically invoke `tools/generate_api_matrix.py` and `tools/export_postman_collection.py`:
62
91
 
92
+ <!-- classification: illustrative -->
63
93
  ```bash
64
94
  # 1. Generate Markdown matrix
65
95
  python3 tools/generate_api_matrix.py --spec path/to/openapi.json --format md -o docs/api_matrix.md
@@ -77,4 +107,20 @@ agent-qa export-postman --domain ecommerce -o ecom_col.json
77
107
  # 5. Execute Newman & Enforce CI/CD Quality Gate
78
108
  newman run postman_collection.json -e postman_env.json -d test_data.csv -r cli,json --reporter-json-export report.json
79
109
  agent-qa analyze-newman report.json --max-failures 0 --sla-avg 500 --markdown pr_report.md
80
- ```
110
+ ```
111
+
112
+ ---
113
+
114
+ ## 4. Verification Points & DoD
115
+
116
+ 1. All endpoints and HTTP methods mapped to positive, boundary, and negative test scenarios.
117
+ 2. Validation rules (min, max, pattern, required, enum) mapped to specific assertions.
118
+ 3. Output matrix compiles into runnable API test skeletons (Pytest / Playwright).
119
+
120
+ ---
121
+
122
+ ## 5. Handoff Protocol
123
+
124
+ - **Deliverables:** API test matrix documentation and runnable API test suite skeletons.
125
+ - **Next Subagent:** api-engineer / test-runner
126
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,23 +1,48 @@
1
1
  ---
2
2
  name: consumer-driven-contract-testing
3
- description: "Standardize Consumer-Driven Contract (CDC) testing with Pact and OpenAPI Bidirectional Contract Testing. Detect and prevent breaking schema changes, payload drift, and microservice integration failures."
3
+ description: "Standardize Consumer-Driven Contract (CDC) testing with Pact and OpenAPI Bidirectional Contract Testing. Detect and prevent breaking schema changes, payload drift, and microservice integration failures. Use when implementing contract testing, verifying CDC providers, or preventing breaking API schema changes."
4
+ category: verification_and_resilience
5
+ version: "3.2.0"
6
+ policies:
7
+ network: localhost-only
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Consumer-Driven Contract (CDC) Testing — Schema Drift & Integration Sentinel
7
12
 
8
13
  > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
9
14
 
10
15
  ---
11
16
 
12
- ## 1. Overview & Architecture
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Use when implementing consumer-driven contract testing, verifying microservice API provider implementations, validating bidirectional contracts (BDCT), or preventing breaking API schema changes before deployment.
20
+ - **Activation Scope:**
21
+ - Microservice integration boundaries where frontend (Web/Mobile) or BFF consumers interface with backend services.
22
+ - Multi-repo or monorepo environments maintaining OpenAPI 3.0/3.1 specifications or Pact contract ledgers.
23
+ - Pre-deployment CI/CD pipelines executing compatibility promotion gates (`can-i-deploy`).
24
+
25
+ ---
26
+
27
+ ## 2. Non-Goals & Boundary Constraints
28
+
29
+ - **What NOT to do:**
30
+ - Do NOT use CDC testing as a substitute for unit tests or deep domain business logic validation.
31
+ - Do NOT hardcode non-hermetic, unresolvable internal domains (e.g. `https://broker.synapse-qa.internal`); use hermetic local brokers (`http://localhost:1234` or mock server instances).
32
+ - Do NOT use lazy ellipsis or truncation (`{ ... }`) in contract payloads; define explicit, valid request and response bodies.
33
+ - Do NOT execute active network requests outside `localhost` in restricted environments.
34
+ - **Sibling Skill Boundaries:**
35
+ - `api-spec-to-e2e-matrix`: Focuses on compiling comprehensive functional E2E test matrices from OpenAPI specs.
36
+ - `api-network-mocking-interception`: Focuses on client-side route stubbing and chaos fault injection within browser test runners.
37
+ - `consumer-driven-contract-testing` (this skill): Owns consumer expectations, broker publishing, provider verification, and deployment gatekeeping.
38
+
39
+ ---
40
+
41
+ ## 3. Ordered Execution Workflow
13
42
 
14
- Consumer-Driven Contract (CDC) Testing shifts integration verification left by formalizing expectations between API consumers (Web/Mobile frontends, backend BFFs) and API providers (microservices) into explicit, machine-readable contracts.
43
+ ### Phase 1: Architecture & Contract Invariants
15
44
 
16
- Instead of relying on fragile, slow, and expensive multi-service end-to-end environments, CDC enables isolated testing:
17
- 1. **Consumer Tests:** The consumer defines its exact expectation contract (HTTP method, headers, request body, response schema, status code) against a mock provider. A signed Pact file (`.json`) or OpenAPI specification is generated.
18
- 2. **Contract Broker:** The contract is published to the Pact Broker / Contract Ledger with semantic versioning.
19
- 3. **Provider Verification:** The provider independently replays all registered consumer contracts against its live endpoints (or generated stubs) in CI/CD without needing any running consumers.
20
- 4. **Deploy Gate (`can-i-deploy`):** Verifies that both consumer and provider versions are compatible before promoting artifacts to staging or production.
45
+ Consumer-Driven Contract (CDC) Testing shifts integration verification left by formalizing expectations between API consumers and API providers into explicit, machine-readable contracts.
21
46
 
22
47
  ```mermaid
23
48
  flowchart LR
@@ -40,13 +65,11 @@ flowchart LR
40
65
  end
41
66
  ```
42
67
 
43
- ---
44
-
45
- ## 2. Bi-Directional Contract Testing (BDCT) & OpenAPI Diffing
68
+ ### Phase 2: Bi-Directional Contract Testing (BDCT) & Breaking Change Rules
46
69
 
47
- In bi-directional contract testing, consumers use mock fixtures or recorded network HAR traffic, while providers supply their authoritative OpenAPI 3.0/3.1 specification. The engine executes automated schema diffing:
70
+ The contract verifier executes automated schema diffing against the provider's authoritative specification:
48
71
 
49
- ### Breaking Changes Checklist (Strictly Blocked by Gatekeeper):
72
+ #### Breaking Changes Checklist (Strictly Blocked by Gatekeeper):
50
73
  - ❌ **Removing an existing field** that any consumer contract depends on.
51
74
  - ❌ **Adding a new mandatory (`required`) field** to a request body without a default value.
52
75
  - ❌ **Mutating property data types** (e.g., `id: string` changed to `id: integer`, or `amount: number` to `amount: string`).
@@ -54,18 +77,16 @@ In bi-directional contract testing, consumers use mock fixtures or recorded netw
54
77
  - ❌ **Altering response status codes** (e.g., changing HTTP 201 Created to HTTP 200 OK without consumer migration).
55
78
  - ❌ **Tightening validation rules** (e.g., lowering `maxLength` below existing consumer field lengths).
56
79
 
57
- ### Non-Breaking Changes (Permitted):
80
+ #### Non-Breaking Changes (Permitted):
58
81
  - ✅ Adding optional fields (`required: false`) to response bodies.
59
82
  - ✅ Adding new endpoints without touching existing routes.
60
83
  - ✅ Loosening validation rules (e.g., increasing `maxLength` or expanding enum options).
61
84
 
62
- ---
63
-
64
- ## 3. Consumer Contract Authoring Standards (Clean POM & Pact DSL)
85
+ ### Phase 3: Consumer Contract Authoring (TypeScript / Pact DSL)
65
86
 
66
- Consumer contracts must use flexible matchers rather than hardcoded static payloads to prevent flakiness:
87
+ Consumer contracts must use flexible matchers rather than hardcoded static values to prevent flakiness:
67
88
 
68
- ### TypeScript / Playwright Pact Pattern:
89
+ <!-- classification: illustrative -->
69
90
  ```typescript
70
91
  import { PactV3, MatchersV3 } from '@pact-foundation/pact';
71
92
 
@@ -104,44 +125,73 @@ describe('Order Service CDC Suite', () => {
104
125
  }
105
126
  })
106
127
  .executeTest(async (mockserver) => {
107
- const client = new OrderApiClient(mockserver.url);
108
- const response = await client.createOrder({ ... });
109
- expect(response.status).toBe('CONFIRMED');
128
+ // Native fetch client implementation with hermetic mock provider target
129
+ const response = await fetch(`${mockserver.url}/api/v1/orders`, {
130
+ method: 'POST',
131
+ headers: {
132
+ 'Content-Type': 'application/json',
133
+ 'Authorization': 'Bearer test-contract-token',
134
+ },
135
+ body: JSON.stringify({
136
+ customerId: 'CUST_1001',
137
+ items: [
138
+ { sku: 'SKU_ITEM_01', quantity: 1, price: 49.99 }
139
+ ]
140
+ }),
141
+ });
142
+ const data = await response.json();
143
+ expect(response.status).toBe(201);
144
+ expect(data.status).toBe('CONFIRMED');
110
145
  });
111
146
  });
112
147
  });
113
148
  ```
114
149
 
115
- ---
116
-
117
- ## 4. Provider Verification Protocol
150
+ ### Phase 4: Provider Verification Protocol
118
151
 
119
- Providers verify all active consumer contracts against their test instances:
152
+ Providers verify all registered consumer contracts against their local test instances:
120
153
 
154
+ <!-- classification: illustrative -->
121
155
  ```bash
122
- # Verify provider implementation against contracts registered in broker
156
+ # Verify provider implementation against contracts registered in local mock/broker
123
157
  pact-verifier \
124
158
  --provider-base-url="http://localhost:8080" \
125
- --pact-broker-url="https://broker.synapse-qa.internal" \
159
+ --pact-broker-url="http://localhost:1234" \
126
160
  --provider="OrderService" \
127
161
  --publish-verification-results \
128
162
  --provider-app-version="3.2.0" \
129
163
  --provider-version-branch="main"
130
164
  ```
131
165
 
132
- ---
133
-
134
- ## 5. Automated CI/CD Deployment Verification (`can-i-deploy`)
166
+ ### Phase 5: Automated CI/CD Deployment Verification (`can-i-deploy`)
135
167
 
136
- Before triggering deployment in CI/CD, the release pipeline invokes the compatibility ledger:
168
+ Before triggering promotion in CI/CD, the release pipeline invokes the compatibility ledger:
137
169
 
170
+ <!-- classification: illustrative -->
138
171
  ```bash
139
- # Enforce deployment gatekeeper
172
+ # Enforce deployment gatekeeper against hermetic broker
140
173
  pact-broker can-i-deploy \
141
- --pact-broker-url="https://broker.synapse-qa.internal" \
174
+ --pact-broker-url="http://localhost:1234" \
142
175
  --pacticipant="SynapseWebFrontend" \
143
176
  --version="3.2.0" \
144
177
  --to-environment="production"
145
178
  ```
146
179
 
147
- If any contract is unverified or broken, the command exits with non-zero code, blocking deployment and preventing live customer-facing API outages.
180
+ ---
181
+
182
+ ## 4. Verification Points & DoD
183
+
184
+ 1. **Consumer Contract Generation:** Pact contract file (`pacts/*.json`) is generated and contains valid JSON with no missing fields or unresolved `{ ... }` truncations.
185
+ 2. **Schema Conformance:** Consumer expectation matches provider OpenAPI schema with 0 breaking change violations.
186
+ 3. **Hermetic Target Validation:** Broker and provider URLs point to localhost or hermetic mock addresses, never unresolvable internal domains.
187
+ 4. **Deploy Gate Check:** `can-i-deploy` verification exits with code 0 before promotion.
188
+
189
+ ---
190
+
191
+ ## 5. Handoff Protocol
192
+
193
+ - **Deliverables:**
194
+ - Signed Pact contract JSON (`pacts/<consumer>-<provider>.json`).
195
+ - OpenAPI verification report and breaking changes diff summary.
196
+ - **Next Subagent:** Pass contract artifacts to `api-engineer` for provider stub generation or `quality-gatekeeper` for CI/CD promotion gate clearance.
197
+ - **Output Format:** Machine-readable JSON contract with SemVer compatibility tag.
@@ -1,16 +1,45 @@
1
1
  ---
2
2
  name: backend-load-and-stress-patterns
3
3
  description: "Orchestrate k6, Locust, and JMeter backend load, stress, and SLA endurance test suites. Use when designing load, stress, or spike test patterns for backend systems."
4
+ category: test_automation_and_execution
5
+ version: "1.0.0"
6
+ policies:
7
+ network: sandbox-only
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Backend Load & Performance Testing Skill
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Orchestrate k6, Locust, and JMeter backend load, stress, and SLA endurance test suites. Use when designing load, stress, or spike test patterns for backend systems.
20
+ - **Activation Scope:** Domain workflows for `04-performance-and-load` involving `backend-load-and-stress-patterns`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT run uncontrolled load tests against production systems without explicit authorization and scheduling.
28
+ - Do NOT ramp virtual users instantly without realistic warm-up stages (prevent artificial cold-start spikes).
29
+ - Do NOT ignore server error rates (p95 latency and HTTP 5xx errors must both be tracked).
30
+ - **Sibling Skill Boundaries:**
31
+ - web-vitals-and-performance-profiler tests frontend client rendering; backend-load-and-stress-patterns tests server throughput and saturation (k6/JMeter).
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  > **Target:** Model concurrent Virtual User (VU) and arrival-rate traffic, execute stress/soak test profiles, and enforce automated SLA gates (P95/P99 latency, error rate < 1.0%) to detect bottlenecks before production.
9
- > **Mandatory Rule:** Adhere strictly to [performance_testing_rules.md](../../rules/performance_testing_rules.md) for safety approvals, hard caps, and truth-anchor reporting.
38
+ > **Mandatory Rule:** Adhere strictly to [performance_testing_rules.md](../../../rules/performance_testing_rules.md) for safety approvals, hard caps, and truth-anchor reporting.
10
39
 
11
40
  ---
12
41
 
13
- ## 1. Test Archetypes & SLA Targets
42
+ ### Test Archetypes & SLA Targets
14
43
 
15
44
  | Archetype | VUs / Rate | Duration | Objective | SLA Assertion |
16
45
  | :--- | :--- | :--- | :--- | :--- |
@@ -22,9 +51,10 @@ description: "Orchestrate k6, Locust, and JMeter backend load, stress, and SLA e
22
51
 
23
52
  ---
24
53
 
25
- ## 2. Tooling Unified Runbook
54
+ ### Tooling Unified Runbook
26
55
 
27
56
  ### Option A: Apache JMeter (Headless CLI + JTL Analyzer)
57
+ <!-- classification: illustrative -->
28
58
  ```bash
29
59
  # 1. Generate XML test plan from OpenAPI / Postman
30
60
  synapse generate-jmx --spec api.json -o load_plan.jmx --vus 50 --duration 180 --sla-p95 500
@@ -39,6 +69,7 @@ synapse analyze-jtl results.jtl --sla-p95 500 --max-error-rate 1.0
39
69
  ### Option B: k6 Production Load Testing (with Kill-Switch & Arrival Rate)
40
70
  Execute high-concurrency production load tests with arrival-rate executors, user pooling, and automatic kill-switches.
41
71
 
72
+ <!-- classification: illustrative -->
42
73
  ```bash
43
74
  # Execute k6 test suite with environment variables
44
75
  k6 run -e BASE_URL=https://api.staging.enterprise.local tests/perf/load_test.js
@@ -48,7 +79,7 @@ k6 run -e BASE_URL=https://api.staging.enterprise.local tests/perf/load_test.js
48
79
 
49
80
  ---
50
81
 
51
- ## 3. Best Practices & Safety Invariants
82
+ ### Best Practices & Safety Invariants
52
83
 
53
84
  - **Isolated Test Data:** Always use dynamic runtime identifiers (`PERF_AUTO_${Date.now()}`) to eliminate primary key collisions.
54
85
  - **TearDown Hygiene:** Complement POST/creation load tests with automated teardown or ephemeral DB snapshots (`tools/db_sandbox.py`).
@@ -57,13 +88,14 @@ k6 run -e BASE_URL=https://api.staging.enterprise.local tests/perf/load_test.js
57
88
 
58
89
  ---
59
90
 
60
- ## 4. Code-as-Code Load Model (Locust)
91
+ ### Code-as-Code Load Model (Locust)
61
92
 
62
93
  > *Borrowed and adapted from the Locust load-testing model (MIT license, locustio/locust).*
63
94
 
64
95
  When version-controlled, reviewable load tests matter more than XML tooling,
65
96
  generate a runnable locustfile from the same API ingestion used for JMeter:
66
97
 
98
+ <!-- classification: illustrative -->
67
99
  ```bash
68
100
  synapse generate-jmx --spec swagger.json --emit-locust locustfile.py \
69
101
  --weighted-mix "70,20,10" --think-time-min 500 --think-time-max 1500
@@ -83,3 +115,19 @@ test suite.
83
115
  for protocol breadth (JDBC/Kafka/gRPC/WS) and Locust for flow logic.
84
116
  3. **Same SLA gates** — run `agent-qa analyze-jtl` semantics on Locust stats:
85
117
  fail CI when P95 breaches the SLA budget.
118
+
119
+ ---
120
+
121
+ ## 4. Verification Points & DoD
122
+
123
+ 1. Load profile defines clear ramp-up, steady-state, and ramp-down stages.
124
+ 2. Thresholds enforce p95/p99 latency ceilings and maximum allowable error rates (< 1%).
125
+ 3. Performance report includes request throughput, response distribution, and failure analysis.
126
+
127
+ ---
128
+
129
+ ## 5. Handoff Protocol
130
+
131
+ - **Deliverables:** Load test scripts (`k6` / `JMeter`), threshold configurations, and performance execution reports.
132
+ - **Next Subagent:** perf-engineer
133
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -3,18 +3,46 @@ name: lean-impact-scoreboard
3
3
  description: "Display empirical impact scoreboards (code reduction, token savings, mutation rigor). Use when reviewing lean engineering benchmarks, token throughput, or reporting quality metrics."
4
4
  category: architecture_and_analysis
5
5
  version: "1.0.0"
6
+ policies:
7
+ network: none
8
+ shell: none
9
+ filesystem: read-only
6
10
  ---
7
-
8
11
  # Lean Impact Scoreboard — Verified Efficiency & Token Benchmarks
9
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Display empirical impact scoreboards (code reduction, token savings, mutation rigor). Use when reviewing lean engineering benchmarks, token throughput, or reporting quality metrics.
20
+ - **Activation Scope:** Domain workflows for `04-performance-and-load` involving `lean-impact-scoreboard`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT report unproven quantitative claims or synthetic savings percentages without empirical provenance.
28
+ - Do NOT sacrifice safety, error handling, or trust boundaries in the name of code conciseness.
29
+ - Do NOT invent per-repository savings figures without executing project analysis tools.
30
+ - **Sibling Skill Boundaries:**
31
+ - repo-quality-audit inspects repository health; lean-impact-scoreboard documents verified empirical efficiency and token benchmarks.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
10
37
  Displays empirical metrics and benchmarks demonstrating the impact of Lean Engineering (The 7-Rung Ladder, Clean POM, and Verification-First).
11
38
 
12
39
  ---
13
40
 
14
- ## 1. Benchmark Overview
41
+ ### Benchmark Overview
15
42
 
16
43
  Based on extensive agentic benchmarks (39 real-world tasks across backend, frontend, security, and test suites):
17
44
 
45
+ <!-- classification: illustrative -->
18
46
  ```text
19
47
  ================================================================================
20
48
  Metric Baseline (No Skill) Lean Mode Delta
@@ -23,19 +51,19 @@ Lines of Code Generated 100% 47% -53%
23
51
  Output Tokens Consumed 100% 55% -45% 📉
24
52
  API Cost 100% 74% -26% 📉
25
53
  Agent Execution Time 100% 59% -41% ⚡
26
- Risky Logic Shipped with Tests 68% 98% +30% 🛡️
54
+ Risky Logic Shipped with Tests Standard Baseline High Priority Substantial Lift 🛡️
27
55
  Bug Detection Rate (Mutants) 46% 66% +20% 🎯
28
56
  ================================================================================
29
57
  ```
30
58
 
31
59
  ---
32
60
 
33
- ## 2. Key Insights
61
+ ### Key Insights
34
62
 
35
63
  1. **Less Code, Zero Loss of Safety:**
36
64
  The goal is never code golfing. Code is concise because unnecessary abstractions, speculative wrappers, and redundant libraries are eliminated. Validation, trust boundaries, error handling, and accessibility are never compromised.
37
65
  2. **Empirical Verification Over Guesswork:**
38
- 98% of all risky logic (branches, parsers, auth, financial paths) ships with an automated unit assertion, compared to only 68% in standard unconstrained AI runs.
66
+ Empirical heuristics show that targeted assertion enforcement significantly increases coverage of critical branch logic (branches, parsers, auth, financial paths) compared to unconstrained AI generation.
39
67
  3. **Real Per-Repo Metrics:**
40
68
  Never hallucinate synthetic per-repo savings figures. For repository-specific health and debt measurements:
41
69
  - Run `agent-qa debt` to review tracked shortcut debt.
@@ -43,6 +71,22 @@ Bug Detection Rate (Mutants) 46% 66% +20%
43
71
 
44
72
  ---
45
73
 
46
- ## 3. Attribution
74
+ ### Attribution
47
75
 
48
76
  Adapted from **ponytail-gain** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-calibrated for Enterprise QA and Synapse Hub benchmarks.
77
+
78
+ ---
79
+
80
+ ## 4. Verification Points & DoD
81
+
82
+ 1. Scoreboard metrics cite explicit empirical benchmark datasets and methodology.
83
+ 2. All quantitative assertions represent contextual heuristics rather than unverified absolutes.
84
+ 3. Project-specific metrics link to actual tool execution (`agent-qa debt`, `tools/analyze_project.py`).
85
+
86
+ ---
87
+
88
+ ## 5. Handoff Protocol
89
+
90
+ - **Deliverables:** Empirical impact scorecards, benchmark comparisons, and debt reduction reports.
91
+ - **Next Subagent:** orchestrator
92
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.