newton

Newton QA

Newton is an agent-native QA harness that turns sprint context into executable web/iOS scenarios and evidence-backed QA reports.

Install

Install the official CLI directly from GitHub:

curl -fsSL https://raw.githubusercontent.com/qyinm/Newton/main/scripts/install.sh | bash
newton version

The installer uses uv tool install when uv is available, falls back to pipx, and installs the Playwright Chromium browser by default. To install only the base CLI:

curl -fsSL https://raw.githubusercontent.com/qyinm/Newton/main/scripts/install.sh | bash -s -- --no-web

Claude Code Plugin

Newton also ships a thin Claude Code plugin wrapper around the newton CLI. Add this repository as a Claude Code plugin marketplace, then install the newton plugin:

claude plugin marketplace add qyinm/Newton
claude plugin install newton@newton

Inside Claude Code, use:

/newton-setup
/newton-dogfood
/newton-plan
/newton-run
/newton-bug-draft

The plugin also includes the newton-qa-workflow skill, which routes natural-language QA planning, execution, tracker, and bug-draft requests through the same newton qa ... CLI artifact contract.

If your Claude Code build expects in-session slash commands for plugin management, use the same arguments with /plugin marketplace add qyinm/Newton and /plugin install newton@newton.

For local development from this checkout:

python -m pip install -e '.[dev]'

For web execution:

python -m pip install -e '.[dev,web]'
python -m playwright install chromium

Plan a QA Bundle

Generate a minimal PRD-style planning bundle from markdown product/ticket context:

newton qa plan-bundle qa/inputs/login-ticket.md \
  --source qa/inputs/login-policy.md \
  --agent template \
  --out qa/plans

The repository includes this demo input pair and the checked-in generated bundle under qa/plans/login/ so agents and CI can validate the PRD planning contract without regenerating fixtures first.

Use --source to merge extra markdown sources such as policy notes, staging notes, or design annotations into the same checklist/test-case bundle. --agent template is the deterministic fallback and does not call an external agent. risk-map.md includes baseline PRD risk categories: edge case, network failure, permission/role, policy conflict, and regression.

To let an external agent draft the bundle while Newton validates and materializes the artifact contract, use --agent codex or --agent claude:

newton qa plan-bundle qa/inputs/login-ticket.md \
  --source qa/inputs/login-policy.md \
  --agent codex \
  --out qa/plans

Agent-backed bundle generation preserves the prompt, raw stdout, and accepted JSON next to the generated artifacts. The agent must include qa_estimate.evidence_factors; each factor cites a provided source path or filename, and Newton rejects the bundle before writing manifest.json if the estimate lacks source-linked evidence. Newton verifies source linkage structurally, not semantic truth.

qa/plans/login/bundle-generation.codex.prompt.txt
qa/plans/login/bundle-generation.codex.raw.txt
qa/plans/login/bundle-generation.codex.json

Outputs:

qa/plans/login/qa-scope.md
qa/plans/login/checklist.md
qa/plans/login/test-cases.csv
qa/plans/login/risk-map.md
qa/plans/login/qa-estimate.md
qa/plans/login/automation-candidates.md
qa/plans/login/qa-run-tracker.md
qa/plans/login/manifest.json

After updating the tracker with a checklist result, generate a bug ticket draft from the first failed item:

newton qa tracker-update qa/plans/login/qa-run-tracker.md \
  --item 5 \
  --env stg \
  --status failed \
  --notes "Dashboard never appears after submit"
newton qa tracker-update-from-run qa/plans/login/qa-run-tracker.md \
  --item 1 \
  --env stg \
  --run qa/runs/run_123
newton qa bug-draft qa/plans/login/qa-run-tracker.md

Output:

qa/plans/login/bug-ticket-draft.md

Validate the generated artifact contract before handing the bundle to another agent or CI job:

newton qa bundle-validate qa/plans/login

Expected:

valid_bundle: login
artifacts: 8
checklist_items: 8
test_cases: 8
tracker_items: 8

Optionally request an advisory QA review after generation. bundle-review does not generate or edit the bundle: template is deterministic; codex and claude use an external agent and preserve prompt/raw output next to the review artifacts. Default external review commands are constrained (codex read-only sandbox, claude tools disabled); --agent-command is an explicit override for tests or custom setups:

newton qa bundle-review qa/plans/login --agent template
newton qa bundle-review qa/plans/login --agent codex

Outputs: