| name | project-discovery |
| description | Onboard a project to this testing boilerplate and generate the context files that every QA and automation session depends on. Runs a 4-phase discovery (Constitution, Architecture, Infrastructure, Specification) that produces PRD, SRS, domain glossary, business-data-map, and test-ready fixtures. Use when the user says: set up this project, onboard this repo, connect to project, discover the architecture, generate business-data-map, or create PRD/SRS. Also use when .context/business/business-data-map.md is missing or stale. Do NOT use for writing tests (test-automation), documenting TCs (test-documentation), running suites (regression-testing), testing a ticket (sprint-testing), adapting the KATA architecture to the target stack (that is `/adapt-framework`), or syncing API endpoints (use `bun run api:sync` for technical sync; the `/business-api-map` command for the business angle). |
| license | MIT |
| compatibility | ["claude-code","copilot","cursor","codex","opencode"] |
| complementary_categories | ["meta-skill"] |
Project Discovery — Onboarding Orchestrator
Turn an unknown codebase into a testable project. Four phases, always in order, gated on completion of the previous one. The output is a set of context files the rest of the skills (shift-left-testing, sprint-testing, test-automation, test-documentation, regression-testing) rely on.
The discovery is conversational: you read the code, ask when ambiguous, confirm before writing files. Never fabricate -- if you cannot verify a claim from the source, mark it as a "Discovery Gap" and move on.
Grounding methodology: IQL (Integrated Quality Lifecycle) — QA is continuous from requirement to release, not a gate at the end. The full rationale and step breakdown live in docs/methodology/IQL-methodology.md (shared across all QA skills). This skill does not depend on reading it — only point the user there if they ask why the discovery is structured this way.
Inputs
Canonical reading order when starting cold on a discovery run. Read in order; stop earlier when the scope is small enough that later inputs add no signal.
- Target project repo — path resolved at session start (see "Before starting: target repo location" below). Read code and any in-repo PRD. This is the primary source of truth — discovery is reverse-engineering, never aspirational design.
- Target repo's
README.md and existing onboarding docs — fastest path to project intent, stack signals, and run commands before deep code reads.
.context/ directory (if partial state exists from a prior discovery run) — informs Phase 0 resume decisions and prevents redundant work. Diff against current code before overwriting..agents/project.yaml and .env.example — variable resolution patterns ({{PROJECT_KEY}}, env URLs, MCP names) that every downstream context file references.kata-manifest.json — registry of existing KATA Components + ATCs. Anchors what test surface the boilerplate already expects so discovery records gaps coherently..claude/skills/agentic-qa-core/references/skill-composition-strategy.md — workflow context for downstream skill hand-offs (/adapt-framework, /sprint-testing, /test-documentation).- Business / domain docs supplied by the user (Confluence, Notion exports, internal wikis) — secondary source for business model and glossary when in-repo signal is thin.
Subagent Dispatch Strategy
Orchestration & Session contracts: this skill follows ./orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND ./session-management.md (Phase 0 resume check, plan-first persistence at .session/<skill-slug>/<scope>/, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional.
This skill is project-scope: no <scope> segment. Session state lives directly at .session/project-discovery/{plan.md, progress.md} per agentic-qa-core/references/session-management.md §3 + §9. This is the longest skill in the QA repo (1.5–4 hours, 4 hard-gate phases) and benefits most from per-phase checkpoints: if interrupted between Phase 2 (PRD/SRS) and Phase 3 (Infrastructure), resume reads progress.md and skips back to the first incomplete phase without re-prompting the user for already-confirmed scope.
This skill is compliant with the doctrine in CLAUDE.md §"Orchestration Mode (Subagent Strategy)" and the session contract in .claude/skills/agentic-qa-core/references/session-management.md. Per-phase dispatch decisions live in Pick the scope first below: Fresh = heavy subagent delegation per phase; Boilerplate adoption = medium; Brownfield + Context refresh = main session only.
Phase 0 — Session resume check (MANDATORY, inline)
Before scope selection or any target-repo discovery, run the resume contract from agentic-qa-core/references/session-management.md §4:
- Check
.session/project-discovery/progress.md.
- If it does NOT exist → proceed to "Before starting: target repo location" below, then "Pick the scope first" (which writes
plan.md).
- If it DOES exist:
- Read
plan.md (chosen scope, target repo path, phase plan).
- Read tail of
progress.md (last completed phase + next planned phase).
- Surface to the user: scope chosen, target repo, last completed phase, next phase, any open Discovery Gaps from the last entry.
- Offer resume / restart / abort. On
restart, archive to .session/.archive/<YYYY-MM-DD>-project-discovery-aborted/ before proceeding.
Resume is high-value here: Fresh onboarding (1.5–4h) crossing a session boundary without resume re-runs Phase 1 from scratch, re-prompting target paths the user already confirmed.
Before starting: target repo location
/project-discovery runs read-only against a project under test — the target repo — that is NOT this boilerplate. Before Phase 1 starts, lock down where the target lives. Block Phase 1 if the target path is ambiguous.
| Layout | What to declare | How to detect |
|---|
| Monorepo (single repo contains FE + BE) | Absolute or relative path from this repo | Check the candidate path for pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or a top-level package.json with no deps of its own |
| Split sibling repos (FE and BE cloned separately) | One path per repo (or a common parent dir) | Look at ../-level siblings with plausible names (*-backend, *-frontend, *-api, *-web); confirm with the user |
| Remote (not cloned yet) | Repo URL + branch, then ask the user to clone locally before Phase 1 | gh repo view only returns metadata; real discovery needs local file access — do not try to discover from a URL |
Record the resolved path(s) in .context/project-config.md §Repositories during Phase 1 sub-step 1 (Project Connection). Every <target-repo> reference in later phases resolves to the path declared here.
If the layout is "split sibling repos", run Phase 1 sub-steps once per repo and merge findings into a single project-config.md; do not interleave.
Pick the scope first
All projects go through the same 4 phases, but depth varies. Pick once, then follow the common pipeline.
| Scenario | Input | Phases to run | Typical depth | Context weight & subagent hint |
|---|
| Fresh onboarding (greenfield or unseen project) | Repo URL or local path(s), no existing context files | 1 -> 2 -> 3 -> 4 -> Context generators | Full. All docs generated. After discovery complete, run /adapt-framework to modify the boilerplate. | Heavy. Delegate each phase's code survey to a dedicated subagent (Phase 1 project-connection + assessment, Phase 2 PRD/SRS drafting, Phase 3 infra mapping). Main session orchestrates, reviews outputs, and gates user confirmation between phases. |
| Boilerplate adoption (this repo adopted for a new project) | Target app repo(s), this repo as the test framework | 1 (project-connection) -> 3 -> Context generators | Skipping Phase 2 or Phase 4 is allowed only if every required input for /adapt-framework is already on disk: .context/SRS/architecture.md, .context/business/business-data-map.md, one of (api/openapi-types.ts non-stub / reachable OpenAPI spec URL / .context/business/business-api-map.md), plus .context/infrastructure/{backend,frontend}.md. If any is missing, fall back to the corresponding phase before invoking /adapt-framework. Do not skip phases on a hand-wave like "the docs exist elsewhere" — verify each file is on disk first. | Medium. Delegate Phase 1 project-connection + Phase 3 infra mapping to a subagent if the target is a monorepo (one subagent per package). Main session stays lean for /adapt-framework handoff. |
| Brownfield (project already documented, tests missing) | Existing .context/ partially filled | 2 (gaps) -> 3 (gaps) -> Context generators | Targeted. Only regenerate what's missing/stale. | Light. Run in main session unless gaps span many files — then delegate the gap-filling pass per phase to a subagent. |
| Context refresh (data-map only) | User says "regenerate business-data-map" / "refresh the entity map" | Context generators only (just business-data-map.md) | One-file refresh. Confirm diffs before overwriting. For PBI template refresh (tracker moved, new custom fields), re-run Phase 4 in full instead — this scope handles data-map updates only, not templates. For the test plan, redirect to /master-test-plan. For API endpoints, redirect to bun run api:sync (technical) or /business-api-map (business angle). | Minimal. Main session only. No delegation needed. |
Default to "Fresh onboarding" when in doubt. Confirm the scope with the user before starting Phase 1.
After scope confirmation, write .session/project-discovery/plan.md per agentic-qa-core/references/session-management.md §6 schema — Goal (the scope picked + target repo + expected outputs), Inputs (target repo path(s), existing .context/ files), Approach (per-phase dispatch pattern per the table above), Phase breakdown (1 → 2 → 3 → 4 → Context generators with skip rules per scope), Risks & open questions, Verification checklist (the pre-adapt-framework bullets below), Cross-references (cites .context/business/, .context/PRD/, .context/SRS/, .context/infrastructure/, .context/PBI/). Append ## Phase 0 — Session Init — <ts> with status: completed, next: Phase 1 — Constitution to progress.md.
Workflow — the 4-phase pipeline
Phase 1: Constitution -> Phase 2: Architecture -> Phase 3: Infrastructure -> Phase 4: Specification
(who/what/why) (PRD + SRS) (backend/frontend/infra) (PBI mapping)
| | | |
.context/business/ .context/PRD/*.md .context/infrastructure/*.md .context/PBI/README.md
business-model.md .context/SRS/*.md templates/*.md
domain-glossary.md
project-config.md
|
v
Context Generators
(.context/business/business-data-map.md)
Test strategy (.context/master-test-plan.md) is
produced by the /master-test-plan command.
API context by `bun run api:sync` (technical) +
`/business-api-map` (business angle).
KATA adaptation is a separate command: /adapt-framework. It runs after discovery outputs exist and modifies this boilerplate's tests/, api/schemas/, and config/ against the target stack.
Each phase has a completion gate: before moving on, the required output files must exist on disk with non-placeholder content. Ask the user to confirm after each phase; never auto-chain.
Phase 1 — Constitution (who, what, why)
Goal: make the project legible. Outputs are read by every future session.
Four sub-steps, in order:
- Project Connection -- repo paths, tech stack detection, environment URLs, credentials from
.env, team contacts.
- Project Assessment -- current testing maturity (frameworks in place, CI presence, lint/typecheck, coverage). Produces a risk profile.
- Business Model Discovery -- problem statement, target users, value proposition, revenue model (if any). Business Model Canvas recommended.
- Domain Glossary -- core entities, relationships, state machines, enumerations, UI-label vs code-identifier mapping.
Completion gate: .context/business/business-model.md, .context/business/domain-glossary.md, .context/project-config.md all exist and are non-empty. Plus a ## Project Assessment (Phase 1) block in CLAUDE.md (CLAUDE.md is a symlink to it). Sanity-check content — these are soft gates, surfaced to the human as warnings, not hard aborts:
domain-glossary.md contains at least 5 core-entity subsections (grep ^### yields 5+ matches, ignoring top-level H3s from "Enumerations" etc. — aim for real entities).business-model.md cites at least one concrete source (Source: or Found in: literal appears 3+ times).project-config.md has a ## Tech Stack section AND a ## Environments section.
After the automated sanity check, show the human the output paths and wait for explicit "Phase 1 complete, continue" before moving on.
Read references/phase-1-constitution.md when running any Phase 1 sub-step. Contains the discovery process, stack-detection commands, required output sections, and quality checklists.
Phase 2 — Architecture (PRD + SRS)
Goal: produce the Product and Software Requirements docs from code (not the other way round -- that is the "creation" direction, this is the "discovery" direction).
PRD sub-steps (run first, in parallel or sequentially — user choice):
- Executive Summary -- problem, solution, success metrics, scope.
- User Personas -- roles, permissions, primary/secondary users, role hierarchy.
- User Journeys -- critical paths through the UI, route map, journey diagrams.
Feature catalog is post-discovery. The full feature inventory (.context/business/business-feature-map.md) is produced by the /business-feature-map command after all four discovery phases complete. Do not attempt to invoke it from here — it is token-heavy and the user is advised to run it in a clean session (see "Next recommended steps" at the end of this skill).
SRS sub-steps (run after PRD, serially):
- Architecture Specs -- C4 context and container diagrams, component structure, database schema, external services, security model.
- Functional Specs -- FR-N entries with preconditions, business rules, validations, state machines.
- Non-Functional Specs -- performance budgets, security posture, reliability (RTO/RPO), scalability, observability, compliance.
API contracts are NOT an SRS output. The technical surface is owned by bun run api:sync (generates api/openapi-types.ts from the project's OpenAPI spec). The business angle is owned by the /business-api-map command (.context/business/business-api-map.md). Phase 2 SRS only records where the spec lives (or flags its absence as a Discovery Gap). See references/phase-2-srs.md §2.
Test-architecture ADR seeding (Phase 2 SRS + Phase 3). When the Architecture Specs / Infrastructure sub-steps settle a hard-to-reverse test-architecture decision — test runner/framework, isolation & parallelization model, fixture/test-data strategy, auth-in-tests, selector/data-testid contract, exploratory-vs-scripted boundary, CI sharding — promote each one that passes the two-gate test (architectural AND hard to reverse) to a standalone ADR-NNNN-<slug>.md in .context/ADR/, and reference it from architecture.md / infrastructure/. Greenfield: you are ENCODING the decision; brownfield: you are RECORDING the one you discovered. Follow agentic-qa-core/references/adr-doctrine.md (detection + authoring) and .context/ADR/README.md (template + lifecycle). AI drafts Proposed; the human accepts.
Completion gate: .context/PRD/executive-summary.md, user-personas.md, user-journeys.md, .context/SRS/architecture.md, functional-specs.md, non-functional-specs.md all exist. API contract source (OpenAPI URL, api/openapi-types.ts, or "Discovery Gap — no spec") is recorded in .context/project-config.md. business-feature-map.md is produced post-discovery by /business-feature-map (see "Next recommended steps" after Phase 4). Soft content checks:
architecture.md contains at least one ```mermaid block AND one of (## Data Flow, ## Database Schema, ## Component Structure).functional-specs.md contains at least one FR- identifier and one BR- identifier.user-personas.md lists at least 2 role entries (### or table rows with role names).
Show outputs to the human and wait for "Phase 2 complete, continue" before moving on.
Read references/phase-2-prd.md when working on any PRD doc. Read references/phase-2-srs.md when working on any SRS doc. They are independent -- do not load both unless you are straddling both sides.
Phase 3 — Infrastructure
Goal: make the project runnable and deployable for the test environment.
Three sub-steps:
- Backend Discovery -- language, framework, database, ORM, auth, dependency manager, run/test commands, migrations, env vars.
- Frontend Discovery -- framework, bundler, routing, state management, design system, component library, test IDs strategy.
- Infrastructure Mapping -- CI/CD providers, deployment targets, environments (dev/staging/prod), infra-as-code, monitoring, rollback procedure.
Completion gate: .context/infrastructure/backend.md, frontend.md, infrastructure.md all exist with the key facts (auth flow, test commands, deploy URLs) filled in. Soft content checks:
backend.md AND frontend.md each contain a ## Runtime (or ## Build Configuration) section AND a commands block (bash fenced) covering install + run.infrastructure.md lists environments explicitly (| Staging | or | Production | table row).- At least one auth-flow pointer exists in
backend.md (e.g., mentions /auth/login, session, JWT, cookie, OAuth).
Show outputs to the human and wait for "Phase 3 complete, continue" before moving on.
Read references/phase-3-infrastructure.md when running any Phase 3 sub-step. Contains framework-detection heuristics, required sections per artifact, and common gotchas (SSR vs CSR, edge vs serverless, monorepo vs split repos).
Phase 4 — Specification (Backlog mapping)
Goal: hook the testing framework into the team's issue tracker without duplicating content.
Two sub-steps:
- PBI Backlog Mapping -- connect to
{{ISSUE_TRACKER}} via [ISSUE_TRACKER_TOOL], discover project key, map hierarchy (Epic/Story/Task/Bug), record queries used to fetch tickets.
- PBI Format-Reference Guides -- produce the format-reference docs (
.context/PBI/templates/user-story.md, bug-report.md, test-plan.md) that document the canonical shape of each artifact. These are reference-only — Jira is the source of truth, and per-ticket PBI content is synced from Jira, not authored locally from these.
Per-ticket PBI is NOT generated by this skill. It is materialized later by /sprint-testing via bun run jira:sync-issues get <KEY> --include-comments, which writes the canonical synced tree .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/ (Module = Epic, 1:1). Those local .md files are a READ-ONLY cache of Jira (Jira = source of truth). This skill does NOT create per-ticket story.md — it only sets up the backlog access recipe (README.md) and the format-reference guides.
Completion gate: .context/PBI/README.md exists with project key + auth recipe; .context/PBI/templates/*.md exist. Soft content checks:
PBI/README.md contains the configured {{PROJECT_KEY}} literal AND a ## Common Queries section (or JQL / WIQL snippet)..context/PBI/templates/user-story.md, bug-report.md, test-plan.md each exist and are non-empty (format-reference guides).
Show outputs to the human and wait for "Phase 4 complete" before running the context generators / emitting the Next Recommended Steps block.
Read references/phase-4-specification.md when running Phase 4. Contains issue-tracker connection recipes, query conventions, and the full template set.
Context Generators — the final deliverables
Two files, always generated last (they pull from every prior phase):
| File | Generator reference | What it contains |
|---|
.context/business/business-data-map.md | context-generators.md §Generator | System flows, entities, triggers, cron jobs, webhooks, integration points. The canonical "what this system does" map. |
.context/master-test-plan.md is not produced by this skill — the /master-test-plan command owns it (reads business-data-map.md + optional business-feature-map.md). Run it after business-data-map.md exists.
Read references/context-generators.md when (re)generating business-data-map.md. This is where most "regenerate business-data-map" user requests land.
API context is NOT a project-discovery output. Endpoint sync is delegated to bun run api:sync (technical, OpenAPI -> TypeScript types) and the /business-api-map command (business angle: auth flows, critical paths, architecture behind the API). See references/context-generators.md §API context — deferred for the deferral note.
See also: After discovery outputs exist, run /adapt-framework to adapt this boilerplate's tests/, api/schemas/, and config/ to the target stack.
Per-phase progress + Archive
After each phase passes its completion gate AND the user confirms "Phase N complete", the orchestrator appends a phase entry to .session/project-discovery/progress.md per agentic-qa-core/references/session-management.md §7. One entry per phase: Phase 1 Constitution, Phase 2 Architecture (PRD then SRS), Phase 3 Infrastructure, Phase 4 Specification, then one per Context Generator. Each entry records artifacts_touched (the .context/ files created or updated), dispatched_as (Single for Fresh-scope phases, inline for Brownfield / Refresh), next (next phase or stop).
After Context Generators land AND the Pre-adapt-framework checklist passes, the orchestrator runs Archive per agentic-qa-core/references/session-management.md §8: moves .session/project-discovery/ to .session/.archive/<YYYY-MM-DD>-project-discovery/ (two-file dir preserved) and calls mem_session_summary including the archive path so future search resolves back. The canonical .context/ deliverables stay in place — those are the discovery output, not the session state.
On Phase-gate REJECT (user marks a phase incomplete or finds a Discovery Gap that blocks), archive does NOT run. The working directory stays so resume picks up at the failing gate.
Next recommended steps (emit after Phase 4 completes)
Discovery populates PRD, SRS, glossary, and business-data-map.md. It does NOT invoke the business-context commands — they are standalone, token-heavy, and best run in a clean session so the AI has full budget.
When Phase 4 is confirmed complete, print this block to the user verbatim:
Discovery complete. `/project-discovery` has populated:
- .context/business/business-model.md, domain-glossary.md
- .context/project-config.md
- .context/PRD/executive-summary.md, user-personas.md, user-journeys.md
- .context/SRS/architecture.md, functional-specs.md, non-functional-specs.md
- .context/infrastructure/backend.md, frontend.md, infrastructure.md
- .context/PBI/README.md + templates/*.md
- .context/business/business-data-map.md
**Recommended next commands** (run each in order — ideally in a clean session; they are token-heavy):
1. `/business-feature-map` — catalog features, CRUD matrix, flags. Output: .context/business/business-feature-map.md
2. `/business-api-map` — auth model, critical endpoints, architecture behind the API. Output: .context/business/business-api-map.md
3. `/master-test-plan` — what to test and why, ranked by risk. Output: .context/master-test-plan.md
These are STANDALONE and can be re-run any time you want to refresh them.
`/project-discovery` itself is typically run once per project (or occasionally to refresh business model / glossary).
After running the three commands above, you are ready for `/adapt-framework`, which wires this boilerplate's KATA architecture against the target stack.
If the user asks to chain them automatically: decline politely. Each command consumes significant tokens and produces better output in its own session.
Pre-adapt-framework checklist
Before the user invokes /adapt-framework, verify every file below is on disk. If any is missing, re-run the phase that produces it (or the corresponding post-discovery command) before invoking /adapt-framework:
Handoff line to print to the user:
Discovery handoff complete. Ready for /adapt-framework iff the 6 bullets above are on disk. Missing any? Re-run the phase listed in the "Phases to run" column of the scopes table that produces it — or review the "Boilerplate adoption" row for phases you can skip when inputs already exist elsewhere.
Stack-specific discovery rules
Base stack detection (package.json → Node, pyproject.toml → Python, go.mod → Go, next.config.* → Next.js, etc.) is a baseline skill any AI has. This section only lists actions the skill should take based on what is detected — rules that are not obvious from general programming knowledge.
| Signal | Action for discovery |
|---|
Monorepo (pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or top-level package.json with no deps of its own) | Split backend/frontend per package. Run Phase 1 once (project-level), Phase 2-3 per package. Merge outputs under .context/infrastructure/ with sub-sections per package. |
| Multiple coexisting signals in one repo (e.g., Next.js + Express) | Almost always a monorepo — treat frontend and backend as separate discoveries even if workspace config is missing. Do NOT produce a merged SRS. |
Dockerfile + docker-compose.yml present | Read compose for service inventory before scanning source — it is the authoritative runtime topology. Use source only to fill gaps. |
| No test framework deps detected | Greenfield test story. Phase 3 documents the absence as a Discovery Gap. Do NOT install tooling in the target repo. /adapt-framework wires this boilerplate's own test stack; it never modifies the target. |
.github/workflows/*.yml present | Extract the test job from CI for Phase 3 Infrastructure — usually the cleanest source for "how CI runs tests". |
| API handlers found but no OpenAPI spec | Flag as Discovery Gap in Phase 2 SRS. Do NOT hand-write an OpenAPI inside project-discovery — either ask the user to expose one (so bun run api:sync works), or defer the business angle to /business-api-map. |
| Hardcoded secrets detected (grep hits in source) | HIGH risk. Record path in .context/risk-assessment.md §Phase 1 Project Assessment. Do NOT paste the secret into any discovery doc — reference path only. |
Gotchas
- Discovery is read-only on the target repo.
.context/ is the only write target. For modifications to this boilerplate's tests/, api/schemas/, and config/, use /adapt-framework.
- Hard-to-reverse test decisions become ADRs, not buried prose. When Phase 2/3 settles a test-runner, isolation, fixture/data, auth-in-tests, or selector-contract decision that is architectural AND hard to reverse, record it as
.context/ADR/ADR-NNNN-<slug>.md (append-only) instead of leaving it only inside architecture.md. Draft Proposed; the human approves. See agentic-qa-core/references/adr-doctrine.md.
- Credentials never live in discovery docs. Read them from
.env (LOCAL_USER_EMAIL, STAGING_USER_EMAIL, etc.). If missing, ask the user to create .env.example or hand over secrets out-of-band -- do not paste them into markdown.
- "Discovery Gaps" section is mandatory in every output. If you could not verify something from the code (e.g., traffic volume, uptime targets), list it in a
## Discovery Gaps section rather than inventing a number. This signals to future sessions what still needs human input.
- PRD/SRS discovered from code is authoritative, not aspirational. Describe what the system does, not what product wants it to do. If the user wants a "to-be" doc, that is PRD/SRS creation (out of scope for this skill); point them to their own product workflow.
- Do not duplicate the backlog. Jira/Linear/GitHub Issues is the source of truth for tickets.
.context/PBI/ holds the backlog access recipe (README.md) and format-reference guides (templates/), never a copy of the full backlog. Per-ticket PBI is synced on demand from Jira by /sprint-testing (bun run jira:sync-issues) as a read-only cache — this skill does not create it.
- Monorepos require scoped discovery. Run Phase 1 once (project as a whole) but Phases 2-3 per package. Merge findings into a single
.context/infrastructure/ with sub-sections per package.
- Database schemas over ORM models. If both exist, prefer the migration files / schema dump over the ORM definitions -- ORM definitions can drift from the live schema.
- API base URL vs route prefix.
{{environments.local.api_url}} includes the protocol+host; route prefixes (e.g., /api/v1) belong in the path. Do not concatenate them twice in any context file that documents endpoints (e.g., business-api-map.md).
- Auth flow is the single most important input for downstream
/adapt-framework. Session tokens, cookies, JWT, OAuth redirects, CSRF -- every project does it differently. Capture the real login request (DevTools / curl) in backend.md so the adaptation phase has a concrete contract to code against.
- Never generate from stale context. If
.context/business/business-data-map.md already exists but the user asks to "refresh" it, diff the current code against the existing file and ask whether to overwrite or merge. Auto-overwrite loses prior human edits.
- Context generators need ALL prior phases. If the user jumps to "regenerate business-data-map" on a fresh repo, do Phase 1 (at minimum project-connection) and Phase 3 (backend discovery) first -- the generator relies on them.
- IQL framing is optional. Mention it only if the user asks "why this structure?" -- do not lecture them on methodology when they just want a working
business-data-map.md.
- API requests get redirected. "Regenerate api-architecture" / "I need an API map" / "document the endpoints" -> stop and explain the split:
bun run api:sync for technical types, /business-api-map for the business angle. This skill does not generate API documentation directly anymore.
Templates (inline -- small, load-bearing)
Discovery Gaps section (every output)
## Discovery Gaps
The following items could not be verified from code and require human confirmation:
- [ ] <Gap>: <what is missing, where you looked, suggested source of truth>
- [ ] ...
Phase completion ping (used after each phase)
Phase N complete.
Generated files:
- <path1>
- <path2>
Next: Phase N+1 (<phase name>). Confirm to continue, or say "pause" to stop here.
.env key list emitted after Phase 1
# Application URLs (per-environment — match the env names you declared
# under `environments:` in `.agents/project.yaml`; consumed by
# `bun run agents:setup --non-interactive` via the `<KEY>_<ENV>` pattern)
WEB_URL_LOCAL=
WEB_URL_STAGING=
API_URL_LOCAL=
API_URL_STAGING=
# Test User Credentials
LOCAL_USER_EMAIL=
LOCAL_USER_PASSWORD=
STAGING_USER_EMAIL=
STAGING_USER_PASSWORD=
# Atlassian / TMS credentials (single source of truth, used by MCP, acli,
# xray-cli, sync scripts, and the Jira-Direct TMS provider — no overrides)
ATLASSIAN_URL=
ATLASSIAN_EMAIL=
ATLASSIAN_API_TOKEN=
Larger templates (full PRD sections, KATA component skeletons, .context/infrastructure/backend.md layout, business-data-map.md structure) live in the references.
Specific tasks -- which reference to read
- Phase 1 (project connection, assessment, business model, glossary) -> read
references/phase-1-constitution.md.
- Phase 2 PRD (executive summary, personas, journeys, features) -> read
references/phase-2-prd.md.
- Phase 2 SRS (architecture, API contracts, functional, non-functional) -> read
references/phase-2-srs.md.
- Phase 3 (backend, frontend, infrastructure) -> read
references/phase-3-infrastructure.md.
- Recording a hard-to-reverse test-architecture decision (ADR) -> read
agentic-qa-core/references/adr-doctrine.md + .context/ADR/README.md.
- Phase 4 (backlog mapping, templates) -> read
references/phase-4-specification.md.
- Generating
business-data-map.md -> read references/context-generators.md. For the test plan, run /master-test-plan (command, not skill).
- API endpoint sync (technical) or business-API map -> NOT this skill. Use
bun run api:sync (technical types) or /business-api-map command (business angle).
- User asks about IQL methodology -> point them to
docs/methodology/IQL-methodology.md (shared across QA skills). This skill no longer carries its own IQL reference.
- Code exploration (grep, read files) -> use built-in tools. If the user wants a browser-driven exploration instead (UI-first discovery), load
/playwright-cli skill.
- Issue-tracker operations (Phase 4) -> resolve
[ISSUE_TRACKER_TOOL] via CLAUDE.md Tool Resolution. For Jira, load /acli skill (primary) or fall back to the Atlassian MCP. If the project also uses Xray for TMS, load /xray-cli additionally.
- Database inspection -> resolve
[DB_TOOL]; read-only queries only during discovery.
- Session contract (Phase 0 resume, plan.md/progress.md schemas, archive policy, Engram per-phase checkpoint) -> read
../agentic-qa-core/references/session-management.md. This skill is a producer of session/project-discovery/... topic keys.
Anti-patterns — NEVER do these
- P1. NEVER invent business entities, flows, or requirements not present in the target repo code or PRD. Discovery is reverse-engineering, not aspirational design — unverified items go in a
## Discovery Gaps block, never inline.
- P2. NEVER skip Phase 1 (Constitution) when starting fresh. Downstream phases (PRD/SRS, infrastructure, PBI mapping) assume the project values and stack are fixed first; skipping leaves later artifacts ungrounded.
- P3. NEVER fill
.context/business/business-data-map.md from memory or from a prior session's draft. Re-read target code and PRD per session, regenerate via the /business-data-map command so the map stays anchored to current source.
- P4. NEVER mix
/project-discovery with /adapt-framework in the same session. Discovery reads the target repo only; adapt edits THIS boilerplate. The blast radii are different and interleaving them confuses the read-only contract.
- P5. NEVER use
/project-discovery for incremental updates. Use the /business-*-map regenerative commands instead — discovery is one-shot per project (or rare full refresh), not a per-feature loop.
- P6. NEVER skip the domain glossary in Phase 1. Downstream skills read it as a precondition when present:
sprint-testing lists it in its Stage 1 planning inputs (ATP, refined ACs, TC outlines) and test-documentation uses it as the vocabulary reference for TC naming and bodies.
- P7. NEVER fabricate Jira / Xray field IDs or status names in
.context/master-test-plan.md or any PBI template. Run bun run jira:sync-fields --force and reference {{jira.<slug>}} via the slug catalog in .agents/jira-required.yaml.
Quick reference
ls -la <target-repo>
cat <target-repo>/package.json | jq .
cat <target-repo>/pyproject.toml
ls <target-repo>/.github/workflows
find <target-repo> -maxdepth 2 -name "docker-compose*.yml" -o -name "Dockerfile"
cat <target-repo>/.env.example
grep -r "process.env\." <target-repo>/src
cat <target-repo>/.github/workflows/*.yml
[ISSUE_TRACKER_TOOL] Get Issue:
key: {{PROJECT_KEY}}-1
[ISSUE_TRACKER_TOOL] Search Issues:
project: {{PROJECT_KEY}}
query: sprint in openSprints() AND assignee = currentUser()
