project-discovery

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.

1. 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.
2. Target repo's README.md and existing onboarding docs — fastest path to project intent, stack signals, and run commands before deep code reads.
3. .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.
4. .agents/project.yaml and .env.example — variable resolution patterns ({{PROJECT_KEY}}, env URLs, MCP names) that every downstream context file references.
5. kata-manifest.json — registry of existing KATA Components + ATCs. Anchors what test surface the boilerplate already expects so discovery records gaps coherently.
6. .agents/skills/agentic-qa-core/references/skill-composition-strategy.md — workflow context for downstream handoffs (project-context, adapt-framework, sprint-testing, test-documentation).
7. 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) AND agentic-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 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 AGENTS.md §"Orchestration Mode (Subagent Strategy)" 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:

1. Check .session/project-discovery/progress.md.
2. If it does NOT exist → proceed to "Before starting: target repo location" below, then "Pick the scope first" (which writes plan.md).
3. 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.

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.

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)                 (PRD + SRS)                    (backend/frontend/infra)       (PBI mapping)
                |                      |                              |                              |
   .context/business/            .context/PRD/*.md           .context/infrastructure/*.md     .context/PBI/ACCESS.md
   business-model.md            .context/SRS/*.md
   domain-glossary.md
   project-config.md

                                                 |
                                                 v
                                    project-context (separate skill)
                                    data -> features -> api -> test-plan
                                    `bun run api:sync` remains the technical
                                    OpenAPI type pipeline.

KATA adaptation is a separate skill: adapt-framework. It runs after discovery and context outputs exist.

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:

1. Project Connection -- repo paths, tech stack detection, environment URLs, credentials from .env, team contacts.
2. Project Assessment -- current testing maturity (frameworks in place, CI presence, lint/typecheck, coverage). Produces a risk profile.
3. Business Model Discovery -- problem statement, target users, value proposition, revenue model (if any). Business Model Canvas recommended.
4. 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 canonical AGENTS.md. 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):

1. Executive Summary -- problem, solution, success metrics, scope.
2. User Personas -- roles, permissions, primary/secondary users, role hierarchy.
3. User Journeys -- critical paths through the UI, route map, journey diagrams.

Feature catalog is post-discovery. project-context mode features owns .context/business/business-feature-map.md. Do not generate it here.

SRS sub-steps (run after PRD, serially):

1. Architecture Specs -- C4 context and container diagrams, component structure, database schema, external services, security model.
2. Functional Specs -- FR-N entries with preconditions, business rules, validations, state machines.
3. 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; the business angle is owned by project-context mode api. Phase 2 records only the spec location or a Discovery Gap.

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 is recorded in .context/project-config.md. business-feature-map.md remains a post-discovery project-context output. 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:

1. Backend Discovery -- language, framework, database, ORM, auth, dependency manager, run/test commands, migrations, env vars.
2. Frontend Discovery -- framework, bundler, routing, state management, design system, component library, test IDs strategy.
3. 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.

One sub-step:

1. 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. Output: .context/PBI/ACCESS.md (backlog access recipe). NEVER write .context/PBI/README.md — it is a committed framework document (tier doctrine + gitignore ladder), not a discovery output; same for the committed templates/ skeletons.

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 (ACCESS.md).

Completion gate: .context/PBI/ACCESS.md exists with project key + auth recipe. Soft content checks:

• PBI/ACCESS.md contains the configured {{PROJECT_KEY}} literal AND a ## Common Queries section (or JQL / WIQL snippet).
• .context/PBI/README.md and .context/PBI/templates/ untouched (framework-owned, committed).

Show outputs 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. Contains issue-tracker connection recipes, query conventions, and the ACCESS.md structure.

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 -> features -> api -> test-plan, including every CREATE/UPDATE approval gate. Exact OpenAPI types remain owned by bun run api:sync.

After those outputs exist, invoke adapt-framework 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 PRD, SRS, glossary, infrastructure, and backlog access. 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:
- .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/ACCESS.md

**Recommended next skill** (run in a clean session):

`project-context` mode `refresh-all`

It runs data -> features -> api -> test-plan in dependency order and can be re-run whenever project context becomes stale.

After it completes, invoke `adapt-framework` to wire KATA against the target stack.

Do not auto-chain the handoff inside this session. Context generation needs its own token budget and approval lifecycle.

Pre-adapt-framework checklist

Before the user invokes adapt-framework, verify every file below is on disk. Missing business maps route to the matching project-context mode.

• .context/PRD/ populated (at least README.md) AND .context/business/business-model.md or domain-glossary.md present
• .context/SRS/architecture.md
• .context/infrastructure/backend.md and .context/infrastructure/frontend.md
• .context/business/business-data-map.md
• API contract source: one of api/openapi-types.ts (non-stub) OR reachable OpenAPI spec URL OR .context/business/business-api-map.md (business-angle fallback)
• .env.example (and .env either present or created during adapt-framework)

Handoff line to print to the user:

Discovery handoff complete. Run project-context refresh-all, then invoke adapt-framework when the six prerequisites are 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.

Gotchas

• Discovery is read-only on the target repo. .context/ is the only write target. For modifications to this boilerplate, 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. Capture the real login request in backend.md so adaptation has a concrete contract.
• Never refresh maps here. Route existing-map refreshes to project-context, which owns 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 business-data-map.md.
• API requests get redirected. Use bun run api:sync for technical types and project-context mode api for the business angle.

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 (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=

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 or refreshing business maps and master test plan -> NOT this skill. Invoke the matching project-context mode.
• API endpoint sync -> bun run api:sync for technical types; project-context mode api for business narrative.
• 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 AGENTS.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 this skill. project-context re-reads evidence and owns the artifact.
• P4. NEVER mix project-discovery with adapt-framework in the same session. Their write boundaries differ.
• P5. NEVER use project-discovery for incremental map updates. Use project-context.
• 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

# 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 — PRD/SRS 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 -> features -> api -> test-plan
#   bun run api:sync                # exact API types from OpenAPI

# Issue tracker (Phase 4) — example placeholder
# Prerequisite: Load /acli skill before executing the commands below.
[ISSUE_TRACKER_TOOL] Get Issue:
  key: {{PROJECT_KEY}}-1
[ISSUE_TRACKER_TOOL] Search Issues:
  project: {{PROJECT_KEY}}
  query: sprint in openSprints() AND assignee = currentUser()