-
Check existing config: If sparq.config.json exists, prompt user:
- Keep: Use existing config, skip to step 8 (verification only)
- Reset: Delete and regenerate from scratch
- Merge: Keep existing values, fill in missing fields with defaults
-
Auto-detect tech stack from package.json and project structure:
package.json -> detect framework (vue, react, angular, svelte) — framework name is NOT stored in config; only derived fields (componentFileExtensions, sourceRoot, routeDiscoveryPattern) are stored in the project section- Component file extensions: derived from detected framework, stored in
project.componentFileExtensions
- Router:
vue-router -> "vue-router", react-router or react-router-dom -> "react-router", @angular/router -> "angular-router", next -> "next-router", nuxt -> "nuxt-router"
- Detect
project.sourceRoot: check for src/, app/, lib/ directories; use whichever exists (prefer src/ if multiple)
- Detect
project.routeDiscoveryPattern: derive from detected router (e.g., "**/router/**/*.ts" for vue-router, "app/**/page.tsx" for Next.js, "**/app-routing*.ts" for Angular)
-
Auto-detect E2E setup from filesystem:
- Check for
playwright.config.* AND cypress.config.* to determine E2E framework
- If no E2E framework detected, default to Playwright and set
e2e.framework: "playwright"
- Scan for
e2e/ or cypress/ directory
- Discover page objects: glob
e2e/pages/**/*.page.ts
- Discover components: glob
e2e/components/**/*.component.ts
- Discover steps: glob
e2e/steps/**/*.steps.ts
- Discover fixtures: glob
e2e/fixtures/**/*.fixture.ts
- Discover specs: glob
e2e/specs/**/*.spec.ts
- Find base class: look for
abstract.page.ts or class extending nothing with abstract methods
- Find fixture index: look for
e2e/fixtures/index.ts
-
Prompt for source configuration (requirements gathering):
- Jira: "Enter Jira project key (e.g., EP) or press Enter to skip"
- Confluence: "Enter Confluence space key or press Enter to skip"
- Figma: "Enable Figma integration? (y/n)"
- Local requirements: "Requirements directory path" (default:
docs/specs)
-
Prompt for export targets (where to publish results):
- TMS provider: "Select TMS provider: (1) TestRail, (2) Qase, (3) Local folder, (4) None" (default: None)
- If TestRail: "Enter TestRail project ID" and "Enter TestRail suite ID"
- If Qase: "Enter Qase project code (e.g., PROJ)"
- If Local: uses default
.sparq/tms-export (configurable via outputs.tms.local.outputDir)
- Jira export: "Link test results back to Jira tickets? (y/n)" (default: yes if Jira source enabled)
- Confluence export: "Publish test plans to Confluence? (y/n)" (default: yes if Confluence source enabled)
- If Confluence export enabled and no source space key: "Confluence space key for publishing"
-
Generate sparq.config.json: Assemble all detected and user-provided values. See .claude/skills/sparq-shared/references/config-schema.md for full schema and defaults.
-
Create .sparq/ directory structure:
.sparq/
├── requirements/ # REQ-{feature}.md files
├── test-cases/ # TC-{feature}-manual.md and .xml files
├── coverage/ # Coverage matrices
├── validation/ # Validation reports
├── refresh/ # S5 diff reports and previous requirement snapshots
├── plans/ # Execution plans
├── parallel/ # Temporary parallel staging (shared file patches only, cleaned after merge)
└── tracking/ # Test registry for traceability
└── test-registry.json # Auto-maintained test-to-requirement mapping
Note: E2E test code (pages, steps, fixtures, specs) is written directly to the project's test directory per e2e.structure.* config. The .sparq/ directory holds metadata only.
Note: .sparq/state/ is NOT created by init — the orchestrator creates it at workflow start and is the sole writer. See resume-protocol.md.
Directory .sparq/tracking/ must be created before initializing test-registry.json.
Initialize test-registry.json with: {"version":"1.0","lastUpdated":null,"entries":[]}
-
Verify MCP server availability (30s timeout per server): Test each enabled source:
- Jira: attempt
mcp__atlassian__jira_get_issue with a known ticket (or list projects)
- Confluence: attempt
mcp__atlassian__confluence_search with space key
- Figma: attempt
mcp__figma__whoami
- TestRail: attempt
mcp__testrail__get_sections with project ID
- Qase: attempt
mcp__qase__list_suites with project code
If verification fails, warn and continue -- user can configure later (see degradation-strategy.md Init Skill Fallback).
- Playwright (when
e2e.framework is playwright): run npx playwright --version to detect CLI availability
- Report status for each: available / unavailable / auth required
Atlassian OAuth note: Jira and Confluence use the Atlassian MCP server which authenticates via OAuth 2.1 browser login — no ENV vars or API tokens needed. On first connection, Claude Code opens a browser for Atlassian login and consent. If "Auth required" is reported, the user needs to complete the OAuth flow (e.g., via /mcp in Claude Code settings). See jira-patterns.md ## Authentication for alternative CI/headless auth methods.
The "Jira project key" prompted during init (e.g., EP, PROJ) is the project identifier used in JQL queries — it is NOT an API key or credential.
After verification, present results in a clear dashboard:
Integration Status
──────────────────
Jira ({key}): {status} -- {action if failed}
Confluence ({key}): {status} -- {action if failed}
Figma: {status} -- {action if failed}
Playwright: {status} -- {action if failed}
Status values:
- "Ready" -- connection verified, tool responded
- "Auth required" -- Atlassian: "Complete OAuth login via /mcp in Claude Code"; Others: "Check your API token in .mcp.json"
- "Not configured" -- "Enable in sparq.config.json or via /sparq:config"
- "Timeout" -- "Service may be temporarily unavailable. SparQ will retry during workflows."
If any source is unavailable, explain impact:
- "Jira unavailable: Requirements must be provided manually (paste or local file)"
- "Figma unavailable: Selectors will be derived from codebase analysis only"
- "Playwright unavailable: Install with
npm i -D @playwright/test && npx playwright install. Browser verification will be skipped until installed."
-
Report setup summary (use plain language — explain what each connection does):
SparQ Configuration Summary
===========================
Project: my-app
Source Root: src/
Tech Stack: {framework} + {e2e.framework}
E2E Framework: {e2e.framework} (from config)
E2E Infrastructure: 3 pages, 2 components, 1 fixture, 5 specs
Connections (how SparQ talks to your tools):
Jira (EP): Reads requirements from your Jira tickets ........... available
Confluence (TEAM): Reads specifications from your Confluence pages ... available
Figma: Reads UI designs for selector discovery ............. not configured
Playwright: Runs tests and verifies selectors in a browser ..... available
Local (docs/specs): Reads requirements from local markdown files .... available
Export Targets (where results are published):
TMS: testrail (project 1, suite 1)
Jira: adds coverage comments to tickets
Confluence: publishes test plans to space TEAM
Config saved to: sparq.config.json
Get started: /sparq:start (guided workflow)
Or jump in: /sparq:generate {ticket-id}
-
Generate quick reference card at .sparq/QUICKREF.md using the claude/templates/sparq-quickref.md template, filling in project-specific values from the config:
{project.name} from package.json name field (not stored in sparq.config.json){e2e.framework} from sparq.config.json e2e.framework{project.testDir} from sparq.config.json e2e.structure.specsDir (e.g., e2e/specs){enabled sources} — comma-separated list of sources where enabled: true (e.g., Jira, Confluence, Local files){outputs.tms.provider} from sparq.config.json outputs.tms.provider (or none if not configured){preferences.checkpointLevel} from sparq.config.json preferences.checkpointLevel- Write the filled template to
.sparq/QUICKREF.md
- Tell the user: "Quick reference card saved to
.sparq/QUICKREF.md"
