@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.
- package/.agents/rules/git-push-protocol.md +2 -2
- package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
- package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
- package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
- package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
- package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
- package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
- package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
- package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
- package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
- package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
- package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
- package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
- package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
- package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
- package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
- package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
- package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
- package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
- package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
- package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
- package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
- package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
- package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
- package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
- package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
- package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
- package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
- package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
- package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
- package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
- package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
- package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
- package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
- package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
- package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
- package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
- package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
- package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
- package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
- package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
- package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
- package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
- package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
- package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
- package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
- package/.cursor/rules/synapse-qa.mdc +20 -7
- package/.cursorrules +19 -5
- package/.windsurfrules +18 -3
- package/AGENTS.md +51 -59
- package/CLAUDE.md +38 -24
- package/LICENSE +5 -5
- package/NOTICE +1 -1
- package/README.en.md +4 -4
- package/README.md +4 -4
- package/agentskills.json +1 -1
- package/docs/ARCHITECTURE.en.md +2 -2
- package/docs/ARCHITECTURE.md +11 -2
- package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
- package/docs/CLI_REFERENCE.en.md +6 -4
- package/docs/CLI_REFERENCE.md +1 -1
- package/docs/CONTRIBUTING.en.md +1 -1
- package/docs/CONTRIBUTING.md +2 -2
- package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
- package/docs/TOOL_CATALOG.md +6 -2
- package/docs/research/agent_skill_training_analysis.md +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills_manifest.json +320 -55
- package/synapse.config.json +1 -1
- package/templates/ai_bridges/CLAUDE.md +29 -26
- package/templates/ai_bridges/copilot-instructions.md +14 -5
- package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
- package/templates/ai_bridges/windsurfrules +14 -3
- package/templates/ui/index.html +2 -2
- package/tools/TOOLS_RUNBOOK.md +1 -1
- package/tools/TOOL_CATALOG.json +63 -3
- package/tools/__init__.py +1 -1
- package/tools/api_fuzzer.py +447 -132
- package/tools/author_integrity.py +121 -11
- package/tools/benchmark_swarm_context.py +130 -22
- package/tools/break_ui_generator.py +233 -0
- package/tools/browser_helpers.js +2 -2
- package/tools/check_version_sync.py +18 -50
- package/tools/cli.py +110 -19
- package/tools/core/bm25_retriever.py +218 -0
- package/tools/core/i18n.py +5 -5
- package/tools/core/provider_usage_adapter.py +383 -0
- package/tools/core/token_estimator.py +81 -15
- package/tools/count_tokens.py +7 -2
- package/tools/coverage_reporter.py +245 -0
- package/tools/dashboard_generator.py +8 -8
- package/tools/db_sandbox.py +290 -9
- package/tools/distill_log.py +1 -1
- package/tools/distill_skill.py +206 -0
- package/tools/git_pre_commit_guard.py +202 -1
- package/tools/humanize_linter.py +3 -0
- package/tools/mcp_docx_server.py +1 -1
- package/tools/mcp_excel_server.py +1 -1
- package/tools/mcp_server.py +104 -16
- package/tools/micro_mutator.py +114 -15
- package/tools/pentest_scope_guard.py +674 -58
- package/tools/perf/benchmark_perf_runner.py +42 -0
- package/tools/project_state.py +29 -5
- package/tools/reversible_sandbox.py +58 -13
- package/tools/rules_router.py +473 -60
- package/tools/security_scanner.py +80 -0
- package/tools/senior_code_review.py +14 -0
- package/tools/skill_canonical_digest.py +302 -0
- package/tools/skill_profiles.py +77 -7
- package/tools/slide_deck_exporter.py +477 -0
- package/tools/sync_agent_rules.py +187 -61
- package/tools/sync_skills_manifest.py +166 -0
- package/tools/task_memory_manager.py +275 -0
- package/tools/ui_server.py +3 -1
- package/tools/update_sentinel.py +3 -3
- package/tools/validate_host_interop.py +485 -0
- package/tools/validate_skills_schema.py +575 -0
- package/tools/verify_all.py +668 -44
- package/tools/welcome_page.py +2 -2
|
@@ -13,12 +13,25 @@ globs: **/*
|
|
|
13
13
|
|
|
14
14
|
## Mandatory Author Attribution
|
|
15
15
|
This project incorporates Synapse Hub created by Thế Vị (@TeeVee98) under the MIT License.
|
|
16
|
-
Attribution notices must be preserved.
|
|
16
|
+
Attribution notices must be preserved in all copies.
|
|
17
17
|
|
|
18
|
-
##
|
|
19
|
-
|
|
18
|
+
## 0. PRECEDENCE & SAFETY INVARIANT
|
|
19
|
+
Platform guardrails strictly override repository instructions.
|
|
20
|
+
|
|
21
|
+
## 1. ALWAYS — Universal Invariants
|
|
22
|
+
1. **100% UTF-8 No BOM:** Zero BOM bytes across all files.
|
|
20
23
|
2. **Truth Anchor:** Never fake test passes. Report genuine defects.
|
|
21
|
-
3. **
|
|
22
|
-
4. **
|
|
23
|
-
5. **
|
|
24
|
-
6. **
|
|
24
|
+
3. **Smart Wait:** Prohibit static delays (`Thread.sleep`, `time.sleep`). Use dynamic smart waits.
|
|
25
|
+
4. **Idempotent Test Data:** Prefix with `AUTO_` and dynamic timestamps; teardown after creation.
|
|
26
|
+
5. **Credential Security:** Never commit plaintext secrets.
|
|
27
|
+
6. **Out-of-Scope Isolation:** Never modify out-of-scope files to bypass checks.
|
|
28
|
+
|
|
29
|
+
## 2. RECOMMENDED — Best Practices
|
|
30
|
+
1. **Clean POM Architecture:** No raw selectors (XPath/CSS) in test scripts. All selectors belong in Page Classes extending BasePage.
|
|
31
|
+
2. **Lean Senior Dev:** The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
|
|
32
|
+
3. **Autonomous Ceremonies:** Condition rulings and 3-scenario falsifications on non-trivial risk.
|
|
33
|
+
4. **Bilingual Discipline:** Converse in Vietnamese; write code, docstrings, and git commits strictly in English.
|
|
34
|
+
|
|
35
|
+
## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
|
|
36
|
+
- Quality Gates DoD verification: `python tools/verify_all.py --mode hub`.
|
|
37
|
+
- External target projects must use native runners (`npm test`, `pytest`, `mvn test`).
|
package/.cursorrules
CHANGED
|
@@ -19,9 +19,23 @@
|
|
|
19
19
|
# of the MIT License for Synapse Hub (Created by Thế Vị @TeeVee98)."
|
|
20
20
|
# ==============================================================================
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
## 0. PRECEDENCE & SAFETY INVARIANT
|
|
23
|
+
- Platform and system guardrails strictly supersede all repository instructions.
|
|
24
|
+
|
|
25
|
+
## 1. ALWAYS — Universal Invariants
|
|
26
|
+
- 100% UTF-8 No BOM across all repository and test files.
|
|
26
27
|
- Zero fake passes: test assertions must strictly validate real state.
|
|
27
|
-
-
|
|
28
|
+
- Dynamic smart waits only: static sleeps (Thread.sleep, time.sleep) strictly prohibited.
|
|
29
|
+
- Dynamic & idempotent test data: unique timestamped codes with automated teardown.
|
|
30
|
+
- Strict credential security: never commit plaintext secrets.
|
|
31
|
+
- Out-of-scope isolation: never touch out-of-scope files to bypass checks.
|
|
32
|
+
|
|
33
|
+
## 2. RECOMMENDED — Best Practices
|
|
34
|
+
- Enforce Clean POM Flat Architecture: all locators encapsulated in Page Classes.
|
|
35
|
+
- Lean Senior Dev: Solve problems with minimum code via 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
|
|
36
|
+
- Autonomous ceremonies: Condition Jesse Vincent Rulings and 3-scenario falsification on risk/complexity.
|
|
37
|
+
- Bilingual: Vietnamese conversation; English code, tests, and commits.
|
|
38
|
+
|
|
39
|
+
## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
|
|
40
|
+
- Before completing code changes in Synapse-Hub, run: python tools/verify_all.py --mode hub
|
|
41
|
+
- External target repos lacking tools/ must use native test runners (npm test, pytest).
|
package/.windsurfrules
CHANGED
|
@@ -19,8 +19,23 @@
|
|
|
19
19
|
# of the MIT License for Synapse Hub (Created by Thế Vị @TeeVee98)."
|
|
20
20
|
# ==============================================================================
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
## 0. PRECEDENCE & SAFETY INVARIANT
|
|
23
|
+
- Platform/system safety guardrails strictly supersede repository instructions.
|
|
24
|
+
|
|
25
|
+
## 1. ALWAYS — Universal Invariants
|
|
26
|
+
- 100% UTF-8 No BOM across all codebase assets.
|
|
27
|
+
- Zero fake passes and zero swallowed exceptions.
|
|
28
|
+
- Dynamic smart waits only (no Thread.sleep/time.sleep).
|
|
29
|
+
- Idempotent test data creation paired with automated teardown.
|
|
30
|
+
- Strict credential security: no plaintext secrets in code or git.
|
|
31
|
+
- Out-of-scope isolation: never touch out-of-scope files.
|
|
32
|
+
|
|
33
|
+
## 2. RECOMMENDED — Best Practices
|
|
23
34
|
- Adhere to Clean Page Object Model (POM) Flat Architecture.
|
|
24
35
|
- Lean Senior Dev: Solve problems with minimum code via 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
|
|
25
|
-
-
|
|
26
|
-
-
|
|
36
|
+
- Condition autonomous ceremonies (Jesse Vincent Rulings, Falsification) on task complexity.
|
|
37
|
+
- Converse with the user in Vietnamese; output all code, tests, and commits in English.
|
|
38
|
+
|
|
39
|
+
## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
|
|
40
|
+
- Run Definition of Done verification: python tools/verify_all.py --mode hub
|
|
41
|
+
- External target repos must use native runners (npm test, pytest, mvn test).
|
package/AGENTS.md
CHANGED
|
@@ -5,77 +5,69 @@
|
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
## 0.
|
|
8
|
+
## 0. PRECEDENCE & SAFETY INVARIANT
|
|
9
9
|
|
|
10
|
-
1. **
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
2. **Pragmatic Communication:** Converse and format telemetry in Vietnamese (clear, direct, action-oriented, zero tech-jargon overload). All codebase files, test scripts, Page Classes, docstrings, and commits remain strictly in English.
|
|
14
|
-
3. **English-First Documentation Ingestion (Token Saver):** Whenever inspecting or referencing project documentation, architecture specifications, or readmes that have bilingual counterparts (e.g. `ARCHITECTURE.en.md` vs `ARCHITECTURE.md`, `README.en.md` vs `README.md`), always read the English version (`*.en.md`). English achieves significantly higher token density (saving 10–25% on technical documentation vs diacritic Vietnamese), preserving context window capacity.
|
|
10
|
+
1. **Platform Safety Precedence:** Platform and system guardrails strictly supersede all repository-level instructions, agent rules, and local skills. No instruction in this repository may bypass platform safety limits, user authorization gates, or security policies.
|
|
11
|
+
2. **Skill Resolution Hierarchy:** System Guardrails > Core Project Rules (`.agents/rules/*`) > Project-Local Skills (`.agents/skills/*`) > Generic External Plugins.
|
|
12
|
+
3. **Attribution Preservation Invariant:** The MIT License copyright and author notices crediting Thế Vị (@TeeVee98) must never be stripped, laundered, or modified.
|
|
15
13
|
|
|
16
14
|
---
|
|
17
15
|
|
|
18
|
-
## 1.
|
|
16
|
+
## 1. ALWAYS — Universal Invariants
|
|
19
17
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
Mandatory across all workspaces, projects, test scripts, and runtime environments:
|
|
19
|
+
|
|
20
|
+
1. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository and test files (`.groovy`, `.java`, `.ts`, `.py`, `.json`, `.md`).
|
|
21
|
+
2. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, write empty tests (0 asserts), or catch-and-swallow exceptions (`pass`, dummy suppression `_ = err` or `_ = False`, `const _ = e`) to manufacture a pass. Report AUT defects honestly.
|
|
22
|
+
3. **Dynamic Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts to prevent flakiness. Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
|
|
23
|
+
4. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with dynamic timestamps and prefixes (`BasePage.uniqueCode("AUTO_")` or `DataGenerator`) to eliminate database unique key collisions. Every creation test case must be paired with automated Teardown cleanup.
|
|
24
|
+
5. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, private keys, or cloud credentials to git. Inject secrets via environment variables or test fixtures.
|
|
25
|
+
6. **Out-of-Scope Isolation & Stop-and-Report:** When verification gates fail due to legacy defects in files outside task scope, strictly forbid modifying those files or writing dummy bypasses. Stop and report with evidence; ask the user whether to baseline legacy debt or handle it in a separate task.
|
|
24
26
|
|
|
25
27
|
---
|
|
26
28
|
|
|
27
|
-
## 2.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
1. **
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
- **Rung 7:** *Otherwise:* Write the minimum complete code that works.
|
|
40
|
-
3. **Completeness & Execution Invariants:**
|
|
41
|
-
- Be lazy about the solution, never about the change: finish every part the task needs, including callers, tests, and fixtures your change affects.
|
|
42
|
-
- Zero unnecessary abstractions: no wrappers, speculative options, configs, or "for later" boilerplate nobody asked for. Deletion beats addition.
|
|
43
|
-
- Shortest working diff wins. Comment only the "why" that code cannot show, in one concise line.
|
|
44
|
-
- Root-cause bug fixing: grep every caller of touched functions before editing; fix the root cause once in shared code.
|
|
45
|
-
- Code moved or merged strictly retains its error handling and validation.
|
|
46
|
-
- Between options of equal size, choose the one that handles edge cases cleanly.
|
|
47
|
-
- Lazy code without checks is unfinished: non-trivial logic (branch, loop, parser, auth, or money path) must leave one small test or self-check assertion before handoff. Trivial changes need none.
|
|
29
|
+
## 2. RECOMMENDED — Best Practices
|
|
30
|
+
|
|
31
|
+
Applicable to QA engineering workflows, test development, and agent pair-programming:
|
|
32
|
+
|
|
33
|
+
1. **Clean Page Object Model (POM) Flat Architecture:**
|
|
34
|
+
- Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
|
|
35
|
+
- Strictly forbidden: raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
|
|
36
|
+
- All locators and DOM operations belong in Page Classes extending `BasePage`. Keep inheritance shallow (flat, max 1 level from `BasePage`).
|
|
37
|
+
2. **Lean Senior Dev Protocol (7-Rung Ladder & YAGNI):**
|
|
38
|
+
- The best code is the code never written. Solve the whole problem with the least new code.
|
|
39
|
+
- Stop at the first rung that fully works: 1. Need to exist? (YAGNI) -> 2. Already in codebase? -> 3. Language stdlib? -> 4. Platform/framework native? -> 5. Installed dependency? -> 6. One clear line? -> 7. Minimum complete code.
|
|
40
|
+
- Zero unnecessary abstractions: no wrappers, speculative options, or boilerplate nobody asked for.
|
|
48
41
|
- Pragmatic technical debt: Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
42
|
+
3. **Risk-Conditioned Autonomous Ceremonies:**
|
|
43
|
+
- **Jesse Vincent Rulings (`Ruling:`):** Mandatory for architectural forks, breaking changes, or non-trivial tradeoffs (`Ruling: <decision> — <why> — <cost if wrong>`). Subagents omit rulings for trivial typo, documentation, or minor locator fixes.
|
|
44
|
+
- **Addy Osmani Falsification (3 Scenarios):** Mandatory before certifying core test cases or complex locators (propose 3 realistic scenarios where code breaks while tests pass). Omit for trivial fixes (< 15 LOC).
|
|
45
|
+
4. **Bilingual Communication & Lean Telemetry:**
|
|
46
|
+
- Emit single-line status badge at top of responses: `> 🛡️ **Synapse Hub Active:** Clean POM / Flat Architecture` (strictly prohibited from containing `[OK]`).
|
|
47
|
+
- Converse and format telemetry in Vietnamese (clear, direct, action-oriented, zero tech-jargon overload).
|
|
48
|
+
- Codebase files, test scripts, Page Classes, docstrings, and commits remain strictly in English.
|
|
49
|
+
5. **English-First Documentation Ingestion (Token Saver):**
|
|
50
|
+
- Whenever inspecting documentation with bilingual counterparts (e.g. `ARCHITECTURE.en.md` vs `ARCHITECTURE.md`), always read the English version (`*.en.md`) to save 10–25% on technical documentation.
|
|
52
51
|
|
|
53
52
|
---
|
|
54
53
|
|
|
55
|
-
## 3.
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
- Security
|
|
68
|
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
-
|
|
72
|
-
- Querying / Storing verified PageClass library -> Run `tools/skill_vault.py`.
|
|
73
|
-
- Vague requirements / story ambiguity -> Autonomously run `tools/interview_story.py`.
|
|
74
|
-
- Optimizing assertions against surviving mutants -> Run `tools/textgrad_mutation_optimizer.py`.
|
|
75
|
-
- User asks to push / release hub ("push lên", "push hub") -> Autonomously bump version based on changes via `tools/bump_version.py <patch|minor|major>` then run `tools/hub_publisher.py` (Push main + Tag + Release + Packages + NPM).
|
|
76
|
-
- Task progress & compaction anchoring -> Autonomously run `tools/project_state.py`.
|
|
77
|
-
- Before completing code tasks -> Autonomously run `tools/verify_all.py` (10 Quality Gates DoD). For quick fixes (< 15 lines of code), apply Fast-Track mode; for external target repos lacking `tools/`, gracefully fallback to native test runners (`npm test`, `pytest`, `mvn test`) per `.agents/rules/stack-auto-router.md` and `.agents/rules/systematic-debugging.md`.
|
|
78
|
-
- Context-aware stack routing -> Strictly adhere to `.agents/rules/stack-auto-router.md` (Web/Mobile/Perf/Security scope) and 5-layer pentest safety gate (`.agents/rules/security_testing_rules.md`).
|
|
54
|
+
## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
|
|
55
|
+
|
|
56
|
+
⚠️ **CRITICAL SCOPE BOUNDARY:** The following CLI tools, verification harnesses, and automation scripts exist **ONLY** within the `Synapse-Hub` repository checkout. Target client projects and external repositories **DO NOT** possess these scripts and must use their own native test runners (`npm test`, `pytest`, `mvn test`):
|
|
57
|
+
|
|
58
|
+
1. **Hub Operational Tools (Synapse-Hub Checkout Only):**
|
|
59
|
+
- Quality Gates DoD: `python tools/verify_all.py --mode hub`
|
|
60
|
+
- Release Publisher: `python tools/hub_publisher.py -y`
|
|
61
|
+
- Multi-Bridge Synchronizer: `python tools/sync_agent_rules.py`
|
|
62
|
+
- Mutation Testing Engine: `python tools/micro_mutator.py`
|
|
63
|
+
- Health Audit & Analysis: `python tools/analyze_project.py`
|
|
64
|
+
- Project State & Diagnostic: `python tools/project_state.py`
|
|
65
|
+
- Dynamic Auto-Healing: `python tools/auto_heal.py` / `python tools/pinpoint_failure.py`
|
|
66
|
+
- Security Scanner: `python tools/skillspector.py` / `python tools/pentest_scope_guard.py`
|
|
67
|
+
2. **External Target Projects Fallback Invariant:**
|
|
68
|
+
- When mounted in a non-Hub repository, agents must NEVER invoke `tools/verify_all.py` or Synapse internal scripts.
|
|
69
|
+
- Use target project native commands defined in `package.json`, `pom.xml`, or `pyproject.toml` (`npm test`, `pytest`, `mvn test`).
|
|
70
|
+
- Bridge templates generated in `templates/ai_bridges/*` for client projects must never reference `tools/` scripts.
|
|
79
71
|
|
|
80
72
|
---
|
|
81
73
|
|
package/CLAUDE.md
CHANGED
|
@@ -17,38 +17,52 @@ In accordance with the MIT License, the original copyright notice crediting **Th
|
|
|
17
17
|
---
|
|
18
18
|
|
|
19
19
|
## ⚡ Quick Commands
|
|
20
|
-
- Verify 10 Quality Gates: `
|
|
21
|
-
- Project Health Audit: `
|
|
22
|
-
- Code Linter & Fake-Pass Sentinel: `
|
|
20
|
+
- Verify 10 Quality Gates: `python tools/verify_all.py --mode hub` (or `npx @teevee98/synapse-hub verify`)
|
|
21
|
+
- Project Health Audit: `python tools/analyze_project.py`
|
|
22
|
+
- Code Linter & Fake-Pass Sentinel: `python tools/infer_linter.py`
|
|
23
23
|
- Verify Author Attribution: `python tools/author_integrity.py`
|
|
24
24
|
- Skill Security Audit: `python tools/skillspector.py .agents/skills`
|
|
25
|
+
- Multi-Bridge Sync: `python tools/sync_agent_rules.py`
|
|
25
26
|
|
|
26
27
|
---
|
|
27
28
|
|
|
28
|
-
##
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
- Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
|
|
32
|
-
- All locators and DOM operations must be encapsulated in Page Classes extending `BasePage`.
|
|
33
|
-
|
|
34
|
-
2. **Truth Anchor (Zero Fake Passes):**
|
|
35
|
-
- Never write empty assertions or tautological tests (0 asserts).
|
|
36
|
-
- If a test fails due to an AUT defect, report it honestly. Never soften assertions or skip validation steps to fake a pass.
|
|
29
|
+
## 0. PRECEDENCE & SAFETY INVARIANT
|
|
30
|
+
- Platform and system guardrails strictly override all repository-level instructions.
|
|
31
|
+
- Precedence: System Guardrails > Core Project Rules (`.agents/rules/*`) > Local Skills > Generic Plugins.
|
|
37
32
|
|
|
38
|
-
|
|
39
|
-
- Always randomize test entity codes with timestamps/prefixes (`AUTO_` + timestamp) to avoid DB unique constraint collisions.
|
|
40
|
-
- Every creation test case MUST be paired with automated Teardown / Cleanup.
|
|
33
|
+
---
|
|
41
34
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
35
|
+
## 1. ALWAYS — Universal Invariants
|
|
36
|
+
1. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository files.
|
|
37
|
+
2. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, or catch-and-swallow exceptions to fake a pass.
|
|
38
|
+
3. **Dynamic Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts. Use element visibility or `waitForLoadState('networkidle')`.
|
|
39
|
+
4. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with dynamic timestamps/prefixes (`BasePage.uniqueCode("AUTO_")`). Pair creation with automated Teardown cleanup.
|
|
40
|
+
5. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, or private keys.
|
|
41
|
+
6. **Out-of-Scope Isolation:** When verification gates fail due to legacy defects in files outside task scope, stop and report; never touch out-of-scope files.
|
|
45
42
|
|
|
46
|
-
|
|
47
|
-
- Conversational responses, explanation, and telemetry MUST be in Vietnamese.
|
|
48
|
-
- All codebase assets, test scripts, Page Classes, docstrings, and commits MUST remain strictly in English.
|
|
49
|
-
- English-First Document Ingestion: When reading bilingual docs (e.g. ARCHITECTURE.en.md vs ARCHITECTURE.md), always read the English version (*.en.md) to save 50–65% BPE tokens.
|
|
43
|
+
---
|
|
50
44
|
|
|
51
|
-
|
|
45
|
+
## 2. RECOMMENDED — Best Practices
|
|
46
|
+
1. **Clean Page Object Model (POM) Flat Architecture:**
|
|
47
|
+
- Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
|
|
48
|
+
- Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
|
|
49
|
+
- All locators and DOM operations belong in Page Classes extending `BasePage`. Keep inheritance flat (max 1 level).
|
|
50
|
+
2. **Lean Senior Dev Protocol (7-Rung Ladder & YAGNI):**
|
|
52
51
|
- The best code is the code never written. Solve the whole problem with the least new code.
|
|
53
52
|
- Descend the 7-rung ladder: 1. Need to exist? 2. Already in codebase? 3. Standard library? 4. Platform native? 5. Installed dependency? 6. One clear line? 7. Minimum working code.
|
|
54
|
-
-
|
|
53
|
+
- Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
|
|
54
|
+
3. **Risk-Conditioned Autonomous Ceremonies:**
|
|
55
|
+
- Jesse Vincent Rulings (`Ruling:`): Mandatory for architectural forks, breaking changes, or non-trivial tradeoffs. Omit for trivial doc/typo fixes.
|
|
56
|
+
- Addy Osmani Falsification (3 failure scenarios): Mandatory before certifying core test cases or complex locators.
|
|
57
|
+
4. **Bilingual Communication & English-First Ingestion:**
|
|
58
|
+
- Conversational responses, explanation, and telemetry in Vietnamese.
|
|
59
|
+
- Codebase files, test scripts, Page Classes, docstrings, and commits strictly in English.
|
|
60
|
+
- Read English versions (`*.en.md`) when bilingual docs exist to preserve tokens.
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
|
|
64
|
+
⚠️ The following CLI tools exist ONLY in the Synapse-Hub repository checkout:
|
|
65
|
+
- Quality Gates DoD: `python tools/verify_all.py --mode hub`
|
|
66
|
+
- Release Publisher: `python tools/hub_publisher.py -y`
|
|
67
|
+
- Rule Synchronizer: `python tools/sync_agent_rules.py`
|
|
68
|
+
- Target external projects must use native runners (`npm test`, `pytest`, `mvn test`).
|
package/LICENSE
CHANGED
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
## 🇻🇳 Phiên Bản Tiếng Việt (Tham Khảo & Giải Thích Pháp Lý)
|
|
8
8
|
|
|
9
|
-
Bản quyền (c) 2026 Thế Vị (@
|
|
10
|
-
Kho mã nguồn gốc: https://github.com/
|
|
9
|
+
Bản quyền (c) 2026 Thế Vị (@TeeVee98). Toàn quyền bảo lưu.
|
|
10
|
+
Kho mã nguồn gốc: https://github.com/TeeVee98/Synapse-Hub
|
|
11
11
|
|
|
12
12
|
*(Lưu ý: Phần tiếng Việt dưới đây là bản giải thích tham khảo nhằm giúp cộng đồng nắm bắt rõ quyền và nghĩa vụ; văn bản tiếng Anh phía dưới là văn bản pháp lý chính thức có hiệu lực của Giấy phép MIT).*
|
|
13
13
|
|
|
@@ -18,7 +18,7 @@ Theo Giấy phép MIT, bạn được cấp quyền miễn phí, không giới h
|
|
|
18
18
|
- **Hợp nhất & Đóng gói:** Tích hợp Synapse Hub vào các bộ kiểm thử nội bộ hoặc giải pháp của bạn.
|
|
19
19
|
|
|
20
20
|
### 2. Nghĩa vụ bắt buộc (Điều kiện tiên quyết)
|
|
21
|
-
- **Ghi nhận nguồn tác giả gốc:** Bạn **BẮT BUỘC** phải giữ nguyên thông báo bản quyền ghi nhận tác giả **Thế Vị (@
|
|
21
|
+
- **Ghi nhận nguồn tác giả gốc:** Bạn **BẮT BUỘC** phải giữ nguyên thông báo bản quyền ghi nhận tác giả **Thế Vị (@TeeVee98)** cùng liên kết mã nguồn gốc `https://github.com/TeeVee98/Synapse-Hub` trong toàn bộ các bản sao hoặc các phần quan trọng của phần mềm.
|
|
22
22
|
- Nghiêm cấm hành vi xóa bỏ bản quyền hoặc mạo danh quyền tác giả.
|
|
23
23
|
|
|
24
24
|
### 3. Tuyên bố miễn trừ trách nhiệm
|
|
@@ -30,8 +30,8 @@ Phần mềm được cung cấp theo nguyên trạng ("AS IS"), không có bấ
|
|
|
30
30
|
|
|
31
31
|
MIT License
|
|
32
32
|
|
|
33
|
-
Copyright (c) 2026 Thế Vị (@
|
|
34
|
-
Original Repository: https://github.com/
|
|
33
|
+
Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
|
|
34
|
+
Original Repository: https://github.com/TeeVee98/Synapse-Hub
|
|
35
35
|
|
|
36
36
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
37
37
|
of this software and associated documentation files (the "Software"), to deal
|
package/NOTICE
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
Synapse Hub
|
|
2
|
-
Copyright (c) 2026 Thế Vị (@
|
|
2
|
+
Copyright (c) 2026 Thế Vị (@TeeVee98). Distributed under the MIT License.
|
|
3
3
|
|
|
4
4
|
This software includes threat vector taxonomy, static rule categories, and security concepts
|
|
5
5
|
inspired by:
|
package/README.en.md
CHANGED
|
@@ -6,13 +6,13 @@
|
|
|
6
6
|
|
|
7
7
|
> **Core Mission:** A standalone linter and guardrail engine (zero external dependencies for core engine & DoD gates) safeguarding automated test suites when AI writes code — Automatically catching "fake-pass" tests (0 assertions, tautologies), eliminating fixed sleeps, compressing 95% of CI/CD log noise, and enforcing Clean POM architecture.
|
|
8
8
|
> **Author:** Thế Vị ([@TeeVee98](https://github.com/TeeVee98)) | **License:** MIT License
|
|
9
|
-
> **Version:** `v4.1
|
|
9
|
+
> **Version:** `v4.2.1` | **Scale:** 53 Standardized QA Skills, 9 Specialized AI Agents, 10 DoD Quality Gates.
|
|
10
10
|
|
|
11
11
|
[](https://www.npmjs.com/package/@teevee98/synapse-hub)
|
|
12
12
|
[](https://nodejs.org)
|
|
13
13
|
[](https://python.org)
|
|
14
14
|
[](docs/QUALITY_GATES.en.md)
|
|
15
|
-
[](#)
|
|
16
16
|
[](https://github.com/TeeVee98/Synapse-Hub/blob/main/LICENSE)
|
|
17
17
|
[](#)
|
|
18
18
|
|
|
@@ -86,7 +86,7 @@ npx @teevee98/synapse-hub verify
|
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
> 💡 **Tip:** Install globally to invoke `synapse-hub <command>` directly without `npx`:
|
|
89
|
-
> `npm install -g @teevee98/synapse-hub` (or via Python: `pip install
|
|
89
|
+
> `npm install -g @teevee98/synapse-hub` (or via Python: `pip install synapse-hub`)
|
|
90
90
|
|
|
91
91
|
> 📦 **Enterprise Reference Test Suites:** Inspect working sample projects adhering to Clean POM & Guardrails in [`examples/`](examples/):
|
|
92
92
|
> [🎭 Playwright TS](examples/playwright-crm-suite) • [🌲 Cypress E2E](examples/cypress-ecommerce-suite) • [🐍 Pytest API](examples/pytest-api-suite) • [☕ Katalon Studio](examples/katalon-suite) • [🌐 Selenium Java](examples/selenium-suite)
|
|
@@ -154,7 +154,7 @@ Every test code change must satisfy all 10 Quality Gates before pull request mer
|
|
|
154
154
|
# Pre-commit hook (.pre-commit-config.yaml):
|
|
155
155
|
repos:
|
|
156
156
|
- repo: https://github.com/TeeVee98/Synapse-Hub
|
|
157
|
-
rev: v4.1
|
|
157
|
+
rev: v4.2.1
|
|
158
158
|
hooks:
|
|
159
159
|
- id: synapse-lint
|
|
160
160
|
- id: synapse-verify
|
package/README.md
CHANGED
|
@@ -6,13 +6,13 @@
|
|
|
6
6
|
|
|
7
7
|
> **Định vị cốt lõi:** Bộ Linter & Guardrails độc lập (zero external dependencies cho core engine & DoD gates) bảo vệ độ tin cậy của test suite khi AI viết code — Tự động bắt test "pass ảo" (0 assert, tautology), loại bỏ hoàn toàn sleep cố định, nén 95% log CI/CD, và chuẩn hóa cấu trúc Clean POM.
|
|
8
8
|
> **Tác giả:** Thế Vị ([@TeeVee98](https://github.com/TeeVee98)) | **Giấy phép:** MIT License
|
|
9
|
-
> **Phiên bản:** `v4.1
|
|
9
|
+
> **Phiên bản:** `v4.2.1` | **Quy mô:** 53 Kỹ năng QA, 9 Vai trò AI Agent, 10 Cổng kiểm định DoD.
|
|
10
10
|
|
|
11
11
|
[](https://www.npmjs.com/package/@teevee98/synapse-hub)
|
|
12
12
|
[](https://nodejs.org)
|
|
13
13
|
[](https://python.org)
|
|
14
14
|
[](docs/QUALITY_GATES.md)
|
|
15
|
-
[](#)
|
|
16
16
|
[](https://github.com/TeeVee98/Synapse-Hub/blob/main/LICENSE)
|
|
17
17
|
[](#)
|
|
18
18
|
|
|
@@ -86,7 +86,7 @@ npx @teevee98/synapse-hub verify
|
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
> 💡 **Mẹo:** Cài đặt toàn cục để gõ trực tiếp `synapse-hub <lệnh>` không cần tiền tố `npx`:
|
|
89
|
-
> `npm install -g @teevee98/synapse-hub` (hoặc qua Python: `pip install
|
|
89
|
+
> `npm install -g @teevee98/synapse-hub` (hoặc qua Python: `pip install synapse-hub`)
|
|
90
90
|
|
|
91
91
|
> 📦 **Kho Dự Án Mẫu Doanh Nghiệp (Reference Suites):** Xem các dự án mẫu đã chuẩn hóa Clean POM & Guardrails tại [`examples/`](examples/):
|
|
92
92
|
> [🎭 Playwright TS](examples/playwright-crm-suite) • [🌲 Cypress E2E](examples/cypress-ecommerce-suite) • [🐍 Pytest API](examples/pytest-api-suite) • [☕ Katalon Studio](examples/katalon-suite) • [🌐 Selenium Java](examples/selenium-suite)
|
|
@@ -154,7 +154,7 @@ Mọi thay đổi mã nguồn kiểm thử đều được kiểm chứng qua 10
|
|
|
154
154
|
# Pre-commit hook (.pre-commit-config.yaml):
|
|
155
155
|
repos:
|
|
156
156
|
- repo: https://github.com/TeeVee98/Synapse-Hub
|
|
157
|
-
rev: v4.1
|
|
157
|
+
rev: v4.2.1
|
|
158
158
|
hooks:
|
|
159
159
|
- id: synapse-lint
|
|
160
160
|
- id: synapse-verify
|
package/agentskills.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agentskills.io/schema/v1.json",
|
|
3
3
|
"name": "Synapse-Hub",
|
|
4
|
-
"version": "4.1
|
|
4
|
+
"version": "4.2.1",
|
|
5
5
|
"description": "Enterprise QA & Test Automation AI Skills Ecosystem — 53 skills organised across 11 Domain Packages adhering to Clean POM Flat Architecture.",
|
|
6
6
|
"author": "Thế Vị (@TeeVee98)",
|
|
7
7
|
"repository": "https://github.com/TeeVee98/Synapse-Hub",
|
package/docs/ARCHITECTURE.en.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[🇻🇳 Tiếng Việt](ARCHITECTURE.md) | [🇬🇧 English Edition](ARCHITECTURE.en.md)
|
|
4
4
|
|
|
5
5
|
> **Scope:** Enterprise Multi-Agent QA Hub
|
|
6
|
-
> **Version:** `4.1
|
|
6
|
+
> **Version:** `4.2.1` | **Status:** Active / Production Standard
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -191,7 +191,7 @@ To maintain strict engineering rigor (**Truth Anchor**), Synapse Hub discloses a
|
|
|
191
191
|
1. **Static Heuristic Mutation Testing vs Runtime Mutation Testing:**
|
|
192
192
|
`tools/micro_mutator.py` in static mode performs fast heuristic assertion reachability analysis (~0.1s) to detect unasserted branches and weak assertions. This is a lexical reachability and dataflow heuristic, **not** a compiler-grade runtime mutation testing engine (such as Stryker or mutmut). To avoid inflated assertion scores and obtain ground-truth mutation kill rates, execute in Dynamic mode (`--test-cmd`) against real test runners.
|
|
193
193
|
2. **Empirical Benchmarks (Self-Reported Baseline):**
|
|
194
|
-
The metrics (
|
|
194
|
+
The metrics (45/45 challenges resolved across 11 domains, 93.8 tokens/bug) reflect author-measured internal baselines on curated challenges (`benchmarks/qa_eval`) rather than independent third-party double-blind audits. Metrics may vary on real-world enterprise suites depending on architectural complexity and test coverage.
|
|
195
195
|
3. **Hub-Spoke Version Pinning (Blast-Radius Isolation):**
|
|
196
196
|
When mounting or referencing Synapse Hub in downstream Spoke projects, downstream repositories should pin a specific Git Submodule commit or release tag (`git checkout v4.1.1`) rather than tracking unpinned `main` HEAD, preventing upstream Hub changes from unexpectedly breaking downstream CI/CD pipelines.
|
|
197
197
|
4. **Supported Runners:**
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
[🇻🇳 Tiếng Việt](ARCHITECTURE.md) | [🇬🇧 English Edition](ARCHITECTURE.en.md)
|
|
4
4
|
|
|
5
5
|
> **Phạm vi:** Enterprise Multi-Agent QA Hub
|
|
6
|
-
> **Version:** `4.1
|
|
6
|
+
> **Version:** `4.2.1` | **Trạng thái:** Hoạt động / Tiêu chuẩn Sản xuất
|
|
7
7
|
> **Tác giả:** Thế Vị (@TeeVee98) | **Giấy phép:** MIT License
|
|
8
8
|
|
|
9
9
|
---
|
|
@@ -192,7 +192,7 @@ flowchart TD
|
|
|
192
192
|
1. **Quét Nhạy Cảm Assert Tĩnh (Heuristic) vs Đột Biến Runtime:**
|
|
193
193
|
`tools/micro_mutator.py` ở chế độ tĩnh sử dụng phân tích độ nhạy assert heuristic (~0.1s) để phát hiện nhanh nhánh rẽ thiếu assert hoặc assertion lỏng lẻo. Đây là cơ chế ước tính độ phủ ngữ nghĩa (reachability & dataflow heuristic), **không phải** công cụ mutation testing thực thi mã cấp trình biên dịch (như Stryker hay mutmut). Để có điểm mutation thực tế không bị thổi phồng, cần chạy chế độ Dynamic (`--test-cmd`) để thực thi test suite trực tiếp trên từng mutant.
|
|
194
194
|
2. **Kết Quả Benchmark Thực Nghiệm (Self-Reported Baseline):**
|
|
195
|
-
Các chỉ số
|
|
195
|
+
Các chỉ số 45/45 bài toán trên 11 nhóm miền lỗi (100.0%) và 93.8 token / lỗi là kết quả đo lường nội bộ do tác giả thực hiện trên bộ benchmark curated nội bộ (`benchmarks/qa_eval`), chưa qua kiểm chứng độc lập của bên thứ ba (third-party double-blind benchmark). Khi áp dụng vào dự án thực tế với kiến trúc phức tạp, các chỉ số có thể thay đổi tùy thuộc vào độ bao phủ của bộ test.
|
|
196
196
|
3. **Cơ Chế Pin Version Hub-Spoke (Chống Lỗi Lan Truyền):**
|
|
197
197
|
Khi tích hợp Synapse Hub vào các dự án Spoke, khuyến nghị bắt buộc pin phiên bản qua Git Submodule commit cụ thể hoặc git release tag (`git checkout v4.1.1`), tránh kéo trực tiếp nhánh `main` tự động để không làm ảnh hưởng pipeline của các Spoke khi Hub có cập nhật chưa kiểm duyệt.
|
|
198
198
|
4. **Test Framework Được Hỗ Trợ Tốt Nhất:**
|
|
@@ -201,3 +201,12 @@ flowchart TD
|
|
|
201
201
|
- Node.js >= 18.0.0 (khuyên dùng Node 20 hoặc 22 LTS).
|
|
202
202
|
- Python >= 3.10 (đã kiểm thử đầy đủ trên 3.10, 3.11, 3.12, 3.13, 3.15).
|
|
203
203
|
- Trình duyệt headless: Cần cài đặt Playwright Chromium để dùng tính năng dò phần tử DOM và tự sửa locator.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 10. Chuẩn Mực Quản Trị Đa Cấp Monorepo (Hierarchical AGENTS.md & Lowest-Layer Design)
|
|
208
|
+
|
|
209
|
+
Học hỏi từ các monorepo quy mô toàn cầu (Next.js, Cloudflare Workers-SDK, Airflow, Sentry):
|
|
210
|
+
1. **Phân Tầng Đa Cấp (Hierarchical Scoping):** Thay vì duy trì một tệp quy tắc 4,000 dòng cồng kềnh tại thư mục gốc, hệ thống áp dụng mô hình phân tán: tệp `AGENTS.md` gốc chỉ định các bất biến toàn cục (DoD, Clean POM, UTF-8 No BOM, Zero Secret Leaks). Các package con (`packages/*/AGENTS.md`) chịu trách nhiệm về tooling, runner và phạm vi kiểm thử hẹp tương ứng.
|
|
211
|
+
2. **Nguyên Lý Thiết Kế Tầng Thấp Nhất (Lowest-Layer Design Axiom):** Khi thực hiện kiểm thử hoặc sửa đổi mã nguồn trong kiến trúc monorepo, quy tắc và test command luôn được kích hoạt tại package thấp nhất có thể (ví dụ: `pnpm test -F <package>` thay vì chạy toàn bộ workspace) nhằm giảm thiểu bán kính rủi ro (blast radius) và bảo vệ lockfile monorepo.
|
|
212
|
+
3. **Nguồn Chân Lý Duy Nhất (Single Source of Truth):** `AGENTS.md` là nguồn chân lý duy nhất cho toàn bộ AI coding agents (Claude, Cursor, Copilot, Windsurf, Antigravity). Các cấu hình khác (`.cursorrules`, `CLAUDE.md`) chỉ đóng vai trò symlink hoặc con trỏ kế thừa.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Client Support & Host Interoperability Matrix
|
|
2
|
+
|
|
3
|
+
> **Synapse Hub Enterprise QA Automation Platform**
|
|
4
|
+
> **Author:** Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
|
|
5
|
+
> **License:** MIT License
|
|
6
|
+
> **Last Updated:** 2026-11-15
|
|
7
|
+
|
|
8
|
+
This document formalizes AI client and IDE host compatibility, distinguishing fully verified integration targets from experimental or unverified environments.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. Comprehensive Host Support Matrix
|
|
13
|
+
|
|
14
|
+
| Client Host | Classification | Discovery / Hook Path | Scope / Capabilities | Limitations / Caveats |
|
|
15
|
+
| :--- | :---: | :--- | :--- | :--- |
|
|
16
|
+
| **Google Antigravity** | **Verified** | `.agents/skills/*/SKILL.md`<br/>`plugin.json`<br/>`agentskills.json` | Subagents, custom tools, rules router, MCP servers, episodic memory | Requires Antigravity environment |
|
|
17
|
+
| **Claude Code** | **Verified** | `CLAUDE.md`<br/>`templates/ai_bridges/CLAUDE.md` | Workspace instructions, CLI command execution, tool calls | In-context prompt adherence only; single agent loop |
|
|
18
|
+
| **Cursor IDE** | **Verified** | `.cursorrules`<br/>`.cursor/rules/synapse-qa.mdc` | Glob-matched file rules (`globs: **/*`), inline assistant, Composer | No background multi-agent swarm; single workspace |
|
|
19
|
+
| **GitHub Copilot** | **Verified** | `.github/copilot-instructions.md`<br/>`.github/instructions/*.instructions.md` | Path-specific instructions (`applyTo:`), Copilot Chat, CLI assistance | Chat and inline code suggestions only; no tool orchestration |
|
|
20
|
+
| **Windsurf** | **Verified** | `.windsurfrules`<br/>`templates/ai_bridges/windsurfrules` | Cascade engine directives, scratchpad, agent pair-programming | Single-agent chat flow |
|
|
21
|
+
| **Node.js / NPX CLI** | **Verified** | `bin/agent-qa.js`<br/>`package.json` | Global CLI execution (`agent-qa`, `npx @teevee98/synapse-hub`) | Requires Node.js >= 18.0.0 |
|
|
22
|
+
| **Python CLI** | **Verified** | `tools/cli.py`<br/>`pyproject.toml` | Full toolsuite execution (`agent-qa`, `synapse-hub`) | Requires Python >= 3.10 |
|
|
23
|
+
| **Codex** | **Unverified / Experimental** | Generic prompt fallback | Code generation & completion | No dedicated workspace instruction configuration file format |
|
|
24
|
+
| **OpenCode** | **Unverified / Experimental** | In-context prompt injection | Code generation & execution traces | Experimental; no standardized repository hook specification |
|
|
25
|
+
| **Goose** | **Unverified / Experimental** | Generic agent instructions | Task automation via MCP | Unverified CLI profile |
|
|
26
|
+
| **Devin / Cline** | **Unverified / Experimental** | Workspace instructions fallback | Autonomous web/CLI workflows | Unverified host configuration |
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. Integration Tiers & Host Requirements
|
|
31
|
+
|
|
32
|
+
### Tier A: Native Multi-Agent & Rule Routing (Verified)
|
|
33
|
+
- **Google Antigravity:** Full support for 53 QA skills, subagent swarm orchestrator, rules routing, and MCP servers.
|
|
34
|
+
- **Node.js & Python CLIs:** Production package distributions supporting hermetic standalone execution.
|
|
35
|
+
|
|
36
|
+
### Tier B: Synchronized IDE Bridge Directives (Verified)
|
|
37
|
+
- **Claude Code, Cursor IDE, Windsurf, GitHub Copilot:**
|
|
38
|
+
- Synchronized via `python tools/sync_agent_rules.py`.
|
|
39
|
+
- Single source of truth is `AGENTS.md`.
|
|
40
|
+
- Scope isolation: Template bridges deployed to client projects (`templates/ai_bridges/*`) omit Synapse-Hub-only CLI tools and reference project-native runners (`npm test`, `pytest`).
|
|
41
|
+
|
|
42
|
+
### Tier C: Unverified / Experimental Hosts
|
|
43
|
+
- Host platforms that lack dedicated configuration hook formats (such as OpenAI Codex API, OpenCode, Goose, Devin, Cline) rely on prompt fallback or generic workspace ingestion.
|
|
44
|
+
- These hosts must be tested on a case-by-case basis before relying on autonomous execution.
|
package/docs/CLI_REFERENCE.en.md
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Synapse-Hub CLI & Tools Reference Manual
|
|
2
2
|
|
|
3
3
|
[🇻🇳 Tiếng Việt](CLI_REFERENCE.md) | [🇬🇧 English Edition](CLI_REFERENCE.en.md)
|
|
4
4
|
|
|
5
|
-
The `Synapse Hub` provides a unified CLI utility `
|
|
5
|
+
The `Synapse Hub` ecosystem provides a unified CLI utility `synapse-hub` (or legacy `agent-qa`, along with direct Python scripts in `tools/`) to execute quality gates, linting, impact analysis, and log distillation.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
## 1. Unified CLI Entrypoint (`agent-qa`)
|
|
9
|
+
## 1. Unified CLI Entrypoint (`synapse-hub` / `agent-qa`)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
After installing globally via `npm install -g @teevee98/synapse-hub` or via Python `pip install synapse-hub` (or `pip install -e .` for local development), the command is globally accessible:
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
|
+
synapse-hub <command> [options]
|
|
15
|
+
# or
|
|
14
16
|
agent-qa <command> [options]
|
|
15
17
|
```
|
|
16
18
|
|
package/docs/CLI_REFERENCE.md
CHANGED
|
@@ -8,7 +8,7 @@ Hệ sinh thái Synapse Hub cung cấp công cụ dòng lệnh `synapse-hub` (ho
|
|
|
8
8
|
|
|
9
9
|
## 1. Điểm Vào Dòng Lệnh Thống Nhất (`synapse-hub` / `agent-qa`)
|
|
10
10
|
|
|
11
|
-
Sau khi cài đặt qua `npm install -g @teevee98/synapse-hub` hoặc `pip install -e
|
|
11
|
+
Sau khi cài đặt qua `npm install -g @teevee98/synapse-hub` hoặc qua Python `pip install synapse-hub` (hoặc `pip install -e .`), bạn có thể gõ trực tiếp:
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
synapse-hub <lệnh> [tùy_chọn]
|
package/docs/CONTRIBUTING.en.md
CHANGED
|
@@ -28,7 +28,7 @@ Every skill resides in `.agents/skills/<category>/<skill-name>/` (across 11 doma
|
|
|
28
28
|
Before submitting a pull request or committing changes:
|
|
29
29
|
|
|
30
30
|
```bash
|
|
31
|
-
# 1. Run regression test suite (
|
|
31
|
+
# 1. Run regression test suite (1,001+ tests)
|
|
32
32
|
pytest tests -q
|
|
33
33
|
|
|
34
34
|
# 2. Verify all 10 DoD Quality Gates (Gate 1–10)
|
package/docs/CONTRIBUTING.md
CHANGED
|
@@ -28,8 +28,8 @@ Mỗi kỹ năng nằm trong thư mục riêng `.agents/skills/<category>/<ten-k
|
|
|
28
28
|
Trước khi mở PR hoặc đẩy code lên nhánh `develop`:
|
|
29
29
|
|
|
30
30
|
```bash
|
|
31
|
-
# 1. Chạy toàn bộ
|
|
32
|
-
|
|
31
|
+
# 1. Chạy toàn bộ 1,001+ bài unit test
|
|
32
|
+
pytest tests -q
|
|
33
33
|
|
|
34
34
|
# 2. Kiểm định toàn vẹn 10 Cổng Chất Lượng DoD (Gate 1–10)
|
|
35
35
|
python3 tools/verify_all.py
|