devlyn-cli 1.14.0 → 2.0.0

package/config/skills/devlyn:auto-resolve/references/build-gate.md

@@ -1,116 +0,0 @@
-# Build Gate — Project Type Detection & Commands
-
-Reference for PHASE 1.4 (Build Gate). The build gate agent reads this file to determine which commands to run.
-
----
-
-## Project Type Detection Matrix
-
-Inspect the repository root and subdirectories (up to 2 levels). A repo can match **multiple** signals — run ALL matching gates. Do not pick "the main one"; a monorepo with a Next.js dashboard + Rust service needs both.
-
-| Signal file(s) | Project type | Gate commands (run in order) |
-|---|---|---|
-| `package.json` with `next` dep | Next.js | `npx tsc --noEmit` → `npx next build` |
-| `package.json` with `nuxt` dep | Nuxt | `npx nuxi typecheck` → `npx nuxi build` |
-| `package.json` with `vite` + `tsconfig.json` | Vite+TS | `npx tsc --noEmit` → `npm run build` (if script exists) |
-| `package.json` with `expo` dep | Expo (React Native) | `npx tsc --noEmit` → `npx expo-doctor` |
-| `package.json` with `react-native` (no expo) | React Native | `npx tsc --noEmit` |
-| `package.json` with `svelte` + `@sveltejs/kit` | SvelteKit | `npm run check` → `npm run build` |
-| `package.json` only, has `build` script | Generic Node | `npm run build` |
-| `package.json` only, has `tsconfig.json` but no `build` | TS library | `npx tsc --noEmit` |
-| `pnpm-workspace.yaml` / `turbo.json` / `lerna.json` | Monorepo | `pnpm -r build` or `turbo run build typecheck lint` — **workspace-wide**, NOT just the changed package |
-| `Cargo.toml` | Rust | `cargo check --all-targets` → `cargo clippy -- -D warnings` |
-| `go.mod` | Go | `go build ./...` → `go vet ./...` |
-| `foundry.toml` | Foundry (Solidity) | `forge build` |
-| `hardhat.config.{js,ts,cjs}` | Hardhat (Solidity) | `npx hardhat compile` |
-| `Anchor.toml` | Anchor (Solana) | `anchor build` |
-| `Move.toml` | Move (Sui/Aptos) | `sui move build` or `aptos move compile` |
-| `pyproject.toml` / `setup.py` + mypy config | Python+mypy | `mypy .` |
-| `pyproject.toml` with `ruff` | Python+Ruff | `ruff check .` |
-| `Package.swift` | Swift package | `swift build` |
-| `*.xcodeproj` / `*.xcworkspace` | iOS/macOS (Xcode) | Skip by default — log "Xcode project detected, manual build gate recommended". Too project-specific without knowing the scheme. |
-| `build.gradle*` / `settings.gradle*` | Gradle/Android | `./gradlew assembleDebug` (debug, not release — keep it fast) |
-| `CMakeLists.txt` | C/C++ (CMake) | `cmake -B build && cmake --build build` |
-| `Makefile` (with no other signals) | Generic Make | `make` (only if no other type matched — Makefiles are too generic) |
-| `Unity/ProjectSettings/` or `ProjectSettings/ProjectVersion.txt` | Unity | Skip by default — log "Unity project detected, manual build gate recommended" |
-| `project.godot` | Godot | Skip by default — log "Godot project detected, manual build gate recommended" |
-| `Dockerfile*` | Docker | `docker build -f <dockerfile> -t _pipeline_gate_test .` — included by default in `auto` mode. Skip with `--build-gate no-docker`. |
-
-## Package Manager Detection
-
-Respect the project's package manager. Check in order:
-1. `packageManager` field in root `package.json` → use that
-2. `pnpm-lock.yaml` exists → `pnpm`
-3. `yarn.lock` exists → `yarn`
-4. `bun.lockb` / `bun.lock` exists → `bun`
-5. Default → `npm`
-
-Replace `npm run build` / `npx` accordingly: `pnpm build` / `pnpm exec`, `yarn build` / `yarn`, `bun run build` / `bunx`.
-
-## Monorepo Handling
-
-Monorepo is the most critical case — cross-package type drift is the #1 source of "tests pass locally, build fails in CI."
-
-1. Detect workspace root markers: `pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, `workspaces` in root `package.json`
-2. Run gates at the **workspace root** level, not per-changed-package:
-   - Turbo: `turbo run build typecheck lint` (respects dependency graph)
-   - pnpm: `pnpm -r build` (runs in topological order)
-   - yarn workspaces: `yarn workspaces foreach -A run build`
-   - npm workspaces: `npm run build --workspaces`
-3. This ensures Package A's type change that breaks Package B's consumer is caught, even if only Package A was directly modified.
-
-## Strict Mode (`--build-gate strict`)
-
-When strict mode is set, treat warnings as failures:
-- TypeScript: add `--strict` if not already in tsconfig (or verify it's set)
-- Clippy: `-D warnings` (already default in the matrix)
-- ESLint: `--max-warnings 0`
-- Go vet: already treats warnings as errors
-- Foundry: `--deny-warnings`
-
-In default (auto) mode, only hard errors (non-zero exit code from the tool's perspective) block.
-
-## Docker Build (default in `auto` mode)
-
-When `Dockerfile*` files are detected AND `--build-gate no-docker` is NOT set:
-1. Run all non-Docker gates first (they're faster and catch most errors before the slow Docker step)
-2. Then run `docker build -f <dockerfile> -t _pipeline_gate_test .` for each Dockerfile found in the repo root and subdirectories (up to 2 levels)
-3. If Docker daemon is not available, log the skip with a warning but do NOT fail — developers without Docker should not be blocked. The warning should note: "Docker builds were skipped because the Docker daemon is unavailable. Use `--build-gate no-docker` to suppress this warning, or ensure Docker is running to catch Dockerfile-specific issues."
-4. This catches Dockerfile-specific issues that no other gate can: COPY paths referencing files excluded by .dockerignore, multi-stage build failures, production-only dependency resolution, and environment differences between dev and container builds
-
-Use `--build-gate no-docker` to skip Docker builds for faster iteration during development — the language-level gates (tsc, cargo check, etc.) still run and catch the majority of issues. Docker builds are most valuable as a final gate before shipping.
-
-## Output Format
-
-Write results to `.devlyn/BUILD-GATE.md`:
-
-```markdown
-# Build Gate Results
-## Verdict: [PASS / FAIL]
-## Detected Project Types
-- [type] ([path/])
-## Gate Commands Run
-| # | Command | Dir | Exit | Status | Time |
-|---|---|---|---|---|---|
-| 1 | `npx tsc --noEmit` | dashboard/ | 0 | PASS | 4.2s |
-| 2 | `npx next build` | dashboard/ | 1 | FAIL | 9.8s |
-| 3 | `cargo check --all-targets` | services/indexer/ | 0 | PASS | 12.1s |
-
-## Failures
-
-### Command #2: `npx next build` (dashboard/, exit 1)
-```
-[full error output — do NOT truncate. Build errors reference files from earlier in output.]
-```
-
-**Root file:line(s)**:
-- `dashboard/app/(dashboard)/settings/page.tsx:90` — Type error: Property 'config' does not exist on type 'SettingsTabsProps'
-
-**Fix guidance**:
-Read `dashboard/app/(dashboard)/settings/page.tsx:88-93` and `dashboard/components/settings/SettingsTabs.tsx` (the SettingsTabsProps type definition). Either add `config` to SettingsTabsProps or remove the prop from the parent. Then re-run `npx next build` from `dashboard/` to verify.
-```
-
-Verdict rules:
-- Any exit code != 0 → **FAIL**
-- All exit codes == 0 → **PASS**
-- No gates detected → **PASS** with note "No build gate detected — project type unknown. Consider adding `--build-gate deploy` if Dockerfiles are present."

package/config/skills/devlyn:auto-resolve/references/engine-routing.md

@@ -1,204 +0,0 @@
-# Engine Routing: Intelligent Model Selection
-
-Instructions for routing work to the optimal model (Claude or Codex) per role and phase. Only read this file when `--engine` is set to `auto` or `codex`.
-
-The routing table below is derived from published benchmarks (April 2026) comparing Claude Opus 4.6 and GPT-5.4 across task-relevant dimensions. The principle: each role's work goes to the model that objectively performs better at that task type.
-
----
-
-## Benchmark Basis
-
-| Dimension | Claude Opus 4.6 | GPT-5.4 | Gap | Source |
-|-----------|-----------------|---------|-----|--------|
-| Long-context retrieval (256k) | 92% | ~64% | Claude +28pp | MRCR v2 |
-| Graduate-level reasoning | 87.4% | 83.9% | Claude +3.5pp | GPQA Diamond |
-| Hard coding problems | ~46% | 57.7% | Codex +11.7pp | SWE-bench Pro |
-| Function-level code gen | 90.4% | 93.1% | Codex +2.7pp | HumanEval |
-| Terminal/CLI tasks | 65.4% | 75.1% | Codex +9.7pp | Terminal-Bench 2.0 |
-| Real-world issue resolution | ~80% | ~80% | Tied | SWE-bench Verified |
-| Security vulnerability detection | — | — | Tied | Semgrep 2025 study |
-| Agentic computer use | 72.7% | 75.0% | Codex +2.3pp | OSWorld |
-| Ambiguous intent handling | Preferred by 70% devs | — | Claude | Developer surveys |
-
----
-
-## Codex Call Defaults
-
-Every Codex call in this file uses these defaults unless stated otherwise:
-
-```
-model: "gpt-5.4"
-reasoningEffort: "xhigh"
-sandbox: varies per role (see table)
-workingDirectory: project root
-```
-
-The `model` field accepts any string — pass `"gpt-5.4"` even if the MCP schema lists older defaults. The Codex CLI resolves it.
-
----
-
-## Role Routing Table
-
-### team-resolve roles
-
-| Role | Engine | Sandbox | Rationale |
-|------|--------|---------|-----------|
-| root-cause-analyst | **Claude** | — | A/B test: Claude traced git history (15 tool calls) finding exact commit + unchecked migration plan. Codex analyzed structure well but lacked git history depth. Tool access > SWE-bench Pro advantage for this role. |
-| test-engineer | **Codex** | workspace-write | Test code generation = HumanEval (+2.7pp), needs file write |
-| security-auditor | **Dual** | read-only | Semgrep: both find unique vulns; GAN > single model |
-| implementation-planner | **Codex** | read-only | Implementation planning = SWE-bench Pro (+11.7pp) |
-| product-designer | **Claude** | — | Ambiguous requirements, user intent = Claude strength |
-| ui-designer | **Claude** | — | Visual spec, design reasoning = non-coding task |
-| ux-designer | **Claude** | — | User flow analysis = ambiguous intent handling |
-| accessibility-auditor | **Claude** | — | A/B test: Claude found 12 issues (1 CRITICAL) vs Codex 4. WCAG auditing requires thoroughness and domain knowledge depth, not code generation speed. Claude 3x coverage. |
-| product-analyst | **Claude** | — | Requirements clarity, scope judgment = ambiguity handling |
-| architecture-reviewer | **Claude** | — | Codebase-wide pattern review = MRCR long-context (+28pp) |
-| performance-engineer | **Codex** | read-only | Terminal tasks + algorithm analysis = Terminal-Bench (+9.7pp) |
-| api-designer | **Dual** | read-only | A/B test: Claude found 9 issues, Codex found 6, with unique findings on both sides (Claude: --version, exit codes; Codex: YAML folded scalar parsing bug). Dual maximizes coverage for API surface review. |
-
-### team-review roles
-
-| Role | Engine | Sandbox | Rationale |
-|------|--------|---------|-----------|
-| security-reviewer | **Dual** | read-only | Same as team-resolve security-auditor |
-| quality-reviewer | **Dual** | read-only | A/B test: Claude found 14 issues (2 HIGH), Codex found 11 (3 HIGH), only ~6 overlap. Dual yields ~19 unique findings (+36-73% coverage). Both models find HIGH-severity issues the other misses. |
-| test-analyst | **Codex** | workspace-write | Test gap analysis + test code suggestions |
-| ux-reviewer | **Claude** | — | UX flow assessment = ambiguity handling |
-| ui-reviewer | **Claude** | — | Design token consistency = non-coding task |
-| accessibility-reviewer | **Claude** | — | Same rationale as team-resolve accessibility-auditor: Claude 3x finding coverage on WCAG audits |
-| product-validator | **Claude** | — | Business logic intent = ambiguity handling |
-| api-reviewer | **Dual** | read-only | Same rationale as team-resolve api-designer: both models find unique API issues |
-| performance-reviewer | **Codex** | read-only | Algorithm complexity = Terminal-Bench (+9.7pp) |
-
-### Summary distribution
-
-| Engine | team-resolve (12) | team-review (9) | Total |
-|--------|-------------------|-----------------|-------|
-| Claude | 7 | 4 | 11 |
-| Codex | 2 | 2 | 4 |
-| Dual | 3 | 3 | 6 |
-
----
-
-## Pipeline Phase Routing (auto-resolve)
-
-| Phase | --engine auto | --engine codex | --engine claude |
-|-------|--------------|----------------|-----------------|
-| BUILD (implementation) | **Codex** | Codex | Claude |
-| BUILD GATE | bash (model-agnostic) | bash | bash |
-| BROWSER VALIDATE | Claude (Chrome MCP only) | Claude | Claude |
-| EVALUATE | **Claude** | Claude | Claude |
-| FIX LOOP | **Codex** | Codex | Claude |
-| SIMPLIFY | Claude | Codex | Claude |
-| REVIEW (team) | **Mixed per table** | Codex all | Claude all |
-| CHALLENGE | **Claude** | Claude | Claude |
-| SECURITY REVIEW | **Dual** | Codex | Claude |
-| CLEAN | Claude | Codex | Claude |
-| DOCS | Claude | Codex | Claude |
-
-Rationale for `--engine auto` choices:
-- BUILD/FIX: Codex — SWE-bench Pro 57.7% vs 46%. The biggest model gap is in hard coding tasks.
-- EVALUATE/CHALLENGE: Claude — evaluating a full diff requires long-context retrieval (MRCR +28pp) and skeptical reasoning (GPQA +3.5pp). Different model family from builder creates GAN dynamic.
-- BROWSER: Claude — Chrome MCP tools are Claude Code session-bound.
-- SECURITY: Dual — Semgrep study shows both models find unique vulnerabilities.
-
----
-
-## Pipeline Phase Routing (ideate)
-
-| Phase | --engine auto | --engine codex | --engine claude |
-|-------|--------------|----------------|-----------------|
-| FRAME | **Claude** | Codex | Claude |
-| EXPLORE | **Claude** | Codex | Claude |
-| CONVERGE | **Claude** | Codex | Claude |
-| CHALLENGE | **Codex** (rubric critic) | Claude (role reversal) | Claude |
-| DOCUMENT | **Claude** | Codex | Claude |
-
-Rationale:
-- FRAME/EXPLORE/CONVERGE: Claude — ambiguous intent handling, multi-perspective reasoning.
-- CHALLENGE: When `--engine auto`, Codex runs the rubric pass as critic — automatic on every run. When `--engine codex`, Claude runs the challenge (role reversal — builder and critic are always different models).
-- DOCUMENT: Claude — writing quality for spec generation.
-
----
-
-## Pipeline Phase Routing (preflight)
-
-| Phase | --engine auto | --engine codex | --engine claude |
-|-------|--------------|----------------|-----------------|
-| EXTRACT COMMITMENTS | Claude | Codex | Claude |
-| CODE AUDIT | **Codex** | Codex | Claude |
-| DOCS AUDIT | **Claude** | **Claude** | Claude |
-| BROWSER AUDIT | Claude (Chrome MCP) | Claude | Claude |
-| SYNTHESIZE | Claude | Claude | Claude |
-
-DOCS AUDIT is always Claude regardless of `--engine` — writing-quality strength on documentation drift detection (READMEs, VISION.md prose, spec status accuracy) is the deciding factor, not code analysis. BROWSER AUDIT is always Claude because Chrome MCP tools are session-bound to Claude Code.
-
----
-
-## How to Spawn a Codex Role
-
-For roles marked **Codex** in the routing table, call `mcp__codex-cli__codex` instead of spawning a Claude Agent subagent. Package the role's full prompt (from the skill's teammate prompt section) into the Codex call.
-
-Template:
-
-```
-mcp__codex-cli__codex({
-  prompt: "[full role prompt with issue context, file paths, and deliverable format]",
-  model: "gpt-5.4",
-  reasoningEffort: "xhigh",
-  sandbox: "[read-only or workspace-write per table]",
-  workingDirectory: "[project root]"
-})
-```
-
-**Important**: Codex has no access to team infrastructure (TeamCreate, SendMessage, TaskCreate). For Codex roles:
-- Include ALL context inline in the prompt (issue description, file paths from investigation, deliverable format)
-- The orchestrator collects Codex's response and routes it where it would have gone via SendMessage
-- Codex roles cannot communicate with other teammates directly — the orchestrator relays findings
-
-For roles marked **Claude**, spawn a normal Agent subagent as before.
-
----
-
-## How to Spawn a Dual Role
-
-For roles marked **Dual**, run BOTH models in parallel and merge findings:
-
-1. Spawn a Claude Agent subagent with the role's prompt
-2. Call `mcp__codex-cli__codex` with the same role's prompt (sandbox: "read-only")
-3. Wait for both to complete
-4. Merge findings:
-   - Same finding from both → keep more detailed description, mark "confirmed by both models"
-   - Claude-only → keep as-is
-   - Codex-only → prefix with `[codex]`
-   - Conflicting findings → keep both, note the disagreement
-   - Take the MORE SEVERE verdict between the two
-
----
-
-## How to Spawn a Codex BUILD/FIX Agent
-
-For BUILD and FIX LOOP phases when engine routes to Codex:
-
-```
-mcp__codex-cli__codex({
-  prompt: "[full build/fix prompt with task description, done criteria, and implementation instructions]",
-  model: "gpt-5.4",
-  reasoningEffort: "xhigh",
-  sandbox: "workspace-write",
-  fullAuto: true,
-  workingDirectory: "[project root]"
-})
-```
-
-**After Codex completes**: verify changes were made (`git diff --stat`), then proceed to the next phase as normal. The file-based handoff (`.devlyn/done-criteria.md`, `.devlyn/EVAL-FINDINGS.md`, etc.) works identically — Codex writes the same files Claude would.
-
-**Session management**: For FIX LOOP iterations, use a fresh call each time (no `sessionId` reuse) because sandbox/fullAuto parameters only apply on the first call of a session.
-
----
-
-## Override Behavior
-
-- `--engine claude` → all roles and phases use Claude (no Codex calls)
-- `--engine codex` → all phases use Codex for implementation/analysis, Claude only for orchestration and Chrome MCP
-- `--engine auto` (default) → each role and phase routes to the optimal model per this table

package/config/skills/devlyn:browser-validate/SKILL.md

@@ -1,164 +0,0 @@
----
-name: devlyn:browser-validate
-description: Browser-based validation for web applications — verifies that implemented features actually work by testing them in a real browser. Starts the dev server, tests the feature end-to-end (click buttons, fill forms, verify results), and reports what's broken with screenshot evidence. Use this skill whenever the user says "test in browser", "check if it works", "does the feature work", "browser test", "validate the UI", or when auto-resolve needs to verify web changes actually function correctly. Also use proactively after implementing UI changes. The primary goal is feature verification, not just checking if pages render.
----
-
-Verify that implemented features actually work in the browser. The primary job is to test the feature that was just built — click the button, fill the form, check the result. Smoke tests and visual checks are supporting checks, not the main event.
-
-The whole point of browser validation is to catch the gap between "code looks correct" and "user can actually do the thing." Static analysis and unit tests can confirm the code is well-structured. Browser validation confirms it *works*.
-
-<config>
-$ARGUMENTS
-</config>
-
-<workflow>
-
-## PHASE 1: DETECT
-
-1. **What was built**: This is the most important input. Read `.devlyn/done-criteria.md` if it exists — it tells you what the feature is supposed to do. If it doesn't exist, read `git diff --stat` and `git log -1` to understand what changed. You need to know what to test before anything else.
-
-2. **Framework detection**: Read `package.json` → identify framework and start command from `scripts.dev`, `scripts.start`, or `scripts.preview`.
-
-3. **Port inference**: Defaults — Next.js: 3000, Vite: 5173, CRA: 3000, Nuxt: 3000, Astro: 4321, Angular: 4200. Override with `--port` flag.
-
-4. **Affected routes**: Map changed files to routes (e.g., `app/dashboard/page.tsx` → `/dashboard`).
-
-5. **Tier selection** — pick the best available browser tool. **You must verify each tier actually works before committing to it** — tools can be registered but not connected:
-   - **Tier 1 probe** (Chrome DevTools): Check if `mcp__claude-in-chrome__*` tools exist. If they do, load `mcp__claude-in-chrome__tabs_context_mcp` via ToolSearch and call it. If the call **succeeds** (returns tab data without error), use Tier 1. Read `references/tier1-chrome.md`. If the call **fails** (timeout, connection error, extension not running), Tier 1 is unavailable — fall through to Tier 2.
-   - **Tier 2 probe** (Playwright): Check if `mcp__playwright__*` tools exist (try ToolSearch for `mcp__playwright__browser_navigate`). If they exist and respond, use Tier 2 Mode A. Else run `npx playwright --version 2>/dev/null` — if it succeeds, use Tier 2 Mode B. Read `references/tier2-playwright.md`.
-   - **Tier 3** (HTTP smoke): Fallback when no browser tool is functional. Read `references/tier3-curl.md`.
-   
-   **Critical rule**: Never treat a tier as available just because its tools appear in the tool list. Deferred/registered tools may not have a running backend. Always probe before committing.
-
-6. **Skip gate**: If no web-relevant files changed (no `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.astro`, `*.css`, `*.scss`, `*.html`, `page.*`, `layout.*`, `route.*`, `+page.*`, `+layout.*`), skip. Report: "Browser validation skipped — no web changes detected."
-
-7. **Parse flags** from `<config>`:
-   - `--skip-feature` — skip feature testing, only run smoke + visual
-   - `--port PORT` — override detected port
-   - `--tier N` — force a specific tier (1, 2, or 3)
-   - `--mobile-only` / `--desktop-only` — limit viewport testing
-   - `--topic SLUG` — override the auto-derived screenshot topic slug
-
-8. **Derive the screenshot topic slug**. All screenshots for this run go under `.devlyn/screenshots/<topic-slug>/` so runs for different features don't pile up together. Resolution order:
-   1. `--topic` flag value, kebab-cased
-   2. First non-blank heading/line of `.devlyn/done-criteria.md` (strip `#`, kebab-case, max 40 chars)
-   3. Current git branch name, if not `main`/`master`/`HEAD`
-   4. Fallback: `run-<YYYYMMDD-HHMM>`
-
-   Then wipe and recreate the topic dir (fresh evidence per run; don't touch other topics' dirs):
-   ```bash
-   SCREENSHOT_DIR=".devlyn/screenshots/<topic-slug>"
-   rm -rf "$SCREENSHOT_DIR"
-   mkdir -p "$SCREENSHOT_DIR"/{smoke,feature,visual}
-   ```
-
-   Record `$SCREENSHOT_DIR` and reuse it through the run. All screenshot paths below are **relative to `$SCREENSHOT_DIR`**:
-   - Smoke: `smoke/<route-slug>.png` (root → `smoke/root.png`)
-   - Feature: `feature/<criterion-slug>-step<N>.png`
-   - Visual: `visual/<viewport>-<route-slug>.png` (e.g., `visual/mobile-dashboard.png`)
-
-Announce:
-```
-Browser validation starting
-Feature: [what was built, from done-criteria or git diff]
-Framework: [detected] | Port: [PORT] | Tier: [N — name]
-Topic: [topic-slug] → .devlyn/screenshots/<topic-slug>/
-Phases: Server → Smoke → Feature Test → Visual → Report
-```
-
-## PHASE 2: SERVER
-
-Get the dev server running. If it doesn't start, diagnose and fix — don't just report failure.
-
-1. Start the dev server in background via Bash with `run_in_background: true`.
-2. Health-check: poll `http://localhost:PORT` every 2s, timeout 30s. Ready when you get an HTTP response.
-3. **If it doesn't come up — troubleshoot** (up to 2 attempts): read stderr for the error, fix it (npm install, port conflict, build error, etc.), restart, re-check.
-4. If still down after 2 attempts: write BLOCKED verdict and stop.
-
-## PHASE 3: SMOKE (quick prerequisite)
-
-Quick check that the app is alive. This is not the main test — it's a gate to make sure feature testing is even possible.
-
-Navigate to `/` and each affected route. For each page, judge: is this the actual application, or an error page? A connection error, framework error overlay, or blank shell is not the app. If broken, try to fix (read console errors, fix source, let hot-reload pick it up). Up to 2 fix attempts per route.
-
-**Tier downgrade on failure**: If you're on Tier 1 or Tier 2 Mode A and the browser tool consistently fails during smoke (connection errors, timeouts, extension disconnected), **do not skip browser testing**. Instead, downgrade to the next tier (Tier 1 → Tier 2 → Tier 3), re-read the corresponding reference file, and retry the smoke phase with the new tier. Announce: `"Tier [N] browser tools not responding — downgrading to Tier [N+1]."` The goal is to always run the best available browser test, not to give up.
-
-If the app isn't rendering, the verdict is BLOCKED — feature testing can't happen.
-
-## PHASE 4: FEATURE TEST (the main event)
-
-This is the primary purpose of browser validation. Everything else is in service of getting here.
-
-Read `.devlyn/done-criteria.md` (or infer from git diff what was built). For each criterion that describes something a user can do or see in the UI, test it end-to-end in the browser:
-
-1. **Plan the test**: What would a user do to verify this feature works? Navigate where, click what, type what, expect what result?
-2. **Execute it**: Navigate to the page, find the interactive elements, perform the actions, verify the outcome. Read `references/flow-testing.md` for patterns on converting criteria to browser steps.
-3. **Capture evidence**: Screenshot at each key step. Record console errors and network failures that happen during the interaction.
-4. **If it fails — try to fix**: Read the error (console, network, or the UI state) to understand why the feature broke. Fix the source code, let hot-reload update, and re-test. Up to 2 fix attempts per criterion.
-5. **Record the result**: For each criterion — PASS (feature works as specified), FAIL (feature doesn't work, include what went wrong), SKIPPED (criterion isn't browser-testable, e.g., "API returns 401"), or UNVERIFIABLE (feature depends on external services not available in the test environment — e.g., real API keys, third-party auth, paid services).
-
-**Don't churn on external dependencies.** If a feature test is blocked because an API times out, a third-party service isn't configured, or auth credentials aren't available — that's not a bug to fix, it's a test environment limitation. Note it as UNVERIFIABLE, move on to the next criterion. Don't spend more than 30 seconds waiting for a response that's never coming. The goal is to verify what *can* be verified in the current environment, and be honest about what can't.
-
-The verdict depends primarily on this phase. If the implemented features don't work in the browser, the validation fails — even if every page renders perfectly and the layout looks great. And if most features couldn't be verified due to environment limitations, be honest about that — don't call it PASS.
-
-## PHASE 5: VISUAL (supporting check)
-
-Quick layout check at two viewports (skip if `--mobile-only` or `--desktop-only`):
-
-1. **Mobile** (375x812): screenshot each affected route, check for overflow/overlap/unreadable text
-2. **Desktop** (1280x800): screenshot each affected route, check for broken layouts
-
-Judgment-based — look at the screenshots and report visible issues.
-
-## PHASE 6: REPORT
-
-Write `.devlyn/BROWSER-RESULTS.md`:
-
-```markdown
-# Browser Validation Results
-
-## Verdict: [PASS / PASS WITH ISSUES / NEEDS WORK / PARTIALLY VERIFIED / BLOCKED]
-Verdict rules:
-- BLOCKED = server won't start or app doesn't render
-- NEEDS WORK = implemented features don't work in the browser
-- PARTIALLY VERIFIED = some features verified working, but others couldn't be tested due to environment limitations (missing API keys, external service dependencies). Be explicit about what was and wasn't verified.
-- PASS WITH ISSUES = all testable features work but visual issues or minor warnings exist
-- PASS = all testable features verified working, pages render, layout clean
-
-## What Was Tested
-[Brief description of the feature/task from done-criteria or git diff]
-
-## Feature Verification (primary)
-| Criterion | Test Steps | Result | Evidence |
-|-----------|-----------|--------|----------|
-| [what should work] | [what you did] | PASS/FAIL/SKIPPED/UNVERIFIABLE | [screenshot, errors, what went wrong] |
-
-## Unverifiable Features (if any)
-[List features that couldn't be tested and why — e.g., "Badge rendering requires /api/backends/status which needs real API keys not present in test env. Verified via source code and unit tests instead."]
-
-## Smoke Test (prerequisite)
-| Route | Renders | Console Errors | Network Failures |
-|-------|---------|---------------|-----------------|
-| / | YES/NO | [count] | [count] |
-
-## Visual Check
-| Viewport | Route | Issues |
-|----------|-------|--------|
-| Mobile (375px) | / | [issues or "Clean"] |
-| Desktop (1280px) | / | [issues or "Clean"] |
-
-## Fixes Applied During Validation
-[List any bugs found and fixed during testing — server startup issues, broken routes, feature bugs]
-
-## Runtime Errors
-[Console errors captured during testing]
-
-## Failed Network Requests
-[Failed API calls captured during testing]
-```
-
-## PHASE 7: CLEANUP
-
-Kill the dev server PID. If `--keep-server` was passed (auto-resolve pipeline), skip — the pipeline handles cleanup.
-
-</workflow>

