@esimplicitylabs/katalyst-xspec 0.6.0 → 0.7.0

package/skills/katalyst-bdd-create-test/references/tui-patterns.md

@@ -7,7 +7,6 @@ Common patterns for TUI (Terminal User Interface) testing with the Katalyst BDD
 ### Start and Verify
 
 ```gherkin
-@tui
 Scenario: Application starts successfully
   Given I start the TUI application
   When I wait for "Welcome"
@@ -17,7 +16,6 @@ Scenario: Application starts successfully
 ### Execute Command
 
 ```gherkin
-@tui
 Scenario: Run a command
   Given I start the TUI application
   When I type "help"
@@ -28,7 +26,6 @@ Scenario: Run a command
 ### Interactive Input
 
 ```gherkin
-@tui
 Scenario: Respond to prompt
   Given I start the TUI application
   When I wait for "Enter your name:"
@@ -42,7 +39,6 @@ Scenario: Respond to prompt
 ### Menu Navigation
 
 ```gherkin
-@tui
 Scenario: Navigate main menu
   Given I start the TUI application
   When I wait for "Main Menu"
@@ -61,7 +57,6 @@ Scenario: Navigate main menu
 ### Arrow Key Navigation
 
 ```gherkin
-@tui
 Scenario: Navigate with arrow keys
   Given I start the TUI application
   When I wait for "Select option:"
@@ -73,7 +68,6 @@ Scenario: Navigate with arrow keys
 ### Navigate to Specific Item
 
 ```gherkin
-@tui
 Scenario: Select specific menu item
   Given I start the TUI application
   When I wait for "Menu"
@@ -84,7 +78,6 @@ Scenario: Select specific menu item
 ### Back Navigation
 
 ```gherkin
-@tui
 Scenario: Go back to previous screen
   Given I start the TUI application
   When I navigate to "Settings" and select
@@ -98,7 +91,6 @@ Scenario: Go back to previous screen
 ### Fill Single Field
 
 ```gherkin
-@tui
 Scenario: Fill text field
   Given I start the TUI application
   When I wait for "Username:"
@@ -112,11 +104,10 @@ Scenario: Fill text field
 ### Fill Form with Table
 
 ```gherkin
-@tui
 Scenario: Fill complete form
   Given I start the TUI application
   When I wait for "New User"
-  And I fill the form:
+  And I fill the TUI form:
     | Field    | Value            |
     | Name     | John Doe         |
     | Email    | john@example.com |
@@ -128,7 +119,6 @@ Scenario: Fill complete form
 ### Select from Dropdown
 
 ```gherkin
-@tui
 Scenario: Select dropdown value
   Given I start the TUI application
   When I wait for "Configuration"
@@ -143,7 +133,6 @@ Scenario: Select dropdown value
 ### Special Keys
 
 ```gherkin
-@tui
 Scenario: Use special keys
   Given I start the TUI application
   When I press "F1"
@@ -155,7 +144,6 @@ Scenario: Use special keys
 ### Modifier Keys
 
 ```gherkin
-@tui
 Scenario: Keyboard shortcuts
   Given I start the TUI application
   When I press ctrl+s
@@ -171,7 +159,6 @@ Scenario: Keyboard shortcuts
 ### Text Editing
 
 ```gherkin
-@tui
 Scenario: Edit text
   Given I start the TUI application
   When I wait for "Editor"
@@ -254,7 +241,6 @@ Scenario: Long operation
 ### Confirm Dialog
 
 ```gherkin
-@tui
 Scenario: Confirm action
   Given I start the TUI application
   When I type "delete all"
@@ -267,7 +253,6 @@ Scenario: Confirm action
 ### Cancel Dialog
 
 ```gherkin
-@tui
 Scenario: Cancel action
   Given I start the TUI application
   When I type "delete all"
@@ -280,7 +265,6 @@ Scenario: Cancel action
 ### Dismiss Dialog
 
 ```gherkin
-@tui
 Scenario: Dismiss with escape
   Given I start the TUI application
   When I press "F1"
@@ -294,7 +278,6 @@ Scenario: Dismiss with escape
 ### Create Baseline Snapshot
 
 ```gherkin
-@tui
 Scenario: Capture main screen
   Given I start the TUI application
   When I wait for "Dashboard"
@@ -304,7 +287,6 @@ Scenario: Capture main screen
 ### Verify Against Snapshot
 
 ```gherkin
