@teevee98/synapse-hub 4.2.0 → 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 (107) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/cli.py +4 -4
  82. package/tools/core/bm25_retriever.py +1 -1
  83. package/tools/core/i18n.py +1 -1
  84. package/tools/core/provider_usage_adapter.py +66 -0
  85. package/tools/core/token_estimator.py +39 -1
  86. package/tools/count_tokens.py +2 -2
  87. package/tools/dashboard_generator.py +8 -8
  88. package/tools/db_sandbox.py +182 -43
  89. package/tools/distill_log.py +1 -1
  90. package/tools/distill_skill.py +17 -2
  91. package/tools/git_pre_commit_guard.py +190 -1
  92. package/tools/mcp_docx_server.py +1 -1
  93. package/tools/mcp_excel_server.py +1 -1
  94. package/tools/mcp_server.py +33 -5
  95. package/tools/micro_mutator.py +30 -1
  96. package/tools/pentest_scope_guard.py +288 -15
  97. package/tools/project_state.py +29 -5
  98. package/tools/reversible_sandbox.py +58 -13
  99. package/tools/rules_router.py +80 -27
  100. package/tools/skill_canonical_digest.py +60 -2
  101. package/tools/sync_agent_rules.py +187 -61
  102. package/tools/task_memory_manager.py +16 -1
  103. package/tools/ui_server.py +3 -1
  104. package/tools/update_sentinel.py +3 -3
  105. package/tools/validate_skills_schema.py +349 -56
  106. package/tools/verify_all.py +96 -2
  107. package/tools/welcome_page.py +1 -1
@@ -8,74 +8,118 @@ policies:
8
8
  shell: workspace-sandbox
9
9
  filesystem: workspace-sandbox
10
10
  ---
11
- # Graphify Impact Analyzer — AST Knowledge Graph Navigation & Zero-Waste Impact Analysis
11
+ # Graphify Impact Analyzer — AST Knowledge Graph Navigation & Impact Analysis
12
12
 
13
- Specialized skill for navigating the codebase's AST Knowledge Graph (`graphify-out/graph.json`), executing sub-second dependency queries, and performing **Zero-Waste Test Impact Analysis** to execute only tests affected by code modifications.
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
14
 
15
15
  ---
16
16
 
17
- ## 1. Core Capabilities
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Use when analyzing the blast radius of code modifications, executing targeted test impact analysis via AST dependency graphs, or locating impacted test suites after refactoring.
20
+ - **Activation Scope:**
21
+ - Code changes in Page Classes, utility helpers, and shared base abstractions.
22
+ - AST knowledge graph queries (`graphify-out/graph.json`).
23
+ - Pre-execution test scoping for CI/CD pipelines to run only affected test cases.
24
+
25
+ ---
26
+
27
+ ## 2. Non-Goals & Boundary Constraints
28
+
29
+ - **What NOT to do:**
30
+ - Do NOT execute blind full-corpus regression runs when changes are strictly localized to isolated leaf classes.
31
+ - Do NOT mutate or corrupt the AST graph without running synchronization (`graphify update .`).
32
+ - Do NOT reference non-existent project files or broken visual report paths.
33
+ - **Sibling Skill Boundaries:**
34
+ - `repo-quality-audit`: Conducts holistic 6-pillar repository architecture and debt audits.
35
+ - `senior-code-review`: Evaluates code diffs against Clean POM, security, and performance standards.
36
+ - `graphify-impact-analyzer` (this skill): Navigates dependency graphs and computes test impact blast radius.
37
+
38
+ ---
39
+
40
+ ## 3. Ordered Execution Workflow
41
+
42
+ ### Phase 1: AST Knowledge Graph Navigation & Capabilities
18
43
 
19
44
  1. **Deterministic AST Parsing (Zero API Cost):**
20
45
  - Automatically maps files, classes, methods, and test scripts into `graphify-out/graph.json`.
