agentleFS
Sn4kyGitSn4kyGit/qa-agent-blueprint/AGENTS.md

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

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
  1. Distinctive:

    Plugin path — two commands: Run from inside the consumer project:

    line 39
  2. Distinctive:

    Ask the user: is your JIRA Atlassian Cloud or self-hosted (Data Center)?

    line 109
  3. Very specific:

    Ask the user: browser visible (headful) or headless?

    line 160
  4. Very specific:

    Never git add a nested repo without the ignore entry — embedded repos become gitlinks and the QA data turns unrecoverable noise.

    line 190
  5. Very specific:

    After the first runs, /skill-review reports which skills the sessions actually used (used) and for which no skills_used data exists …

    line 206
  6. Distinctive:

    When the user wants the repo locally (to read or hack on the code they run):

    line 218
  7. Common:

    No secrets in the chat — ever: Never ask the user to paste a PAT, password or API key into the conversation (transcripts keep it).

    line 231
  8. Very specific:

    Run /onboard-project — needs the JIRA project key, the deployment kind (cloud/datacenter), and the stage URL.

    line 247
  9. Very specific:

    Do not copy .claude/ contents into the consumer repo by hand — that is what the plugin mechanism replaces (integrate mode exists, but only …

    line 265
  10. Distinctive:

    Do not add MCP servers beyond the declared two.

    line 268
  11. Distinctive:

    Never overwrites existing names in the new folder (reported SKIPPED, left for a human merge).

    line 307
  12. Very specific:

    After any change, run the fixture battery and the manifest validator.

    line 330

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.md while 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-marketplace

Then 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 skills

Full 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 project enables 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.git must 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, then gh auth login is the ONE step you cannot do: it opens a browser. Hand it to the human, wait, then verify with the git ls-remote check 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 atlassian entry 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 /mcp OAuth (a human step).
  • Data Center — the plugin's default atlassian entry (Cloud remote server) will not reach their JIRA. Replace it in the consumer's .mcp.json yourself — keep the name atlassian (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. Add confluence_* 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, service JIRA_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 -w

    Fallback (non-macOS, CI): export JIRA_PERSONAL_TOKEN in 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) atlassian entry 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-blueprint

Expected 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> --yes

Same 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:

  1. 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: export JIRA_PERSONAL_TOKEN in the shell). An agent cannot do either.
  2. Fill .env.playwright-secrets with 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.
  3. Browser mode (headful/headless) — answer the question from setup/the wizard, or accept the headless default (see "Browser mode" above).
  4. Run /onboard-project — needs the JIRA project key, the deployment kind (cloud/datacenter), and the stage URL.
  5. Shadow mode is ON by default: the agent composes JIRA comments but posts nothing until the user writes Shadow mode: off in the project file or sets QA_AGENT_SHADOW=0. Mention this before the first /test-ticket.
  6. 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/rm on .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 the qa-secrets.mjs mcp wrapper (ephemeral --secrets mask 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-blueprint

Restart 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> --yes

Moves 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.sh

opencode-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 verify claude plugin details shows the new version with the full inventory (the 0.2.0 duplicate-hooks bug only ever appeared on update+restart, never in validate). Then claude 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.md

Download now (ZIP)

Does 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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.