-@tui
 Scenario: Verify screen matches snapshot
   Given I start the TUI application
   When I wait for "Dashboard"
@@ -314,7 +296,6 @@ Scenario: Verify screen matches snapshot
 ### Multiple Snapshots
 
 ```gherkin
-@tui
 Scenario: Capture workflow snapshots
   Given I start the TUI application
   When I wait for "Welcome"
@@ -332,7 +313,6 @@ Scenario: Capture workflow snapshots
 ### Error Messages
 
 ```gherkin
-@tui
 Scenario: Show error on invalid input
   Given I start the TUI application
   When I type "invalid-command"
@@ -343,11 +323,10 @@ Scenario: Show error on invalid input
 ### Validation Errors
 
 ```gherkin
-@tui
 Scenario: Form validation
   Given I start the TUI application
   When I wait for "New User"
-  And I fill the form:
+  And I fill the TUI form:
     | Field | Value         |
     | Email | not-an-email  |
   And I submit the form
@@ -359,7 +338,6 @@ Scenario: Form validation
 ### Restart Application
 
 ```gherkin
-@tui
 Scenario: Application restart
   Given I start the TUI application
   When I wait for "Ready"
@@ -375,7 +353,6 @@ Scenario: Application restart
 ### Quit Application
 
 ```gherkin
-@tui
 Scenario: Graceful quit
   Given I start the TUI application
   When I quit the application
@@ -390,7 +367,6 @@ Scenario: Force quit
 ## Complete Example: CLI Todo App
 
 ```gherkin
-@tui
 Feature: Todo CLI Application
   As a user
   I want to manage todos from the terminal
@@ -446,7 +422,7 @@ Feature: Todo CLI Application
     And I press enter
     Then I should see "Settings"
     
-    When I fill the form:
+    When I fill the TUI form:
       | Field     | Value |
       | Theme     | Dark  |
       | Compact   | Yes   |

package/skills/katalyst-bdd-create-test/references/ui-patterns.md

@@ -7,7 +7,6 @@ Common patterns for UI testing with the Katalyst BDD framework.
 ### Basic Navigation
 
 ```gherkin
-@ui
 Scenario: Navigate to page
   Given I navigate to "/dashboard"
   Then I should see text "Dashboard"
@@ -17,7 +16,6 @@ Scenario: Navigate to page
 ### Navigation with Auth
 
 ```gherkin
-@ui
 Scenario: Navigate after login
   Given I am authenticated in UI as "user"
   Given I navigate to "/profile"
@@ -27,7 +25,6 @@ Scenario: Navigate after login
 ### Back Navigation
 
 ```gherkin
-@ui
 Scenario: Go back to previous page
   Given I navigate to "/page1"
   When I click the link "Go to Page 2"
@@ -41,7 +38,6 @@ Scenario: Go back to previous page
 ### Simple Login Form
 
 ```gherkin
-@ui
 Scenario: User login
   Given I navigate to "/login"
   When I fill in "Email" with "user@example.com"
@@ -54,7 +50,6 @@ Scenario: User login
 ### Login with Fetch Intercept (Bypassing Auth)
 
 ```gherkin
-@ui
 Scenario: Test page as authenticated user
   Given I am authenticated in UI as "admin"
   Given I navigate to "/admin/dashboard"
@@ -64,7 +59,6 @@ Scenario: Test page as authenticated user
 ### Login with Specific Roles
 
 ```gherkin
-@ui
 Scenario: Test with multiple roles
   Given I am authenticated in UI as "admin,manager,editor"
   Given I navigate to "/settings"
@@ -75,7 +69,6 @@ Scenario: Test with multiple roles
 ### Login with Tenant
 
 ```gherkin
-@ui
 Scenario: Multi-tenant login
   Given I am authenticated in UI as "admin" for tenant "acme-corp"
   Given I navigate to "/dashboard"
@@ -87,7 +80,6 @@ Scenario: Multi-tenant login
 ### Simple Form Fill
 
 ```gherkin
