{"slug":"project-discovery","title":"project-discovery","summary":"Onboard a project through four discovery phases: Constitution, Architecture, Infrastructure, and Specification. Produces PRD, SRS, domain glossary, infrastructure context, and backlog access, then hands business maps and the master test plan to `project-context`. Use for set up t","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-25T15:20:13.109785Z","repo":{"url":"https://github.com/upex-galaxy/agentic-qa-boilerplate","stars":22,"forks":13,"license":"MIT","updatedAt":"2026-09-23T10:18:12Z"},"bodyHtml":"<hr>\n<h2>name: project-discovery\ndescription: \"Onboard a project through four discovery phases: Constitution, Architecture, Infrastructure, and Specification. Produces PRD, SRS, domain glossary, infrastructure context, and backlog access, then hands business maps and the master test plan to <code>project-context</code>. 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 (<code>project-context</code>), writing tests, TMS documentation, running suites, adapting KATA (<code>adapt-framework</code>), or technical OpenAPI sync (<code>bun run api:sync</code>).\"\nlicense: MIT\ncompatibility: [claude-code, copilot, cursor, codex, opencode]\ncomplementary_categories: [meta-skill]</h2>\n<h1>Project Discovery — Onboarding Orchestrator</h1>\n<p>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 (<code>shift-left-testing</code>, <code>sprint-testing</code>, <code>test-automation</code>, <code>test-documentation</code>, <code>regression-testing</code>) rely on.</p>\n<p>The discovery is <strong>conversational</strong>: 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.</p>\n<p>Grounding methodology: <strong>IQL (Integrated Quality Lifecycle)</strong> — QA is continuous from requirement to release, not a gate at the end. The full rationale and step breakdown live in <code>docs/methodology/IQL-methodology.md</code> (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.</p>\n<hr>\n<h2>Inputs</h2>\n<p>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.</p>\n<ol>\n<li><strong>Target project repo</strong> — 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.</li>\n<li><strong>Target repo's <code>README.md</code> and existing onboarding docs</strong> — fastest path to project intent, stack signals, and run commands before deep code reads.</li>\n<li><strong><code>.context/</code> directory</strong> (if partial state exists from a prior discovery run) — informs Phase 0 resume decisions and prevents redundant work. Diff against current code before overwriting.</li>\n<li><strong><code>.agents/project.yaml</code> and <code>.env.example</code></strong> — variable resolution patterns (<code>{{PROJECT_KEY}}</code>, env URLs, MCP names) that every downstream context file references.</li>\n<li><strong><code>kata-manifest.json</code></strong> — registry of existing KATA Components + ATCs. Anchors what test surface the boilerplate already expects so discovery records gaps coherently.</li>\n<li><strong><code>.agents/skills/agentic-qa-core/references/skill-composition-strategy.md</code></strong> — workflow context for downstream handoffs (<code>project-context</code>, <code>adapt-framework</code>, <code>sprint-testing</code>, <code>test-documentation</code>).</li>\n<li><strong>Business / domain docs supplied by the user</strong> (Confluence, Notion exports, internal wikis) — secondary source for business model and glossary when in-repo signal is thin.</li>\n</ol>\n<hr>\n<h2>Subagent Dispatch Strategy</h2>\n<blockquote>\n<p><strong>Orchestration &amp; Session contracts</strong>: this skill follows <code>agentic-qa-core/references/orchestration-doctrine.md</code> (mandatory subagent dispatch — main thread is command center) AND <code>agentic-qa-core/references/session-management.md</code> (Phase 0 resume check, plan-first persistence at <code>.session/&lt;skill-slug&gt;/&lt;scope&gt;/</code>, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional.</p>\n</blockquote>\n<p>This skill is <strong>project-scope</strong>: no <code>&lt;scope&gt;</code> segment. Session state lives directly at <code>.session/project-discovery/{plan.md, progress.md}</code> per <code>agentic-qa-core/references/session-management.md</code> §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 <code>progress.md</code> and skips back to the first incomplete phase without re-prompting the user for already-confirmed scope.</p>\n<p>This skill is compliant with the doctrine in <code>AGENTS.md</code> §\"Orchestration Mode (Subagent Strategy)\" and the session contract in <code>.agents/skills/agentic-qa-core/references/session-management.md</code>. Per-phase dispatch decisions live in <code>Pick the scope first</code> below: Fresh = heavy subagent delegation per phase; Boilerplate adoption = medium; Brownfield + Context refresh = main session only.</p>\n<hr>\n<h2>Phase 0 — Session resume check (MANDATORY, inline)</h2>\n<p>Before scope selection or any target-repo discovery, run the resume contract from <code>agentic-qa-core/references/session-management.md</code> §4:</p>\n<ol>\n<li>Check <code>.session/project-discovery/progress.md</code>.</li>\n<li>If it does NOT exist → proceed to \"Before starting: target repo location\" below, then \"Pick the scope first\" (which writes <code>plan.md</code>).</li>\n<li>If it DOES exist:\n<ul>\n<li>Read <code>plan.md</code> (chosen scope, target repo path, phase plan).</li>\n<li>Read tail of <code>progress.md</code> (last completed phase + next planned phase).</li>\n<li>Surface to the user: scope chosen, target repo, last completed phase, next phase, any open Discovery Gaps from the last entry.</li>\n<li>Offer <strong>resume / restart / abort</strong>. On <code>restart</code>, archive to <code>.session/.archive/&lt;YYYY-MM-DD&gt;-project-discovery-aborted/</code> before proceeding.</li>\n</ul>\n</li>\n</ol>\n<p>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.</p>\n<hr>\n<h2>Before starting: target repo location</h2>\n<p><code>/project-discovery</code> runs <strong>read-only</strong> against a project under test — the <strong>target repo</strong> — that is NOT this boilerplate. Before Phase 1 starts, lock down where the target lives. Block Phase 1 if the target path is ambiguous.</p>\n<table>\n<thead>\n<tr>\n<th>Layout</th>\n<th>What to declare</th>\n<th>How to detect</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><strong>Monorepo</strong> (single repo contains FE + BE)</td>\n<td>Absolute or relative path from this repo</td>\n<td>Check the candidate path for <code>pnpm-workspace.yaml</code>, <code>turbo.json</code>, <code>nx.json</code>, <code>lerna.json</code>, or a top-level <code>package.json</code> with no deps of its own</td>\n</tr>\n<tr>\n<td><strong>Split sibling repos</strong> (FE and BE cloned separately)</td>\n<td>One path per repo (or a common parent dir)</td>\n<td>Look at <code>../</code>-level siblings with plausible names (<code>*-backend</code>, <code>*-frontend</code>, <code>*-api</code>, <code>*-web</code>); confirm with the user</td>\n</tr>\n<tr>\n<td><strong>Remote (not cloned yet)</strong></td>\n<td>Repo URL + branch, then ask the user to clone locally before Phase 1</td>\n<td><code>gh repo view</code> only returns metadata; real discovery needs local file access — do not try to discover from a URL</td>\n</tr>\n</tbody>\n</table>\n<p>Record the resolved path(s) in <code>.context/project-config.md</code> §Repositories during Phase 1 sub-step 1 (Project Connection). Every <code>&lt;target-repo&gt;</code> reference in later phases resolves to the path declared here.</p>\n<p>If the layout is \"split sibling repos\", run Phase 1 sub-steps once per repo and merge findings into a single <code>project-config.md</code>; do not interleave.</p>\n<hr>\n<h2>Pick the scope first</h2>\n<p>All projects go through the same 4 phases, but depth varies. Pick once, then follow the common pipeline.</p>\n<table>\n<thead>\n<tr>\n<th>Scenario</th>\n<th>Input</th>\n<th>Phases to run</th>\n<th>Typical depth</th>\n<th>Context weight &amp; subagent hint</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><strong>Fresh onboarding</strong> (greenfield or unseen project)</td>\n<td>Repo URL or local path(s), no existing context files</td>\n<td>1 -&gt; 2 -&gt; 3 -&gt; 4, then <code>project-context refresh-all</code></td>\n<td>Full discovery. Business maps and test strategy are generated by their dedicated skill. After context completion, run <code>adapt-framework</code>.</td>\n<td><strong>Heavy.</strong> Delegate each phase's code survey to a dedicated subagent.</td>\n</tr>\n<tr>\n<td><strong>Boilerplate adoption</strong> (this repo adopted for a new project)</td>\n<td>Target app repo(s), this repo as the test framework</td>\n<td>1 (project-connection) -&gt; 3, then <code>project-context</code> for missing maps</td>\n<td>Skip Phase 2 or 4 only when their required artifacts already exist. Verify files on disk before <code>adapt-framework</code>.</td>\n<td><strong>Medium.</strong> Delegate Phase 1 and Phase 3 per package for monorepos.</td>\n</tr>\n<tr>\n<td><strong>Brownfield</strong> (project already documented, tests missing)</td>\n<td>Existing <code>.context/</code> partially filled</td>\n<td>2 (gaps) -&gt; 3 (gaps) -&gt; 4 (gaps), then <code>project-context</code> for stale maps</td>\n<td>Fill discovery gaps here; refresh map artifacts in their owning skill.</td>\n<td><strong>Light.</strong> Main session unless gaps span many files.</td>\n</tr>\n<tr>\n<td><strong>Context refresh</strong></td>\n<td>User asks to regenerate a business map or master test plan</td>\n<td>Redirect to the matching <code>project-context</code> mode</td>\n<td>This skill does not refresh those artifacts. For PBI access changes, re-run Phase 4. For exact OpenAPI types, use <code>bun run api:sync</code>.</td>\n<td><strong>Minimal.</strong> Handoff only.</td>\n</tr>\n</tbody>\n</table>\n<p>Default to \"Fresh onboarding\" when in doubt. Confirm the scope with the user before starting Phase 1.</p>\n<p>After scope confirmation, <strong>write <code>.session/project-discovery/plan.md</code></strong> per <code>agentic-qa-core/references/session-management.md</code> §6. The phase breakdown ends at Phase 4; record <code>project-context refresh-all</code> as the post-discovery handoff, not as a discovery phase.</p>\n<hr>\n<h2>Workflow — the 4-phase pipeline</h2>\n<pre><code>Phase 1: Constitution        -&gt; Phase 2: Architecture       -&gt; Phase 3: Infrastructure    -&gt; Phase 4: Specification\n(who/what/why)                 (PRD + SRS)                    (backend/frontend/infra)       (PBI mapping)\n                |                      |                              |                              |\n   .context/business/            .context/PRD/*.md           .context/infrastructure/*.md     .context/PBI/ACCESS.md\n   business-model.md            .context/SRS/*.md\n   domain-glossary.md\n   project-config.md\n\n                                                 |\n                                                 v\n                                    project-context (separate skill)\n                                    data -&gt; features -&gt; api -&gt; test-plan\n                                    `bun run api:sync` remains the technical\n                                    OpenAPI type pipeline.\n</code></pre>\n<blockquote>\n<p>KATA adaptation is a separate skill: <code>adapt-framework</code>. It runs after discovery and context outputs exist.</p>\n</blockquote>\n<p>Each phase has a <strong>completion gate</strong>: 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.</p>\n<h3>Phase 1 — Constitution (who, what, why)</h3>\n<p><strong>Goal</strong>: make the project legible. Outputs are read by every future session.</p>\n<p>Four sub-steps, in order:</p>\n<ol>\n<li><strong>Project Connection</strong> -- repo paths, tech stack detection, environment URLs, credentials from <code>.env</code>, team contacts.</li>\n<li><strong>Project Assessment</strong> -- current testing maturity (frameworks in place, CI presence, lint/typecheck, coverage). Produces a risk profile.</li>\n<li><strong>Business Model Discovery</strong> -- problem statement, target users, value proposition, revenue model (if any). Business Model Canvas recommended.</li>\n<li><strong>Domain Glossary</strong> -- core entities, relationships, state machines, enumerations, UI-label vs code-identifier mapping.</li>\n</ol>\n<p><strong>Completion gate</strong>: <code>.context/business/business-model.md</code>, <code>.context/business/domain-glossary.md</code>, <code>.context/project-config.md</code> all exist and are non-empty. Plus a <code>## Project Assessment (Phase 1)</code> block in canonical <code>AGENTS.md</code>. Sanity-check content — these are soft gates, surfaced to the human as warnings, not hard aborts:</p>\n<ul>\n<li><code>domain-glossary.md</code> contains at least 5 core-entity subsections (grep <code>^### </code> yields 5+ matches, ignoring top-level H3s from \"Enumerations\" etc. — aim for real entities).</li>\n<li><code>business-model.md</code> cites at least one concrete source (<code>Source:</code> or <code>Found in:</code> literal appears 3+ times).</li>\n<li><code>project-config.md</code> has a <code>## Tech Stack</code> section AND a <code>## Environments</code> section.</li>\n</ul>\n<p>After the automated sanity check, show the human the output paths and wait for explicit \"Phase 1 complete, continue\" before moving on.</p>\n<p>Read <code>references/phase-1-constitution.md</code> when running any Phase 1 sub-step. Contains the discovery process, stack-detection commands, required output sections, and quality checklists.</p>\n<h3>Phase 2 — Architecture (PRD + SRS)</h3>\n<p><strong>Goal</strong>: produce the Product and Software Requirements docs from code (not the other way round -- that is the \"creation\" direction, this is the \"discovery\" direction).</p>\n<p>PRD sub-steps (run first, in parallel or sequentially — user choice):</p>\n<ol>\n<li><strong>Executive Summary</strong> -- problem, solution, success metrics, scope.</li>\n<li><strong>User Personas</strong> -- roles, permissions, primary/secondary users, role hierarchy.</li>\n<li><strong>User Journeys</strong> -- critical paths through the UI, route map, journey diagrams.</li>\n</ol>\n<blockquote>\n<p><strong>Feature catalog is post-discovery.</strong> <code>project-context</code> mode <code>features</code> owns <code>.context/business/business-feature-map.md</code>. Do not generate it here.</p>\n</blockquote>\n<p>SRS sub-steps (run after PRD, serially):</p>\n<ol>\n<li><strong>Architecture Specs</strong> -- C4 context and container diagrams, component structure, database schema, external services, security model.</li>\n<li><strong>Functional Specs</strong> -- FR-N entries with preconditions, business rules, validations, state machines.</li>\n<li><strong>Non-Functional Specs</strong> -- performance budgets, security posture, reliability (RTO/RPO), scalability, observability, compliance.</li>\n</ol>\n<blockquote>\n<p><strong>API contracts are NOT an SRS output.</strong> The technical surface is owned by <code>bun run api:sync</code>; the business angle is owned by <code>project-context</code> mode <code>api</code>. Phase 2 records only the spec location or a Discovery Gap.</p>\n</blockquote>\n<blockquote>\n<p><strong>Test-architecture ADR seeding (Phase 2 SRS + Phase 3).</strong> When the Architecture Specs / Infrastructure sub-steps settle a hard-to-reverse <strong>test</strong>-architecture decision — test runner/framework, isolation &amp; parallelization model, fixture/test-data strategy, auth-in-tests, selector/<code>data-testid</code> contract, exploratory-vs-scripted boundary, CI sharding — promote each one that passes the two-gate test (architectural AND hard to reverse) to a standalone <code>ADR-NNNN-&lt;slug&gt;.md</code> in <code>.context/ADR/</code>, and reference it from <code>architecture.md</code> / <code>infrastructure/</code>. Greenfield: you are ENCODING the decision; brownfield: you are RECORDING the one you discovered. Follow <code>agentic-qa-core/references/adr-doctrine.md</code> (detection + authoring) and <code>.context/ADR/README.md</code> (template + lifecycle). AI drafts <code>Proposed</code>; the human accepts.</p>\n</blockquote>\n<p><strong>Completion gate</strong>: <code>.context/PRD/executive-summary.md</code>, <code>user-personas.md</code>, <code>user-journeys.md</code>, <code>.context/SRS/architecture.md</code>, <code>functional-specs.md</code>, <code>non-functional-specs.md</code> all exist. API contract source is recorded in <code>.context/project-config.md</code>. <code>business-feature-map.md</code> remains a post-discovery <code>project-context</code> output. Soft content checks:</p>\n<ul>\n<li><code>architecture.md</code> contains at least one <code> ```mermaid</code> block AND one of (<code>## Data Flow</code>, <code>## Database Schema</code>, <code>## Component Structure</code>).</li>\n<li><code>functional-specs.md</code> contains at least one <code>FR-</code> identifier and one <code>BR-</code> identifier.</li>\n<li><code>user-personas.md</code> lists at least 2 role entries (<code>### </code> or table rows with role names).</li>\n</ul>\n<p>Show outputs to the human and wait for \"Phase 2 complete, continue\" before moving on.</p>\n<p>Read <code>references/phase-2-prd.md</code> when working on any PRD doc. Read <code>references/phase-2-srs.md</code> when working on any SRS doc. They are independent -- do not load both unless you are straddling both sides.</p>\n<h3>Phase 3 — Infrastructure</h3>\n<p><strong>Goal</strong>: make the project runnable and deployable for the test environment.</p>\n<p>Three sub-steps:</p>\n<ol>\n<li><strong>Backend Discovery</strong> -- language, framework, database, ORM, auth, dependency manager, run/test commands, migrations, env vars.</li>\n<li><strong>Frontend Discovery</strong> -- framework, bundler, routing, state management, design system, component library, test IDs strategy.</li>\n<li><strong>Infrastructure Mapping</strong> -- CI/CD providers, deployment targets, environments (dev/staging/prod), infra-as-code, monitoring, rollback procedure.</li>\n</ol>\n<p><strong>Completion gate</strong>: <code>.context/infrastructure/backend.md</code>, <code>frontend.md</code>, <code>infrastructure.md</code> all exist with the key facts (auth flow, test commands, deploy URLs) filled in. Soft content checks:</p>\n<ul>\n<li><code>backend.md</code> AND <code>frontend.md</code> each contain a <code>## Runtime</code> (or <code>## Build Configuration</code>) section AND a commands block (<code>bash</code> fenced) covering install + run.</li>\n<li><code>infrastructure.md</code> lists environments explicitly (<code>| Staging |</code> or <code>| Production |</code> table row).</li>\n<li>At least one auth-flow pointer exists in <code>backend.md</code> (e.g., mentions <code>/auth/login</code>, <code>session</code>, <code>JWT</code>, <code>cookie</code>, <code>OAuth</code>).</li>\n</ul>\n<p>Show outputs to the human and wait for \"Phase 3 complete, continue\" before moving on.</p>\n<p>Read <code>references/phase-3-infrastructure.md</code> 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).</p>\n<h3>Phase 4 — Specification (Backlog mapping)</h3>\n<p><strong>Goal</strong>: hook the testing framework into the team's issue tracker without duplicating content.</p>\n<p>One sub-step:</p>\n<ol>\n<li><strong>PBI Backlog Mapping</strong> -- connect to <code>{{ISSUE_TRACKER}}</code> via <code>[ISSUE_TRACKER_TOOL]</code>, discover project key, map hierarchy (Epic/Story/Task/Bug), record queries used to fetch tickets. Output: <code>.context/PBI/ACCESS.md</code> (backlog access recipe). NEVER write <code>.context/PBI/README.md</code> — it is a committed framework document (tier doctrine + gitignore ladder), not a discovery output; same for the committed <code>templates/</code> skeletons.</li>\n</ol>\n<blockquote>\n<p><strong>Per-ticket PBI is NOT generated by this skill.</strong> It is materialized later by <code>/sprint-testing</code> via <code>bun run jira:sync-issues get &lt;KEY&gt; --include-comments</code>, which writes the canonical synced tree <code>.context/PBI/epics/EPIC-&lt;KEY&gt;-&lt;slug&gt;/stories/STORY-&lt;KEY&gt;-&lt;slug&gt;/</code> (Module = Epic, 1:1). Those local <code>.md</code> files are a READ-ONLY cache of Jira (Jira = source of truth). This skill does NOT create per-ticket <code>story.md</code> — it only sets up the backlog access recipe (<code>ACCESS.md</code>).</p>\n</blockquote>\n<p><strong>Completion gate</strong>: <code>.context/PBI/ACCESS.md</code> exists with project key + auth recipe. Soft content checks:</p>\n<ul>\n<li><code>PBI/ACCESS.md</code> contains the configured <code>{{PROJECT_KEY}}</code> literal AND a <code>## Common Queries</code> section (or JQL / WIQL snippet).</li>\n<li><code>.context/PBI/README.md</code> and <code>.context/PBI/templates/</code> untouched (framework-owned, committed).</li>\n</ul>\n<p>Show outputs to the human and wait for \"Phase 4 complete\" before emitting the <code>project-context</code> handoff.</p>\n<p>Read <code>references/phase-4-specification.md</code> when running Phase 4. Contains issue-tracker connection recipes, query conventions, and the <code>ACCESS.md</code> structure.</p>\n<h3>Business-context handoff</h3>\n<p>Business maps and the master test plan are not generated here. After Phase 4, open a clean session and invoke <code>project-context</code> mode <code>refresh-all</code>. It owns the deterministic sequence <code>data -&gt; features -&gt; api -&gt; test-plan</code>, including every CREATE/UPDATE approval gate. Exact OpenAPI types remain owned by <code>bun run api:sync</code>.</p>\n<p>After those outputs exist, invoke <code>adapt-framework</code> to wire this boilerplate to the target stack.</p>\n<hr>\n<h2>Per-phase progress + Archive</h2>\n<p>After each phase passes its completion gate AND the user confirms \"Phase N complete\", append a phase entry to <code>.session/project-discovery/progress.md</code>. Entries end at Phase 4; the next action is the separate <code>project-context</code> skill.</p>\n<p>After Phase 4 passes, archive the project-discovery session per <code>agentic-qa-core/references/session-management.md</code> §8 and record the <code>project-context refresh-all</code> handoff. Context generation has its own lifecycle and does not keep this session open.</p>\n<p>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.</p>\n<hr>\n<h2>Next recommended steps (emit after Phase 4 completes)</h2>\n<p>Discovery populates PRD, SRS, glossary, infrastructure, and backlog access. It does not invoke <code>project-context</code>, which is token-heavy and best run in a clean session.</p>\n<p>When Phase 4 is confirmed complete, print this block to the user verbatim:</p>\n<pre><code>Discovery complete. `/project-discovery` has populated:\n- .context/business/business-model.md, domain-glossary.md\n- .context/project-config.md\n- .context/PRD/executive-summary.md, user-personas.md, user-journeys.md\n- .context/SRS/architecture.md, functional-specs.md, non-functional-specs.md\n- .context/infrastructure/backend.md, frontend.md, infrastructure.md\n- .context/PBI/ACCESS.md\n\n**Recommended next skill** (run in a clean session):\n\n`project-context` mode `refresh-all`\n\nIt runs data -&gt; features -&gt; api -&gt; test-plan in dependency order and can be re-run whenever project context becomes stale.\n\nAfter it completes, invoke `adapt-framework` to wire KATA against the target stack.\n</code></pre>\n<p>Do not auto-chain the handoff inside this session. Context generation needs its own token budget and approval lifecycle.</p>\n<h3>Pre-adapt-framework checklist</h3>\n\n<p>Before the user invokes <code>adapt-framework</code>, verify every file below is on disk. Missing business maps route to the matching <code>project-context</code> mode.</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <code>.context/PRD/</code> populated (at least <code>README.md</code>) AND <code>.context/business/business-model.md</code> or <code>domain-glossary.md</code> present</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <code>.context/SRS/architecture.md</code></li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <code>.context/infrastructure/backend.md</code> and <code>.context/infrastructure/frontend.md</code></li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <code>.context/business/business-data-map.md</code></li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> API contract source: one of <code>api/openapi-types.ts</code> (non-stub) OR reachable OpenAPI spec URL OR <code>.context/business/business-api-map.md</code> (business-angle fallback)</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <code>.env.example</code> (and <code>.env</code> either present or created during <code>adapt-framework</code>)</li>\n</ul>\n<p>Handoff line to print to the user:</p>\n<blockquote>\n<p>Discovery handoff complete. Run <code>project-context refresh-all</code>, then invoke <code>adapt-framework</code> when the six prerequisites are present.</p>\n</blockquote>\n<hr>\n<h2>Stack-specific discovery rules</h2>\n<p>Base stack detection (package.json → Node, pyproject.toml → Python, go.mod → Go, <code>next.config.*</code> → Next.js, etc.) is a baseline skill any AI has. This section only lists <strong>actions the skill should take based on what is detected</strong> — rules that are not obvious from general programming knowledge.</p>\n<table>\n<thead>\n<tr>\n<th>Signal</th>\n<th>Action for discovery</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Monorepo (<code>pnpm-workspace.yaml</code>, <code>turbo.json</code>, <code>nx.json</code>, <code>lerna.json</code>, or top-level <code>package.json</code> with no deps of its own)</td>\n<td>Split backend/frontend per package. Run Phase 1 <strong>once</strong> (project-level), Phase 2-3 <strong>per package</strong>. Merge outputs under <code>.context/infrastructure/</code> with sub-sections per package.</td>\n</tr>\n<tr>\n<td>Multiple coexisting signals in one repo (e.g., Next.js + Express)</td>\n<td>Almost always a monorepo — treat frontend and backend as separate discoveries even if workspace config is missing. Do NOT produce a merged SRS.</td>\n</tr>\n<tr>\n<td><code>Dockerfile</code> + <code>docker-compose.yml</code> present</td>\n<td>Read compose for service inventory <strong>before</strong> scanning source — it is the authoritative runtime topology. Use source only to fill gaps.</td>\n</tr>\n<tr>\n<td>No test framework deps detected</td>\n<td>Greenfield test story. Phase 3 documents the absence as a Discovery Gap. <strong>Do NOT install tooling in the target repo.</strong> <code>adapt-framework</code> wires this boilerplate's own test stack; it never modifies the target.</td>\n</tr>\n<tr>\n<td><code>.github/workflows/*.yml</code> present</td>\n<td>Extract the test job from CI for Phase 3 Infrastructure — usually the cleanest source for \"how CI runs tests\".</td>\n</tr>\n<tr>\n<td>API handlers found but no OpenAPI spec</td>\n<td>Flag as Discovery Gap in Phase 2 SRS. Do NOT hand-write an OpenAPI inside project-discovery; ask for a spec or defer the business angle to <code>project-context</code> mode <code>api</code>.</td>\n</tr>\n<tr>\n<td>Hardcoded secrets detected (grep hits in source)</td>\n<td>HIGH risk. Record path in <code>.context/risk-assessment.md</code> §Phase 1 Project Assessment. Do NOT paste the secret into any discovery doc — reference path only.</td>\n</tr>\n</tbody>\n</table>\n<hr>\n<h2>Gotchas</h2>\n<ul>\n<li><strong>Discovery is read-only on the target repo.</strong> <code>.context/</code> is the only write target. For modifications to this boilerplate, use <code>adapt-framework</code>.</li>\n<li><strong>Hard-to-reverse test decisions become ADRs, not buried prose.</strong> 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 <code>.context/ADR/ADR-NNNN-&lt;slug&gt;.md</code> (append-only) instead of leaving it only inside <code>architecture.md</code>. Draft <code>Proposed</code>; the human approves. See <code>agentic-qa-core/references/adr-doctrine.md</code>.</li>\n<li><strong>Credentials never live in discovery docs.</strong> Read them from <code>.env</code> (<code>LOCAL_USER_EMAIL</code>, <code>STAGING_USER_EMAIL</code>, etc.). If missing, ask the user to create <code>.env.example</code> or hand over secrets out-of-band -- do not paste them into markdown.</li>\n<li><strong>\"Discovery Gaps\" section is mandatory in every output.</strong> If you could not verify something from the code (e.g., traffic volume, uptime targets), list it in a <code>## Discovery Gaps</code> section rather than inventing a number. This signals to future sessions what still needs human input.</li>\n<li><strong>PRD/SRS discovered from code is authoritative, not aspirational.</strong> Describe what the system does, not what product wants it to do. If the user wants a \"to-be\" doc, that is PRD/SRS <em>creation</em> (out of scope for this skill); point them to their own product workflow.</li>\n<li><strong>Do not duplicate the backlog.</strong> Jira/Linear/GitHub Issues is the source of truth for tickets. <code>.context/PBI/</code> holds the backlog access recipe (<code>README.md</code>) and format-reference guides (<code>templates/</code>), never a copy of the full backlog. Per-ticket PBI is synced on demand from Jira by <code>/sprint-testing</code> (<code>bun run jira:sync-issues</code>) as a read-only cache — this skill does not create it.</li>\n<li><strong>Monorepos require scoped discovery.</strong> Run Phase 1 once (project as a whole) but Phases 2-3 per package. Merge findings into a single <code>.context/infrastructure/</code> with sub-sections per package.</li>\n<li><strong>Database schemas over ORM models.</strong> If both exist, prefer the migration files / schema dump over the ORM definitions -- ORM definitions can drift from the live schema.</li>\n<li><strong>API base URL vs route prefix.</strong> <code>{{environments.local.api_url}}</code> includes the protocol+host; route prefixes (e.g., <code>/api/v1</code>) belong in the path. Do not concatenate them twice in any context file that documents endpoints (e.g., <code>business-api-map.md</code>).</li>\n<li><strong>Auth flow is the single most important input for downstream <code>adapt-framework</code>.</strong> Capture the real login request in <code>backend.md</code> so adaptation has a concrete contract.</li>\n<li><strong>Never refresh maps here.</strong> Route existing-map refreshes to <code>project-context</code>, which owns diff and overwrite approval.</li>\n<li><strong>Context modes need grounded discovery.</strong> If the user requests a business map on a fresh repo, complete at least Phase 1 and Phase 3 before handing off.</li>\n<li><strong>IQL framing is optional.</strong> Mention it only if the user asks \"why this structure?\" -- do not lecture them on methodology when they just want a working <code>business-data-map.md</code>.</li>\n<li><strong>API requests get redirected.</strong> Use <code>bun run api:sync</code> for technical types and <code>project-context</code> mode <code>api</code> for the business angle.</li>\n</ul>\n<hr>\n<h2>Templates (inline -- small, load-bearing)</h2>\n<h3>Discovery Gaps section (every output)</h3>\n<pre><code>## Discovery Gaps\n\nThe following items could not be verified from code and require human confirmation:\n\n- [ ] &lt;Gap&gt;: &lt;what is missing, where you looked, suggested source of truth&gt;\n- [ ] ...\n</code></pre>\n<h3>Phase completion ping (used after each phase)</h3>\n<pre><code>Phase N complete.\nGenerated files:\n- &lt;path1&gt;\n- &lt;path2&gt;\nNext: Phase N+1 (&lt;phase name&gt;). Confirm to continue, or say \"pause\" to stop here.\n</code></pre>\n<h3><code>.env</code> key list emitted after Phase 1</h3>\n<pre><code># Application URLs (per-environment — match the env names you declared\n# under `environments:` in `.agents/project.yaml`; consumed by\n# `bun run agents:setup --non-interactive` via the `&lt;KEY&gt;_&lt;ENV&gt;` pattern)\nWEB_URL_LOCAL=\nWEB_URL_STAGING=\nAPI_URL_LOCAL=\nAPI_URL_STAGING=\n\n# Test User Credentials\nLOCAL_USER_EMAIL=\nLOCAL_USER_PASSWORD=\nSTAGING_USER_EMAIL=\nSTAGING_USER_PASSWORD=\n\n# Atlassian / TMS credentials (used by MCP, acli, xray-cli, sync scripts, and\n# the Jira-Direct TMS provider — no overrides)\n# NOTE: the Atlassian site HOST is not a .env variable. It lives in\n# .agents/project.yaml -&gt; issue_tracker.atlassian_url (`bun run agents:setup`).\nATLASSIAN_EMAIL=\nATLASSIAN_API_TOKEN=\n</code></pre>\n<p>Larger templates (full PRD sections, KATA component skeletons, <code>.context/infrastructure/backend.md</code> layout, <code>business-data-map.md</code> structure) live in the references.</p>\n<hr>\n<h2>Specific tasks -- which reference to read</h2>\n<ul>\n<li><strong>Phase 1 (project connection, assessment, business model, glossary)</strong> -&gt; read <code>references/phase-1-constitution.md</code>.</li>\n<li><strong>Phase 2 PRD (executive summary, personas, journeys, features)</strong> -&gt; read <code>references/phase-2-prd.md</code>.</li>\n<li><strong>Phase 2 SRS (architecture, API contracts, functional, non-functional)</strong> -&gt; read <code>references/phase-2-srs.md</code>.</li>\n<li><strong>Phase 3 (backend, frontend, infrastructure)</strong> -&gt; read <code>references/phase-3-infrastructure.md</code>.</li>\n<li><strong>Recording a hard-to-reverse test-architecture decision (ADR)</strong> -&gt; read <code>agentic-qa-core/references/adr-doctrine.md</code> + <code>.context/ADR/README.md</code>.</li>\n<li><strong>Phase 4 (backlog mapping, templates)</strong> -&gt; read <code>references/phase-4-specification.md</code>.</li>\n<li><strong>Generating or refreshing business maps and master test plan</strong> -&gt; NOT this skill. Invoke the matching <code>project-context</code> mode.</li>\n<li><strong>API endpoint sync</strong> -&gt; <code>bun run api:sync</code> for technical types; <code>project-context</code> mode <code>api</code> for business narrative.</li>\n<li><strong>User asks about IQL methodology</strong> -&gt; point them to <code>docs/methodology/IQL-methodology.md</code> (shared across QA skills). This skill no longer carries its own IQL reference.</li>\n<li><strong>Code exploration (grep, read files)</strong> -&gt; use built-in tools. If the user wants a browser-driven exploration instead (UI-first discovery), load <code>/playwright-cli</code> skill.</li>\n<li><strong>Issue-tracker operations (Phase 4)</strong> -&gt; resolve <code>[ISSUE_TRACKER_TOOL]</code> via AGENTS.md Tool Resolution. For Jira, load <code>/acli</code> skill (primary) or fall back to the Atlassian MCP. If the project also uses Xray for TMS, load <code>/xray-cli</code> additionally.</li>\n<li><strong>Database inspection</strong> -&gt; resolve <code>[DB_TOOL]</code>; read-only queries only during discovery.</li>\n<li><strong>Session contract (Phase 0 resume, plan.md/progress.md schemas, archive policy, Engram per-phase checkpoint)</strong> -&gt; read <code>../agentic-qa-core/references/session-management.md</code>. This skill is a producer of <code>session/project-discovery/...</code> topic keys.</li>\n</ul>\n<hr>\n<h2>Anti-patterns — NEVER do these</h2>\n<ul>\n<li><strong>P1.</strong> 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 <code>## Discovery Gaps</code> block, never inline.</li>\n<li><strong>P2.</strong> 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.</li>\n<li><strong>P3.</strong> NEVER fill <code>.context/business/business-data-map.md</code> from this skill. <code>project-context</code> re-reads evidence and owns the artifact.</li>\n<li><strong>P4.</strong> NEVER mix <code>project-discovery</code> with <code>adapt-framework</code> in the same session. Their write boundaries differ.</li>\n<li><strong>P5.</strong> NEVER use <code>project-discovery</code> for incremental map updates. Use <code>project-context</code>.</li>\n<li><strong>P6.</strong> NEVER skip the domain glossary in Phase 1. Downstream skills read it as a precondition when present: <code>sprint-testing</code> lists it in its Stage 1 planning inputs (ATP, refined ACs, TC outlines) and <code>test-documentation</code> uses it as the vocabulary reference for TC naming and bodies.</li>\n<li><strong>P7.</strong> NEVER fabricate Jira / Xray field IDs or status names in <code>.context/master-test-plan.md</code> or any PBI template. Run <code>bun run jira:sync-fields --force</code> and reference <code>{{jira.&lt;slug&gt;}}</code> via the slug catalog in <code>.agents/jira-required.yaml</code>.</li>\n</ul>\n<hr>\n<h2>Quick reference</h2>\n<pre><code># Phase 1 — Project Connection (detection commands)\nls -la &lt;target-repo&gt;                      # repo root\ncat &lt;target-repo&gt;/package.json | jq .     # JS/TS stack\ncat &lt;target-repo&gt;/pyproject.toml          # Python stack\nls &lt;target-repo&gt;/.github/workflows        # CI presence\nfind &lt;target-repo&gt; -maxdepth 2 -name \"docker-compose*.yml\" -o -name \"Dockerfile\"\n\n# Phase 2 — PRD/SRS source-of-truth order\n# 1. Read routes (frontend app/ or pages/ or router.ts)\n# 2. Read API handlers (src/controllers/ or src/routes/ or src/api/)\n# 3. Read DB schema (prisma/schema.prisma, migrations/, schema.sql)\n# 4. Read auth config (middleware.ts, auth.config.ts, passport config)\n\n# Phase 3 — Infrastructure\ncat &lt;target-repo&gt;/.env.example             # env var contract\ngrep -r \"process.env\\.\" &lt;target-repo&gt;/src  # env vars actually read\ncat &lt;target-repo&gt;/.github/workflows/*.yml  # CI/CD pipeline\n\n# Post-discovery context handoff (separate skill):\n#   project-context refresh-all     # data -&gt; features -&gt; api -&gt; test-plan\n#   bun run api:sync                # exact API types from OpenAPI\n\n# Issue tracker (Phase 4) — example placeholder\n# Prerequisite: Load /acli skill before executing the commands below.\n[ISSUE_TRACKER_TOOL] Get Issue:\n  key: {{PROJECT_KEY}}-1\n[ISSUE_TRACKER_TOOL] Search Issues:\n  project: {{PROJECT_KEY}}\n  query: sprint in openSprints() AND assignee = currentUser()\n</code></pre>\n","files":[{"path":"evals/evals.json","sizeBytes":3119,"isText":true},{"path":"references/phase-1-constitution.md","sizeBytes":14564,"isText":true},{"path":"references/phase-2-prd.md","sizeBytes":13027,"isText":true},{"path":"references/phase-2-srs.md","sizeBytes":15105,"isText":true},{"path":"references/phase-3-infrastructure.md","sizeBytes":15809,"isText":true},{"path":"references/phase-4-specification.md","sizeBytes":12421,"isText":true},{"path":"SKILL.md","sizeBytes":35574,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":23,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-16T15:01:39.755958Z","sha256":"4C50674729D389744222F5F17E26AB0AE795DCA09A8A74ED484DC0A4AF40DD0D","sizeBytes":44248},"review":null,"source":{"repositoryUrl":"https://github.com/upex-galaxy/agentic-qa-boilerplate","path":".agents/skills/project-discovery","license":"MIT","commit":"d287bb21d184a8a2001d056ab3edb96085bc3264","subtreeSha":"2E81A5B8B631BBDF40ADF9BD3B23007A36D4358655C472A1E8BC02252CB0CB8E","lastSyncedAt":"2026-09-23T13:51:07.971432Z"},"reviewedAt":"2026-09-16T15:05:08.614618Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/upex-galaxy/agentic-qa-boilerplate/tree/main/.agents/skills/project-discovery"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install upex-galaxy-agentic-qa-boilerplate@llmmart"},{"target":"git","command":"git clone https://github.com/upex-galaxy/agentic-qa-boilerplate.git"}]}