qa-agent-blueprint
AGENTS.md2 starsChanged 7 days agoApache-2.0View on GitHub
You were probably pointed here with a prompt like "look at this repo and set it up as a plugin for me." This file is the machine-readable entry point for that task. Humans start at README.md. Do not follow CLAUDE.md while setting up. It is the product — the QA router the plugin injects into consumer sessions — not meta-documentation about this repo. qa-agent-blueprint: a ticket-driven QA Manager + Tester for Claude Code (JIRA ticket in → tested ticket out,…
- Reads credentials
- Installs packages
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository34 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- accessibility-testingSkill
- agentswitchSkill
- api-testingSkill
- bug-reportSkill
- bug-reproductionSkill
- demoSkill
- deploy-to-stageSkill
- exploratory-testingSkill
- failure-analysisSkill
- model-setupSkill
- onboard-productSkill
- onboard-projectSkill
- perf-analysisSkill
- qa-helpSkill
- qa-metricsSkill
- qa-reportSkill
- re-boardSkill
- reconSkill
- release-readinessSkill
- report-to-jiraSkill
- retest-bugSkill
- retro-learnSkill
- risk-based-testingSkill
- scaffold-suiteSkill
- security-testingSkill
- skill-reviewSkill
- test-automationSkill
- test-case-managementSkill
- test-reliabilitySkill
- test-ticketSkill
- visual-testingSkill
- webdriverio-testingSkill
- whats-newSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 1 is common, 5 are distinctive, and 6 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Plugin path — two commands: Run from inside the consumer project:
- Distinctive: line 109
Ask the user: is your JIRA Atlassian Cloud or self-hosted (Data Center)?
- Very specific: line 160
Ask the user: browser visible (headful) or headless?
- Very specific: line 190
Never git add a nested repo without the ignore entry — embedded repos become gitlinks and the QA data turns unrecoverable noise.
- Very specific: line 206
After the first runs, /skill-review reports which skills the sessions actually used (used) and for which no skills_used data exists …
- Distinctive: line 218
When the user wants the repo locally (to read or hack on the code they run):
- Common: line 231
No secrets in the chat — ever: Never ask the user to paste a PAT, password or API key into the conversation (transcripts keep it).
- Very specific: line 247
Run /onboard-project — needs the JIRA project key, the deployment kind (cloud/datacenter), and the stage URL.
- Very specific: line 265
Do not copy .claude/ contents into the consumer repo by hand — that is what the plugin mechanism replaces (integrate mode exists, but only …
- Distinctive: line 268
Do not add MCP servers beyond the declared two.
- Distinctive: line 307
Never overwrites existing names in the new folder (reported SKIPPED, left for a human merge).
- Very specific: line 330
After any change, run the fixture battery and the manifest validator.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — setup runbook for AI agents
You were probably pointed here with a prompt like "look at this repo and set it
up as a plugin for me." This file is the machine-readable entry point for that
task. Humans start at README.md.
Do not follow
CLAUDE.mdwhile setting up. It is the product — the QA router the plugin injects into consumer sessions — not meta-documentation about this repo.
What this is
qa-agent-blueprint: a ticket-driven QA Manager + Tester for Claude Code
(JIRA ticket in → tested ticket out, mandatory evidence, learning loop).
Ships 33 skills, 9 subagents, 4 hooks, and 2 MCP servers (playwright,
atlassian). Installs into any project as a Claude Code plugin — nothing is
copied into the consumer repo; only the user's own data (projects/,
memory/, evidence/) lives there.
Setup — guided wizard, or two commands (verified end-to-end 2026-09-07, claude 2.1.263)
Guided path (the human's UX). Clone the repo and run the installer wizard from inside the consumer project — it asks mode, target, JIRA deployment, browser mode and optional model lanes one question at a time, and writes nothing until the final confirmation:
git clone https://github.com/Sn4kyGit/qa-agent-blueprint.git ~/qa-blueprint
~/qa-blueprint/install.sh --target <consumer-repo>As an agent you usually have no TTY for the wizard: skip it and pass the
answers as flags — --mode, --jira cloud|datacenter --jira-url <url>,
--browser headless|headful, --model-setup now|later|skip. --yes alone
takes the defaults (Cloud, headless, no model setup) and does not answer
the wizard's preference questions. Wizard and flags run the same code; the
rest of this runbook applies unchanged.
Plugin path — two commands. Run from inside the consumer project:
claude plugin marketplace add Sn4kyGit/qa-agent-blueprint
claude plugin install --scope project qa-agent-blueprint@qa-agent-blueprint-marketplaceThen tell the user to restart Claude Code and accept the trust dialog.
opencode instead of Claude Code?
The same blueprint runs under opencode (model-agnostic source —
the default model is the user's /models choice; optional consumer lane overrides
live in opencode.json via /model-setup). If you are
an agent that was given only the GitHub link, the full run from zero is:
git clone https://github.com/Sn4kyGit/qa-agent-blueprint.git ~/qa-blueprint
~/qa-blueprint/install.sh --mode opencode --target <consumer-repo> --yes(or install.sh --target <consumer-repo> for the guided wizard — pick
opencode at the mode question; --yes takes the defaults as above and needs
explicit --jira/--browser/--model-setup flags for anything else.)
(private repo → clone needs GitHub auth on the machine, see "Missing
prerequisites" below — gh auth login is the one human step there.)
The installer symlinks .opencode/{ROUTER.md,agents,commands,plugins} plus
compat links (.claude, docs, .agents) into the consumer and merges
opencode/opencode.template.jsonc into its opencode.json (existing mcp
names win; playwright contract flags force-upgrade). Prerequisites it checks:
node ≥ 18, opencode CLI (npm install -g opencode-ai — you may install it
with the user's OK), python3. Verify afterwards from the consumer:
opencode run "list your skills" # should show the 32 blueprint skillsFull walkthrough incl. human steps (provider connect via /connect, JIRA auth,
browser mode, shadow mode): docs/quickstart-opencode.md. A consumer picks
one harness per installation mode — the .claude compat symlink and the
Claude plugin would double-register skills. For alternating Claude Code and
opencode in one QA home, use install.sh --mode shared instead: it disables the
project plugin and links both surfaces without re-onboarding. /agentswitch
checks that layout read-only.
--scope projectenables the plugin only in this project (writes one key into.claude/settings.json). Drop the flag for user scope (all projects — note the PreToolUse guard hook then fires in every repo).- While the repo is private, the fetch needs GitHub auth on the machine
(
gh auth login, or any git credential with access) — it is git under the hood. Check first:git ls-remote https://github.com/Sn4kyGit/qa-agent-blueprint.gitmust not prompt.
Missing prerequisites? Install them yourself.
You are an agent — act like one. Check and, with the user's OK, install:
- Node.js ≥ 18 (
node --version) →brew install node - Claude Code (
claude --version) →npm install -g @anthropic-ai/claude-code - GitHub auth (private repo) →
brew install gh, thengh auth loginis the ONE step you cannot do: it opens a browser. Hand it to the human, wait, then verify with thegit ls-remotecheck above. uv(uv --version) →brew install uv— only needed when the user's JIRA is self-hosted (see below).
JIRA deployment: ask BEFORE the restart
Ask the user: is your JIRA Atlassian Cloud or self-hosted (Data Center)?
- Cloud — nothing to do; the plugin's
atlassianentry fits. It uses the default v2 URL (discovery/execute meta-tools) — never append?tools=all, which inflates every session and subagent spawn with the full Atlassian suite. Auth happens later via/mcpOAuth (a human step). Data Center — the plugin's default
atlassianentry (Cloud remote server) will not reach their JIRA. Replace it in the consumer's.mcp.jsonyourself — keep the nameatlassian(the audit and evidence hooks match on it):"atlassian": { "command": "uvx", "args": ["mcp-atlassian==0.23.1"], "env": { "JIRA_URL": "https://jira.<their-company>.tld", "ENABLED_TOOLS": "jira_get_issue,jira_search,jira_create_issue,jira_update_issue,jira_add_comment,jira_get_transitions,jira_transition_issue,jira_batch_get_changelogs,jira_get_project_issue_types,jira_get_create_fields,jira_download_attachments" } }ENABLED_TOOLS(since 0.10.0) shrinks the tool surface from 98 tools (incl. the whole Confluence suite) to the 11 the blueprint's flows actually call — tool schemas ride in every session AND every subagent spawn, so this is the single biggest baseline saving on DC. Jira attachment upload does not exist in this server (download/images only); evidence files are attached per the project's report format, not via MCP. Addconfluence_*tools back only if a project genuinely documents in Confluence.Uses
sooperset/mcp-atlassian(Jira DC v8.14+). Auth is a Personal Access Token the human creates in their JIRA profile. Preferred storage (≥ 0.5.0): the macOS login keychain, serviceJIRA_PAT_<jira-host>— the session-start hook resolves it into the session via$CLAUDE_ENV_FILE, so the token lives in no file and no global shell export:security add-generic-password -s JIRA_PAT_jira.<their-company>.tld -a jira -wFallback (non-macOS, CI): export
JIRA_PERSONAL_TOKENin the environment — the hook skips keychain resolution whenever the variable is already set. Either way the token goes never into.mcp.json, the repo, or the chat. Tell them this explicitly. Note: the plugin's own (Cloud)atlassianentry stays configured alongside — Claude Code does not override same-named plugin servers, it runs both; the dead Cloud entry is harmless, and the audit hook's matcher covers both namespaces.
Browser mode: ask together with the JIRA question
Ask the user: browser visible (headful) or headless? Headful lets them
watch the agent work; headless is the safe default (and mandatory for
unattended claude -p/CI runs — no display). The answer is not an MCP edit:
the plugin's playwright entry hard-references the consumer-owned preference
file .playwright-mcp.config.json (seeded on first session start). Write the
answer into it yourself:
- headful → set
"launchOptions": { "headless": false } - headless / no answer → keep the seeded default (
"headless": true)
The server reads the file at launch, so edits apply after a restart. Anything
else Playwright MCP can configure (persistent profile via "isolated": false,
viewport, browser channel) lives in the same file — preferences belong there,
never in a second same-named MCP server entry. Contract vs. preference:
docs/rules/testing/playwright-mcp.md.
If the target folder holds its own git repos (e.g. S/skp/, S/wdio/ …)
The consumer folder becomes the QA home (projects/, memory/, evidence/
live there). Nothing in the blueprint requires that folder to be a git repo —
if the user does not want it versioned (or wants no remote), skip this
section entirely and leave the folder untracked. If versioning IS wanted,
the product repos inside must stay independent — before the first commit:
git init
printf '<subrepo1>/\n<subrepo2>/\n' >> .gitignore # every subfolder that is its own repo
git add . && git commit -m "QA home: blueprint data"Never git add a nested repo without the ignore entry — embedded repos become
gitlinks and the QA data turns unrecoverable noise. The products' repos are
referenced read-only from each product's PRODUCT.md (App repo field) during
/onboard-product.
Verify
claude plugin details qa-agent-blueprintExpected inventory: Skills (33), Agents (9), Hooks (4)
(SessionStart/Stop/PreToolUse/PostToolUse), MCP servers (2).
Skill usage and profiles — /skill-review
After the first runs, /skill-review reports which skills the sessions
actually used (used) and for which no skills_used data exists (unknown —
never "unused"; with no data at all coverage is 0%). It is read-only and
deactivates nothing. A skill profile (full/standard/minimal/custom) is
proposed as a dry-run naming the exact exclude list, and applied only
after the user's explicit confirmation of that concrete proposal and only
in an integrate installation. The plugin never deactivates skills, and nothing
is ever applied automatically — when a user asks for a slimmer install, hand
them the dry-run and wait for the confirmation.
Alternative: clone + installer
When the user wants the repo locally (to read or hack on the code they run):
git clone https://github.com/Sn4kyGit/qa-agent-blueprint.git ~/qa-blueprint
~/qa-blueprint/install.sh --mode plugin --target <consumer-repo> --yesSame result, sourced from the local checkout; updates are a git pull.
Full walkthrough incl. a no-clone settings.json variant:
docs/quickstart-plugin.md.
Steps that need the human — say so explicitly
No secrets in the chat — ever. Never ask the user to paste a PAT, password
or API key into the conversation (transcripts keep it). Point them at the
keychain command instead (security add-generic-password … — macOS prompts
with hidden input) or the GUI dialog (resolve-secrets.sh --capture). The
steps that genuinely need a human are the ones that need a browser or a typed
credential:
- JIRA auth — Cloud:
/mcp→ authorize atlassian (OAuth browser flow). Data Center: the human creates a Personal Access Token in their JIRA profile and stores it in the macOS keychain (JIRA_PAT_<jira-host>; non-macOS/CI: exportJIRA_PERSONAL_TOKENin the shell). An agent cannot do either. - Fill
.env.playwright-secretswith test-user credentials (created as a placeholder on first session start; values are masked in transcripts) — typed into the file or the keychain dialog, never into the chat. - Browser mode (headful/headless) — answer the question from setup/the wizard, or accept the headless default (see "Browser mode" above).
- Run
/onboard-project— needs the JIRA project key, the deployment kind (cloud/datacenter), and the stage URL. - Shadow mode is ON by default: the agent composes JIRA comments but posts
nothing until the user writes
Shadow mode: offin the project file or setsQA_AGENT_SHADOW=0. Mention this before the first/test-ticket. - Secret reads stay blocked by default (0.11.0): the guard refuses
cat .env& co. unless a human writes{"secrets_read": "allow"}into the QA home's.qa-guard.json— the guard refuses agent edits to that file (an agent that can edit it can grant itself access), so never offer to flip it; point the human at it. Writes/copies/sed -i/rmon.env*stay blocked even with allow. The value-free paths need no toggle:node .claude/scripts/qa-secrets.mjs run <KEY…> -- <runner>(test-runner injection with output redaction; needs Node ≥ 20.12) and theqa-secrets.mjs mcpwrapper (ephemeral--secretsmask file — installer and session scans treat such playwright entries as secrets-wired).
Do NOT
- Do not copy
.claude/contents into the consumer repo by hand — that is what the plugin mechanism replaces (integrate mode exists, but only on explicit user request:install.sh --mode integrate). - Do not add MCP servers beyond the declared two; the register is deliberate.
Updating an existing install
claude plugin marketplace update qa-agent-blueprint-marketplace
claude plugin update --scope project qa-agent-blueprintRestart Claude Code afterwards. CHANGELOG.md lists what changed; releases
are SemVer git tags (qa-agent-blueprint--v*). If an update misbehaves,
claude plugin uninstall + reinstall pins you back, and the project's own
data (projects/, memory/, evidence/) is never touched by updates.
Rollback
claude plugin uninstall qa-agent-blueprint
claude plugin marketplace remove qa-agent-blueprint-marketplace(Clone path: the installer's --uninstall supports integrate|opencode|shared
modes only. For plugin mode, use claude plugin uninstall +
claude plugin marketplace remove above — they remove the same settings keys.)
opencode: wrong target folder? Move, don't re-onboard
opencode commands are per-folder — they exist only where the installer
linked them. If a user picked the fresh ~/qa-workspace but actually wants
the commands inside their project workspace (a classic: option 1 instead of
option 2 at the "Installationsziel" question), do NOT re-install and
re-onboard — move the QA home, data included:
~/qa-blueprint/install.sh --mode opencode --target <old-folder> \
--move <project-workspace> --yesMoves projects/, memory/, evidence/, seed files and the merged
opencode.json, links the surface in the new folder, unlinks the old.
Never overwrites existing names in the new folder (reported SKIPPED, left
for a human merge). Installing into several folders is allowed — but each is
then a separate QA home with its own learnings; say that trade-off out
loud before doing it.
QA home resolution (walk-up, since 0.9.1)
Hooks and the opencode plugin resolve the QA home by walking up from the
session cwd to the nearest .qa-home marker (written at bootstrap) or the
legacy trio (projects/ + memory/ + evidence/), stopping at $HOME.
Data always lands at that root — never duplicated into a subfolder (field
report: a session in KPS-Development/test-automation/ scaffolded a second
copy of everything). Harness-scoped files (opencode.json/.mcp.json,
.env.playwright-secrets, .playwright-mcp.config.json) stay with the
session cwd — the harness reads them from where it started.
If you are developing on this repo
opencode port: the dual-harness plan (Claude Code + opencode, model-agnostic,
TDD phasing) lives in docs/opencode-port-plan.md. Read it before touching
anything under opencode/; its decision log (§7) is authoritative for the
port's open questions.
After any change, run the fixture battery and the manifest validator. After any
change to rules, skills, or the router, also run the behavioral evals and
update the norm→test matrix (evals/COVERAGE.md) if you touched a norm:
for t in .claude/hooks/tests/*.sh; do bash "$t"; done # "within budget" + 16x "all fixtures passed"
claude plugin validate .
bash evals/run.sh # behavioral gate: exit 1 below 0.9
# or billed per-token via OpenRouter instead of subscription quota (key in
# gitignored evals/.env.openrouter; see evals/README.md → "Billing via OpenRouter"):
bash evals/run-openrouter.shopencode-side equivalents (single entry: bash opencode/tests/run-all.sh =
bun unit tests + the bash battery above):
bash opencode/tests/run-all.sh # bun test opencode/tests + fixture battery
QA_EVAL_MODEL=openrouter/<provider-id> bash evals/run-opencode.sh # opencode behavioral gate
# (models are never defaulted — QA_EVAL_MODEL/QA_JUDGE_MODEL or --model flags; D6)Eval cost discipline: during development run only the cases whose norms you
touched (evals/COVERAGE.md maps norm → case); the full gate is a pre-release
step. Eval sessions strip MCP servers by default (--with-mcp opts back in) —
see evals/README.md → "Cost discipline".
Releasing: bump version in BOTH .claude-plugin/plugin.json and
.claude-plugin/marketplace.json (they must agree — manifest-conventions.sh
checks this early), add the CHANGELOG.md entry, commit, then update
smoke-test before tagging: in a scratch consumer, install the previous
release, run claude plugin marketplace update qa-agent-blueprint-marketplace
claude plugin update --scope project qa-agent-blueprint, and verifyclaude plugin detailsshows the new version with the full inventory (the 0.2.0 duplicate-hooks bug only ever appeared on update+restart, never invalidate). Thenclaude plugin tag --push -m "%s". The tag command validates manifest agreement and refuses a dirty tree. Finally create the GitHub release. The release notes are reader-friendly prose, not the raw changelog: one-sentence headline, then "Warum" (the problem in plain language), "Was sich ändert" (what the user notices), "Außerdem" (minor items), upgrade commands. German, spickzettel tone — the audience is the team, not the maintainer:
gh release create qa-agent-blueprint--v<X.Y.Z> --title "<X.Y.Z> — <headline>" --notes-file /tmp/relnotes.mdDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