-@ui
 Scenario: Fill contact form
   Given I navigate to "/contact"
   When I fill in "Name" with "John Doe"
@@ -100,7 +92,6 @@ Scenario: Fill contact form
 ### Form with Data Table
 
 ```gherkin
-@ui
 Scenario: Fill registration form
   Given I navigate to "/register"
   When I fill the form:
@@ -117,7 +108,6 @@ Scenario: Fill registration form
 ### Form with Dropdowns
 
 ```gherkin
-@ui
 Scenario: Fill form with dropdown
   Given I navigate to "/settings"
   When I fill in "Display Name" with "John"
@@ -130,7 +120,6 @@ Scenario: Fill form with dropdown
 ### Clear and Fill Form
 
 ```gherkin
-@ui
 Scenario: Update existing form data
   Given I navigate to "/profile/edit"
   When I clear and fill the form:
@@ -144,7 +133,6 @@ Scenario: Update existing form data
 ### Form Validation
 
 ```gherkin
-@ui
 Scenario: Form shows validation errors
   Given I navigate to "/register"
   When I fill in "Email" with "invalid-email"
@@ -245,7 +233,6 @@ Then I verify that "first" element with "test ID" "result" becomes "visible" dur
 ### Modal Interaction
 
 ```gherkin
-@ui
 Scenario: Confirm deletion in modal
   Given I navigate to "/items"
   When I click the button "Delete"
@@ -259,7 +246,6 @@ Scenario: Confirm deletion in modal
 ### Cancel Modal
 
 ```gherkin
-@ui
 Scenario: Cancel modal
   Given I navigate to "/items"
   When I click the button "Delete"
@@ -273,7 +259,6 @@ Scenario: Cancel modal
 ### Tab Interaction
 
 ```gherkin
-@ui
 Scenario: Switch between tabs
   Given I navigate to "/settings"
   Then the "General" tab should be active
@@ -285,7 +270,6 @@ Scenario: Switch between tabs
 ### Sidebar Navigation
 
 ```gherkin
-@ui
 Scenario: Sidebar navigation
   Given I navigate to "/app"
   Then the sidebar should be visible
@@ -298,7 +282,6 @@ Scenario: Sidebar navigation
 ### Test Mobile View
 
 ```gherkin
-@ui
 Scenario: Mobile navigation
   Given the viewport is "mobile" size
   Given I navigate to "/home"
@@ -310,7 +293,6 @@ Scenario: Mobile navigation
 ### Test Custom Viewport
 
 ```gherkin
-@ui
 Scenario: Test at specific resolution
   Given the viewport is 1920x1080
   Given I navigate to "/dashboard"
@@ -362,7 +344,6 @@ Then I log all cookies
 ## Complete Example: E-commerce Checkout
 
 ```gherkin
-@ui
 Feature: Checkout Flow
   As a customer
   I want to complete checkout

package/skills/katalyst-bdd-quickstart/SKILL.md

@@ -9,22 +9,23 @@ This skill helps you get started with the @esimplicitylabs/katalyst-xspec BDD te
 
 ## Step 1: Scaffold a New Project
 
-Run the scaffolding command:
+Run the scaffolding command (positional target folder, or `.` for the current folder):
 
 ```bash
