@xera-ai/skills 0.1.0

package/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@xera-ai/skills",
+  "version": "0.1.0",
+  "files": ["*.md", "version.json"]
+}

package/version.json

@@ -0,0 +1,13 @@
+{
+  "skills": "0.1.0",
+  "compatible_prompts": "^1.0.0",
+  "skill_files": [
+    "xera-run.md",
+    "xera-fetch.md",
+    "xera-feature.md",
+    "xera-script.md",
+    "xera-exec.md",
+    "xera-report.md",
+    "xera-promote.md"
+  ]
+}

package/xera-exec.md

@@ -0,0 +1,18 @@
+---
+name: xera-exec
+description: Run the Playwright test for a ticket. Refreshes auth state automatically. Use when QA wants to execute an existing spec without regenerating.
+---
+
+The user invoked `/xera-exec <TICKET>`. If no key, ask.
+
+1. Verify `.xera/{{TICKET}}/spec.ts` exists. If not: "Generate the spec first with `/xera-script {{TICKET}}`." STOP.
+
+2. Run: `bun run xera:exec {{TICKET}}`
+   - Exit 0 → all scenarios passed.
+   - Exit 1 → user/config error (lock held, missing env var). Show the error verbatim and STOP.
+   - Exit 3 → test failure. This is expected; continue.
+   - Exit 4 → infra error (Playwright crashed). Show stderr; STOP.
+
+3. Read the latest run directory: `.xera/{{TICKET}}/runs/<latest>/`. Tell the user the runId.
+
+4. Suggest: "Diagnose this run with `/xera-report {{TICKET}}`."

package/xera-feature.md

@@ -0,0 +1,29 @@
+---
+name: xera-feature
+description: Generate or regenerate the Gherkin test.feature file for a Jira ticket. Use when QA wants AI to produce Gherkin scenarios from the fetched user story.
+---
+
+You are running inside a project repo configured for xera. The user has invoked `/xera-feature <TICKET>`.
+
+If no ticket key was given, ask for one.
+
+1. Verify `.xera/{{TICKET}}/story.md` exists. If not, say: "No story.md yet. Run `/xera-fetch {{TICKET}}` first." STOP.
+
+2. Read `.xera/{{TICKET}}/meta.json`:
+   - If `feature_generated_from_story_hash === story_hash` AND `.xera/{{TICKET}}/test.feature` exists, the feature is current. Ask the user: "test.feature is up-to-date with the current story. Regenerate anyway? (y/N)". If no, STOP and tell user nothing to do.
+   - If `story_hash` differs (story drift), say so: "Story has changed since the last feature was generated. Regenerating."
+
+3. Read the prompt template from `node_modules/@xera-ai/prompts/feature-from-story.md`. Follow its hard rules.
+
+4. Read `.xera/{{TICKET}}/story.md` and write `.xera/{{TICKET}}/test.feature` following the prompt. Do NOT include any text outside the Gherkin file body.
+
+5. Run: `bun run xera:validate-feature {{TICKET}}`
+   - Exit 0 → success.
+   - Exit 2 → parse error. Read the line/message, rewrite test.feature to fix it, re-run. Try at most 2 retries. If still failing, show the user the parser output and stop.
+
+6. Update `.xera/{{TICKET}}/meta.json`:
+   - `feature_generated_at` = now (ISO)
+   - `feature_generated_from_story_hash` = the current `story_hash`
+   - `feature_hash` = sha256 of the file contents (the skill will compute by reading the file and using the same hashing scheme as `xera-internal`; just record `feature_generated_at` and let `xera:fetch`-style helpers re-hash as needed).
+
+7. Summarize to the user: number of scenarios, list of scenario names. Suggest: "Generate Playwright spec? `/xera-script {{TICKET}}`."

package/xera-fetch.md

