@exodus/xqa 1.4.0 → 1.5.0

package/dist/skills/xqa-spec/SKILL.md

@@ -26,7 +26,6 @@ IMPORTANT: Never generate a draft before the interview is complete. The user des
 Silently scan `.xqa/specs/*.test.md`. Learn:
 
 - Naming conventions
-- Tag vocabulary
 - Level of detail and step granularity
 
 Also read `.xqa/app.md` if it exists for app context.
@@ -47,19 +46,18 @@ Ask one question at a time. Wait for the answer before asking the next. Prefer m
 **Question sequence:**
 
 1. **What flow?** — Confirm what's being tested if not already clear. Suggest a filename and `feature` name.
-2. **Entry point** — "What's the navigation path to reach this flow?" (e.g., `App launch`, `Home > Wallet`) → becomes `entry:` frontmatter
-3. **Starting state** — "What's already set up? What state is the device/app in?" → becomes `## Setup`
-4. **Steps** — "Walk me through the steps, one at a time. I'll ask for the next when you're done." → collect each step, then ask "What should happen?" for the assertion (optional)
-5. **Global assertions** — "Any overall things that should be true at the end of the flow?" → becomes `## Assertions` (skip if none)
-6. **Max steps** — "Set a timeout in seconds? (optional, for long-running specs)" → becomes `timeout:` frontmatter (offer to skip)
+2. **Starting state** — "What's already set up? What state is the device/app in?" → becomes `## Setup`
+3. **Steps** — "Walk me through the steps, one at a time. For each step, describe the intent (what the user is trying to do), and optionally the expected outcome and a hint about the current label or wording." → collect each step. Prompt for outcome only when user mentions something to verify. Prompt for hint only when current label wording is useful.
+4. **Global assertions** — "Any overall things that should be true at the end of the flow?" → becomes `## Assertions` (skip if none)
+5. **Timeout** — "Set a timeout in seconds? (optional, for long-running specs)" → becomes `timeout:` frontmatter (offer to skip)
 
 IMPORTANT: Ask each question in its own message. Never batch questions.
 
 ### 4. Draft
 
-Assemble using ONLY these frontmatter fields: `feature`, `entry`, `timeout`. Do not add any other frontmatter field. `feature` MUST be present. `timeout` MUST be a positive number (seconds) if included.
+Assemble using ONLY these frontmatter fields: `feature`, `timeout`. Do not add any other frontmatter field. `feature` MUST be present. `timeout` MUST be a positive number (seconds) if included.
 
-Steps and assertions come from the user — never invent them. Present the full draft for review.
+Steps come from the user — never invent them. Use intent-first language: describe the user's goal, not literal widget taps. Present the full draft for review.
 
 ### 5. Review
 
@@ -72,32 +70,62 @@ Iterate until approved. One round of changes per message.
 Before writing, verify the draft passes all checks:
 
 - [ ] `feature` is present and non-empty
-- [ ] frontmatter contains only permitted fields: `feature`, `entry`, `timeout`
+- [ ] frontmatter contains only permitted fields: `feature`, `timeout`
 - [ ] `timeout` if present is a positive number in seconds (not a string, not zero)
 - [ ] `## Setup` section is present
 - [ ] `## Steps` section is present
-- [ ] No forbidden fields: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`
+- [ ] No step begins with `Tap "<literal label>"` or equivalent literal-widget references — steps use intent-first language
+- [ ] No forbidden fields: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`, `version`, `entry`
 
 Fix any failure before writing. Save to `.xqa/specs/<name>.test.md` only after explicit approval.
 
+## Step Grammar
+
+```
+<intent phrase> [→ <outcome state>] [hint: <advisory text>]
+```
+
+- **Intent phrase** — imperative, action-oriented, describes the user's goal. No literal widget labels. Include a domain noun (e.g., "agreement", "asset", "settings").
+- **Outcome state** — optional. Include only when the step has something to verify. Observable screen state or content predicate.
+- **Hint** — optional. Free-form natural text describing expected label or qualities. Agent infers role (primary/secondary/dismissal) from context. Never use structured `role=` syntax.
+
+### Valid examples
+
+```md
+1. Accept the terms and conditions → Portfolio screen visible [hint: "Agree and continue"]
+2. Open the settings menu
+3. Dismiss the backup reminder [hint: skip or maybe later button]
+4. Enter the recovery phrase words in order → All 12 fields filled, Confirm becomes active
+```
+
+### Anti-patterns
+
+```md
+# Literal label as selector — breaks on rename
+
+1. Tap the "Agree and continue" button
+
+# Vague intent — agent has nothing to anchor on
+
+2. Do the onboarding thing
+```
+
 ## File format
 
 FRONTMATTER SCHEMA — exact fields, exact types, no others:
 
 ```
 feature    string           REQUIRED
-entry      string           OPTIONAL — omit if not provided
-timeout  positive number (seconds) OPTIONAL — omit if not provided
+timeout    positive number (seconds) OPTIONAL — omit if not provided
 ```
 
-FORBIDDEN frontmatter fields — never generate these: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`, `version`
+FORBIDDEN frontmatter fields — never generate these: `tags`, `max_steps`, `priority`, `type`, `description`, `id`, `author`, `version`, `entry`
 
 CANONICAL OUTPUT FORMAT:
 
 ```md
 ---
 feature: <string>
-entry: <string>
 timeout: <seconds>
 ---
 
@@ -107,19 +135,21 @@ timeout: <seconds>
 
 ## Steps
 
-1. <action> → <expected outcome>
-2. <action>
+1. <intent> → <outcome> [hint: <advisory>]
+2. <intent>
 
 ## Assertions
 
 - <global flow-level check>
 ```
 
-Omit `entry` and `timeout` lines if not provided. Omit `## Assertions` section if none.
+Omit `timeout` line if not provided. Omit `## Assertions` section if none. Omit `→ <outcome>` or `[hint: ...]` per-step when not applicable.
 
 ## Rules
 
-- Inline assertion syntax: `action → outcome` using the → character
+- Step grammar: `<intent> [→ <outcome>] [hint: <advisory>]` using the → character
+- Outcome and hint are optional per step; include only when useful
 - Steps come from the user — never invent them
+- Intent-first language only; no literal `Tap "<label>"` references
 - Write file only after explicit approval
 - In edit mode, ask before touching anything