-npx @esimplicitylabs/katalyst-xspec init
+npx @esimplicitylabs/katalyst-xspec init my-tests
+cd my-tests
+npm install
+npx playwright install chromium   # REQUIRED once: UI tests fail without the browser
+npm test                          # scaffolded examples pass with no .env
 ```
 
 Options:
-- `--dir <name>` - Create in specific directory
+- `<dir>` or `--dir <name>` - Target directory (`init .` = current folder)
 - `--force` - Overwrite existing files
+- `--with-skills` / `--no-skills` - Install (or skip) agent skills without prompting
+- `--skills-agents opencode,claude-code,cursor,generic` - Which agents get skills
 
-Example:
-```bash
-npx @esimplicitylabs/katalyst-xspec init --dir my-tests
-cd my-tests
-npm install
-```
+The project's `package.json` name comes from the folder name (npm-safe, e.g. `My Demo` -> `my-demo`).
 
 ## Step 2: Understand the Project Structure
 
@@ -34,22 +35,20 @@ The scaffold creates:
 my-tests/
 ├── features/
 │   ├── api/
-│   │   └── 00_api_examples.feature    # API test examples
+│   │   └── example.feature   # JSONPlaceholder: GET /users/1, POST /posts
 │   ├── ui/
-│   │   └── 00_ui_examples.feature     # UI test examples
-│   ├── hybrid/
-│   │   └── 00_hybrid_examples.feature # Combined API+UI tests
-│   ├── tui/
-│   │   └── 00_tui_examples.feature    # Terminal UI tests
+│   │   └── example.feature   # Sauce Demo login (standard_user / secret_sauce)
 │   └── steps/
-│       ├── fixtures.ts                 # Adapter configuration
-│       └── steps.ts                    # Step registration
-├── playwright.config.ts                # BDD project config
-├── .env.example                        # Environment template
-├── tsconfig.json                       # TypeScript config
-└── package.json                        # Dependencies
+│       ├── fixtures.ts       # Adapter configuration
+│       └── steps.ts          # Step registration
+├── playwright.config.ts      # Projects: api, ui (tui commented out)
+├── .env.example              # Environment template
+├── tsconfig.json             # TypeScript config
+└── package.json              # Dependencies
 ```
 
+Each Playwright project reads one folder. Steps are untagged: any step works in any scenario. Do NOT add `@api`/`@ui`/`@hybrid`/`@tui` tags — they are not needed (and are ignored).
+
 ### Key Files
 
 **`features/steps/fixtures.ts`** - Configures adapters:
@@ -75,17 +74,21 @@ export { test };
 ```typescript
 import { defineBddProject } from 'playwright-bdd';
 
+import { tagsForProject, resolveExtraTags } from '@esimplicitylabs/katalyst-xspec';
+
+const tags = tagsForProject({ extraTags: resolveExtraTags(process.env.TEST_TAGS) });
+
 const apiBdd = defineBddProject({
   name: 'api',
-  features: 'features/api/**/*.feature',
+  features: 'features/api/**/*.feature',   // selected by folder only
   steps: 'features/steps/**/*.ts',
-  tags: '@api',
+  tags,                                     // only skips @Skip/@ignore + applies TEST_TAGS
 });
 ```
 
-## Step 3: Configure Environment
+## Step 3: Point It at Your App
 
-Copy the environment template:
+The examples use absolute URLs to public demo sites. To test your own app, copy the environment template:
 
 ```bash
 cp .env.example .env
@@ -99,9 +102,9 @@ API_BASE_URL=http://localhost:3000
 
 # Authentication (required -- no hardcoded defaults)
 DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_ADMIN_PASSWORD=changeme
 DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=user123
+DEFAULT_USER_PASSWORD=changeme
 API_AUTH_LOGIN_PATH=/auth/login
 
 # UI Configuration
@@ -113,13 +116,15 @@ HEADLESS=true
 # CLEANUP_RULES='[{"varMatch":"user","path":"/api/users/{id}"}]'
 ```
 
-### Required Variables by Test Type
+Then use relative paths in features, e.g. `Given I navigate to "/login"`, `When I GET "/health"`.
 
-| Test Type | Required Variables |
+### Required Variables by Step Type
+
+| Steps used | Required Variables |
 |-----------|-------------------|
-| `@api` | `API_BASE_URL` |
-| `@ui` | `FRONTEND_URL` or `BASE_URL` |
-| `@hybrid` | Both API and UI variables |
+| API steps with relative paths | `API_BASE_URL` |
+| UI steps with relative paths | `FRONTEND_URL` or `BASE_URL` |
+| Both in one scenario | Both API and UI variables |
 | Auth steps | `DEFAULT_*_USERNAME`, `DEFAULT_*_PASSWORD` |
 
 ## Step 4: Write Your First Test
@@ -129,7 +134,6 @@ HEADLESS=true
 Create `features/api/health.feature`:
 
 ```gherkin
-@api
 Feature: Health Check
 
   Scenario: API is healthy
@@ -142,7 +146,6 @@ Feature: Health Check
 Create `features/ui/home.feature`:
 
 ```gherkin
-@ui
 Feature: Home Page
 
   Scenario: Home page loads