@@ -0,0 +1,35 @@
+---
+name: xera-fetch
+description: Fetch a Jira ticket and write its user story to .xera/<TICKET>/story.md. Use when QA wants to start working on a ticket without yet generating tests.
+---
+
+You are running inside a project repo configured for xera. The user has invoked `/xera-fetch <TICKET>`.
+
+If the user did not provide a ticket key, ask: "Which Jira ticket key?" and wait. The key must look like `PROJ-123`.
+
+1. Check whether `.xera/{{TICKET}}/story.md` already exists.
+   - If yes, read its first line to confirm the ticket key matches.
+   - If the file exists and the user did not explicitly ask to re-fetch, ask: "story.md exists for {{TICKET}}. Re-fetch from Jira and overwrite? (y/N)". Default to no.
+
+2. Detect Jira backend:
+   - If an Atlassian MCP tool is available in this session (a tool whose name starts with `mcp__atlassian__` or `mcp__plugin_engineering_atlassian__`), use it:
+     a. Call `getJiraIssue` (or equivalent) with the ticket key.
+     b. Map the response into the shape `xera-internal fetch` expects: `{ key, summary, story, acceptanceCriteria?, attachments, raw }`.
+        - `story` is the value of the field named in `xera.config.ts.jira.fields.story`.
+        - `acceptanceCriteria` is the value of `jira.fields.acceptanceCriteria` if set.
+        - `attachments` is the array of attachments, each mapped to `{ filename, url }`.
+     c. Write that object as JSON to a temp file at `$TMPDIR/xera-mcp/{{TICKET}}.json` (create the dir if missing).
+     d. Set the environment variable `XERA_MCP_JIRA=1` for the next subprocess call.
+   - Else: use the REST backend implicitly via `JIRA_EMAIL` + `JIRA_API_TOKEN` from `.env`.
+
+3. Run: `bun run xera:fetch {{TICKET}}`
+   - Exit 0 → continue.
+   - Exit 1 → user/config error. Read stderr, show the user the fix instructions, STOP.
+   - Exit 4 → infra error. Show error, STOP.
+
+4. Read `.xera/{{TICKET}}/story.md` and `.xera/{{TICKET}}/meta.json`. Summarize to the user:
+   - Ticket key, summary
+   - First 200 chars of story
+   - Whether AC was found in a separate field
+
+5. Suggest next step: "Generate Gherkin? Run `/xera-feature {{TICKET}}` or run the full pipeline with `/xera-run {{TICKET}}`."

package/xera-promote.md

