sumo-qa 0.1.0__tar.gz

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 (125) hide show
  1. sumo_qa-0.1.0/.claude-plugin/marketplace.json +20 -0
  2. sumo_qa-0.1.0/.claude-plugin/plugin.json +22 -0
  3. sumo_qa-0.1.0/.codex-plugin/plugin.json +43 -0
  4. sumo_qa-0.1.0/.cursor-plugin/plugin.json +25 -0
  5. sumo_qa-0.1.0/.dockerignore +13 -0
  6. sumo_qa-0.1.0/.github/copilot-instructions.md +24 -0
  7. sumo_qa-0.1.0/.github/dependabot.yml +21 -0
  8. sumo_qa-0.1.0/.github/workflows/lint.yml +29 -0
  9. sumo_qa-0.1.0/.github/workflows/release.yml +45 -0
  10. sumo_qa-0.1.0/.github/workflows/test.yml +34 -0
  11. sumo_qa-0.1.0/.gitignore +23 -0
  12. sumo_qa-0.1.0/.opencode/INSTALL.md +81 -0
  13. sumo_qa-0.1.0/AGENTS.md +97 -0
  14. sumo_qa-0.1.0/DEMO.md +105 -0
  15. sumo_qa-0.1.0/Dockerfile +17 -0
  16. sumo_qa-0.1.0/LICENSE +202 -0
  17. sumo_qa-0.1.0/NOTICE +3 -0
  18. sumo_qa-0.1.0/PKG-INFO +125 -0
  19. sumo_qa-0.1.0/README.md +102 -0
  20. sumo_qa-0.1.0/conftest.py +16 -0
  21. sumo_qa-0.1.0/docs/ARCHITECTURE.md +108 -0
  22. sumo_qa-0.1.0/docs/CONFIGURATION.md +45 -0
  23. sumo_qa-0.1.0/docs/DEVELOPMENT.md +75 -0
  24. sumo_qa-0.1.0/docs/INSTALL.md +176 -0
  25. sumo_qa-0.1.0/docs/SKILLS.md +57 -0
  26. sumo_qa-0.1.0/docs/TEST-DATA.md +63 -0
  27. sumo_qa-0.1.0/docs/TOOLS.md +55 -0
  28. sumo_qa-0.1.0/docs/superpowers/iteration-runs/.gitkeep +0 -0
  29. sumo_qa-0.1.0/docs/superpowers/iteration-runs/MCP-STATE-AND-CAPABILITIES.md +359 -0
  30. sumo_qa-0.1.0/docs/superpowers/iteration-runs/TEMPLATE.md +46 -0
  31. sumo_qa-0.1.0/docs/superpowers/iteration-runs/post-cleanup-verification-2026-05-08-0142.md +124 -0
  32. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-1-2026-05-07-1830.md +69 -0
  33. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-10-phase-3-verification.md +123 -0
  34. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-11-phase-4-deletion.md +102 -0
  35. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-12-phase-5-docs.md +46 -0
  36. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-13-cross-host-validation.md +75 -0
  37. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-2-2026-05-07-1846.md +89 -0
  38. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-6-2026-05-08-0220.md +136 -0
  39. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-7-2026-05-08-1254.md +88 -0
  40. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-8-phase-1-scaffolding.md +104 -0
  41. sumo_qa-0.1.0/docs/superpowers/iteration-runs/round-9-phase-2-skills.md +76 -0
  42. sumo_qa-0.1.0/docs/superpowers/iteration-runs/steady-state-2026-05-07-1927.md +158 -0
  43. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-07-ai-driven-iteration-loop.md +1453 -0
  44. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-08-superpowers-phase-1-scaffolding.md +2227 -0
  45. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-08-superpowers-phase-2-skills.md +1518 -0
  46. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-08-superpowers-phase-3-verification.md +387 -0
  47. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-08-superpowers-phase-4-deletion.md +571 -0
  48. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-08-superpowers-phase-5-docs.md +738 -0
  49. sumo_qa-0.1.0/docs/superpowers/plans/2026-05-12-oss-readiness.md +700 -0
  50. sumo_qa-0.1.0/docs/superpowers/specs/2026-05-07-ai-driven-iteration-loop-design.md +346 -0
  51. sumo_qa-0.1.0/docs/superpowers/specs/2026-05-08-superpowers-restructure-design.md +419 -0
  52. sumo_qa-0.1.0/docs/superpowers/specs/2026-05-12-oss-readiness-design.md +204 -0
  53. sumo_qa-0.1.0/hooks/hooks-cursor.json +10 -0
  54. sumo_qa-0.1.0/hooks/hooks.json +16 -0
  55. sumo_qa-0.1.0/hooks/run-hook.cmd +46 -0
  56. sumo_qa-0.1.0/hooks/session-start +53 -0
  57. sumo_qa-0.1.0/install.py +557 -0
  58. sumo_qa-0.1.0/install.sh +125 -0
  59. sumo_qa-0.1.0/knowledge/approaches.md +46 -0
  60. sumo_qa-0.1.0/knowledge/classifications.md +54 -0
  61. sumo_qa-0.1.0/knowledge/principles.md +79 -0
  62. sumo_qa-0.1.0/knowledge/specialty_tools.md +54 -0
  63. sumo_qa-0.1.0/knowledge/techniques.md +87 -0
  64. sumo_qa-0.1.0/knowledge/test_data/auth/sample_accounts.yaml +38 -0
  65. sumo_qa-0.1.0/knowledge/test_data/billing/sample_invoices.yaml +38 -0
  66. sumo_qa-0.1.0/pyproject.toml +59 -0
  67. sumo_qa-0.1.0/ruff.toml +18 -0
  68. sumo_qa-0.1.0/skills/qa-answering-testing-question/SKILL.md +82 -0
  69. sumo_qa-0.1.0/skills/qa-creating-test-plan/SKILL.md +114 -0
  70. sumo_qa-0.1.0/skills/qa-deciding-approach/SKILL.md +104 -0
  71. sumo_qa-0.1.0/skills/qa-executing-qa-rollout/SKILL.md +112 -0
  72. sumo_qa-0.1.0/skills/qa-executing-qa-rollout/prompts/implementer-prompt.md +60 -0
  73. sumo_qa-0.1.0/skills/qa-executing-qa-rollout/prompts/quality-reviewer-prompt.md +56 -0
  74. sumo_qa-0.1.0/skills/qa-executing-qa-rollout/prompts/spec-reviewer-prompt.md +51 -0
  75. sumo_qa-0.1.0/skills/qa-finding-test-data/SKILL.md +97 -0
  76. sumo_qa-0.1.0/skills/qa-finishing-qa-work/SKILL.md +134 -0
  77. sumo_qa-0.1.0/skills/qa-implementing-with-tdd/SKILL.md +116 -0
  78. sumo_qa-0.1.0/skills/qa-planning-qa-rollout/SKILL.md +160 -0
  79. sumo_qa-0.1.0/skills/qa-preparing-for-work/SKILL.md +87 -0
  80. sumo_qa-0.1.0/skills/qa-reviewing-before-merge/SKILL.md +115 -0
  81. sumo_qa-0.1.0/skills/qa-strengthening-tests/SKILL.md +116 -0
  82. sumo_qa-0.1.0/skills/sumo-qa-strategising/SKILL.md +119 -0
  83. sumo_qa-0.1.0/skills/using-sumo-qa/SKILL.md +140 -0
  84. sumo_qa-0.1.0/src/sumo_qa/__init__.py +3 -0
  85. sumo_qa-0.1.0/src/sumo_qa/__main__.py +4 -0
  86. sumo_qa-0.1.0/src/sumo_qa/debug_capture.py +51 -0
  87. sumo_qa-0.1.0/src/sumo_qa/knowledge_loaders.py +138 -0
  88. sumo_qa-0.1.0/src/sumo_qa/rules.py +130 -0
  89. sumo_qa-0.1.0/src/sumo_qa/server.py +316 -0
  90. sumo_qa-0.1.0/src/sumo_qa/skill_prompts.py +119 -0
  91. sumo_qa-0.1.0/src/sumo_qa/standards.py +127 -0
  92. sumo_qa-0.1.0/src/sumo_qa/tdm_catalogue.py +179 -0
  93. sumo_qa-0.1.0/src/sumo_qa/tdm_models.py +121 -0
  94. sumo_qa-0.1.0/src/sumo_qa/tdm_service.py +378 -0
  95. sumo_qa-0.1.0/src/sumo_qa/tdm_validation.py +151 -0
  96. sumo_qa-0.1.0/src/sumo_qa/tools.py +174 -0
  97. sumo_qa-0.1.0/standards/packs/istqb_v1.yml +135 -0
  98. sumo_qa-0.1.0/standards/packs/qa_shift_left_v1.yml +51 -0
  99. sumo_qa-0.1.0/standards/rules/change_rules.yaml +237 -0
  100. sumo_qa-0.1.0/tests/scenarios/SCENARIOS.md +231 -0
  101. sumo_qa-0.1.0/tests/scenarios/worked-examples/01-plan-qa-for-story.md +116 -0
  102. sumo_qa-0.1.0/tests/scenarios/worked-examples/02-review-my-changes.md +126 -0
  103. sumo_qa-0.1.0/tests/scenarios/worked-examples/03-fix-bug-regression-first.md +202 -0
  104. sumo_qa-0.1.0/tests/scenarios/worked-examples/04-add-tests-tdd-scaffold.md +203 -0
  105. sumo_qa-0.1.0/tests/scenarios/worked-examples/05-strengthen-tests-mutation.md +309 -0
  106. sumo_qa-0.1.0/tests/scenarios/worked-examples/06-generic-testing-question.md +43 -0
  107. sumo_qa-0.1.0/tests/scenarios/worked-examples/07-find-test-data.md +160 -0
  108. sumo_qa-0.1.0/tests/scenarios/worked-examples/08-audit-and-strategy.md +236 -0
  109. sumo_qa-0.1.0/tests/scenarios/worked-examples/09-formal-test-plan.md +206 -0
  110. sumo_qa-0.1.0/tests/scenarios/worked-examples/10-no-tests-needed.md +63 -0
  111. sumo_qa-0.1.0/tests/scenarios/worked-examples/README.md +33 -0
  112. sumo_qa-0.1.0/tests/test_debug_capture.py +38 -0
  113. sumo_qa-0.1.0/tests/test_error_envelope.py +84 -0
  114. sumo_qa-0.1.0/tests/test_knowledge_loaders.py +132 -0
  115. sumo_qa-0.1.0/tests/test_phase3_e2e_skill_path.py +170 -0
  116. sumo_qa-0.1.0/tests/test_rules.py +129 -0
  117. sumo_qa-0.1.0/tests/test_server.py +140 -0
  118. sumo_qa-0.1.0/tests/test_session_start_hook.py +127 -0
  119. sumo_qa-0.1.0/tests/test_skill_conformance.py +86 -0
  120. sumo_qa-0.1.0/tests/test_skill_prompts.py +122 -0
  121. sumo_qa-0.1.0/tests/test_standards.py +207 -0
  122. sumo_qa-0.1.0/tests/test_tdm.py +460 -0
  123. sumo_qa-0.1.0/tests/test_token_weight_regression.py +130 -0
  124. sumo_qa-0.1.0/tests/test_tools.py +57 -0
  125. sumo_qa-0.1.0/uv.lock +1404 -0
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "sumo-qa-dev",
3
+ "description": "Self-hosted marketplace for the sumo-qa skills library + MCP server.",
4
+ "owner": {
5
+ "name": "Sumith Ramsookbhai",
6
+ "email": "sumithr51@gmail.com"
7
+ },
8
+ "plugins": [
9
+ {
10
+ "name": "sumo-qa",
11
+ "description": "Senior-QA-shaped MCP server + skills library: pre-coding QA planning, TDD scaffolding, mutation-testing follow-up, code review, test-data discovery.",
12
+ "version": "0.1.0",
13
+ "source": "./",
14
+ "author": {
15
+ "name": "Sumith Ramsookbhai",
16
+ "email": "sumithr51@gmail.com"
17
+ }
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "name": "sumo-qa",
3
+ "description": "Senior-QA-shaped MCP server + skills library: pre-coding QA planning, TDD scaffolding, mutation-testing follow-up, code review, test-data discovery. Iron-Law-enforced workflows for deciding approach, prepping for work, TDD-scaffolding, reviewing diffs, strengthening tests, and repo-wide strategising.",
4
+ "version": "0.1.0",
5
+ "author": {
6
+ "name": "Sumith Ramsookbhai",
7
+ "email": "sumithr51@gmail.com"
8
+ },
9
+ "homepage": "https://github.com/sumithr/sumo-qa",
10
+ "repository": "https://github.com/sumithr/sumo-qa",
11
+ "license": "Apache-2.0",
12
+ "keywords": [
13
+ "qa",
14
+ "testing",
15
+ "tdd",
16
+ "mutation-testing",
17
+ "code-review",
18
+ "istqb",
19
+ "senior-qa",
20
+ "test-data"
21
+ ]
22
+ }
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "sumo-qa",
3
+ "version": "0.1.0",
4
+ "description": "Senior-QA skills library + MCP server: pre-coding QA planning, TDD scaffolding, mutation-testing follow-up, code review, repo-wide QA strategy, and test-data discovery.",
5
+ "author": {
6
+ "name": "Sumith Ramsookbhai",
7
+ "email": "sumithr51@gmail.com",
8
+ "url": "https://github.com/SumithRamsookbhai"
9
+ },
10
+ "homepage": "https://github.com/sumithr/sumo-qa",
11
+ "repository": "https://github.com/sumithr/sumo-qa",
12
+ "license": "Apache-2.0",
13
+ "keywords": [
14
+ "qa",
15
+ "testing",
16
+ "tdd",
17
+ "mutation-testing",
18
+ "code-review",
19
+ "istqb",
20
+ "senior-qa",
21
+ "test-data"
22
+ ],
23
+ "skills": "./skills/",
24
+ "interface": {
25
+ "displayName": "Sumo QA",
26
+ "shortDescription": "Senior-QA workflows: pre-coding QA planning, TDD, mutation-testing follow-up, code review, test-data discovery.",
27
+ "longDescription": "Use Sumo QA to drive software changes through a disciplined senior-QA workflow: pick the right approach for the change shape, name risks anchored in code, scaffold red tests before production code, strengthen weak assertions against mutation survivors, review diffs with fresh verification evidence, and find or register known-good test data \u2014 all grounded in ISTQB principles, change classifications, and the team's loaded standards.",
28
+ "developerName": "Sumith Ramsookbhai",
29
+ "category": "Coding",
30
+ "capabilities": [
31
+ "Interactive",
32
+ "Read",
33
+ "Write"
34
+ ],
35
+ "defaultPrompt": [
36
+ "Plan QA for this story before I start coding.",
37
+ "Review my changes for risk before I merge.",
38
+ "Audit our test coverage and design a QA strategy.",
39
+ "Find me a known-good test data record for this scenario."
40
+ ],
41
+ "websiteURL": "https://github.com/sumithr/sumo-qa"
42
+ }
43
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "name": "sumo-qa",
3
+ "displayName": "Sumo QA",
4
+ "description": "Senior-QA skills library + MCP server: pre-coding QA planning, TDD scaffolding, mutation-testing follow-up, code review, test-data discovery.",
5
+ "version": "0.1.0",
6
+ "author": {
7
+ "name": "Sumith Ramsookbhai",
8
+ "email": "sumithr51@gmail.com"
9
+ },
10
+ "homepage": "https://github.com/sumithr/sumo-qa",
11
+ "repository": "https://github.com/sumithr/sumo-qa",
12
+ "license": "Apache-2.0",
13
+ "keywords": [
14
+ "qa",
15
+ "testing",
16
+ "tdd",
17
+ "mutation-testing",
18
+ "code-review",
19
+ "istqb",
20
+ "senior-qa",
21
+ "test-data"
22
+ ],
23
+ "skills": "./skills/",
24
+ "hooks": "./hooks/hooks-cursor.json"
25
+ }
@@ -0,0 +1,13 @@
1
+ .git
2
+ .venv
3
+ __pycache__
4
+ *.py[cod]
5
+ *.egg-info
6
+ .coverage
7
+ .pytest_cache
8
+ .ruff_cache
9
+ .mypy_cache
10
+ .DS_Store
11
+ .env
12
+ dist
13
+ build
@@ -0,0 +1,24 @@
1
+ # QA tasks via sumo-qa MCP
2
+
3
+ For QA-shaped requests in this repo (test plans, code review, scaffolding
4
+ tests, finding test data, deciding QA approach), fetch the relevant prompt
5
+ from the `sumo-qa` MCP and follow its checklist.
6
+
7
+ Available skills (each registered as an MCP prompt with the same name,
8
+ hyphens replaced by underscores):
9
+
10
+ - `using_sumo_qa` — entry router; load this first for any QA intent
11
+ - `qa_deciding_approach` — pick the QA approach for the work
12
+ - `qa_preparing_for_work` — plan QA before coding starts
13
+ - `qa_creating_test_plan` — produce entry/exit criteria, phases, deliverables
14
+ - `qa_implementing_with_tdd` — red-green-refactor cycle
15
+ - `qa_reviewing_before_merge` — review local diff
16
+ - `qa_strengthening_tests` — mutation-testing follow-up
17
+ - `qa_finding_test_data` — known-good test data discovery and validation
18
+ - `qa_answering_testing_question` — generic "how do I test this?"
19
+ - `sumo_qa_strategising` — repo-wide QA strategy
20
+
21
+ The skills carry the senior-QA discipline (Iron Laws, checklists, Red Flags).
22
+ Knowledge catalogues are accessed via the `sumo_qa_load_*` tools — use them
23
+ for principles, techniques, classifications, approaches, and specialty tool
24
+ fits before relying on training-data knowledge.
@@ -0,0 +1,21 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ day: monday
8
+ time: "08:00"
9
+ timezone: Europe/London
10
+ open-pull-requests-limit: 5
11
+ labels: ["deps"]
12
+
13
+ - package-ecosystem: github-actions
14
+ directory: /
15
+ schedule:
16
+ interval: weekly
17
+ day: monday
18
+ time: "08:00"
19
+ timezone: Europe/London
20
+ open-pull-requests-limit: 5
21
+ labels: ["deps", "ci"]
@@ -0,0 +1,29 @@
1
+ name: lint
2
+
3
+ on:
4
+ push:
5
+ branches: ["**"]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ ruff:
11
+ name: ruff check + format
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Install uv
17
+ uses: astral-sh/setup-uv@v3
18
+ with:
19
+ enable-cache: true
20
+ cache-dependency-glob: "uv.lock"
21
+
22
+ - name: Sync dependencies
23
+ run: uv sync --all-extras
24
+
25
+ - name: ruff check
26
+ run: uv run ruff check .
27
+
28
+ - name: ruff format --check
29
+ run: uv run ruff format --check .
@@ -0,0 +1,45 @@
1
+ name: release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ jobs:
9
+ build:
10
+ name: Build wheel + sdist
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+
15
+ - name: Install uv
16
+ uses: astral-sh/setup-uv@v3
17
+ with:
18
+ enable-cache: true
19
+ cache-dependency-glob: "uv.lock"
20
+
21
+ - name: Build
22
+ run: uv build
23
+
24
+ - name: Upload artefacts
25
+ uses: actions/upload-artifact@v4
26
+ with:
27
+ name: dist
28
+ path: dist/
29
+
30
+ publish:
31
+ name: Publish to PyPI
32
+ needs: build
33
+ runs-on: ubuntu-latest
34
+ environment: pypi
35
+ permissions:
36
+ id-token: write # OIDC trusted publishing
37
+ steps:
38
+ - name: Download artefacts
39
+ uses: actions/download-artifact@v4
40
+ with:
41
+ name: dist
42
+ path: dist/
43
+
44
+ - name: Publish to PyPI
45
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,34 @@
1
+ name: tests
2
+
3
+ on:
4
+ push:
5
+ branches: ["**"]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ test:
11
+ name: pytest (${{ matrix.os }} · py${{ matrix.python-version }})
12
+ runs-on: ${{ matrix.os }}
13
+ strategy:
14
+ fail-fast: false
15
+ matrix:
16
+ os: [ubuntu-latest, macos-latest]
17
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
18
+ steps:
19
+ - uses: actions/checkout@v4
20
+
21
+ - name: Install uv
22
+ uses: astral-sh/setup-uv@v3
23
+ with:
24
+ enable-cache: true
25
+ cache-dependency-glob: "uv.lock"
26
+
27
+ - name: Set up Python
28
+ run: uv python install ${{ matrix.python-version }}
29
+
30
+ - name: Sync dependencies
31
+ run: uv sync --all-extras --python ${{ matrix.python-version }}
32
+
33
+ - name: Run pytest
34
+ run: uv run --python ${{ matrix.python-version }} pytest -q
@@ -0,0 +1,23 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .coverage
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .mypy_cache/
8
+ .venv/
9
+ venv/
10
+ dist/
11
+ build/
12
+ .DS_Store
13
+ .env
14
+
15
+ # Per-machine MCP config written by install.py
16
+ .vscode/mcp.json
17
+
18
+ # Team-local test data fixtures. The repo ships domain-neutral samples
19
+ # (auth/, billing/) — keep your team's actual catalogue entries local
20
+ # rather than committing them. Add a line per domain folder you maintain
21
+ # privately.
22
+ knowledge/test_data/fulfilment/
23
+ knowledge/test_data/stock/
@@ -0,0 +1,81 @@
1
+ # Installing Sumo QA for OpenCode
2
+
3
+ ## Prerequisites
4
+
5
+ - [OpenCode.ai](https://opencode.ai) installed
6
+ - `uv` (used to install the `sumo-qa` server binary that the skills call). Get it with `curl -LsSf https://astral.sh/uv/install.sh | sh` if you don't have it.
7
+
8
+ ## Installation
9
+
10
+ Add sumo-qa to the `plugin` array in your `opencode.json` (global or project-level):
11
+
12
+ ```json
13
+ {
14
+ "plugin": ["sumo-qa@git+https://github.com/sumithr/sumo-qa.git"]
15
+ }
16
+ ```
17
+
18
+ Then install the MCP server binary that the skills call into:
19
+
20
+ ```bash
21
+ uv tool install --from git+https://github.com/sumithr/sumo-qa.git sumo-qa
22
+ ```
23
+
24
+ Restart OpenCode. The plugin registers all sumo-qa skills.
25
+
26
+ Verify by asking: *"load the QA classifications"* — you should get 10 names back (api_contract_change, business_logic_change, security_change, performance_change, frontend_change, infrastructure_change, test_change, docs_change, config_change, data_migration).
27
+
28
+ OpenCode uses its own plugin install. If you also use Claude Code, Cursor, Codex, JetBrains, or VS Code, install sumo-qa separately for each one.
29
+
30
+ ## Usage
31
+
32
+ Use OpenCode's native `skill` tool:
33
+
34
+ ```
35
+ use skill tool to list skills
36
+ use skill tool to load sumo-qa/using-sumo-qa
37
+ use skill tool to load sumo-qa/qa-deciding-approach
38
+ ```
39
+
40
+ Or just describe a QA task in natural language ("plan QA for this story", "review my changes") — OpenCode's skill router picks the right one from the descriptions.
41
+
42
+ ## Updating
43
+
44
+ ```json
45
+ {
46
+ "plugin": ["sumo-qa@git+https://github.com/sumithr/sumo-qa.git#v0.1.0"]
47
+ }
48
+ ```
49
+
50
+ To get the latest commit on `main`, omit the `#tag`. Some OpenCode / Bun versions cache the resolved git dependency — if updates don't appear, clear OpenCode's package cache or reinstall the plugin.
51
+
52
+ ## Tool name mapping
53
+
54
+ If you're authoring a skill that references Claude Code tool names, OpenCode uses different names for the same tools:
55
+
56
+ | Claude Code | OpenCode |
57
+ |---|---|
58
+ | `TodoWrite` | `todowrite` |
59
+ | `Read` | `read` |
60
+ | `Edit` | `edit` |
61
+ | `Write` | `write` |
62
+ | `Bash` | `bash` |
63
+ | `Skill` | `skill` |
64
+ | `Glob` | `glob` |
65
+ | `Grep` | `grep` |
66
+
67
+ The sumo-qa skills are written in tool-name-agnostic prose, so this mapping mostly matters if you fork and extend.
68
+
69
+ ## Troubleshooting
70
+
71
+ ### Plugin not loading
72
+ 1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i sumo-qa`
73
+ 2. Verify the plugin line in your `opencode.json`
74
+ 3. Make sure you're running a recent version of OpenCode
75
+
76
+ ### MCP tools not available
77
+ Confirm `sumo-qa` is on `PATH`:
78
+ ```bash
79
+ which sumo-qa
80
+ ```
81
+ If not, re-run the `uv tool install` step above.
@@ -0,0 +1,97 @@
1
+ # AGENTS.md — sumo-qa setup
2
+
3
+ If you're an AI agent setting up sumo-qa for the user, follow this exactly. One command for the common case; per-host flags if you only need to wire one host.
4
+
5
+ ## Default: configure every detected host
6
+
7
+ ```bash
8
+ python3 install.py
9
+ ```
10
+
11
+ What this does:
12
+
13
+ 1. Installs `sumo-qa` via `uv` (prints `uv` install instructions if missing).
14
+ 2. **Claude Code** (if `~/.claude/` exists): symlinks each `skills/<name>/` into `~/.claude/skills/<name>/`. Writes `claude_desktop_config.json` with the MCP entry pointing at the absolute binary path.
15
+ 3. **VS Code + Copilot** (if cwd is a workspace with `.git` / `.vscode` / `package.json` / etc.): writes `.vscode/mcp.json` with the **VS Code-native schema** (`servers` key, `type: stdio`).
16
+ 4. **JetBrains IDEs** (if JetBrains config dir exists): prints exact Settings UI steps. JetBrains' MCP plugin requires Settings UI registration — external XML writes don't reliably register the runtime coroutine.
17
+ 5. Verifies the binary responds to JSON-RPC `initialize`.
18
+
19
+ ## Per-host flags
20
+
21
+ Use these when you only want to configure one host:
22
+
23
+ ```bash
24
+ python3 install.py --claude-code # Claude Code only
25
+ python3 install.py --vscode # VS Code workspace (cwd-based)
26
+ python3 install.py --vscode --workspace /path/to/repo
27
+ python3 install.py --jetbrains # Prints JetBrains UI steps only
28
+ python3 install.py --vscode --skip-mcp-install # Skip uv reinstall for speed
29
+ ```
30
+
31
+ Re-runs are idempotent.
32
+
33
+ ## VS Code specifics
34
+
35
+ - VS Code reads `.vscode/mcp.json` from the **workspace root**, not from `$HOME`. install.py refuses to write to `~/.vscode/mcp.json` and prints a clear error if you're cd'd into `$HOME`.
36
+ - VS Code uses a different MCP schema than Claude Desktop:
37
+ ```json
38
+ { "servers": { "sumo-qa": { "type": "stdio", "command": "...", "args": [] } } }
39
+ ```
40
+ install.py writes this format. Earlier versions wrote `mcpServers` (the Claude Desktop schema) which VS Code silently ignored. If you upgrade install.py and re-run, it strips the stale `mcpServers` key.
41
+ - After running install.py, in VS Code: **Cmd+Shift+P → Developer: Reload Window**. VS Code caches the MCP server list at startup; it doesn't re-read the file mid-session.
42
+ - Use **Agent mode** (not Ask, not Edit) in Copilot Chat. Tools require Agent mode.
43
+ - Use a capable model — **Claude Sonnet 4.5** or **GPT-5 (full)**. Mini/fast variants don't reliably call MCP tools.
44
+
45
+ ## JetBrains specifics
46
+
47
+ JetBrains AI Assistant's MCP config (`llm.mcpServers.xml`) is not reliably writable externally on IDEA 2026.1 — the plugin requires its in-process Settings UI to register the runtime coroutine. install.py prints the exact UI fields (with the absolute binary path):
48
+
49
+ ```
50
+ Settings → Tools → AI Assistant → Model Context Protocol → + Add server
51
+ Name: sumo-qa
52
+ Command: <absolute path printed by install.py>
53
+ Args: (empty)
54
+ Working directory: (empty)
55
+ Apply.
56
+ ```
57
+
58
+ For **Junie** (JetBrains' agentic coding agent), drop this into `~/.junie/mcp/sumo-qa.json`:
59
+
60
+ ```json
61
+ {
62
+ "mcpServers": {
63
+ "sumo-qa": {
64
+ "command": "<absolute path printed by install.py>"
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ Or per-project at `<repo>/.junie/mcp/sumo-qa.json`. Junie reads MCP configs from those directories on startup.
71
+
72
+ ## Verify
73
+
74
+ In any host, ask in chat:
75
+
76
+ ```
77
+ load the QA classifications
78
+ ```
79
+
80
+ You should get 10 canonical names back: api_contract_change, business_logic_change, security_change, performance_change, frontend_change, infrastructure_change, test_change, docs_change, config_change, data_migration. If yes, the MCP is wired correctly.
81
+
82
+ ## After install
83
+
84
+ The host needs to re-read its MCP config:
85
+
86
+ - Claude Code: restart the app
87
+ - JetBrains IDEs: restart the IDE (or restart the AI Assistant tool window)
88
+ - VS Code: **Developer: Reload Window**
89
+
90
+ ## What an AI agent can vs. must ask the user for
91
+
92
+ | You (the agent) CAN | You MUST ASK the user |
93
+ |---|---|
94
+ | Run `python3 install.py` (with whatever host flags) | Restart their host application(s) after install |
95
+ | Run the verification call | Anything that requires admin / sudo elevation |
96
+ | Re-run install.py to refresh | The JetBrains AI Assistant Settings UI add (it's a clicks-only flow; can't be scripted) |
97
+ | Verify Junie's `~/.junie/mcp/sumo-qa.json` file content | |
sumo_qa-0.1.0/DEMO.md ADDED
@@ -0,0 +1,105 @@
1
+ # 5-minute sumo-qa demo
2
+
3
+ Open any real repo. Run one of the prompts below. Watch the senior-QA workflow happen on actual code, in front of you. No staged data, no scripted output — sumo-qa walks your repo and produces senior-grade QA on whatever it finds.
4
+
5
+ ## Step 1 — Install (60 seconds)
6
+
7
+ **Claude Code:**
8
+
9
+ ```text
10
+ /plugin marketplace add sumithr/sumo-qa
11
+ /plugin install sumo-qa@sumo-qa-dev
12
+ ```
13
+
14
+ ```bash
15
+ uv tool install --from git+https://github.com/sumithr/sumo-qa.git sumo-qa
16
+ ```
17
+
18
+ Restart Claude Code. That's it. The SessionStart hook auto-loads `using-sumo-qa` on every conversation; the 13 skills are slash-invocable; the 21 MCP tools are available by natural language.
19
+
20
+ For Cursor / Codex / OpenCode / JetBrains / VS Code + Copilot: see [`docs/INSTALL.md`](docs/INSTALL.md).
21
+
22
+ ## Step 2 — Run one of these prompts on your repo
23
+
24
+ Open your repo in Claude Code. Pick the prompt that matches the QA situation you actually have. Each is a one-liner.
25
+
26
+ ---
27
+
28
+ ### 1. Pre-merge safety check — *the strongest opener*
29
+
30
+ ```
31
+ Review my changes — is this safe to merge?
32
+ ```
33
+
34
+ **What happens:** sumo-qa reads your `git diff` directly (no asking you what changed), classifies the change shape, names 3–7 risks anchored to file + line, asks ONE focused question if anything's ambiguous, **runs your full test suite right now** (refuses to call safe-to-merge from "CI was green earlier"), maps each named risk to a covering test, and delivers SAFE / NOT SAFE / NEEDS WORK with concrete evidence.
35
+
36
+ **The wow moment:** when it refuses to declare safe-to-merge because one of the risks it named has no covering test, and tells you the exact regression test to add — by file + function + assertion shape. Walk through [worked example 02](tests/scenarios/worked-examples/02-review-my-changes.md) to see the pattern.
37
+
38
+ ---
39
+
40
+ ### 2. Pre-coding QA plan — *for a fresh story*
41
+
42
+ ```
43
+ Plan QA for this story before I start coding: <paste the ticket / one-liner>.
44
+ Files likely touch <main_module.py> and <related_module.py>.
45
+ ```
46
+
47
+ **What happens:** sumo-qa reads the actual files, names 3–7 risks specific to *this* change (not "edge cases"), picks one design technique per risk from the loaded ISTQB-grounded catalogue, proposes the **smallest useful test set** tied to those risks, asks you to confirm any open assumptions. No code yet — this is the prep.
48
+
49
+ **The wow moment:** risks like *"currency conversion at the GBP→USD boundary rounds incorrectly when the rate is supplied with >6 decimal places"* — not *"input validation breaks"*.
50
+
51
+ ---
52
+
53
+ ### 3. Bug fix the right way — *regression-first TDD*
54
+
55
+ ```
56
+ Fix this bug regression-first: <describe the bug + the likely file>.
57
+ ```
58
+
59
+ **What happens:** sumo-qa walks the repo to find the production file and the sibling tests (it reads your test conventions; it doesn't ask "what framework do you use?"), picks the smallest failing test idea, confirms the one ambiguous detail with a single question, writes the failing test, runs it, **surfaces the red output verbatim** as proof, then hands off for you to make it green.
60
+
61
+ **The wow moment:** it refuses to write the test AND the production fix in the same turn. The red phase is non-negotiable — the proof that the test actually catches the bug must come before the fix. Most AI assistants skip this.
62
+
63
+ ---
64
+
65
+ ### 4. Repo-wide audit + QA strategy
66
+
67
+ ```
68
+ Audit our test coverage and design a QA strategy.
69
+ ```
70
+
71
+ **What happens:** sumo-qa walks your repo with its file tools (services, modules, test directories, CI config), produces a per-area provisional analysis with risks anchored to file paths, walks you through 6 confirmation gates one at a time (scope → risks → specialty tool fit → prioritisation → target pyramid → phased rollout → residual risks), then offers to write the result to `docs/qa-strategy.md`.
72
+
73
+ **The wow moment:** when it tells you a service that "feels well-tested" actually has 12 unit tests and zero mutation coverage on its highest-branching function — and proposes a 3-phase rollout to close the gap, with named gates at the end of each phase (not a calendar).
74
+
75
+ ---
76
+
77
+ ### 5. Multi-task QA rollout with agents — *the showpiece*
78
+
79
+ ```
80
+ Plan QA for the <feature> across <module1>, <module2>, <module3> — then dispatch
81
+ subagents to execute it in parallel.
82
+ ```
83
+
84
+ **What happens:** sumo-qa runs the full agent-execution chain:
85
+
86
+ 1. **`qa-planning-qa-rollout`** — turns the work into a written plan at `docs/qa/plans/YYYY-MM-DD-<feature>.md` with 6–12 bite-sized tasks, each tagged with its approach and the named risk it covers.
87
+ 2. **`qa-executing-qa-rollout`** — dispatches **one fresh subagent per task** in parallel waves; each output goes through **two-stage review** (spec-correctness then test-quality) before the task is marked done.
88
+ 3. **`qa-finishing-qa-work`** — runs the full suite one last time, builds the risk-to-test coverage map, surfaces any uncovered risks honestly, writes a PR-ready summary to `docs/qa/runs/...`.
89
+
90
+ **The wow moment:** watching parallel subagents write tests against different risks at once, each getting reviewed twice (once for *"did it catch the right risk?"*, once for *"is the test well-shaped?"*) before counting as done. That's how senior QA scales — and it's the gap most AI assistants don't even attempt.
91
+
92
+ ---
93
+
94
+ ## What to tell teammates after the demo
95
+
96
+ > *"Install with one line. Pick a real change. Ask for a review or a plan. The AI will walk your actual repo, name risks anchored to file:line, run tests right now (not from CI memory), and either declare safe-to-merge with evidence — or tell you exactly what's missing. For multi-task QA work it dispatches subagents in parallel with two-stage review."*
97
+
98
+ That's the value prop in one paragraph. Run any of the 5 prompts above on your real repo to see it.
99
+
100
+ ## Want to go deeper?
101
+
102
+ - **All 10 scenarios documented:** [`tests/scenarios/SCENARIOS.md`](tests/scenarios/SCENARIOS.md) — every QA situation sumo-qa handles, with expected interaction shape + anti-patterns.
103
+ - **Polished worked examples:** [`tests/scenarios/worked-examples/`](tests/scenarios/worked-examples/) — full multi-turn transcripts showing what each scenario looks like end-to-end.
104
+ - **The 13 skills:** [`skills/`](skills/) — each one Iron-Law-enforced, with HARD GATEs and one-section-per-turn confirmation discipline.
105
+ - **Architecture:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how the layers fit together.
@@ -0,0 +1,17 @@
1
+ FROM python:3.12-slim
2
+
3
+ ENV PYTHONDONTWRITEBYTECODE=1
4
+ ENV PYTHONUNBUFFERED=1
5
+ ENV QA_STANDARDS_PATH=/app/standards/packs
6
+
7
+ WORKDIR /app
8
+
9
+ COPY pyproject.toml README.md ./
10
+ COPY src ./src
11
+ COPY standards ./standards
12
+ COPY evaluation ./evaluation
13
+ COPY knowledge ./knowledge
14
+
15
+ RUN pip install --no-cache-dir .
16
+
17
+ CMD ["sumo-qa"]