@@ -150,12 +153,11 @@ Feature: Home Page
     Then I should see text "Welcome"
 ```
 
-### Hybrid Test
+### Mixed API + UI Test
 
-Create `features/hybrid/workflow.feature`:
+Any scenario can mix API and UI steps — no tag or separate project needed. Put it in a folder a project reads (e.g. `features/ui/`, since it needs a browser). Create `features/ui/workflow.feature`:
 
 ```gherkin
-@hybrid
 Feature: User Workflow
 
   Scenario: Create via API, verify in UI
@@ -173,19 +175,18 @@ Feature: User Workflow
 
 ## Step 5: Run Tests
 
-**IMPORTANT:** You must generate Playwright tests before running.
+`npm test` runs `bddgen && playwright test` (generates specs from features, then runs them). If you call `npx playwright test` directly, run `npm run gen` first.
 
 ```bash
-# 1. Generate tests from feature files (REQUIRED)
-npm run gen
-
-# 2. Run all tests
+# Run all tests
 npm test
 
-# 3. Run specific project
-npx playwright test --project=api
-npx playwright test --project=ui
-npx playwright test --project=hybrid
+# Run one project (folder)
+npx playwright test --project api
+npx playwright test --project ui
+
+# Run only scenarios with your own tag
+TEST_TAGS=@smoke npm test
 ```
 
 ### Common Run Commands
