Agentic QA Core — Foundation reference host

agentic-qa-core is the shared reference library that every workflow skill in this repo cites. It exists so doctrine (briefing template, dispatch patterns, orchestration rules, skill composition tiers) lives in one place instead of being duplicated across every SKILL.md.

Loading a workflow skill (e.g. shift-left-testing, sprint-testing, test-automation) implies loading the relevant agentic-qa-core/references/*.md on demand — workflow skills declare a ## Dependencies block at the top so the AI knows what to pull in.

This skill does NOT orchestrate workflows, does NOT generate files, and does NOT bootstrap a target repo. The entire framework (skills, foundation files, scripts) ships together as one repo; à la carte adoption is not supported — see "Install model" below.

Compact Rules

• DO NOT create, modify, or delete ANY file while acting as agentic-qa-core. It is a passive reference library with no write path of its own.
• DO NOT write .context/ artifacts here (that is /project-discovery), scaffold tests / fixtures / KATA components (that is /test-framework-adaptation and /test-automation), adapt the framework to a stack (/test-framework-adaptation), or sync OpenAPI schemas (bun run api:sync).
• DO NOT orchestrate a workflow or bootstrap a target repo from this skill. It hosts doctrine; the workflow skills execute it.
• WHEN a workflow skill cites agentic-qa-core/references/*.md: load ONLY the files that skill's ## Dependencies block names. Never preload the whole reference set.
• WHEN deriving test cases or coverage from acceptance criteria in ANY testing skill: references/test-design-doctrine.md is mandatory reading first.
• WHEN filing any bug / defect / improvement: references/defect-management-doctrine.md is mandatory reading first.
• DO use every credential, token or session file by NAME only (Critical Rule #1): NEVER open .env* (except .env.example and the committed .env*.schema files), .auth/** or .claude/settings.local.json, NEVER run printenv / env / echo $SECRET / set -x / curl -v, check presence with bunx varlock load --agent and only against the committed schemas (vars:schema:check green; a scratch schema is banned, since --agent redacts only @sensitive items), write a non-sensitive value the human asked for ONLY with bun run env:set KEY=value (never by editing .env), and leave every secret value for the human to type. Forms, presence check and leak protocol: references/secret-hygiene.md.
• WHEN dispatching a subagent: use the 7-component briefing in references/briefing-template.md and pick the pattern via references/dispatch-patterns.md. A subagent that must answer the user directly also loads references/behavioral-layer.md — it inherits no register from the orchestrator.
• WHEN a turn would end with small open items for the human (a decision, an unconfirmed assumption, an item left for later): the session the human types into (a top-level conductor, a super-conductor, an independent worker) asks ALL of them with the harness's own structured-question tool, in rounds at the tool's per-call limit until done, each with a recommended option, a free-text way out and a "Later" option; no tool or refused → a numbered list. Heavy decisions (tradeoffs, architecture, larger changes) go to the mkd deck: weight decides, never the count. A session launched by another session (its prompt carries the fleet token /<skill> <label> fleet worker: a worker, or a middle conductor) NEVER asks the human: no question tool, no mkd deck, no sweep; it sends the four escalation kinds and every blocker it cannot clear to its launcher (blocking ask, escalation, or a BLOCKED: status without a dispatch), which relays, unless the human typed that request into its own terminal or its brief grants it in writing (then it tells its launcher what it asked and the answer). Subagents and routines never ask: they list pendings in their report. Full: references/decision-elicitation-doctrine.md §0 and §7.
• WHEN closing a workflow stage: verify that stage's Definition of Done in references/stage-gates.md BEFORE advancing.
• WHEN about to ask a person to decide, or to pick between defensible options: run references/decision-protocol.md first. Search the record (session plan, .session/decisions/, ADRs, the synced ticket comments, Engram) and follow what is settled; decide a technical call inside the approved plan and report it as decided; escalate only product behaviour, a new security posture, an irreversible or outward action, and what the stage's "The person signs" column lists. An unattended routine parks those four, never assumes them.
• DO edit the owning skill's references/*.md when a rule changes, then run bun run skills:registry, then refresh the deck under packages/decks/agentic-qa-core/. That order keeps prose, registry, and decks from drifting.
• DO treat this boilerplate as clone-in-full. Copying a single skill directory in isolation leaves it without the foundation files it depends on, and it will not function.

Read full SKILL.md when: you need the full table of hosted references and who cites each one, the deck-hosting details, or the exact ## Dependencies block shape to add to a skill.

References hosted

When a skill cites one of these, it includes a Dependencies block at the top so the AI knows to load agentic-qa-core before continuing.

Core reference decks (visual, human-facing)

agentic-qa-core hosts the canonical presentations below under packages/decks/agentic-qa-core/ (published on the GitHub Pages hub; see agentic-qa-onboard for the opening protocol):

They are the human-facing mirror of the rules that live in prose across the workflow skills' references/*.md. The Naming Codex answers "how is this artifact named"; the skills-io deck answers "what does this skill need and emit"; the output-style deck answers "why does the AI talk like that". Navigate with arrow keys (naming deck: O = overview, F = fullscreen; skills-io deck: tabs + 1-9). Offer the matching deck when a user asks about naming or about how the skills chain together end-to-end.

Keep them canonical: when a rule changes, edit the owning skill's references/*.md, regenerate REGISTRY.md (bun run skills:registry), then refresh the deck in packages/decks/agentic-qa-core/ so the decks never drift from the prose source.

Dependency declaration for downstream skills

Every workflow skill that cites agentic-qa-core/references/*.md should declare it explicitly so the AI knows what to load on demand. Example block to add near the top of the skill's SKILL.md:

## Dependencies
Requires `agentic-qa-core`. Loads on demand:
- agentic-qa-core/references/briefing-template.md
- agentic-qa-core/references/dispatch-patterns.md

The block is documentation — the AI reads it and pulls the cited files. There is no automated wiring: skills are markdown, not code.

Install model

This boilerplate is designed to be cloned in full. The workflow skills under .agents/skills/ depend on foundation files that live at the repo root (AGENTS.md, .agents/, scripts/, package.json, tests/) and on shared references under agentic-qa-core/references/. Installing only a subset of skills (e.g. copying one skill directory in isolation) leaves those skills without their dependencies and they will not function.

If a downstream user has only the skills and not the rest of the repo, the supported path is to clone the full boilerplate repository and integrate it as a single unit. No per-skill scaffolding action is provided by this skill — the skill set is intentionally inseparable from the foundation.

Out of scope

agentic-qa-core does not:

• Create or modify any files. It is a passive reference library.
• Create or modify .context/ files (that belongs to /project-discovery).
• Generate or scaffold tests, fixtures, or KATA components (that belongs to /test-framework-adaptation and /test-automation).
• Adapt the framework to a specific stack (that belongs to /test-framework-adaptation).
• Sync AI-critical documents or project-specific facts in AGENTS.md (the docs follow-through of /framework-development in the boilerplate, /test-framework-adaptation Phase 9.3 in a project).
• Sync OpenAPI / API schemas (that's bun run api:sync).

For framework evolution (changes to KATA bases, fixtures, cli/, scripts/, api/schemas/ pipeline), see /framework-development.