create-agentic-qa

Official scaffolder for the Agentic QA ecosystem. Downloads the boilerplate template, scrubs git history, initializes a fresh repository, installs dependencies, and runs the interactive installer.

Usage

bunx create-agentic-qa my-app

That single command:

1. Downloads upex-galaxy/agentic-qa-boilerplate (latest main) as a tarball.
2. Extracts into ./my-app/ (no git history).
3. Rewrites package.json name + .agents/project.yaml project.project_name (and project.project_key when --project-key is passed).
4. Initializes a fresh repository on main and creates the initial commit.
5. Runs bun install.
6. Hands off to the boilerplate's interactive installer (bun run setup), which runs cli/doctor.ts --preflight first, then wires Engram memory, agent skills, MCPs, .env, and — at the end — optionally creates a GitHub repository for you via gh.

Interactive menu

Run the CLI with no positional argument in a TTY (or pass --menu explicitly) and you get an interactive launcher instead of going straight to scaffold:

bunx create-agentic-qa            # no args + TTY → menu
bunx create-agentic-qa --menu     # force menu even when args are present

The menu offers these options:

| Option | What it does | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Create a new project | Prompts for a project name, sanitizes it, then runs the normal scaffold flow. | | Check prerequisites | Runs the scaffolder's doctor (see below) and returns to the menu. | | What will this install? | Runs inspect (see below) — a manifest-driven tour of every skill, MCP, file and auth step the downstream installer will touch. | | Quit | Exit without doing anything. |

Suppress the ASCII banner with --no-banner (useful for CI or piped output).

Doctor — pre-clone system checks

The scaffolder's doctor verifies a short list of universal prerequisites before you clone anything. This is intentionally a thin layer — the boilerplate's own installer (bun run setup, invoked at the end of this CLI) has a much bigger cli/doctor.ts that handles agent CLIs, Engram, MCP credentials and the per-skill binary matrix. See INSTALLER.md for the downstream version.

The checks, as src/doctor.ts defines them:

| Check | Required | Why | | ------------- | -------- | --------------------------------------------------------- | | bun | yes | Runs this CLI, bun install, and bun run setup. | | git | yes | git init + initial commit on main (skipped on --no-git). | | node >= 18 | yes | Some downstream tools shell out to a Node 18+ runtime. Probes the real binary — under bunx, process.versions.node is emulated by Bun and would pass on a machine with no Node. | | gh | optional | Needed only for --github-create at the end of setup. | | internet | yes | Reaches api.github.com to fetch the template tarball. | | disk space | optional | Warns if less than 200 MB free in the current directory. |

The doctor is reachable from the interactive menu. There is no standalone CLI flag — if you need machine-readable output, parse the menu run or use the downstream bun run setup:doctor.

Inspect — what will the installer actually touch?

The inspect view is a read-only walkthrough driven by src/installer-manifest.json. It answers "what is this thing going to do to my machine?" before you commit to running it.

The view renders these sections:

1. Prerequisites — every binary the downstream installer expects, with a live present / MISSING / n/a status next to it.
2. Will install — Engram memory, community project-level skills, and community user-level skills (a count and the first few of each, with a drill-down prompt to expand any category).
3. Will configure — MCP servers (with the .env keys each one reads), .env files written or updated, authentication services, and the non-interactive vs interactive post-install steps.
4. Will NOT install — services and CLIs you handle yourself, each with a one-line docs pointer.
5. Drill-down — pick any of the three skill categories to print its full list; loop back into the inspect view until you choose "Back to menu".

Inspect is purely informational — it does not write to disk, hit the network beyond a binary probe, or modify any project state.

In-repo mode

If you already cloned agentic-qa-boilerplate manually, you can run the CLI inside that folder:

cd existing-clone
bunx create-agentic-qa --here

The CLI detects the .template/installer.lock.json sentinel, skips the download stage entirely, and jumps straight to the installer.

What you get

A ready-to-use QA project wired for:

• Playwright + KATA + TypeScript test architecture (Layer 1-4 fixtures).
• Skills-based AI workflows — invoke /agentic-qa-onboard for a tour, /project-discovery to reverse-engineer your target app, /test-framework-adaptation to wire KATA fixtures to your stack, /shift-left-testing for pre-sprint AC refinement on backlog Stories, and /sprint-testing for per-ticket in-sprint manual QA.
• MCPs preconfigured for all three harnesses: the servers the template's .mcp.json declares, mirrored in opencode.jsonc and .codex/config.toml; bun run setup records the harnesses you select and, if you accept its offer, deletes the other harnesses' files.
• Allure + Xray reporting — pre-wired Allure reporter and bun xray CLI for syncing automated runs back to your test management system.

