the-frame-ai 0.9.6 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-frame-ai",
-  "version": "0.9.6",
+  "version": "0.10.1",
   "description": "FRAME — Framework for AI-Assisted Solo Development",
   "type": "module",
   "bin": {

package/src/init.js

@@ -10,8 +10,10 @@ import {
   writeFile,
   applyVars,
   mergeVscodeSettings,
+  mergeClaudeSettings,
+  mergeVscodeMcp,
 } from './utils.js';
-import { LANGUAGES, getLanguageInstruction, promptLanguage, promptConfig, promptCopilot } from './languages.js';
+import { LANGUAGES, getLanguageInstruction, promptLanguage, promptConfig, promptCopilot, promptFrontend } from './languages.js';
 import { doctor } from './doctor.js';
 
 const PLANNING_DIRS = [
@@ -85,7 +87,14 @@ export async function init(target, flags = {}) {
   const commandCount = readdirSync(commandsSrc).filter((f) => f.endsWith('.md')).length;
   logSuccess(`${commandCount} commands → .claude/commands/`);
 
-  // 2b. Copilot Chat support
+  // 2b. Frontend: Playwright MCP
+  const frontend = await promptFrontend(flags.yes);
+  if (frontend) {
+    mergeClaudeSettings(join(target, '.claude', 'settings.json'));
+    logSuccess(`Playwright MCP → .claude/settings.json`);
+  }
+
+  // 2c. Copilot Chat support
   const copilot = await promptCopilot(flags.yes);
   if (copilot) {
     const promptsDest = join(target, '.github', 'prompts');
@@ -96,7 +105,9 @@ export async function init(target, flags = {}) {
     const vscodeDest = join(target, '.vscode');
     ensureDir(vscodeDest);
     mergeVscodeSettings(join(vscodeDest, 'settings.json'));
+    if (frontend) mergeVscodeMcp(join(vscodeDest, 'mcp.json'));
     logSuccess(`${commandCount} Copilot prompts → .github/prompts/`);
+    if (frontend) logSuccess(`Playwright MCP → .vscode/mcp.json`);
   }
 
   // 3. Copy agents and apply quality.commands substitution
@@ -163,6 +174,7 @@ export async function init(target, flags = {}) {
   if (fileExists(configPath)) {
     resolvedConfig.language = language;
     resolvedConfig.copilot = copilot;
+    resolvedConfig.frontend = frontend;
     writeFile(configPath, JSON.stringify(resolvedConfig, null, 2));
   }
 
@@ -184,6 +196,7 @@ export async function init(target, flags = {}) {
   log(`  Planning:  files in .planning/`);
   log(`  Config:    .frame/config.json`);
   if (copilot) log(`  Copilot:   ${commandCount} prompts in .vscode/`);
+  if (frontend) log(`  Playwright MCP: .claude/settings.json${copilot ? ' + .vscode/mcp.json' : ''}`);
   log('');
 
   // 11. Auto-run doctor

package/src/languages.js

@@ -140,3 +140,14 @@ export async function promptCopilot(yes = false) {
     });
   });
 }
+
+export async function promptFrontend(yes = false) {
+  if (!process.stdin.isTTY || yes) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question('\n? Is this a frontend project? Adds Playwright MCP for UI verification (y/N): ', (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}

package/src/update.js

@@ -1,7 +1,8 @@
 import { join } from 'node:path';
 import { readdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { TEMPLATES_DIR, VERSION, log, logSuccess } from './manifest.js';
-import { copyDir, makeExecutable, fileExists, applyVars, writeFile, ensureDir, mergeVscodeSettings } from './utils.js';
+import { copyDir, makeExecutable, fileExists, applyVars, writeFile, ensureDir, mergeVscodeSettings, mergeClaudeSettings, mergeVscodeMcp } from './utils.js';
+import { promptFrontend } from './languages.js';
 
 
 export async function update(target, flags = {}) {
@@ -99,6 +100,19 @@ export async function update(target, flags = {}) {
     }
   }
 
+  // 5. Update Playwright MCP (frontend projects)
+  if (config.frontend === undefined || config.frontend === false) {
+    if (process.stdin.isTTY && !flags.yes) {
+      const frontend = await promptFrontend(false);
+      config.frontend = frontend;
+      writeFileSync(join(target, '.frame', 'config.json'), JSON.stringify(config, null, 2), 'utf-8');
+    }
+  }
+  if (config.frontend) {
+    mergeClaudeSettings(join(target, '.claude', 'settings.json'));
+    if (config.copilot) mergeVscodeMcp(join(target, '.vscode', 'mcp.json'));
+  }
+
   // 5. Write new version
   writeFileSync(join(target, '.frame', '.frame-version'), VERSION, 'utf-8');
 

package/src/utils.js

@@ -63,3 +63,28 @@ export function mergeVscodeSettings(settingsPath) {
   settings['chat.promptFiles'] = true;
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
 }
+
+const PLAYWRIGHT_MCP = {
+  command: 'npx',
+  args: ['@playwright/mcp@latest'],
+};
+
+export function mergeClaudeSettings(settingsPath) {
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); } catch {}
+  }
+  settings.mcpServers = settings.mcpServers ?? {};
+  settings.mcpServers.playwright = PLAYWRIGHT_MCP;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+}
+
+export function mergeVscodeMcp(mcpPath) {
+  let config = {};
+  if (existsSync(mcpPath)) {
+    try { config = JSON.parse(readFileSync(mcpPath, 'utf-8')); } catch {}
+  }
+  config.servers = config.servers ?? {};
+  config.servers.playwright = PLAYWRIGHT_MCP;
+  writeFileSync(mcpPath, JSON.stringify(config, null, 2), 'utf-8');
+}

package/templates/commands/frame:build.md

@@ -140,6 +140,19 @@ If unclosed tasks exist — return and complete them or report to user.
 
 **D-step**: All checks must pass.
 
+### Step 6.5: UI Verification (if UI tasks present)
+
+**Detect UI tasks**: any task changed files with `.tsx`, `.vue`, `.css`, `component`, `page`, `layout`, `style`.
+
+If UI tasks exist AND Playwright MCP is available:
+1. `browser_navigate: {dev server URL}`
+2. `browser_screenshot`
+3. Compare with spec from `docs/specs/{feature}/spec.md`
+4. **PASS** → proceed to Step 7
+5. **FAIL** → describe problem, fix, re-run quality gates, re-verify
+
+If Playwright MCP is not available — skip and note: "UI not verified (no browser tool)".
+
 ### Step 7: Update STATE.md (COMPLETE)
 
 ```markdown

package/templates/commands/frame:debug.md

@@ -91,6 +91,7 @@ Update STATE.md: `Current Phase: 3/4`
    - **D-step**: Regression test must PASS
    - Run all tests: `{quality.commands.test}`
    - Type check: `{quality.commands.typecheck}`
+   - **If UI bug** (visual, layout, component): open browser via Playwright MCP → `browser_navigate` → `browser_screenshot` → confirm the bug is gone visually
 
 ### Phase 4: Review and Knowledge Capture
 

package/templates/commands/frame:fast.md

@@ -45,6 +45,19 @@ Execute:
 4. Run quality gates: `{quality.commands.typecheck} && {quality.commands.test} && {quality.commands.lint}`
 5. Git commit: `git add {files} && git commit -m "{type}({scope}): {description}"`
 
+### Step 3.5: UI Verification (if UI task)
+
+**Detect UI task**: task description or changed files contain `.tsx`, `.vue`, `.css`, `component`, `page`, `layout`, `style`, `UI`, or `interface`.
+
+If this is a UI task AND Playwright MCP is available (`browser_navigate` tool exists):
+1. `browser_navigate: {dev server URL from .frame/config.json or ask user}`
+2. `browser_screenshot`
+3. Compare screenshot with task description
+4. **PASS** → continue to Step 4
+5. **FAIL** → describe the problem, return to Step 3 and fix, then re-verify
+
+If Playwright MCP is not available — skip this step and note: "UI not verified (no browser tool)".
+
 ### Step 4: Update STATE.md and wins
 
 Update `.planning/STATE.md`:

package/templates/commands/frame:verify-ui.md

@@ -0,0 +1,101 @@
+# /frame:verify -- Browser UI Verification
+
+Verifies UI result in a real browser via Playwright MCP. Use when the agent claims "done" but the interface looks wrong.
+
+## Instructions
+
+Verify the UI for: **$ARGUMENTS** (if empty — verify the last completed task from STATE.md)
+
+### Step 1: Determine what to verify
+
+If `$ARGUMENTS` is provided — use it as the verification target.
+Otherwise read `.planning/STATE.md` → find the last completed task/feature.
+
+### Step 2: Determine the URL
+
+Check in order:
+1. `$ARGUMENTS` contains a URL → use it
+2. `.frame/config.json` → `devServer.url` field
+3. Ask the user: "What URL should I open to verify? (e.g. http://localhost:3000)"
+
+### Step 3: Open browser and take screenshot
+
+```
+browser_navigate: {url}
+browser_screenshot
+```
+
+Describe what you see: layout, content, interactive elements.
+
+### Step 4: Compare with expected result
+
+Compare the screenshot with:
+- The task description from `$ARGUMENTS` or STATE.md
+- The spec from `docs/specs/{feature}/spec.md` (if exists)
+
+**Verdict:**
+- **PASS** — the interface matches the expected result → report success
+- **FAIL** — something is wrong → describe exactly what is wrong and what was expected
+
+### Step 5: On FAIL — interact to dig deeper
+
+If the initial screenshot shows a problem, try to reproduce it:
+```
+browser_click: {element}        # click buttons, links
+browser_type: {selector} {text} # fill forms
+browser_screenshot              # screenshot after interaction
+```
+
+Describe the exact problem: what element, what behavior, what was expected.
+
+### Step 6: Report
+
+**On PASS:**
+```
+✅ UI verified: {what was checked}
+- URL: {url}
+- Result: matches expected behavior
+```
+
+**On FAIL:**
+```
+❌ UI verification failed: {what was checked}
+- URL: {url}
+- Problem: {exact description}
+- Expected: {what should be}
+- Actual: {what is}
+- Suggested fix: {where to look}
+```
+
+On FAIL — do NOT auto-fix. Report to the user and wait for a decision:
+- Fix and re-verify → run `/frame:fast {fix description}`, then `/frame:verify` again
+- It's acceptable → mark as known issue
+
+## Rules
+
+- **Never auto-fix** — verify only, report problems
+- **Be specific** — describe exact elements, not "looks wrong"
+- **Screenshot first** — always take a screenshot before interacting
+- **Check mobile too** — if the project has responsive design, mention it
+
+## When to Use
+
+- After `/frame:fast`, `/frame:build`, `/frame:wave` on UI tasks
+- When the agent says "done" but visually something is off
+- Before `/frame:ship` for frontend features
+- When debugging visual regressions
+
+## Playwright MCP Setup
+
+If `browser_navigate` is not available, Playwright MCP is not configured.
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```

package/templates/commands/frame:wave.md

@@ -141,6 +141,13 @@ Repeat Steps 5-6 for each wave until all waves are complete.
 git log --oneline -10
 ```
 
+**UI Verification** (if any wave contained UI tasks — files with `.tsx`, `.vue`, `.css`, `component`, `page`, `layout`):
+
+If Playwright MCP is available:
+1. `browser_navigate: {dev server URL}`
+2. `browser_screenshot`
+3. Compare with spec — PASS → continue, FAIL → report to user with exact description, do NOT auto-fix
+
 Check completeness:
 ```bash
 TOTAL=$(grep -c "^### Task" plan.md)