@@ -225,16 +226,14 @@ Open the Playwright report:
 npx playwright show-report
 ```
 
-## Common Tags
+## Optional Tags
+
+Tags are only for your own grouping and filtering (`TEST_TAGS=@smoke npm test`, or `TEST_TAGS=smoke,critical`).
 
 | Tag | Purpose |
 |-----|---------|
-| `@api` | API-only tests |
-| `@ui` | UI-only tests |
-| `@tui` | Terminal UI tests |
-| `@hybrid` | Combined API+UI tests |
 | `@smoke` | Quick smoke tests |
-| `@Skip` | Skip this scenario |
+| `@Skip` / `@ignore` | Skip this scenario (excluded by default) |
 | `@wip` | Work in progress |
 
 ## Quick Reference: Essential Steps
@@ -266,14 +265,15 @@ Given I register cleanup DELETE "/resource/{id}"
 
 | Issue | Solution |
 |-------|----------|
-| "No tests found" | Run `npm run gen` first |
-| Steps not available | Check you have the correct tag |
+| "No tests found" | Run `npm run gen` first; check the feature is in a folder a project reads |
+| "Executable doesn't exist" | Run `npx playwright install chromium` |
+| Step not found | Check exact step wording in `katalyst-bdd-step-reference` (no tags needed) |
 | Auth fails | Verify `.env` credentials |
 | Can't find element | Use `When I pause for debugging` |
 
 ## Next Steps
 
-1. **Create more tests** - Add feature files to `features/api/`, `features/ui/`, etc.
+1. **Create more tests** - Add feature files to `features/api/` or `features/ui/`
 2. **Learn steps** - See full step reference with `katalyst-bdd-step-reference` skill
 3. **Patterns** - Learn test patterns with `katalyst-bdd-create-test` skill
 4. **Custom adapters** - Extend framework with `katalyst-bdd-architecture` skill
@@ -290,3 +290,5 @@ This updates:
 - Package dependencies
 - Configuration templates
 - Step definitions
+
+Upgrading from 0.6 or earlier: run `npx katalyst-xspec upgrade --migrate` to remove old `@api`/`@ui`/`@hybrid`/`@tui` tag filters from `playwright.config.*`. Old tags left in feature files are harmless.

package/skills/katalyst-bdd-step-reference/SKILL.md

@@ -1,24 +1,19 @@
 ---
 name: katalyst-bdd-step-reference
-description: Complete reference of all available BDD step definitions in the Katalyst framework. Use when writing feature files, looking up step syntax, understanding what steps are available for a tag, or finding the right step for a specific action like clicking, filling forms, making API calls, or terminal interactions.
+description: Complete reference of all available BDD step definitions in the Katalyst framework. Use when writing feature files, looking up step syntax, checking exact step wording, or finding the right step for a specific action like clicking, filling forms, making API calls, or terminal interactions.
 ---
 
 # Katalyst BDD Step Reference
 
 This skill provides a complete reference of all step definitions available in @esimplicitylabs/katalyst-xspec.
 
-## Tag System
+## Where Steps Work
 
-Steps are enabled based on the feature/scenario tag:
+Built-in steps are untagged. Once registered (`registerApiSteps`, `registerUiSteps`, `registerSharedSteps`, `registerTuiSteps`, ...), **any step works in any scenario**, so a single scenario can mix API, UI and shared steps.
 
-| Tag | Available Steps | Use Case |
-|-----|-----------------|----------|
-| `@api` | API + Shared | HTTP API testing only |
-| `@ui` | UI + Shared | Browser UI testing only |
-| `@tui` | TUI + Shared | Terminal UI testing only |
-| `@hybrid` | API + UI + Shared | Combined API and UI testing |
-
-**Important:** Always tag your feature or scenario. Without a tag, steps may not be available.
+- Do not add `{ tags: ... }` to steps or type tags to scenarios; they are not needed.
+- Playwright projects pick feature files by folder (`features/api/`, `features/ui/`).
+- Tags like `@smoke` or `@wip` are optional, for the user's own filtering (`TEST_TAGS`).
 
 ## Variable Interpolation
 
@@ -31,7 +26,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 
 ## Quick Reference - Most Common Steps
 
-### API Steps (`@api` or `@hybrid`)
+### API Steps
 
 | Step | Example |
 |------|---------|
@@ -49,7 +44,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `Given I am authenticated as a user via API` | User API authentication |
 | `Given I set header {string} to {string}` | `Given I set header "X-Custom" to "value"` |
 
-### UI Steps (`@ui` or `@hybrid`)
+### UI Steps
 
 | Step | Example |
 |------|---------|
@@ -64,7 +59,7 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `Then the element {string} should be visible` | `Then the element "#modal" should be visible` |
 | `When I pause for debugging` | Opens Playwright Inspector |
 
-### TUI Steps (`@tui`)
+### TUI Steps
 
 | Step | Example |
 |------|---------|
@@ -73,9 +68,13 @@ When I GET "/users/{userId}"  # Becomes /users/123
 | `When I press {string}` | `When I press "Enter"` |
 | `When I press enter` | Press Enter key |
 | `Then I should see {string}` | `Then I should see "Welcome"` |
+| `Then I should see {string} in the terminal` | `Then I should see "Ready" in the terminal` |
 | `Then the screen should contain {string}` | Assert screen has text |
+| `When I fill the TUI form:` | Data table of `field`/`value` |
+
+TUI has no `I should see text {string}` (that's the UI step), and the TUI form step is `I fill the TUI form:` (UI uses `I fill the form:`).
 
-### Shared Steps (All Tags)
+### Shared Steps
 
 | Step | Example |
 |------|---------|
@@ -106,7 +105,6 @@ For complete step definitions with all parameters and examples:
 ### API CRUD Test
 
 ```gherkin
-@api
 Scenario: Create and fetch user
   Given I am authenticated as an admin via API
   When I POST "/users" with JSON body:
@@ -122,7 +120,6 @@ Scenario: Create and fetch user
 ### UI Login Test
 
 ```gherkin
-@ui
 Scenario: User login
   Given I navigate to "/login"
   When I fill in "Email" with "user@example.com"
@@ -131,10 +128,9 @@ Scenario: User login
   Then I should see text "Dashboard"
 ```
 
-### Hybrid Test (API + UI)
+### Mixed API + UI Test (no tag needed)
 
 ```gherkin
-@hybrid
 Scenario: Create via API, verify in UI
   Given I am authenticated as an admin via API
   When I POST "/users" with JSON body:

package/skills/katalyst-bdd-step-reference/references/api-steps.md

@@ -1,6 +1,6 @@
 # API Steps Reference
 
-Complete reference for API steps. Available in `@api` and `@hybrid` scenarios.
+Complete reference for API steps. Steps are untagged and work in any scenario (including alongside UI steps).
 
 ## HTTP Method Steps
 
@@ -207,7 +207,6 @@ And I store the value at "items[0].id" as "firstItemId"
 ## Complete API Example
 
 ```gherkin
-@api
 Feature: User Management API
 
   Background: