devlyn-cli 1.3.1 → 1.3.2

package/CLAUDE.md

@@ -56,10 +56,13 @@ For hands-free build-evaluate-polish cycles — works for bugs, features, refact
 /devlyn:auto-resolve [task description]
 ```
 
-This runs the full pipeline automatically: **Build → Evaluate → Fix Loop → Simplify → Review → Security Review → Clean → Docs**. Each phase runs as a separate subagent with its own context. Communication between phases happens via files (`.claude/done-criteria.md`, `.claude/EVAL-FINDINGS.md`).
+This runs the full pipeline automatically: **Build → Browser Validate → Evaluate → Fix Loop → Simplify → Review → Security Review → Clean → Docs**. Each phase runs as a separate subagent with its own context. Communication between phases happens via files (`.claude/done-criteria.md`, `.claude/EVAL-FINDINGS.md`, `.claude/BROWSER-RESULTS.md`).
+
+For web projects, the Browser Validate phase starts the dev server and tests the implemented feature in a real browser — clicking buttons, filling forms, verifying results. If the feature doesn't work, findings feed back into the fix loop.
 
 Optional flags:
 - `--max-rounds 3` — increase max evaluate-fix iterations (default: 2)
+- `--skip-browser` — skip browser validation phase (auto-skipped for non-web changes)
 - `--skip-review` — skip team-review phase
 - `--skip-clean` — skip clean phase
 - `--skip-docs` — skip update-docs phase
@@ -99,6 +102,13 @@ Steps 4-6 are optional depending on the scope of changes. `/simplify` should alw
 - Preserves all forward-looking content: roadmaps, future plans, visions, open questions
 - If no docs exist, proposes a tailored docs structure and generates initial content
 
+## Browser Testing Workflow
+
+- **Standalone**: Use `/devlyn:browser-validate` to test any web feature in the browser — starts the dev server, tests the feature end-to-end, fixes issues it finds
+- **In pipeline**: Auto-resolve includes browser validation automatically for web projects (between Build and Evaluate phases)
+- **Tiered**: Uses chrome MCP tools if available, falls back to Playwright, then curl
+- **Feature-first**: Tests the implemented feature (from done-criteria), not just "does the page load"
+
 ## Debugging Workflow
 
 - **Simple bugs**: Use `/devlyn:resolve` for systematic bug fixing with test-driven validation

package/README.md

@@ -39,9 +39,10 @@ Structured prompts and role-based instructions that shape _what the AI knows and
 
 Pipeline orchestration that controls _how agents execute_ — permissions, state management, multi-phase workflows, and cross-model evaluation.
 
-- **`/devlyn:auto-resolve`** — 8-phase automated pipeline (build → evaluate → fix loop → simplify → review → security → clean → docs)
+- **`/devlyn:auto-resolve`** — 9-phase automated pipeline (build → browser validate → evaluate → fix loop → simplify → review → security → clean → docs)
+- **`/devlyn:browser-validate`** — feature verification in a real browser with tiered fallback (Chrome MCP → Playwright → curl)
 - **`bypassPermissions` mode** for autonomous subagent execution
-- **File-based state machine** — agents communicate via `.claude/done-criteria.md` and `EVAL-FINDINGS.md`
+- **File-based state machine** — agents communicate via `.claude/done-criteria.md`, `EVAL-FINDINGS.md`, and `BROWSER-RESULTS.md`
 - **Git checkpoints** at each phase for rollback safety
 - **Cross-model evaluation** via `--with-codex` flag (OpenAI Codex as independent evaluator)
 
@@ -89,7 +90,8 @@ Slash commands are invoked directly in Claude Code conversations (e.g., type `/d
 |---|---|
 | `/devlyn:resolve` | Systematic bug fixing with root-cause analysis and test-driven validation |
 | `/devlyn:team-resolve` | Spawns a full agent team — root cause analyst, test engineer, security auditor — to investigate complex issues |
-| `/devlyn:auto-resolve` | Fully automated pipeline for any task — bugs, features, refactors, chores. Build → evaluate → fix loop → simplify → review → clean → docs. One command, zero human intervention. Supports `--with-codex` for cross-model evaluation via OpenAI Codex |
+| `/devlyn:auto-resolve` | Fully automated pipeline for any task — bugs, features, refactors, chores. Build → browser validate → evaluate → fix loop → simplify → review → clean → docs. One command, zero human intervention. Supports `--with-codex` for cross-model evaluation via OpenAI Codex |
+| `/devlyn:browser-validate` | Verify implemented features work in a real browser — starts dev server, tests the feature end-to-end (clicks, forms, verification), with tiered fallback (Chrome MCP → Playwright → curl) |
 
 ### Code Review & Quality
 