Flags

| Flag | Default | Description | | ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | <project-name> | (required) | Target directory name. Required unless --here is passed or you are in a TTY (menu will prompt). | | --here | off | Bootstrap into the current directory; or, if already inside a bootstrapped project, skip download and run setup only. | | --template <ref> | main | Branch / tag / SHA of the template repo to download. | | --template-repo <owner/repo> | upex-galaxy/agentic-qa-boilerplate | Override the upstream repository (useful for forks). | | --project-key <KEY> | (prompted) | Jira project key (e.g. UPEX). Optional — leave blank to fill in later. | | --no-install | off | Skip bun install. | | --no-setup | off | Skip bun run setup — only download + git init. | | --no-git | off | Skip git init + initial commit. | | --non-interactive | auto on no-TTY | Forwarded to the installer. Prompts use safe defaults. | | --menu | off | Force the interactive menu even when a project name is provided. | | --no-banner | off | Suppress the ASCII banner (useful for CI / piped output). | | --help, -h | | Print help and exit. | | --version, -v | | Print CLI version and exit. |

Examples

# Standard scaffold
bunx create-agentic-qa my-app

# Scaffold with the Jira project key pre-filled
bunx create-agentic-qa my-app --project-key ACME

# Bootstrap into the current directory (or resume setup inside an existing clone)
bunx create-agentic-qa --here

# Use a fork of the template
bunx create-agentic-qa my-app --template-repo my-fork/agentic-qa-boilerplate

# Pin to a specific tag or SHA
bunx create-agentic-qa my-app --template v0.5.0

# Open the interactive menu even though arguments are provided
bunx create-agentic-qa my-app --menu

# CI-friendly: no banner, no prompts
bunx create-agentic-qa my-app --no-banner --non-interactive

# Download only — skip install and setup
bunx create-agentic-qa my-app --no-install --no-setup

Requirements

The scaffolder itself needs only a small set of CLIs. The downstream installer (bun run setup) — which this scaffolder invokes by default — has a larger prerequisite list. Both are documented here so you do not get stopped mid-flow.

For the scaffolder itself (this CLI)

| Tool | Min version | Required for | Where it is checked | | ----- | ----------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | | bun | any | Running bun install + handing off to bun run setup | src/runners.ts (ensureBunAvailable) — exit 10 if missing | | tar | any | Extracting the template tarball. GNU tar or bsdtar, either works | src/download.ts — exit 10 if missing | | git | any | git init + initial commit on main (skipped with --no-git) | src/runners.ts (ensureGitAvailable) — exit 10 if missing | | node | engines.node in package.json | Running this CLI under npx | Reported by Check prerequisites in the menu | | gh | any | Optional — creating a GitHub repository at the end of bun run setup | Verified inside the boilerplate installer, not by this CLI |

Windows: PowerShell and cmd are supported; WSL and Git Bash work but are not required. Install Bun via powershell -c "irm bun.sh/install.ps1 | iex" rather than npm i -g bun — the npm route writes only a bun.cmd shim, which this CLI then has to launch through cmd.exe. tar needs no install: Windows 10 1803+ and Windows 11 ship bsdtar at C:\Windows\System32\tar.exe.

WSL: scaffold onto the Linux filesystem (~/projects/...). On a /mnt/c path Bun cannot create its bin shims, and bun install fails with could not open bin metadata file.