package/config/skills/devlyn:browser-validate/references/flow-testing.md

@@ -1,118 +0,0 @@
-# Flow Testing: Done-Criteria to Browser Steps
-
-How to read `.devlyn/done-criteria.md` and convert testable criteria into browser action sequences. This is the bridge between "what should work" and "prove it works in the browser."
-
-Read this file only during PHASE 4 (FLOW) when done-criteria exists.
-
----
-
-## Step 1: Classify Each Criterion
-
-Read `.devlyn/done-criteria.md` and classify each criterion:
-
-**Browser-testable** — the criterion describes something a user can see or do in the UI:
-- "User can create a new project from the dashboard"
-- "Error message appears when form is submitted with empty fields"
-- "Navigation shows active state on current page"
-- "Data table loads and displays 10 rows"
-
-**Not browser-testable** — the criterion is about backend logic, data integrity, or code quality:
-- "API returns 401 for unauthenticated requests"
-- "Database migration runs without errors"
-- "Test coverage exceeds 80%"
-- "No TypeScript errors"
-
-Skip non-browser-testable criteria. Note them as "Skipped — not browser-testable" in the report.
-
-## Step 2: Convert to Action Sequences
-
-For each browser-testable criterion, generate a sequence of steps:
-
-### Pattern: Navigation + Verification
-```
-Criterion: "Dashboard shows project count"
-Steps:
-  1. Navigate to /dashboard
-  2. Find element containing project count (look for text matching a number pattern)
-  3. Verify: element exists and contains a numeric value
-  4. Screenshot
-```
-
-### Pattern: Form Interaction
-```
-Criterion: "User can create a new project"
-Steps:
-  1. Navigate to /dashboard (or wherever the create action lives)
-  2. Find "Create" or "New Project" button
-  3. Click it
-  4. Find form fields (name, description, etc.)
-  5. Fill with test data: name="Test Project", description="Browser validation test"
-  6. Find and click submit button
-  7. Verify: success indicator appears (toast, redirect, new item in list)
-  8. Screenshot at steps 3, 6, and 7
-```
-
-### Pattern: Error State
-```
-Criterion: "Error message shows when form submitted empty"
-Steps:
-  1. Navigate to the form page
-  2. Find submit button
-  3. Click submit without filling any fields
-  4. Verify: error message(s) visible
-  5. Screenshot showing error state
-```
-
-### Pattern: Conditional UI
-```
-Criterion: "Empty state shows when no data exists"
-Steps:
-  1. Navigate to the list/table page
-  2. Check if data exists — if so, this test needs a clean state
-  3. If clean state achievable: verify empty state message/illustration
-  4. If not: skip with note "Cannot verify empty state — data already exists"
-  5. Screenshot
-```
-
-## Step 3: Handle Data Dependencies
-
-Some flow tests need specific data to exist (or not exist). Approach:
-
-1. **Read-only tests preferred** — test flows that verify existing state rather than create/modify
-2. **Create test data if safe** — if the flow creates something (like a project), use obvious test names ("Browser Validation Test — safe to delete")
-3. **Skip if destructive** — don't test delete flows, don't modify existing data, don't test flows that send emails or notifications
-4. **Note dependencies** — if a test can't run because of missing data, note it as "Skipped — requires [specific data state]"
-
-## Step 4: Handle Auth-Protected Pages
-
-If a route requires authentication:
-1. Check if the app redirects to a login page
-2. If login is a simple form (email + password): note "Auth required — skipping unless test credentials available"
-3. If login uses OAuth/SSO: skip entirely, note "Skipped — requires OAuth flow"
-4. Do not attempt to log in with guessed credentials
-
-## Test Data Guidelines
-
-When filling forms during flow tests, use obviously fake but valid data:
-- Name: "Test User" or "Browser Validate Test"
-- Email: "test@browser-validate.local"
-- Description: "Created by browser-validate skill — safe to delete"
-- Numbers: use small, obvious values (1, 10, 100)
-
-This makes test data easy to identify and clean up later.
-
-## Output Format
-
-For each flow test, report:
-
-```
-Criterion: [original text from done-criteria]
-Classification: browser-testable | skipped
-Steps executed: [N of total]
-Result: PASS | FAIL | SKIPPED
-Evidence:
-  - Screenshot: [path]
-  - Console errors during flow: [count] — [details]
-  - Network failures during flow: [count] — [details]
-  - Failure point: [which step failed and why]
-```