@@ -151,6 +153,7 @@ One command runs the full cycle — no human intervention needed:
 | Phase | What Happens |
 |---|---|
 | **Build** | `team-resolve` investigates and implements, writes testable done criteria |
+| **Browser Validate** | For web projects: starts dev server, tests the implemented feature end-to-end in a real browser, fixes issues found |
 | **Evaluate** | Independent evaluator grades against done criteria with calibrated skepticism |
 | **Fix Loop** | If evaluation fails, fixes findings and re-evaluates (up to N rounds) |
 | **Simplify** | Quick cleanup pass for reuse and efficiency |
@@ -159,7 +162,7 @@ One command runs the full cycle — no human intervention needed:
 | **Clean** | Remove dead code and unused dependencies |
 | **Docs** | Sync documentation with changes |
 
-Each phase runs as a separate subagent (fresh context), communicates via files, and commits a git checkpoint for rollback safety. Skip phases with flags: `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 3`, `--with-codex` (cross-model evaluation via OpenAI Codex).
+Each phase runs as a separate subagent (fresh context), communicates via files, and commits a git checkpoint for rollback safety. Skip phases with flags: `--skip-browser`, `--skip-review`, `--skip-clean`, `--skip-docs`, `--max-rounds 3`, `--with-codex` (cross-model evaluation via OpenAI Codex).
 
 ### Manual Workflow
 
@@ -237,6 +240,15 @@ Installed via the [skills CLI](https://github.com/anthropics/skills) (`npx skill
 | `anthropics/skills` | Official Anthropic skill-creator with eval framework and description optimizer |
 | `Leonxlnx/taste-skill` | Premium frontend design skills — modern layouts, animations, and visual refinement |
 
+### MCP Servers
+
+Installed via `claude mcp add` during setup.
+
+| Server | Description |
+|---|---|
+| `codex-cli` | Codex MCP server for cross-model evaluation via OpenAI Codex |
+| `playwright` | Playwright MCP for browser testing — powers `devlyn:browser-validate` Tier 2 |
+
 > **Want to add a pack?** Open a PR adding your pack to the `OPTIONAL_ADDONS` array in [`bin/devlyn.js`](bin/devlyn.js).
 
 ## How It Works

package/config/skills/devlyn:auto-resolve/SKILL.md

@@ -91,8 +91,12 @@ You are a browser validation agent. Read the skill instructions at `.claude/skil
 **After the agent completes**:
 1. Read `.claude/BROWSER-RESULTS.md`
 2. Extract the verdict
-3. If `BLOCKED` → the app doesn't even render. Go directly to PHASE 2.5 fix loop with browser findings as context.
-4. Otherwise → continue to PHASE 2 (the evaluator will read `BROWSER-RESULTS.md` as additional evidence)
+3. Branch on verdict:
+   - `PASS` → continue to PHASE 2
+   - `PASS WITH ISSUES` → continue to PHASE 2 (evaluator reads browser results as extra context)
+   - `PARTIALLY VERIFIED` → continue to PHASE 2, but flag to the evaluator that browser coverage was incomplete — unverified features should be weighted more heavily
+   - `NEEDS WORK` → features don't work in the browser. Go to PHASE 2.5 fix loop. Fix agent reads `.claude/BROWSER-RESULTS.md` for which criterion failed, at what step, with what error. After fixing, re-run PHASE 1.5 to verify the fix before proceeding to Evaluate.
+   - `BLOCKED` → app doesn't render. Go to PHASE 2.5 fix loop. After fixing, re-run PHASE 1.5.
 
 ## PHASE 2: EVALUATE
 

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

@@ -71,9 +71,11 @@ Read `.claude/done-criteria.md` (or infer from git diff what was built). For eac
 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), or SKIPPED (criterion isn't browser-testable, e.g., "API returns 401").
+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).
 
-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.
+**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)
 
@@ -91,12 +93,13 @@ Write `.claude/BROWSER-RESULTS.md`:
 ```markdown
 # Browser Validation Results
 
-## Verdict: [PASS / PASS WITH ISSUES / NEEDS WORK / BLOCKED]
+## 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 (this is the primary failure mode)
-- PASS WITH ISSUES = features work but visual issues or minor warnings exist
-- PASS = features verified working, pages render, layout clean
+- 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]
@@ -104,7 +107,10 @@ Verdict rules:
 ## Feature Verification (primary)
 | Criterion | Test Steps | Result | Evidence |
 |-----------|-----------|--------|----------|
-| [what should work] | [what you did] | PASS/FAIL/SKIPPED | [screenshot, errors, what went wrong] |
+| [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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"