From 23d03352a705c680bb39256ebdedee66e066f9f9 Mon Sep 17 00:00:00 2001 From: Ruslan Strazhnyk Date: Thu, 5 Nov 2026 11:33:22 +0100 Subject: [PATCH] docs: make the product overview developer-centric Lead every overview with the developer: their repository, their terminal, their choice of model and agent, their keys in their keychain. QualityMax stays an optional, first-class MCP integration but no longer frames the opening copy. README: replace the "Where it sits" / "What qmax-code can do" sections with "Built for developers" (local by default, your keys, one binary, nothing hidden, QA in the dev loop, QualityMax when you want it), "Where it is going", and a capability table that states exactly what works in --local versus connected mode. The standalone boundary is taken from internal/agent/tools.go: five local tools plus /orch backends and /skills; everything else needs a QualityMax connection. AGENTS.md and CLAUDE.md: same positioning for agents, with an explicit instruction not to imply connected tools work offline. doc.go: package comment rewritten to match. Documentation only; go build, go vet, go test ./... and git diff --check pass. --- AGENTS.md | 39 +++++++++++------- CLAUDE.md | 30 ++++++++------ README.md | 117 ++++++++++++++++++++++++++++++------------------------ doc.go | 19 +++++---- 4 files changed, 119 insertions(+), 86 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 77dcead..4453b08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,23 +4,33 @@ Instructions for coding agents working on qmax-code. ## What this is -qmax-code is evolving into a **standalone IDE with optional, first-class -QualityMax connectivity through MCP**. The current Go terminal agent is the -foundation: it works on local repositories without a QualityMax account and -can connect to QualityMax for hosted QA workflows. Through `/orch` it can -launch Claude Code, Codex, Antigravity, or OpenCode while keeping qmax tools -and terminal UX — or run the built-in loop on Anthropic, Cerebras, or Ollama. +qmax-code is a **developer-first coding environment**: a Go terminal agent +that works on the repository in front of the user, with no account, no +project, and no QualityMax request in standalone mode. It is evolving into a +**standalone IDE with optional, first-class QualityMax connectivity through +MCP**. Through `/orch` it hosts Claude Code, Codex, Antigravity, or OpenCode +while keeping qmax tools and terminal UX, or runs the built-in loop on +Anthropic, Cerebras, or Ollama. This repository is **Go 1.27.3+**, not TypeScript. The thing users install is one compiled binary. ## Positioning -The product direction is an independent development environment for coding, -testing, review, and agent workflows. QualityMax is an optional integration -with first-class MCP support, rather than a prerequisite for using the IDE. -QA remains a core strength: crawl, generate/run tests, review, heal, and receipts. -Claude Code, Codex, Antigravity, and OpenCode are selectable coding backends. +Lead with the developer. The product is the environment a developer works +in: their repo, their terminal, their choice of model and agent, their keys +in their keychain. QualityMax is an optional integration with first-class +MCP support, never a prerequisite. QA remains a core strength, framed as part +of the developer's own loop (write, test, review, ship) rather than as a +separate service. + +Be exact about the standalone boundary. `--local` exposes five agent tools +(`update_plan`, `read_file`, `write_file`, `edit_file`, `run_command`), the +`/orch` backends, and `/skills`. Test generation from managed test cases, +hosted test runs, crawls, repository review, project and test-case +management, PR creation, CI setup, and script healing require a QualityMax +connection. Say so when describing a feature; do not imply a connected tool +works offline. Distinguish the IDE direction from capabilities shipped today. The current release is a terminal application; describe planned IDE features as future work. @@ -34,9 +44,10 @@ release is a terminal application; describe planned IDE features as future work. - **OpenCode** = opt-in providers (Z.AI GLM, Groq, OpenRouter) via `/providers`. -When writing product-direction copy, say “a standalone IDE with optional, -first-class QualityMax connectivity through MCP.” Describe current terminal -capabilities accurately and attribute inference speed to the backend. +When writing product-direction copy, say "a developer-first coding +environment, evolving into a standalone IDE with optional, first-class +QualityMax connectivity through MCP." Describe current terminal capabilities +accurately and attribute inference speed to the backend. ## Why Go diff --git a/CLAUDE.md b/CLAUDE.md index bf3a118..12e9b34 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,18 +1,22 @@ # CLAUDE.md -qmax-code is evolving into a **standalone IDE with optional, first-class -QualityMax connectivity through MCP**. Its current foundation is a **Go** -terminal agent (Go 1.27.3+). It ships as one compiled binary: -`curl | bash` installs a file, not a Node or Python runtime. -Claude Code, Codex, Antigravity, and OpenCode are separate subprocesses that `/orch` can -host; they are not this repository's runtime. - -**Positioning:** an independent environment for coding, testing, review, and -agent workflows. QualityMax is optional, with first-class MCP connectivity; -using qmax-code does not require a QualityMax account. QA (tests, crawls, -review, receipts) remains a core strength. Describe the standalone IDE as the -product direction and the terminal app as what ships today; describe planned -IDE features as future work. +qmax-code is a **developer-first coding environment** evolving into a +**standalone IDE with optional, first-class QualityMax connectivity through +MCP**. Its current foundation is a **Go** terminal agent (Go 1.27.3+). It +ships as one compiled binary: `curl | bash` installs a file, not a Node or +Python runtime. Claude Code, Codex, Antigravity, and OpenCode are separate +subprocesses that `/orch` can host; they are not this repository's runtime. + +**Positioning:** lead with the developer: their repo, their terminal, their +choice of model and agent, their keys in their keychain. Standalone mode +(`--local`) needs no QualityMax account and exposes five agent tools (plan, +read, write, edit, run command) plus `/orch` backends and `/skills`. Hosted +test runs, test generation from managed cases, crawls, repository review, +project management, PR creation, CI setup, and healing require a QualityMax +connection; say so rather than implying they work offline. QA is a core +strength, framed as part of the developer's own write-test-review-ship loop. +Describe the standalone IDE as the product direction and the terminal app as +what ships today; describe planned IDE features as future work. qmax-code switches inference in `/orch`. **Cerebras** is the fast path (~1000–2000+ tok/s: GPT-OSS 120B, GLM 4.7, Gemma 4; **Qwen 3.8 coming soon**). Do not add Qwen to the picker until Cerebras publishes the live model ID. diff --git a/README.md b/README.md index 031cc56..ca72a89 100644 --- a/README.md +++ b/README.md @@ -26,22 +26,19 @@ [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/qualitymax) -**Building an open-source standalone IDE with optional, first-class QualityMax connectivity through MCP.** Named after Max, the real cat who inspired it all. +**An open-source coding environment built for developers first: your repository, your terminal, your choice of models and agents.** One Go binary, no account required. Evolving into a standalone IDE with optional, first-class QualityMax connectivity through MCP. Named after Max, the real cat who inspired it all. -qmax-code is evolving into an independent development environment for coding, -testing, review, and agent workflows. QualityMax is an optional integration, -with first-class connectivity through MCP as part of that direction. +qmax-code runs against the repository in front of you. It reads, edits, and +searches code, runs allowlisted commands and tests, and keeps QA in the same +loop as coding: write the change, generate the tests, run them, review the +diff, ship. Bring your own inference (Anthropic, Cerebras, or Ollama) or host +the coding agent you already use (Claude Code, Codex, Antigravity, or +OpenCode) and switch between them with `/orch`. -Today, qmax-code ships as a Go terminal application that works on local -repositories without a QualityMax account. Connect to QualityMax to manage -projects and test cases, crawl sites, generate and run tests, review -repositories, heal scripts, and prepare CI. The current client calls the -QualityMax API directly and exposes tools to coding-agent backends through -its embedded MCP server; the separate `qmax` CLI is optional. - -Use the built-in agent with Anthropic, Cerebras, or Ollama, or use -**orchestration mode** to run Claude Code, Codex, Antigravity, or OpenCode with the same qmax -QA tools through MCP. +QualityMax is an opt-in extension, not a prerequisite. Connect it when you +want hosted browser test runs, crawls, project and test-case management, or +repository review. Its tools reach whichever agent you run through the +embedded MCP server, and `/disconnect` takes them away again. ![qmax-code startup banner in standalone local-only mode](docs/img/terminal.png) @@ -65,18 +62,37 @@ cloud reach a private network). Only hosted QualityMax needs an account. > including for commercial use. No waiting period or non-compete restriction. > [Read the announcement →](docs/releases/v1.38.0.md) -## Where it sits - -The goal is a **standalone IDE** where local development, coding agents, and -QA workflows share one environment. QualityMax connectivity through MCP is -optional and first-class: it extends the environment with hosted QA services -without making a QualityMax account a requirement for local work. - -The current terminal application is the foundation for that IDE. It already -supports local file editing, commands, tests, and selectable coding backends. -Connected workflows add crawls, hosted tests, repository review, and healing. -The standalone IDE is the product direction; the capabilities documented -below describe the terminal release available today. +## Built for developers + +- **Local by default.** `qmax-code --local` needs no login, no project, and + makes no QualityMax request. Your code leaves the machine only through the + inference backend you chose; pick Ollama when it should not leave at all. +- **Your keys, your agents.** Use an Anthropic or Cerebras key, a local Ollama + endpoint, or a Claude Code or Codex install you have already signed in to. + Keys live in the OS keychain or in environment variables, never in a + QualityMax proxy. +- **One binary.** `curl | bash` installs a single Go executable for macOS, + Linux, and Windows on Intel and ARM. No Node, Python, or version manager. +- **Nothing hidden.** Exposure Receipts write a signed local manifest of every + LLM and cloud-API egress. Telemetry is off unless you set two environment + variables. Local commands run under an allowlist with your user permissions. +- **QA inside the dev loop.** A catalog of QA skills (diff risk, secrets, + dependencies, accessibility, Core Web Vitals, flaky selectors, release + gates, and more) installs into Claude Code, Codex, and OpenCode with + `/skills install`, so review happens before the PR, not after. +- **QualityMax when you want it.** Connected mode adds hosted Playwright + execution, crawls, test generation from managed test cases, repository + review, script healing, and CI setup through MCP. Disconnect and everything + above keeps working. + +## Where it is going + +The direction is a standalone IDE where local development, coding agents, and +QA share one environment, with QualityMax as an optional, first-class MCP +integration. The terminal application is the foundation and what ships today: +file editing, commands, tests, selectable backends, QA skills, and the +connected tools listed below. Planned IDE features are future work; everything +documented in this README describes the current release. Go makes the binary install once. **Cerebras** makes tokens fast (today: GPT-OSS 120B, GLM 4.7, Gemma 4 at ~1000–2000+ tok/s; **Qwen 3.8 coming @@ -85,40 +101,39 @@ in `/orch`; do not run two CLIs and two configs. | Job | Pick | | --- | --- | -| Tests, crawls, coverage, QualityMax projects | qmax-code connected (or `--local` for workspace-only) | +| Edit, search, run commands and tests in a local repo | qmax-code `--local` with any backend | | Fast loops, bulk generation, cheap iteration | `/orch` → Cerebras | | Hard design, tricky refactors | `/orch` → Claude Code or Codex | | GLM on a coding plan | `/providers` → Z.AI, then OpenCode in `/orch` | | Air-gapped / local weights | Ollama | - -In the current terminal release, use `/orch` to select the backend for your -next task. Local coding works without QualityMax; enable connected mode when -you need its hosted QA workflows. +| Hosted browser tests, crawls, coverage, QualityMax projects | qmax-code connected | ## What qmax-code can do ![Plan, generate, execute, review, and ship, over a local repository lane](docs/img/lifecycle.svg) -- **Plan and manage QA work:** list and manage projects and test cases, enhance - cases, find coverage gaps, and import requirements or repositories. -- **Generate and execute tests:** create Playwright, pytest, Go, and Rust tests; - run browser tests in QualityMax, run Go/Rust tests on the native runner, or - execute supported tests locally. -- **Crawl and inspect applications:** discover pages, generate test scenarios, - analyze screenshots and page elements, and optionally watch test/crawl runs - through a live terminal browser feed. -- **Review and ship:** analyze repositories for quality, coverage, security, and - testing risk; honor saved review preferences; create test PRs; and generate a - GitHub Actions test workflow. -- **Work on local repositories:** read, create, and edit files; search code; run - allowlisted commands and tests. Standalone mode provides this lane without a - QualityMax login. -- **Extend coding agents:** install QA skills into Claude Code, Codex, and - OpenCode, including accessibility, performance, security, dependency, - usability, flaky-selector, and release-gate workflows. - -Some advanced surfaces—k6, QTML, framework export/trigger operations, and -background-job health—remain experimental and are only exposed when +The table shows what works in standalone mode and what connecting to +QualityMax adds. Standalone exposes exactly five agent tools (plan, read, +write, edit, run command) plus whichever backend `/orch` selects; every other +tool is refused until you connect. + +| Capability | Standalone (`--local`) | Connected to QualityMax | +| --- | --- | --- | +| Read, create, edit, and search files in your repository | Yes | Yes | +| Run allowlisted commands and your own test suites | Yes | Yes | +| Host Claude Code, Codex, Antigravity, or OpenCode through `/orch` | Yes | Yes, with qmax tools served over MCP | +| Install QA skills into those agents with `/skills install` | Yes | Yes | +| Exposure Receipts for every outbound request | Yes | Yes | +| Generate Playwright, pytest, Go, and Rust tests from managed test cases | No (the model writes tests directly with the file tools) | Yes | +| Run browser tests in QualityMax, Go and Rust tests on the native runner | No | Yes | +| Crawl an app, generate scenarios, analyze screenshots and page elements | No | Yes, optionally with the live terminal browser feed | +| Review a repository for quality, coverage, security, and testing risk | No | Yes, honoring saved review preferences | +| Manage projects and test cases, enhance cases, find coverage gaps, import requirements | No | Yes | +| Create test PRs and a GitHub Actions test workflow | No | Yes | +| Heal broken scripts and roll back script versions | No | Yes | + +Some advanced surfaces (k6, QTML, framework export/trigger operations, and +background-job health) remain experimental and are only exposed when `QMAX_EXPERIMENTAL=1`. ## Latest changes diff --git a/doc.go b/doc.go index e5be114..ee75ab5 100644 --- a/doc.go +++ b/doc.go @@ -1,12 +1,15 @@ -// Command qmax-code is the terminal foundation for a standalone IDE with -// optional, first-class QualityMax connectivity through MCP. +// Command qmax-code is a developer-first coding environment: a terminal +// agent that works on the local repository with no account required, and the +// foundation for a standalone IDE with optional, first-class QualityMax +// connectivity through MCP. // -// It runs standalone against a local repository or connects to QualityMax, -// and can switch inference between the Anthropic API, Cerebras, Ollama, and -// hosted coding agents (Claude Code, Codex, Antigravity, OpenCode) through -// /orch. It supports local coding, QA work, and exposure receipts. Connected -// workflows add test generation and execution, app crawling, and repository -// review. +// In standalone mode (--local) it reads, writes, edits, and searches files +// and runs allowlisted commands and tests, using the Anthropic API, Cerebras, +// or Ollama for inference, or hosting Claude Code, Codex, Antigravity, or +// OpenCode through /orch. Every outbound request is recorded in a signed +// Exposure Receipt. Connecting to QualityMax adds hosted test generation and +// execution, app crawling, repository review, and project management over +// the same MCP server. // // Install a release binary: //