For bun run setup (the boilerplate's interactive installer this CLI hands off to)

Hand-off happens unless you pass --no-setup. The boilerplate installer enforces these additional preconditions:

| Tool | Min version | Why | Behavior on miss | | --------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Agent — Claude Code, OpenCode or Codex | latest | Step 4-agent-detect finds the config directory, the binary on PATH, or .codex/config.toml; exits 1 only when none is found. | Hard exit 1 with every harness's docs URL. Install Claude Code, OpenCode or Codex before re-running. | | engram | MIN_ENGRAM_VERSION in the template's cli/install.ts | The Engram persistent-memory binary; the installer wires it into each selected agent with engram setup. Optional: skipping it only turns cross-session memory off. | Warns + offers the install commands and the docs URL; you can continue without it or exit and install. | | Per-skill CLIs | latest | Each one is required by a specific skill; the list, with the owning skill and an install hint, is EXTERNAL_CLIS in the template's cli/install.ts. Missing ones are reported, never blocking. | Non-blocking — step 11-verify-clis prints a status table with quick: install commands (where cross-platform) and a docs: URL per missing CLI. Install on-demand when the owning skill surfaces a missing-binary error. | | MCP credentials | — | The .env keys the MCP configs reference. The installer discovers them from the .env loader's --filter list in each selected harness's config and prompts for the missing ones. | Non-blocking — bun run setup:doctor lists pending vars with where URLs (token-generation pages) until you fill them. |

The scaffolder prints actionable install hints up front for its own requirements (bun, tar, git). For the boilerplate-side preconditions above, see the unified Prerequisites section in the parent README and the more detailed INSTALLER.md → Before you run setup contract.

Exit codes

| Code | Meaning | | ---- | ---------------------------------------------------------------- | | 0 | Success | | 2 | Usage error (missing name, conflicting flags) | | 10 | Environment error (no bun / no tar / no git) | | 11 | Network error (template download failed) | | 12 | Target directory already exists and is not an agentic-qa project | | 20 | Bootstrap error (extract / scrub / git init failed) | | 30 | bun install failed | | 31 | bun run setup failed | | 130 | User cancelled (Ctrl+C) |

Troubleshooting

The menu opens when I just want to scaffold. Pass a project name as the first positional argument: bunx create-agentic-qa my-app. The menu only opens when there is no project name and you are in a TTY (or when you pass --menu explicitly).

Doctor says gh is missing but I do not need it. gh is optional — it is only required if you opt into --github-create at the end of bun run setup. A warn row on gh will not block the scaffold.

Inspect says a prerequisite is MISSING but doctor was happy. Inspect uses the manifest's prerequisite list (everything the downstream installer touches), while doctor only checks the universal prerequisites the scaffolder itself needs. The wider list is expected to surface more gaps.

ASCII banner mangles my CI logs. Pass --no-banner to suppress it. Combine with --non-interactive to also disable prompts and the menu.

Network error (exit 11) on a corporate network. The scaffolder reaches https://codeload.github.com/... for the tarball and https://api.github.com for the doctor's internet check. If either is blocked, set the standard HTTPS_PROXY env var before running.

Local development / testing without npm publish

git clone https://github.com/upex-galaxy/agentic-qa-boilerplate
cd agentic-qa-boilerplate/packages/create-agentic-qa
bun install
bun run build

# Symlink the bin globally:
bun link

# Anywhere else on your machine:
create-agentic-qa test-app

To run directly from source without building:

bun run src/cli.ts test-app

Releasing a new version to npm

Publishing is manual — there is no release workflow in .github/workflows/. The package is owned by a single npm account, so whoever publishes needs to be logged in as an owner (npm owner ls create-agentic-qa lists them).

The ordering that matters

This package and the template it downloads ship separately, and the scaffolder fetches the template from GitHub main at runtime rather than bundling it. So a change to the boilerplate itself (package.json scripts, cli/, skills, docs) reaches users the moment it lands on main — no publish involved. Only changes under packages/create-agentic-qa/ need npm.

When one release touches both, push the template first. Publishing a scaffolder that expects template changes which are not yet on main breaks every scaffold until the push lands.

Steps

# 1. From the repo root — the whole suite must be green before you publish.
bun run repo:check

# 2. Package-level gates.
cd packages/create-agentic-qa
bun test
bun run types:check
bun run check:manifest      # installer-manifest.json must not have drifted

# 3. Bump the version. Semver against the PUBLISHED version, not the file:
#    npm view create-agentic-qa version
#    patch = bug fix · minor = new flag or behaviour · major = breaking CLI change
npm version patch --no-git-tag-version

# 4. Record the change in the root CHANGELOG.md (move the relevant
#    "Unreleased" entries under the new version heading).

# 5. Commit, then push the TEMPLATE side first if this release depends on it.
git add -A
git commit -m "chore(create-agentic-qa): bump to X.Y.Z"
git push origin main

# 6. Publish. `prepublishOnly` runs `check:manifest` + `build` for you.
npm login                   # if `npm whoami` errors with 401
npm publish

# 7. Tag the release.
git tag create-cli-vX.Y.Z
git push origin create-cli-vX.Y.Z

# 8. Verify what actually went out.
npm view create-agentic-qa version
cd "$(mktemp -d)" && bunx create-agentic-qa@latest smoke-test --no-setup

What ends up in the tarball

files is ["README.md", "dist"], so the published package holds only README.md, dist/cli.js and package.json. Nothing under src/, tests/ or scripts/ ships; dist/cli.js is the bundled build of all of them.

Gotcha: npm pack --dry-run does not rebuild

prepublishOnly is what regenerates dist/cli.js, and only npm publish runs it. npm pack --dry-run packs whatever dist/cli.js is already on disk — which is gitignored, so it can be weeks stale and predate the very fix you are shipping. To inspect the real contents before publishing, build first:

bun run build && npm pack --dry-run

License

MIT — same as the parent repo.