native-qa

Files (22)

• native-qa.md · .claude/commands/
• settings.local.json · .claude/
• .env.example
• .gitignore
• ARCHITECTURE.md
• CLAUDE.md
• CONTRIBUTING.md
• LICENSE
• QA-AGENT-FULL-ARCHITECTURE.md
• README.md
• SKILL.md
• package-lock.json
• package.json
• pyproject.toml
• generate-report.js · scripts/allure/
• qa-screenshot.js · scripts/
• registry.json · skills/_registry/
• engagement-protocol.md · skills/_shared/
• fallback-discipline.md · skills/_shared/
• fingerprint-questions.md · skills/_shared/
• principles.md · skills/_shared/
• tsconfig.json

SKILL.md (first lines)

# Native App QA Skill

An autonomous QA engineer for **any native or web application**. It asks you to select a platform, initializes a typed workspace, launches your app, takes screenshots for visual analysis, discovers every UI flow, and generates comprehensive test cases — organized by flow, feature, or risk priority.

**Supported platforms**: macOS ✅ | Web (Playwright) ✅ | Windows 🔜 | iOS 🔜 | Android 🔜

---

## DO THIS NOW — Platform Selection

> ⛔ **HARD GATE — Do NOT run any bash commands. Do NOT read any workspace files. Do NOT check `qa/`. Do NOT show a welcome message. Do NOT proceed past this section until the user has answered the platform question below. The only allowed action before this question is answered: read `skills/_registry/registry.json`.**

Read `skills/_registry/registry.json`. Build a numbered menu from all registered skills. Then output exactly this (substituting real status from the registry):

> "Which platform would you like to test on?
>
> 1. macOS — production ✅
> 2. Web (Playwright) — beta ✅
> 3. Windows — stub 🔜
> 4. iOS — stub 🔜
> 5. Android — stub 🔜"

**STOP. Output nothing else. Do not continue to Step 0 until the user replies with their platform choice.**

The selected platform determines: state file name, workspace mode detection, welcome message wording, and which platform SKILL.md to load for Steps 4+. Nothing downstream works correctly without it.

---

## Step 0: Mode Detection and Session Resume

### 0.1b Session Resume Check

Immediately after platform selection, check if a saved session exists for that platform:

```bash
STATE_FILE="qa/state.md"
[ -f "$STATE_FILE" ] && echo "EXISTS" || echo "NONE"
```

#### If state file EXISTS — read it and ask the user

Read `qa/state.md`. Extract:
- App name (from the App table)
- Phase (e.g. `EXPLORATION_COMPLETE`, `PHASE_2_IN_PROGRESS`)
- Next action (from Resume Instructions → "Next action" line)
- Counts: flows done, TCs written

Present to the user:

> "Found a saved **[platform]** session:
>
> | Field | Value |
> |-------|-------|
> | App | [AppName] |
> | Phase | [phase] |
> | Next action | [next action] |
> | Flows traced | [N done] / [N total] |
> | TCs written | [N] |
>
> **1) Resume** — continue from: *[next action]*
> **2) New session** — start fresh (saved state will be overwritten at next checkpoint)"

Wait for the user's choice:

- **"1"** or **"resume"** → Read the full state file for context. Jump directly to the saved next action. Do NOT re-run workspace init, app selection, or discovery. Announce: *"Resuming [AppName] on [platform] — [next action]"* and continue.
- **"2"** or **"new"** → **Clean up the old workspace first**, then proceed to Step 0.2 as INIT:

  ```bash
  # Cross-platform recursive remove with retries for OS-level file locks
  node -e "require('fs').rmSync('qa',{recursive:true,force:true,maxRetries:10,retryDelay:250})"

  # Verify — if anything remains, a process still has a file open
  if [ -d "qa" ]; then
    echo "WARN: qa/ still exists after cleanup."
    ls -la qa/ 2>&1 | head
  fi
  echo "Old workspace removed (or flagged for engagement). Starting fresh."
  ```

  This ensures Step 0.2 correctly detects INIT mode. **Engagement protocol** (`skills/_shared/engagement-protocol.md`): if `qa/` still exists after the rm, do NOT `exit 1`. Surface to the user via AskUserQuestion with three options: (a) identify the locking process and retry, (b) rename `qa/` to `qa-old-<timestamp>/` and continue, (c) halt with resume instructions. Never terminate silently.

#### If state file does NOT exist — proceed silently

No prompt. Go directly to Step 0.2.

### 0.2 Workspace Mode

```bash
if [ ! -d "qa" ] || [ ! -f "qa/.qa-config.json" ]; then
  echo "INIT"
elif [ ! -d "qa/flows" ] && [ ! -d "qa/features" ] && [ ! -d "qa/test-cases/P1-critical" ]; then
  echo "CONFIGURED_NO_FLOWS"
else
  # Count TC files — if zero, exploration is done but Phase 2 hasn't run
  TC_COUNT=$(find qa -name "TC-*.md" 2>/dev/null | wc -l | tr -d ' ')
  if [ "$TC_COUNT" -eq 0 ]; then
    echo "EXPLORATION_COMPLETE"
  else
    echo "HAS_WORKSPACE"
  fi
fi
```

| Result | Action |
|--------|--------|
| `INIT` | → **Step 1: INIT MODE** |
| `CONFIGURED_NO_FLOWS` | → **Step 2: App Selection** (workspace ready, need discovery) |
| `EXPLORATION_COMPLETE` | → Load the platform SKILL.md and jump directly to its **Phase 2** entry point (Web → Step W-7, macOS → Step 8). Announce: *"Phase 1 already complete — continuing to Phase 2."* |
| `HAS_WORKSPACE` | → Load the platform SKILL.md and jump to its **Update Mode** section (Web → Step W-13, macOS → Step 12). Announce: *"Existing workspace found — entering update mode."* |

---

## Context Window Management

**After every completed flow, reset the context window. This is not optional.**

Reading screenshots, flow.md files, and accumulated tool output fills the context fast. By flow 3-4 the context is full and the session crashes mid-run. The fix: treat each flow as an isolated unit — complete it, save everything to `qa/state.md`, start fresh.

### STOP / PAUSE / SAVE STATE — Immediate Handler

From mtkinverse/claude-qa, MIT.

More from mtkinverse/claude-qa