project-discovery
Skill26 starsChanged 10 days agoMITView on GitHub
Onboard a project through four discovery phases: Constitution, Architecture, Infrastructure, and Specification. Produces the domain map (business model + glossary) inside `business-domain-context` and the infra map (architecture, NFRs, backend, frontend, environments, CI/CD) inside `infra-context`, plus `.context/project-config.md` and a backlog connection check, then hands the business maps and the master test plan to `project-context`. Use for set up this project, onboard this repo, connect to project, discover architecture, or create PRD/SRS. Do NOT use for incremental context refresh (`project-context`), writing tests, TMS documentation, running suites, adapting KATA (`test-framework-adaptation`), or technical OpenAPI sync (`bun run api:sync`).
- Reads credentials
6 other projects use a version of this.
Adopted by
Most recently taken up by
- NAVANEETHVVINOD/agent-orchestratortheir own version, first seen Oct 3, 2026
- rikvanriel/code-hygienetheir own version, first seen Sep 17, 2026
- bhagyamudgal/skillstheir own version, first seen Sep 9, 2026
- ntaffzii/Skill-Agentstheir own version, first seen Sep 2, 2026
- taipm/setup-c2their own version, first seen Apr 12, 2026
- kognar-ai/claude-skillstheir own version, first seen Jan 20, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- ntaffzii/Skill-Agents★ 4same name
- bhagyamudgal/skills★ 2same name
- rikvanriel/code-hygiene★ 2same name
- taipm/setup-c2★ 1same name
- kognar-ai/claude-skills★ 0same name
- NAVANEETHVVINOD/agent-orchestrator★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- acliSkill
- agentic-qa-coreSkill
- agentic-qa-onboardSkill
- bug-screenshot-annotationSkill
- business-api-contextSkill
- business-data-contextSkill
- business-domain-contextSkill
- business-e2e-contextSkill
- evidence-artifactSkill
- exploratory-testingSkill
- framework-developmentSkill
- git-flow-masterSkill
- infra-contextSkill
- iql-contextSkill
- jira-administrationSkill
- judgment-daySkill
- orca-orchestrationSkill
- project-contextSkill
- pr-review-leadSkill
- regression-testingSkill
- session-handoffSkill
- shift-left-testingSkill
- sprint-conductorSkill
- sprint-testingSkill
- test-automationSkill
- test-documentationSkill
- test-framework-adaptationSkill
- xray-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
49 rules. 0 are common, 14 are distinctive, and 35 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
14
Distinctive
This author's own choices. Worth a look.
35
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
DO: run the four phases in order (Constitution → Architecture → Infrastructure → Specification), each gated on the previous.
- Very specific: line 25
DO NOT: write anything into the target repo.
- Very specific: line 26
DO: act as the GENERATOR of those two maps, per agentic-qa-core/references/business-context-maps.md (anatomy §2, reading §3, CREATE/UPDATE …
- Very specific: line 27
DO: read a project's old .context/business/, .context/SRS/ and .context/infrastructure/ markdown files (the legacy list of …
- Very specific: line 28
DO: before drawing a figure, run the point-of-use check for capability diagrams (agentic-qa-core/references/business-context-maps.md §7).
- Very specific: line 29
DO NOT: invent business entities, flows, requirements, or Jira/Xray field IDs and status names.
- Distinctive: line 30
DO: describe what the system DOES, not what product wants it to do.
- Distinctive: line 31
DO: lock the target repo path(s) before Phase 1 and block on ambiguity.
- Very specific: line 32
WHEN the layout is split sibling repos: run the Phase 1 sub-steps once per repo and merge into ONE project-config.md, never interleaved.
- Very specific: line 33
DO NOT: fill the business-data-context, business-api-context or business-e2e-context maps, and do not write personas, journeys, the feature …
- Very specific: line 34
DO NOT: create per-ticket PBI content or copy the backlog.
- Very specific: line 35
DO NOT: paste credentials or a detected secret into any discovery output.
- Very specific: line 37
DO NOT: mix a discovery session with test-framework-adaptation, and do not use this skill for incremental map refreshes — the write …
- Very specific: line 38
DO NOT: skip Phase 1 or its domain glossary on a fresh start.
- Distinctive: line 39
WHEN both a DB schema/migrations and ORM models exist: prefer the schema or migrations.
- Distinctive: line 40
DO: mention the IQL methodology only if the user asks why the discovery is structured this way — never lecture someone who just wants the …
- Very specific: line 41
DO: before any step that uses a declared capability (metadata.requires_capabilities: db, api-schema, diagrams), run the point-of-use check …
- Very specific: line 73
Before scope selection or any target-repo discovery, run the resume contract from agentic-qa-core/references/session-management.md §4:
- Very specific: line 76
If it does NOT exist → proceed to "Before starting: target repo location" below, then "Pick the scope first" (which writes plan.md).
- Distinctive: line 77
If it DOES exist:
- Very specific: line 78
Read plan.md (chosen scope, target repo path, phase plan).
- Very specific: line 79
Read tail of progress.md (last completed phase + next planned phase).
- Very specific: line 99
If the layout is "split sibling repos", run Phase 1 sub-steps once per repo and merge findings into a single project-config.md.
- Distinctive: line 105
All projects go through the same 4 phases, but depth varies.
- Distinctive: line 114
Default to "Fresh onboarding" when in doubt.
- Very specific: line 116
After scope confirmation, write .session/project-discovery/plan.md per agentic-qa-core/references/session-management.md §6.
- Distinctive: line 162
After the automated sanity check, show the human the map index and the file path, and wait for explicit "Phase 1 complete, continue" before …
- Very specific: line 164
Read references/phase-1-constitution.md when running any Phase 1 sub-step.
- Very specific: line 184
Every numeric NFR claim cites evidence in its section or sits in discovery-gaps.
- Very specific: line 188
Read references/phase-2-srs.md when running any Phase 2 sub-step.
- Very specific: line 206
Read references/phase-3-infrastructure.md when running any Phase 3 sub-step.
- Very specific: line 221
Read references/phase-4-specification.md when running Phase 4.
- Very specific: line 227
After those outputs exist, invoke test-framework-adaptation to wire this boilerplate to the target stack.
- Very specific: line 233
After each phase passes its completion gate AND the user confirms "Phase N complete", append a phase entry to …
- Very specific: line 235
After Phase 4 passes, archive the project-discovery session per agentic-qa-core/references/session-management.md §8 and record the …
- Distinctive: line 245
When Phase 4 is confirmed complete, print this block to the user verbatim:
- Distinctive: line 278
Do not auto-chain the handoff inside this session.
- Very specific: line 284
Before the user invokes test-framework-adaptation, verify every item below.
- Very specific: line 319
Credentials never live in discovery docs: Read them from .env (LOCAL_USER_EMAIL, STAGING_USER_EMAIL, etc.).
- Very specific: line 323
Monorepos require scoped discovery: Run Phase 1 once (project as a whole) but Phases 2-3 per package.
- Distinctive: line 324
Database schemas over ORM models: If both exist, prefer the migration files / schema dump over the ORM definitions -- ORM definitions can …
- Distinctive: line 328
Context modes need grounded discovery: If the user requests a business map on a fresh repo, complete at least Phase 1 and Phase 3 before …
- Very specific: line 330
API requests get redirected: Use bun run api:sync for technical types and project-context mode api for the business angle.
- Very specific: line 409
P1.: NEVER invent business entities, flows, or requirements not present in the target repo code or PRD.
- Distinctive: line 410
P2.: NEVER skip Phase 1 (Constitution) when starting fresh.
- Very specific: line 411
P3.: NEVER fill the data, API or E2E maps (the HTML inside business-data-context, business-api-context, business-e2e-context) from this …
- Very specific: line 412
P4.: NEVER mix project-discovery with test-framework-adaptation in the same session.
- Very specific: line 413
P5.: NEVER use project-discovery for incremental updates of the data, API or E2E maps.
- Very specific: line 415
P7.: NEVER fabricate Jira / Xray field IDs or status names in the Master Test Plan or any PBI template.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 the domain map and the infra map inside their context skills, plus .context/project-config.md: the knowledge 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 stage contract every QA skill enforces lives in agentic-qa-core/references/stage-gates.md; the methodology narrative is the official IQL site: https://upexgalaxy.com/metodologia (ES) / https://upexgalaxy.com/en/methodology (EN). This skill does not depend on reading it — only point the user there if they ask why the discovery is structured this way.
Compact Rules
- DO: run the four phases in order (Constitution → Architecture → Infrastructure → Specification), each gated on the previous. Show the output paths and wait for an explicit "Phase N complete" before continuing — never auto-chain.
- DO NOT: write anything into the target repo. Discovery is read-only on it. The write targets are
.context/project-config.md,.context/ADR/, and the maps ofbusiness-domain-contextandinfra-context(theirreferences/<map>.html), nothing else (plus the Phase 1## Project Assessment (Phase 1)block in.agents/instructions/agent-project.md); modifying the boilerplate itself istest-framework-adaptation. - DO: act as the GENERATOR of those two maps, per
agentic-qa-core/references/business-context-maps.md(anatomy §2, reading §3, CREATE/UPDATE §4, staleness §5). Map absent or placeholder → CREATE every section. Map generated → UPDATE only the stale sections (§5 staleness check), show a section-level diff, WAIT for approval. Never regenerate a whole generated map. - DO: read a project's old
.context/business/,.context/SRS/and.context/infrastructure/markdown files (thelegacylist ofbusiness-domain-contextandinfra-contextinCONTEXT_MAP_SKILLS,cli/lib/context-maps.ts) as INPUT when present, cite them indata-migrated-fromon the sections they seed, and never delete or rewrite them. - DO: before drawing a figure, run the point-of-use check for capability
diagrams(agentic-qa-core/references/business-context-maps.md§7). Figures are optional where a table says it better: the glossary is tables; the architecture overview usually earns a figure. - DO NOT: invent business entities, flows, requirements, or Jira/Xray field IDs and status names. Anything not verifiable from the source goes in the map's
discovery-gapssection (or the## Discovery Gapsblock ofproject-config.md). - DO: describe what the system DOES, not what product wants it to do. Discovery is reverse-engineering; a "to-be" PRD/SRS is out of scope — point the user at their own product workflow.
- DO: lock the target repo path(s) before Phase 1 and block on ambiguity. A repo that is not cloned locally cannot be discovered from a URL — ask for the clone first.
- WHEN the layout is split sibling repos: run the Phase 1 sub-steps once per repo and merge into ONE
project-config.md, never interleaved. WHEN it is a monorepo: Phase 1 once project-wide, Phases 2-3 per package. - DO NOT: fill the
business-data-context,business-api-contextorbusiness-e2e-contextmaps, and do not write personas, journeys, the feature catalog or the master test plan here. Those areproject-contextmodes, which own their diff and overwrite approval. Exact API types arebun run api:sync. - DO NOT: create per-ticket PBI content or copy the backlog. Phase 4 is a connection check and writes no file; the committed
README.mdandtemplates/under.context/PBI/stay untouched. - DO NOT: paste credentials or a detected secret into any discovery output. Reference the
.envkey or the file path only; a hardcoded-secret hit is recorded as a HIGH risk (path only) in the Phase 1 assessment. - WHEN Phase 2 or 3 settles a test-architecture decision that is architectural AND hard to reverse (runner, isolation/parallelization, fixture and test-data strategy, auth-in-tests, selector contract, CI sharding): record it as an append-only ADR under
.context/ADR/, draftedProposedfor the human to accept. In a brownfield repo the decision was DISCOVERED, not made here: write itProposed, mark it discovered (where it was found), and have the human confirm it at that phase's completion checkpoint, which flips it toAccepted. - DO NOT: mix a discovery session with
test-framework-adaptation, and do not use this skill for incremental map refreshes — the write boundaries differ. - DO NOT: skip Phase 1 or its domain glossary on a fresh start. Downstream skills load
business-domain-contextas a precondition for ATP authoring and TC naming. - WHEN both a DB schema/migrations and ORM models exist: prefer the schema or migrations. ORM definitions drift from the live schema.
- DO: mention the IQL methodology only if the user asks why the discovery is structured this way — never lecture someone who just wants the artifact.
- DO: before any step that uses a declared capability (
metadata.requires_capabilities:db,api-schema,diagrams), run the point-of-use check inagentic-qa-core/references/preflight-gate.md§8: resolve by tool-name suffix, and when no available tool provides it STOP and name the capability + how to enable it, never a silent fallback.
Read full SKILL.md when: running any phase's sub-steps, applying a completion gate's content checks, or resolving the pre-test-framework-adaptation prerequisite list.
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.mdand existing onboarding docs — fastest path to project intent, stack signals, and run commands before deep code reads. - Prior discovery state (if any):
bun run context:map business-domain-context --listandbun run context:map infra-context --list,.context/project-config.md, and any legacy markdown a project kept under.context/business/,.context/SRS/,.context/infrastructure/(input only). Informs Phase 0 resume decisions and CREATE vs UPDATE, and prevents redundant work. .agents/project.yamland.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..agents/skills/agentic-qa-core/references/skill-composition-strategy.md— workflow context for downstream handoffs (project-context,test-framework-adaptation,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
agentic-qa-core/references/orchestration-doctrine.md(mandatory subagent dispatch — main thread is command center) ANDagentic-qa-core/references/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 skill runs long (hours, four hard-gate phases) and benefits most from per-phase checkpoints: if interrupted between Phase 2 (Architecture) 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 AGENTS.md §3 (Orchestration Mode) and the session contract in .agents/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.
- Read
Resume is high-value here: Fresh onboarding (hours) 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, then project-context refresh-all | Full discovery. Business maps and test strategy are generated by their dedicated skill. After context completion, run test-framework-adaptation. | Heavy. Delegate each phase's code survey to a dedicated subagent. |
| Boilerplate adoption (this repo adopted for a new project) | Target app repo(s), this repo as the test framework | 1 -> 3, then project-context for missing maps | Phase 1 runs in full: the domain map is a test-framework-adaptation prerequisite. Skip Phase 2 or 4 only when their required artifacts already exist. Verify files on disk before test-framework-adaptation. | Medium. Delegate Phase 1 and Phase 3 per package for monorepos. |
| Brownfield (project already documented, tests missing) | Existing .context/ partially filled | 2 (gaps) -> 3 (gaps) -> 4 (gaps), then project-context for stale maps | Fill discovery gaps here; refresh map artifacts in their owning skill. | Light. Main session unless gaps span many files. |
| Context refresh | User asks to regenerate a business map or master test plan | Redirect to the matching project-context mode | This skill does not refresh those artifacts. For the domain or infra map, re-run Phase 1 or Phases 2-3 in UPDATE mode (stale sections only). For a backlog connection change, re-run Phase 4. For exact OpenAPI types, use bun run api:sync. | Minimal. Handoff only. |
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. The phase breakdown ends at Phase 4; record project-context refresh-all as the post-discovery handoff, not as a discovery phase.
Workflow — the 4-phase pipeline
Phase 1: Constitution -> Phase 2: Architecture -> Phase 3: Infrastructure -> Phase 4: Specification
(who/what/why) (architecture + NFRs) (backend/frontend/envs/CI) (backlog connection check)
| | | |
.context/project-config.md infra-context map: infra-context map: no file written
AGENTS.md assessment block overview, architecture, backend, frontend, `bun run jira:check`
business-domain-context map: external-services, nfr-<slug> environments, ci-cd
overview, business-model,
term-<slug>, enumerations
|
v
project-context (separate skill)
data -> e2e -> api -> test-plan
`bun run api:sync` remains the technical
OpenAPI type pipeline.Both maps close with a discovery-gaps section. Read them back with bun run context:map <slug> (or --list for the section index), never as raw HTML.
KATA adaptation is a separate skill:
test-framework-adaptation. It runs after discovery and context outputs exist.
Each phase has a completion gate: before moving on, the phase's sections must print through bun run context:map with real content (and the files it names must exist on disk). 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. Output:.context/project-config.md. - Project Assessment -- current testing maturity (frameworks in place, CI presence, lint/typecheck, coverage). Output: the
## Project Assessment (Phase 1)block in.agents/instructions/agent-project.md. HIGH risks (a hardcoded-secret hit included, path only) are recorded there and carried to the handoff as seed input forproject-contextmodetest-plan(the MTP). No separate risk file is written. - Business Model Discovery -- problem statement, target users, value proposition, revenue model (if any). Output: the
overviewandbusiness-modelsections of thebusiness-domain-contextmap. - Domain Glossary -- core entities and concepts, UI-label vs code-identifier mapping, enumerations. Output: one
term-<slug>section per core entity or concept, plusenumerationsanddiscovery-gaps, in the same map.
Completion gate: bun run context:map business-domain-context --list prints sections and no placeholder notice; .context/project-config.md exists and is non-empty; the ## Project Assessment (Phase 1) block is in .agents/instructions/agent-project.md. Sanity-check content (soft gates, surfaced to the human as warnings, not hard aborts):
- Several
term-sections exist, one per real core entity from the schema (not one catch-all section, not only enumerations). overviewandbusiness-modelcarrydata-sources(the reader's--listshows them).project-config.mdhas a## Tech Stacksection AND a## Environmentssection.
After the automated sanity check, show the human the map index and the file path, 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, the content of each domain map section, and quality checklists.
Phase 2 — Architecture
Goal: describe how the system is built, from code (the "discovery" direction, never the "creation" one).
Sub-steps, serially:
- Architecture -- system overview, component structure, database schema at the architecture level, data and auth flow, security model. Output:
infra-contextsectionsoverviewandarchitecture. - External Services -- third-party dependencies and their integration points. Output:
external-services. - Non-Functional -- performance, security posture, reliability, scalability, observability, compliance. Output: one
nfr-<slug>section per category that has evidence.
Personas, user journeys and functional specs are not discovery outputs.
project-contextmodee2ebuilds them as the persona, journey and feature sections ofbusiness-e2e-context.
API contracts are NOT a Phase 2 output. The technical surface is owned by
bun run api:sync; the business angle is owned byproject-contextmodeapi. Phase 2 records only the spec location (in.context/project-config.md) or a discovery gap.
Test-architecture ADR seeding (Phase 2 + Phase 3). When the Architecture / 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-testidcontract, exploratory-vs-scripted boundary, CI sharding — promote each one that passes the two-gate test (architectural AND hard to reverse) to a standaloneADR-NNNN-<slug>.mdin.context/ADR/, and cite it in thearchitecturesection of the infra map. Greenfield: you are ENCODING the decision; brownfield: you are RECORDING the one you discovered. Followagentic-qa-core/references/adr-doctrine.md(detection + authoring) and.context/ADR/README.md(template + lifecycle). AI draftsProposed; the human accepts. A brownfield ADR is writtenProposedand marked discovered (its Context names the file, config or code where the decision was found, and says nobody decided it in this session); the human confirms it at the phase's completion checkpoint ("Phase N complete"), and only that confirmation flips it toAccepted. Never write a discovered decisionAcceptedbecause the code already does it: the code shows what was built, not that anyone still endorses it.
Completion gate: bun run context:map infra-context --list shows an architecture section and at least one nfr- section. The API contract source is recorded in .context/project-config.md. Soft content checks:
architecturecarries a figure, or adiscovery-gapsentry explaining why not.external-servicesexists, ordiscovery-gapssays none were found and where you looked.- Every numeric NFR claim cites evidence in its section or sits in
discovery-gaps.
Show the map index to the human and wait for "Phase 2 complete, continue" before moving on.
Read references/phase-2-srs.md when running any Phase 2 sub-step.
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. Output:
infra-contextsectionbackend(monorepo:backend-<pkg>). - Frontend Discovery -- framework, bundler, routing, state management, design system, component library, test IDs strategy. Output:
frontend(monorepo:frontend-<pkg>). - Infrastructure Mapping -- CI/CD providers, deployment targets, environments (dev/staging/prod), infra-as-code, monitoring, rollback procedure. Output:
environmentsandci-cd.
Completion gate: bun run context:map infra-context --list shows backend, frontend, environments and ci-cd (or their per-package forms) with the key facts (auth flow, test commands, deploy URLs) filled in. Soft content checks:
backendANDfrontendeach carry the commands to install and run (a<pre><code>block).environmentsholds an environments table (a Staging or Production row).backendpoints at the auth flow (e.g.,/auth/login,session,JWT,cookie,OAuth).
Show the map index 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, the content of each infra map section, and common gotchas (SSR vs CSR, edge vs serverless, monorepo vs split repos).
Phase 4 — Specification (backlog connection)
Goal: prove the testing framework can reach the team's issue tracker, without duplicating content. Phase 4 writes no file.
One sub-step:
- Backlog connection check -- connect to
{{ISSUE_TRACKER}}via[ISSUE_TRACKER_TOOL], confirm the project key in.agents/project.yaml, runbun run jira:check(readpackage.jsonfirst to confirm the script), and confirm the hierarchy the sync will use is declared in.agents/jira-required.yaml. NEVER write.context/PBI/README.mdor the committedtemplates/: the access recipe lives in.context/PBI/README.mdand.agents/instructions/agent-local-context-pbi.md.
Per-ticket PBI is NOT generated by this skill. It is materialized later by
/sprint-testingviabun 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.mdfiles are a READ-ONLY cache of Jira (Jira = source of truth). This skill does NOT create per-ticketstory.md.
Completion gate: bun run jira:check green, or a recorded discovery gap (in project-config.md ## Discovery Gaps) when the team has no tracker access yet. .context/PBI/README.md and .context/PBI/templates/ untouched.
Show the check output to the human and wait for "Phase 4 complete" before emitting the project-context handoff.
Read references/phase-4-specification.md when running Phase 4.
Business-context handoff
Business maps and the master test plan are not generated here. After Phase 4, open a clean session and invoke project-context mode refresh-all. It owns the deterministic sequence data -> e2e -> api -> test-plan, including every CREATE/UPDATE approval gate; the maps land inside the business context skills. Exact OpenAPI types remain owned by bun run api:sync.
After those outputs exist, invoke test-framework-adaptation to wire this boilerplate to the target stack.
Per-phase progress + Archive
After each phase passes its completion gate AND the user confirms "Phase N complete", append a phase entry to .session/project-discovery/progress.md. Entries end at Phase 4; the next action is the separate project-context skill.
After Phase 4 passes, archive the project-discovery session per agentic-qa-core/references/session-management.md §8 and record the project-context refresh-all handoff. Context generation has its own lifecycle and does not keep this session open.
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 the domain map, the infra map and project-config.md, and checks the backlog connection. It does not invoke project-context, which is token-heavy and best run in a clean session.
When Phase 4 is confirmed complete, print this block to the user verbatim:
Discovery complete. `/project-discovery` has populated:
- `business-domain-context` map (business model + glossary): `bun run context:map business-domain-context`
- `infra-context` map (architecture, NFRs, backend, frontend, environments, CI/CD): `bun run context:map infra-context`
- .context/project-config.md
- Backlog connection check: `bun run jira:check` <green | discovery gap: why>
**Recommended next skill** (run in a clean session):
`project-context` mode `refresh-all`
It runs data -> e2e -> api -> test-plan in dependency order, writes the maps inside `business-data-context`, `business-e2e-context` and `business-api-context`, and can be re-run whenever project context becomes stale (UPDATE regenerates only stale sections).
**Seed input for the master test plan** (`project-context` mode `test-plan`): the HIGH risks from the Phase 1 assessment:
- <risk, severity, evidence path> (or "none recorded")
After it completes, invoke `test-framework-adaptation` to wire KATA against the target stack.
**Judgment the context skills could start with** (proposed, not written: each becomes a dated rule in that skill's `## Rules` after its map is generated and the user approves):
- `business-domain-context`: <one line: a term the team and the code name differently, or "no candidate yet">
- `infra-context`: <one line: an environment-only behaviour, or "no candidate yet">
- `business-data-context`: <one line: the judgment a session needs to read the data right, or "no candidate yet">
- `business-api-context`: <one line, or "no candidate yet">
- `business-e2e-context`: <one line, or "no candidate yet">
**Other context skills this project could carry** (proposed, not created: `project-context` mode `context-skill <aspect>` creates each one through `skill-creator`, once what it sits over exists):
- <any other aspect the discovery surfaced>: <one line>The judgment lines cover the context skills in CONTEXT_MAP_SKILLS (cli/lib/context-maps.ts); the template names each slug only because it is a fill-in. Fill each proposal line from what the phases actually found: a soft-delete convention, a derived field, an auth edge case, an environment-only behaviour. A proposal is one sentence naming the judgment, never a file: the facts go in the map, and a rule is born later, over an approved map, with its date. "No candidate yet" is a valid line.
Do not auto-chain the handoff inside this session. Context generation needs its own token budget and approval lifecycle.
Pre-test-framework-adaptation checklist
<!-- keep in sync with .agents/skills/test-framework-adaptation/references/adaptation-workflow.md §Hard prerequisites -->Before the user invokes test-framework-adaptation, verify every item below. A missing domain or infra map routes back to the matching discovery phase; a missing business map routes to the matching project-context mode.
business-domain-contextholds a generated map (bun run context:map business-domain-contextprints sections, no placeholder notice)infra-contextholds a generated map with itsbackendandfrontendsections (bun run context:map infra-context --list).context/project-config.mdbusiness-data-contextholds a generated map (bun run context:map business-data-contextprints sections, no placeholder notice)- API contract source: one of
api/openapi-types.ts(non-stub) OR reachable OpenAPI spec URL OR a generatedbusiness-api-contextmap (business-angle fallback) .env.example(and.enveither present or created duringtest-framework-adaptation)
Handoff line to print to the user:
Discovery handoff complete. Run
project-context refresh-all, then invoketest-framework-adaptationwhen every prerequisite above is present.
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 into the one infra map as per-package sections (backend-<pkg>, frontend-<pkg>). |
| 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 merge them into one backend / frontend section. |
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. test-framework-adaptation 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 a discovery gap in Phase 2 (infra map discovery-gaps). Do NOT hand-write an OpenAPI inside project-discovery; ask for a spec or defer the business angle to project-context mode api. |
| Hardcoded secrets detected (grep hits in source) | HIGH risk. Record it in the Phase 1 assessment's ### Identified Risks table, path only, and carry it to the MTP seed in the handoff. Do NOT paste the secret into any discovery output. |
Gotchas
- Discovery is read-only on the target repo. It writes only
.context/project-config.md,.context/ADR/and the domain and infra maps (see Compact Rules). For modifications to this boilerplate, usetest-framework-adaptation. - 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 the infra map'sarchitecturesection. DraftProposed; the human approves. A brownfield ADR is also marked discovered and confirmed at the phase's completion checkpoint. Seeagentic-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.exampleor hand over secrets out-of-band -- do not paste them into markdown. - A discovery-gaps record is mandatory in every output. If you could not verify something from the code (e.g., traffic volume, uptime targets), list it in the map's
discovery-gapssection (orproject-config.md## Discovery Gaps) rather than inventing a number. This signals to future sessions what still needs human input. - What discovery writes 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" PRD/SRS, that is 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/never holds 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 the one infra map as per-package sections (
backend-<pkg>,frontend-<pkg>). - 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., thebusiness-api-contextmap). - Auth flow is the single most important input for downstream
test-framework-adaptation. Capture the real login request in the infra map'sbackendsection so adaptation has a concrete contract. - Refresh only your own maps here. The domain and infra maps are refreshed by re-running their phase in UPDATE mode (stale sections only, approval first). Route the data, API and E2E maps to
project-context, which owns their diff and overwrite approval. - Context modes need grounded discovery. If the user requests a business map on a fresh repo, complete at least Phase 1 and Phase 3 before handing off.
- 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 data map.
- API requests get redirected. Use
bun run api:syncfor technical types andproject-contextmodeapifor the business angle.
Templates (inline -- small, load-bearing)
Discovery gaps (every output)
In project-config.md, a markdown block; in a map, the closing <section id="discovery-gaps"> carries the same list as a <ul>.
## 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.
Written:
- <file path, or `<slug>` map sections: <id>, <id>, ...>
Read back: bun run context:map <slug> --list
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 (used by MCP, acli, xray-cli, sync scripts, and
# the Jira-Direct TMS provider — no overrides)
# NOTE: the Atlassian site HOST is not a .env variable. It lives in
# .agents/project.yaml -> issue_tracker.atlassian_url (`bun run agents:setup`).
ATLASSIAN_EMAIL=
ATLASSIAN_API_TOKEN=The content of each domain and infra map section lives in the phase references; the map anatomy lives in agentic-qa-core/references/business-context-maps.md §2; the business map structure lives in project-context.
Specific tasks -- which reference to read
- Phase 1 (project connection, assessment, business model, glossary →
business-domain-contextmap) -> readreferences/phase-1-constitution.md. - Phase 2 (architecture, external services, non-functional →
infra-contextmap; API contract source) -> readreferences/phase-2-srs.md. - Phase 3 (backend, frontend, environments, CI/CD →
infra-contextmap) -> readreferences/phase-3-infrastructure.md. - Map anatomy, reading, CREATE/UPDATE, staleness, diagrams -> read
agentic-qa-core/references/business-context-maps.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 connection check) -> read
references/phase-4-specification.md. - Personas, journeys, functional specs -> NOT this skill.
project-contextmodee2e. - Generating or refreshing business maps and master test plan -> NOT this skill. Invoke the matching
project-contextmode. - API endpoint sync ->
bun run api:syncfor technical types;project-contextmodeapifor business narrative. - User asks about IQL methodology ->
iql-context(the methodology index: it cites the official site https://upexgalaxy.com/metodologia for the narrative andagentic-qa-core/references/stage-gates.mdfor the enforced per-stage contract). This skill carries no IQL reference of its own. - Code exploration (grep, read files) -> use built-in tools. If the user wants a browser-driven exploration instead (UI-first discovery), load
/playwright-cliskill. - Issue-tracker operations (Phase 4) -> resolve
[ISSUE_TRACKER_TOOL]via AGENTS.md Tool Resolution. For Jira, load/acliskill (primary) or fall back to the Atlassian MCP. If the project also uses Xray for TMS, load/xray-cliadditionally. - 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 ofsession/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-gapssection, never inline. - P2. NEVER skip Phase 1 (Constitution) when starting fresh. Downstream phases (architecture, infrastructure, backlog connection) assume the project values and stack are fixed first; skipping leaves later artifacts ungrounded.
- P3. NEVER fill the data, API or E2E maps (the HTML inside
business-data-context,business-api-context,business-e2e-context) from this skill.project-contextre-reads evidence and owns those artifacts. This skill generates only thebusiness-domain-contextandinfra-contextmaps. - P4. NEVER mix
project-discoverywithtest-framework-adaptationin the same session. Their write boundaries differ. - P5. NEVER use
project-discoveryfor incremental updates of the data, API or E2E maps. Useproject-context. Its own two maps are updated section by section, never regenerated whole. - P6. NEVER skip the domain glossary in Phase 1. It lives in
business-domain-context, and downstream skills load that skill as a precondition when its map is generated:sprint-testinglists it in its Stage 1 planning inputs (ATP, refined ACs, TC outlines) andtest-documentationuses it as the vocabulary reference for TC naming and bodies. - P7. NEVER fabricate Jira / Xray field IDs or status names in the Master Test Plan or any PBI template. Run
bun run jira:sync-fields --forceand reference{{jira.<slug>}}via the slug catalog in.agents/jira-required.yaml.
Quick reference
# Phase 1 — Project Connection (detection commands)
ls -la <target-repo> # repo root
cat <target-repo>/package.json | jq . # JS/TS stack
cat <target-repo>/pyproject.toml # Python stack
ls <target-repo>/.github/workflows # CI presence
find <target-repo> -maxdepth 2 -name "docker-compose*.yml" -o -name "Dockerfile"
# Phase 2 — Architecture source-of-truth order
# 1. Read routes (frontend app/ or pages/ or router.ts)
# 2. Read API handlers (src/controllers/ or src/routes/ or src/api/)
# 3. Read DB schema (prisma/schema.prisma, migrations/, schema.sql)
# 4. Read auth config (middleware.ts, auth.config.ts, passport config)
# Phase 3 — Infrastructure
cat <target-repo>/.env.example # env var contract
grep -r "process.env\." <target-repo>/src # env vars actually read
cat <target-repo>/.github/workflows/*.yml # CI/CD pipeline
# Post-discovery context handoff (separate skill):
# project-context refresh-all # data -> e2e -> api -> test-plan
# bun run api:sync # exact API types from OpenAPI
# Read back the two maps discovery generates
bun run context:map business-domain-context --list
bun run context:map infra-context --list
# Issue tracker (Phase 4): connection check, writes no file
# Prerequisite: Load /acli skill before executing the commands below.
bun run jira:check
[ISSUE_TRACKER_TOOL] Get Issue:
key: {{PROJECT_KEY}}-1Does 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.