21
46
  - Replaces blind, expensive full-corpus grepping with targeted graph traversals.
22
47
 
23
- 2. **Automated Test Impact Analysis (Zero Waste):**
24
- - When any Page Class in `Keywords/<project>/pages/` or `pages/*.ts` is modified, the impact analyzer computes reverse dependencies in `graph.json`.
25
- - Pinpoints the exact subset of Test Cases affected, reducing CI/CD execution time by up to 90+%.
48
+ 2. **Automated Test Impact Analysis:**
49
+ - When a Page Class (e.g. `examples/playwright-crm-suite/pages/CustomerPage.ts`) is modified, the impact analyzer computes reverse dependencies in `graphify-out/graph.json`.
50
+ - Pinpoints the exact subset of Test Cases affected, significantly reducing test execution overhead.
26
51
 
27
52
  3. **God Node & Technical Debt Detection:**
28
53
  - Detects over-coupled classes and guides safe, modular refactoring.
29
54
 
30
- ---
31
-
32
- ## 2. Test Impact Analysis Workflow (`tools/test_impact.py`)
55
+ ### Phase 2: Test Impact Analysis Workflow (`tools/test_impact.py`)
33
56
 
34
57
  Run impact analysis before dispatching test suites:
35
58
 
36
- ### 2.1. Check Impact of Modified Page Class
59
+ #### Check Impact of Modified Page Class
60
+
61
+ <!-- classification: illustrative -->
37
62
  ```bash
38
- synapse impact -f Keywords/pages/CategoryPage.groovy
63
+ # Analyze impact for a specific modified Page Class
64
+ synapse impact -f examples/playwright-crm-suite/pages/CustomerPage.ts
39
65
  ```
40
- *Output:*
41
- - Target File: `Keywords/pages/CategoryPage.groovy`
42
- - Directly Impacted: **12 / 250 TCs**
43
- - Skipped: **238 TCs**
44
- - Time Saved: **95.2%**
45
66
 
46
- ### 2.2. Automatically Analyze Git Changes
67
+ *Expected Output:*
68
+ - Target File: `examples/playwright-crm-suite/pages/CustomerPage.ts`
69
+ - Directly Impacted: `examples/playwright-crm-suite/tests/customers.spec.ts`
70
+ - Status: Isolated blast radius
71
+
72
+ #### Automatically Analyze Git Changes
73
+
74
+ <!-- classification: illustrative -->
47
75
  ```bash
76
+ # Analyze impact from current working tree git diff
48
77
  synapse impact --git-diff
49
78
  ```
50
79
 
51
- ### 2.3. Output Machine-Readable JSON (For CI/CD Pipelines)
80
+ #### Output Machine-Readable JSON (For CI/CD Pipelines)
81
+
82
+ <!-- classification: illustrative -->
52
83
  ```bash
84
+ # Export structured blast radius JSON report
53
85
  synapse impact --git-diff --json
54
86
  ```
55
87
 
56
- ---
88
+ See reference schema in `examples/dependency_blast_radius.json`.
89
+
90
+ ### Phase 3: Knowledge Graph Navigation Commands
91
+
92
+ <!-- classification: illustrative -->
93
+ ```bash
94
+ # Explain a Page Class or Script and its connections
95
+ graphify explain "CustomerPage"
96
+
97
+ # Find shortest dependency path between two classes/scripts
98
+ graphify path "CustomerPage" "BasePage"
99
+
100
+ # Refresh AST graph after code modifications
101
+ graphify update .
102
+ ```
57
103
 
58
- ## 3. Knowledge Graph CLI Navigation Commands
104
+ ### Phase 4: Visual Artifacts Inspection
59
105
 
60
- | Command | Purpose | Example |
61
- |---|---|---|
62
- | `graphify explain "<Node>"` | Explain a Page Class or Script and its connections | `graphify explain "UserAdminPage"` |
63
- | `graphify path "<A>" "<B>"` | Find shortest path between two classes/scripts | `graphify path "LoginPage" "BasePage"` |
64
- | `graphify query "<Concept>"` | Query a concept or test case subgraph | `graphify query "TC-101"` |
65
- | `graphify update .` | Refresh AST graph after code modifications (No LLM needed) | `graphify update .` |
106
+ - **Interactive Visualizer:** `graphify-out/graph.html`
107
+ - **Call-flow Diagrams:** `graphify-out/Agent-Skill-callflow.html`
108
+ - **Summary Report:** `graphify-out/GRAPH_REPORT.md`
66
109
 
67
110
  ---
68
111
 
69
- ## 4. Visual Artifacts
112
+ ## 4. Verification Points & DoD
70
113
 
71
- - **2D/3D Interactive Visualizer:** `graphify-out/graph.html`
72
- - **Call-flow & Mermaid Diagrams:** `graphify-out/callflow.html`
73
- - **Architectural Summary Report:** `graphify-out/GRAPH_REPORT.md`
114
+ 1. **AST Graph Integrity:** `graphify-out/graph.json` exists, parses as valid JSON, and reflects current workspace state.
115
+ 2. **Blast Radius Accuracy:** Impact analysis accurately identifies callers and dependent test suites of touched files.
116
+ 3. **Artifact Resolution:** Visualizer files (`graphify-out/Agent-Skill-callflow.html`, `graphify-out/graph.html`) resolve cleanly.
117
+ 4. **Tool Command Exit Code:** `synapse impact` executes with exit code 0.
74
118
 
75
119
  ---
76
120
 
77
- ## 5. Agent Operational Guardrails
121
+ ## 5. Handoff Protocol
78
122
 
79
- 1. **Before modifying any Page Class:** Run `synapse impact -f <path>` to identify dependent Test Cases.
80
- 2. **After modifying code:** Run `graphify update .` to keep the knowledge graph synchronized.
81
- 3. **DoD Compliance:** Always verify that all changes pass `synapse verify`.
123
+ - **Deliverables:** Impacted test suite list, blast radius classification report (`examples/dependency_blast_radius.json`), and updated knowledge graph.
124
+ - **Next Subagent:** Pass the list of impacted test files to `test-runner` for targeted execution or `quality-gatekeeper` for change validation.
125
+ - **Output Format:** JSON list of affected test files and summary markdown.
@@ -1,8 +1,7 @@
1
1
  {
2
- "modifiedFile": "src/pages/CheckoutPage.ts",
2
+ "modifiedFile": "examples/playwright-crm-suite/pages/CustomerPage.ts",
3
3
  "impactedSuites": [
4
- "tests/e2e/checkout.spec.ts",
5
- "tests/e2e/payment.spec.ts"
4
+ "examples/playwright-crm-suite/tests/customers.spec.ts"
6
5
  ],
7
6
  "blastRadiusScore": "LOW_ISOLATED"
8
- }
7
+ }
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Lean Code Ladder — Enterprise Reuse-First Standard
12
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:** Apply a 7-rung reuse-first ladder so every new test-automation code path is the smallest complete change that fully solves the task. Use when adding helpers, Page Class methods, dependencies, or any new code where a shorter existing option might already exist.
20
+ - **Activation Scope:** Domain workflows for `08-code-quality` involving `lean-code-ladder`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT add speculative wrappers, unrequested options, or 'for later' abstractions (YAGNI).
28
+ - Do NOT skip the lower rungs of the 7-rung ladder; use existing code and language stdlib first.
29
+ - Do NOT sacrifice validation, trust boundaries, error handling, or security for code brevity.
30
+ - **Sibling Skill Boundaries:**
31
+ - surgical-coding-principles limits diff surface; lean-code-ladder dictates what minimal solution level to build.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
13
37
  Specialized skill for minimizing newly written code in test automation projects: solve the whole problem with the least new code, then finish the change completely (callers, fixtures, and the small test that proves it).
14
38
 
15
39
  ---
16
40
 
17
- ## 1. The 7-Rung Ladder & Intensity Levels
41
+ ### The 7-Rung Ladder & Intensity Levels
18
42
 
19
43
  ### Intensity Levels
20
44
 
@@ -39,12 +63,12 @@ Before writing any new code, descend the ladder and take the **first rung that f
39
63
  | 5 | One line? | Can it be one line a reader gets at a glance? Then one line. |
40
64
  | 6 | Minimum new code | Write the minimum that works, and no more. |
41
65
 
42
- ## 2. Reading Order Before Writing
66
+ ### Reading Order Before Writing
43
67
 
44
68
  - Read the task and the code it touches. List every place the change must reach: callers, tests, fixtures, config, exports.
45
69
  - Check what the change could break: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
46
70
 
47
- ## 3. Completeness Rules (Be Lazy About the Solution, Never About the Change)
71
+ ### Completeness Rules (Be Lazy About the Solution, Never About the Change)
48
72
 
49
73
  - Finish every part the task needs, including the callers, tests, and fixtures the change affects.
50
74
  - No abstraction, wrapper, option, config, or "for later" code nobody asked for. Keep values in the form the platform already gives. Deletion beats addition; keep the structure the codebase already has.
@@ -56,7 +80,7 @@ Before writing any new code, descend the ladder and take the **first rung that f
56
80
  - New non-trivial logic (a branch, loop, parser, money/security path, or a whole new script) leaves one small test or assert-based self-check before it counts as finished; trivial changes need none.
57
81
  - A shortcut with a known limit gets a code comment: `shortcut: <the limit>, <when to upgrade>`.
58
82
 
59
- ## 4. Never Cut (Hard Floor)
83
+ ### Never Cut (Hard Floor)
60
84
 
61
85
  The ladder minimizes code, never safety. The following are never removed or skipped in the name of leanness:
62
86
 
@@ -66,13 +90,13 @@ The ladder minimizes code, never safety. The following are never removed or skip
66
90
  - Accessibility behavior
67
91
  - Anything the user explicitly asked for
68
92
 
69
- ## 5. Evidence of Leanness
93
+ ### Evidence of Leanness
70
94
 
71
95
  - Run `python3 tools/infer_linter.py` after the change: zero fake-pass findings confirms the lean diff did not trade rigor for brevity.
72
96
  - Run the affected subset from `python3 tools/test_impact.py --git-diff` to prove the shortest diff still reaches everything it had to reach.
73
97
  - Lean code without its check is unfinished: Gate 8 (`tools/micro_mutator.py`, Mutation Score >= 80%) remains the floor for any assertion logic written on this ladder.
74
98
 
75
- ## 6. Worked Comparison
99
+ ### Worked Comparison
76
100
 
77
101
  | Situation | Bloated answer | Lean answer |
78
102
  |---|---|---|
@@ -80,7 +104,7 @@ The ladder minimizes code, never safety. The following are never removed or skip
80
104
  | Need retry around a flaky API call | New generic retry framework with policy classes | The installed HTTP client's retry option (Rung 4) + one test |
81
105
  | Need a formatted timestamp in test data | New utility module | One line with the stdlib formatter (Rung 2) |
82
106
 
83
- ## 7. Boundary vs Sibling Skills (Do Not Confuse)
107
+ ### Boundary vs Sibling Skills (Do Not Confuse)
84
108
 
85
109
  | Sibling | Owns | Hand-off |
86
110
  |---|---|---|
@@ -88,12 +112,28 @@ The ladder minimizes code, never safety. The following are never removed or skip
88
112
  | `code-refactoring-refactor-clean` | Deliberate SOLID refactors of existing debt | Refactoring is not ladder work; only new/changed code descends the ladder |
89
113
  | `clean-pom-crafter` | Page Class architecture and locator tiers | Ladder applies inside and around Page Classes, not to their architecture contract |
90
114
 
91
- ## 8. Reference Documentation
115
+ ### Reference Documentation
92
116
 
93
117
  - `python3 tools/infer_linter.py` — fake-pass scan for the new logic.
94
118
  - `python3 tools/test_impact.py --git-diff` — confirm the lean diff still covers all impacted tests.
95
119
  - `python3 tools/micro_mutator.py` — Gate 8 mutation floor (>= 80%) for non-trivial new logic.
96
120
 
97
- ## 9. Attribution
121
+ ### Attribution
98
122
 
99
123
  Adapted from **ponytail** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. The lazy-senior ladder, completeness rules, and never-cut floor are re-scoped for enterprise test automation in Synapse Hub; wording, structure, and examples modified.
124
+
125
+ ---
126
+
127
+ ## 4. Verification Points & DoD
128
+
129
+ 1. Solution stops at the lowest rung of the 7-rung ladder that satisfies the requirement.
130
+ 2. Zero speculative options or unused abstractions added.
131
+ 3. Deliberate simplifications marked with `shortcut: <limit>, <upgrade>` comments.
132
+
133
+ ---
134
+
135
+ ## 5. Handoff Protocol
136
+
137
+ - **Deliverables:** Minimal complete code changes, YAGNI audit rationale, and shortcut markers ledger.
138
+ - **Next Subagent:** orchestrator
139
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -10,13 +10,37 @@ policies:
10
10
  ---
11
11
  # Repo Quality Audit — Comprehensive Repository Health & Risk Audit
12
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:** Comprehensive codebase quality audit covering bugs, security, bottlenecks, and bloat. Use when auditing an entire project, evaluating repository health, or prioritizing technical debt.
20
+ - **Activation Scope:** Domain workflows for `08-code-quality` involving `repo-quality-audit`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT produce superficial line-count summaries without evaluating architectural health.
28
+ - Do NOT perform full-corpus reading of monolithic files into LLM context window.
29
+ - Do NOT report quality violations without referencing exact file paths and line spans.
30
+ - **Sibling Skill Boundaries:**
31
+ - senior-code-review evaluates pull request diffs; repo-quality-audit inspects holistic codebase architecture across 6 dimensions.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
13
37
  Audit an entire repository like the senior engineer who just inherited it and will be paged when it breaks.
14
38
  Prioritize: **Correctness -> Safety -> Scale -> Tests -> Speed -> Lean**.
15
39
  Always rank issues and provide a clear **"Fix this first"** verdict.
16
40
 
17
41
  ---
18
42
 
19
- ## 1. Mapping the Codebase First
43
+ ### Mapping the Codebase First
20
44
 
21
45
  Before diagnosing defects:
22
46
  1. **Entry Points & Architecture:** Inspect entry points (CLI commands, route handlers, test runners, background workers) and dependency manifests (`package.json`, `pyproject.toml`, `pom.xml`, `build.gradle`).
@@ -29,7 +53,7 @@ Before diagnosing defects:
29
53
 
30
54
  ---
31
55
 
32
- ## 2. Six Audit Dimensions
56
+ ### Six Audit Dimensions
33
57
 
34
58
  | Dimension | Inspection Focus | Red Flags |
35
59
  |---|---|---|
@@ -42,7 +66,7 @@ Before diagnosing defects:
42
66
 
43
67
  ---
44
68
 
45
- ## 3. Reporting Structure
69
+ ### Reporting Structure
46
70
 
47
71
  1. **Overview & Assumptions:**
48
72
  - What this codebase does
@@ -58,7 +82,7 @@ Before diagnosing defects:
58
82
 
59
83
  ---
60
84
 
61
- ## 4. Complementary Hub Tools
85
+ ### Complementary Hub Tools
62
86
 
63
87
  - `python3 tools/analyze_project.py` — 5-in-1 automated health audit and AST repo map.
64
88
  - `python3 tools/verify_all.py` — 10 Quality Gates DoD gatekeeper.
@@ -66,6 +90,22 @@ Before diagnosing defects:
66
90
 
67
91
  ---
68
92
 
69
- ## 5. Attribution
93
+ ### Attribution
70
94
 
71
95
  Adapted from **ponytail-audit** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-architected for Enterprise QA and Synapse Hub Standards.
96
+
97
+ ---
98
+
99
+ ## 4. Verification Points & DoD
100
+
101
+ 1. Codebase mapped via AST / repo_map before auditing.
102
+ 2. Audit covers architecture, Clean POM separation, test coverage, security, and technical debt.
103
+ 3. Findings prioritized by severity with actionable remediation steps.
104
+
105
+ ---
106
+
107
+ ## 5. Handoff Protocol
108
+
109
+ - **Deliverables:** Comprehensive repository quality audit report (`PROJECT_HEALTH_REPORT.md`) and debt catalog.
110
+ - **Next Subagent:** orchestrator
111
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -10,13 +10,37 @@ policies:
10
10
  ---
11
11
  # Senior Code Review — Enterprise Quality & Lean Diff Review
12
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:** Review code changes across logic, security, concurrency, and test coverage. Use when conducting pull request reviews, diff inspections, or auditing commit changes before merge.
20
+ - **Activation Scope:** Domain workflows for `08-code-quality` involving `senior-code-review`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT approve code containing fake passes, swallowed exceptions, or static sleeps.
28
+ - Do NOT nitpick subjective formatting preferences that automated linters already handle.
29
+ - Do NOT review diffs without inspecting callers and impact blast radius.
30
+ - **Sibling Skill Boundaries:**
31
+ - repo-quality-audit audits entire repos; senior-code-review performs 6-pillar inspection on active git diffs and PRs.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
13
37
  Review code changes like the senior engineer who will be paged at 2 AM when it breaks.
14
38
  Order of importance: **Correctness -> Safety -> Scale -> Tests -> Speed -> Lean**.
15
39
  Lean still matters: every extra line must be read, tested, and fixed later.
16
40
 
17
41
  ---
18
42
 
19
- ## 1. Understand First
43
+ ### Understand First
20
44
 
21
45
  - **Target Scoping:** Review what the user requests: uncommitted or staged changes, a branch, a PR link, or specific files. If unspecified: uncommitted changes (or last commit if clean).
22
46
  - **Read Beyond the Diff:** Read the diff, then read the code it touches:
@@ -28,7 +52,7 @@ Lean still matters: every extra line must be read, tested, and fixed later.
28
52
 
29
53
  ---
30
54
 
31
- ## 2. Six Core Review Pillars
55
+ ### Six Core Review Pillars
32
56
 
33
57
  ### 1. Bug & Edge Cases
34
58
  - Wrong calculation, crash, or unhandled edge cases (empty collections, zero values, timezone drift, string encoding).
@@ -67,7 +91,7 @@ Lean still matters: every extra line must be read, tested, and fixed later.
67
91
 
68
92
  ---
69
93
 
70
- ## 3. The 4-Angle Cleanup Model (`simplify`)
94
+ ### The 4-Angle Cleanup Model (`simplify`)
71
95
 
72
96
  > Adapted from the Claude Codex `simplify` plugin. Evaluate every diff through four independent cleanup lenses before accepting changes:
73
97
 
@@ -80,10 +104,11 @@ Lean still matters: every extra line must be read, tested, and fixed later.
80
104
 
81
105
  ---
82
106
 
83
- ## 4. Concrete Reporting Format
107
+ ### Concrete Reporting Format
84
108
 
85
109
  Every finding **must** have a concrete, reproducible failure scenario:
86
110
 
111
+ <!-- classification: illustrative -->
87
112
  ```markdown
88
113
  #### [Severity: Must fix | Should fix | Nice to have] <Finding Title> (`<file>:<line>`)
89
114
  - **What this is:** <One concise sentence describing the touched code>
@@ -94,9 +119,10 @@ Every finding **must** have a concrete, reproducible failure scenario:
94
119
 
95
120
  ---
96
121
 
97
- ## 5. Automation CLI
122
+ ### Automation CLI
98
123
 
99
124
  Run the automated senior review tool on your current working tree:
125
+ <!-- classification: illustrative -->
100
126
  ```bash
101
127
  python3 tools/senior_code_review.py # Review uncommitted changes
102
128
  python3 tools/senior_code_review.py --staged # Review staged git changes
@@ -106,6 +132,22 @@ python3 tools/senior_code_review.py --output-md REVIEW_REPORT.md # Export to ma
106
132
 
107
133
  ---
108
134
 
109
- ## 6. Attribution
135
+ ### Attribution
110
136
 
111
137
  Adapted from **ponytail-review** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert, and **claude-codex-settings / simplify** (Apache-2.0 / MIT). Re-architected for Enterprise QA, Clean POM, and Synapse Hub Quality Gates.
138
+
139
+ ---
140
+
141
+ ## 4. Verification Points & DoD
142
+
143
+ 1. Code diff evaluated across 6 pillars (Architecture, Clean POM, Tests, Security, Performance, Lean Dev).
144
+ 2. Zero raw locators in test scripts and zero secret leaks confirmed.
145
+ 3. Review verdict issued with constructive, actionable pair-programming feedback.
146
+
147
+ ---
148
+
149
+ ## 5. Handoff Protocol
150
+
151
+ - **Deliverables:** Senior code review assessment report with line-specific recommendations.
152
+ - **Next Subagent:** quality-gatekeeper
153
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Surgical Coding Principles — Enterprise Minimal-Diff Discipline
12
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:** Enforce four behavioral principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) when writing or modifying test automation code. Use when implementing Page Classes, editing test scripts, or changing hub tools to prevent assumption drift and over-engineering.
20
+ - **Activation Scope:** Domain workflows for `08-code-quality` involving `surgical-coding-principles`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT perform broad speculative edits across unrelated files.
28
+ - Do NOT reformat untouched lines of code creating noisy diffs.
29
+ - Do NOT modify code without reading the target file and verifying callers first.
30
+ - **Sibling Skill Boundaries:**
31
+ - lean-code-ladder decides what to build; surgical-coding-principles restricts where and how to modify existing files.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
13
37
  Specialized skill for reducing the three classic LLM coding failure modes — silent assumptions, over-engineering, and out-of-scope edits — across Page Classes, test scripts, and `tools/*.py` maintenance.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. The Four Principles
41
+ ### The Four Principles
18
42
 
19
43
  ```mermaid
20
44
  flowchart LR
@@ -25,7 +49,7 @@ flowchart LR
25
49
 
26
50
  **Tradeoff:** these principles bias toward caution over speed. For trivial, single-line fixes, apply judgment and do not ritualize.
27
51
 
28
- ## 2. Principle 1: Think Before Coding
52
+ ### Principle 1: Think Before Coding
29
53
 
30
54
  - **Rule:** Do not assume; do not hide confusion. Before implementing, state assumptions explicitly and ask when uncertain.
31
55
  - **Enforcement:**
@@ -33,13 +57,13 @@ flowchart LR
33
57
  - If a simpler approach exists, say so before writing code; push back when warranted.
34
58
  - If something is unclear, stop, name what is confusing, and ask. Proceeding on a guess converts one clarification into one full rework cycle.
35
59
 
36
- ## 3. Principle 2: Simplicity First
60
+ ### Principle 2: Simplicity First
37
61
 
38
62
  - **Rule:** Write the minimum code that solves the stated problem. Nothing speculative.
39
63
  - **Forbidden:** features beyond what was asked; abstractions for single-use code; "flexibility" or configurability that was not requested; error handling for impossible scenarios.
40
64
  - **Self-test:** if 200 lines were written and 50 would do, rewrite. Ask: "Would a senior engineer call this overcomplicated?" If yes, simplify before continuing.
41
65
 
42
- ## 4. Principle 3: Surgical Changes
66
+ ### Principle 3: Surgical Changes
43
67
 
44
68
  - **Rule:** Touch only what the request requires. Clean up only the mess your own change created.
45
69
  - **When editing existing code (Page Classes, test scripts, hub tools):**
@@ -49,7 +73,7 @@ flowchart LR
49
73
  - **Orphan rule:** remove imports, variables, or functions that YOUR change made unused; leave pre-existing dead code untouched unless asked.
50
74
  - **The test:** every changed line must trace directly to the user's request.
51
75
 
52
- ## 5. Principle 4: Goal-Driven Execution
76
+ ### Principle 4: Goal-Driven Execution
53
77
 
54
78
  - **Rule:** Transform every task into a verifiable goal with explicit success criteria, then loop until verified.
55
79
  - **Rewrites:** "add validation" becomes "write tests for invalid inputs, then make them pass"; "fix the bug" becomes "write a test that reproduces it, then make it pass" (pair with `test-driven-development`).
@@ -63,7 +87,7 @@ flowchart LR
63
87
 
64
88
  Strong success criteria allow independent looping; weak criteria ("make it work") force constant clarification.
65
89
 
66
- ## 6. Pre-Diff Self-Check
90
+ ### Pre-Diff Self-Check
67
91
 
68
92
  Before handing back any change, verify all boxes:
69
93
 
@@ -75,7 +99,7 @@ Before handing back any change, verify all boxes:
75
99
 
76
100
  These principles are working if diffs shrink, rewrites due to overcomplication disappear, and clarifying questions arrive before implementation instead of after mistakes.
77
101
 
78
- ## 7. Boundary vs Sibling Skills (Do Not Confuse)
102
+ ### Boundary vs Sibling Skills (Do Not Confuse)
79
103
 
80
104
  | Sibling | Owns | Hand-off |
81
105
  |---|---|---|
@@ -83,12 +107,28 @@ These principles are working if diffs shrink, rewrites due to overcomplication d
83
107
  | `code-refactoring-refactor-clean` | Deliberate debt-elimination refactors | A refactor task still obeys surgical scope: diff lines trace to the refactor request |
84
108
  | `lean-code-ladder` | The 7-rung reuse-first decision ladder | Use the ladder to choose the solution; use this skill to keep the diff disciplined |
85
109
 
86
- ## 8. Reference Documentation
110
+ ### Reference Documentation
87
111
 
88
112
  - `python3 tools/verify_all.py --mode hub` — 10 Quality Gates as the verification anchor for Goal-Driven Execution.
89
113
  - `python3 tools/test_impact.py --git-diff` — scope the blast radius of a change before editing.
90
114
  - `python3 tools/infer_linter.py` — confirm no fake-pass assertions were introduced by the change.
91
115
 
92
- ## 9. Attribution
116
+ ### Attribution
93
117
 
94
118
  Adapted from **andrej-karpathy-skills** (https://github.com/multica-ai/andrej-karpathy-skills) — MIT License (declared in repository `plugin.json`), by forrestchang, derived from Andrej Karpathy's published observations on LLM coding pitfalls. Principles re-scoped for enterprise QA automation in Synapse Hub; wording, structure, and examples modified.
119
+
120
+ ---
121
+
122
+ ## 4. Verification Points & DoD
123
+
124
+ 1. Shortest working diff that achieves the requirement.
125
+ 2. Existing comments, docstrings, and unrelated logic preserved intact.
126
+ 3. Callers of modified functions verified to prevent regression.
127
+
128
+ ---
129
+
130
+ ## 5. Handoff Protocol
131
+
132
+ - **Deliverables:** Minimal surgical patch diff and caller impact verification report.
133
+ - **Next Subagent:** pom-crafter
134
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.