@@ -0,0 +1,24 @@
+---
+name: xera-promote
+description: Promote a Page Object Model from a single ticket's .xera/<TICKET>/page-objects/ to shared/page-objects/ so other tests can reuse it. Use when QA notices a POM is generally useful.
+---
+
+The user invoked `/xera-promote <TICKET> <PomClassName>`.
+
+1. Verify `.xera/<TICKET>/page-objects/<PomClassName>.ts` exists. If not, list available POMs in that directory and ask the user to pick.
+
+2. Check `shared/page-objects/<PomClassName>.ts`:
+   - If it does NOT exist → safe to promote.
+   - If it exists with identical content → just delete the ticket-local copy and update the import (run `bun run xera:promote {{TICKET}} {{POM}}` will refuse; manually delete with the user's confirmation).
+   - If it exists with different content → STOP. Show a unified diff. Ask the user to reconcile manually.
+
+3. Run: `bun run xera:promote {{TICKET}} {{POM}}`
+   - This moves the file and rewrites the import in `.xera/{{TICKET}}/spec.ts`.
+
+4. Run `bun run xera:typecheck {{TICKET}}` to confirm nothing broke. If errors, surface them.
+
+5. Suggest the user commit the changes:
+   ```
+   git add shared/page-objects/{{POM}}.ts .xera/{{TICKET}}/
+   git commit -m "tests: promote {{POM}} from {{TICKET}}"
+   ```

package/xera-report.md

@@ -0,0 +1,31 @@
+---
+name: xera-report
+description: Classify the latest run, draft a Jira comment, and post it. Use after `/xera-exec` when QA wants the diagnosis and Jira update.
+---
+
+The user invoked `/xera-report <TICKET>`. If no key, ask.
+
+1. Verify `.xera/{{TICKET}}/runs/` has at least one run directory. If not: "Run the test first with `/xera-exec {{TICKET}}`." STOP.
+
+2. Run: `bun run xera:normalize {{TICKET}}`
+   - Exit 0 → continue.
+   - Otherwise show stderr, STOP.
+
+3. Read the latest `.xera/{{TICKET}}/runs/<latest>/normalized.json`. Also read:
+   - `.xera/{{TICKET}}/test.feature`
+   - `.xera/{{TICKET}}/story.md`
+   - `.xera/{{TICKET}}/spec.ts`
+   - `.xera/{{TICKET}}/status.json` (may not exist on first run)
+   - `.xera/{{TICKET}}/meta.json`
+
+4. Read `node_modules/@xera-ai/prompts/diagnose-failure.md`. Follow its decision algorithm. Produce `classifier-input.json` matching the exact shape described. Save to `.xera/{{TICKET}}/classifier-input.json`.
+
+5. Run: `bun run xera:report {{TICKET}} -- --input=.xera/{{TICKET}}/classifier-input.json`
+
+6. Read the drafted Jira comment at `.xera/{{TICKET}}/jira-comment.draft.md`. Show it to the user. Ask: "Post to Jira? (Y/n)"
+
+7. If yes:
+   - If Atlassian MCP is available, use `addCommentToJiraIssue` with the draft as the body. Capture the comment id.
+   - Else: run `bun run xera:post {{TICKET}}` (will use REST creds from .env).
+
+8. Summarize result and link to the Jira comment (if MCP returned a URL).

package/xera-run.md

@@ -0,0 +1,43 @@
+---
+name: xera-run
+description: Run the full xera pipeline for a Jira ticket end-to-end — fetch story, generate Gherkin, generate Playwright spec, execute, diagnose, post to Jira. Use when QA wants to test a ticket from scratch.
+---
+
+The user invoked `/xera-run <TICKET>`. If no key, ask.
+
+This skill orchestrates the other six skills with quality gates between each step. If any step fails non-recoverably, STOP and surface the cause.
+
+## Step 0 — Health gate
+
+Run: `bunx xera doctor --strict {{TICKET}}`
+If non-zero exit → STOP. Show the output verbatim. Suggest the user fix env and re-run.
+
+## Step 1 — Fetch
+
+Follow the same instructions as `xera-fetch.md`, but never prompt the user about re-fetching here — just proceed unless story.md already exists and meta.json shows a `story_hash` < 24 hours old (then skip fetch).
+
+If meta is missing or story_hash is older, refresh.
+
+## Step 2 — Feature
+
+Follow `xera-feature.md`. If `feature_generated_from_story_hash !== story_hash`, regenerate. If unchanged AND spec.ts exists, skip feature generation entirely.
+
+## Step 3 — Script
+
+Follow `xera-script.md`. If `script_generated_from_feature_hash !== feature_hash`, regenerate. Else skip.
+
+## Step 4 — Exec
+
+Run `bun run xera:exec {{TICKET}}`.
+
+## Step 5 — Normalize
+
+Run `bun run xera:normalize {{TICKET}}`.
+
+## Step 6 — Diagnose + report + post
+
+Follow `xera-report.md` from step 3 onwards. If the user is the SAMPLE-001 ticket (meta.source === "local"), do NOT post to Jira and do NOT prompt about posting — only print the drafted comment.
+
+## Step 7 — Summary
+
+Print a single-paragraph summary covering: overall result, classification, per-scenario counts, link to Jira comment (if posted), and the reproduce command (`bunx xera-internal exec {{TICKET}} --replay=<runId>`).

package/xera-script.md

@@ -0,0 +1,29 @@
+---
+name: xera-script
+description: Generate the Playwright spec.ts and any new Page Objects for a ticket from its Gherkin feature. Use when QA wants AI to produce test code from the agreed-on Gherkin.
+---
+
+The user invoked `/xera-script <TICKET>`. If no key, ask.
+
+1. Verify `.xera/{{TICKET}}/test.feature` exists. Otherwise say "Generate Gherkin first with `/xera-feature {{TICKET}}`." STOP.
+
+2. Read `.xera/{{TICKET}}/meta.json`:
+   - If `script_generated_from_feature_hash === feature_hash` AND `.xera/{{TICKET}}/spec.ts` exists, ask "spec.ts is up-to-date. Regenerate? (y/N)". Default no.
+
+3. List existing shared POMs by reading `shared/page-objects/` (every `.ts` file, parse exported class names). Pass this list to yourself as context for reuse decisions.
+
+4. Read `node_modules/@xera-ai/prompts/script-from-feature.md`. Follow its hard rules.
+
+5. Read `.xera/{{TICKET}}/test.feature` and `.xera/{{TICKET}}/story.md`. Generate:
+   - `.xera/{{TICKET}}/spec.ts`
+   - `.xera/{{TICKET}}/page-objects/<ClassName>.ts` for each new POM
+   Do not modify anything under `shared/`.
+
+6. Run quality gates:
+   - `bun run xera:typecheck {{TICKET}}` — if exit 2, read errors, fix in the generated files, retry up to 2 times.
+   - `bun run xera:lint {{TICKET}}` — same retry policy. If a CSS selector is truly necessary, add `// xera-allow-css: <reason>` on the line above it.
+
+7. Update meta.json: `script_generated_at`, `script_generated_from_feature_hash`.
+
+8. Summarize: list of files written, count of new POMs, mention any POM that *looked* reusable but didn't quite fit (suggest the user might want `/xera-promote` later).
+   Suggest: "Run the test now with `/xera-exec {{TICKET}}`, or do the whole pipeline with `/xera-run {{TICKET}}`."