app-navigator

name	app-navigator
description	Use when you need to map the application's routes, pages, and components, build reusable Playwright playbooks, or perform a UI/UX audit across the application
allowed-tools	Bash, Read, Write, Glob, Grep, Agent, mcp__playwright__*

App Navigator

Map your application's UI and build reusable Playwright playbooks for browser-based testing and verification.

Core principle: Know your app before you test it. This skill creates a living knowledge base of routes, pages, components, and interactions that other skills (like trust-but-verify) build on.

When to Use

• Setting up browser-based testing for the first time in a project
• After significant UI changes that may have shifted routes or layouts
• Before running trust-but-verify, if no app-map.md exists yet
• When you need to understand the app's page structure

Not for: API-only projects, backend-only changes, or projects without a web UI.

Invocation

• /app-navigator setup -- map the app and write playbooks
• /app-navigator audit -- UI/UX audit (v2, not yet implemented)
• If no argument given and no app-map.md exists, runs setup mode automatically

Setup Mode Process

digraph setup {
    "Check credentials" [shape=box];
    "Creds in memory?" [shape=diamond];
    "Ask user + save" [shape=box];
    "Check dev server" [shape=box];
    "Server reachable?" [shape=diamond];
    "Tell user what to start" [shape=box];
    "User authorizes start?" [shape=diamond];
    "Start server" [shape=box];
    "Login via browser" [shape=box];
    "Walk top-level routes" [shape=box];
    "For each page" [shape=box];
    "Screenshot + document" [shape=box];
    "Map to source component" [shape=box];
    "Write playbooks" [shape=box];
    "Save app-map.md + component-map.md" [shape=box];
    "Done" [shape=doublecircle];

    "Check credentials" -> "Creds in memory?";
    "Creds in memory?" -> "Check dev server" [label="yes"];
    "Creds in memory?" -> "Ask user + save" [label="no"];
    "Ask user + save" -> "Check dev server";
    "Check dev server" -> "Server reachable?";
    "Server reachable?" -> "Login via browser" [label="yes"];
    "Server reachable?" -> "Tell user what to start" [label="no"];
    "Tell user what to start" -> "User authorizes start?";
    "User authorizes start?" -> "Start server" [label="yes"];
    "User authorizes start?" -> "Login via browser" [label="no, user starts manually"];
    "Start server" -> "Login via browser";
    "Login via browser" -> "Walk top-level routes";
    "Walk top-level routes" -> "For each page";
    "For each page" -> "Screenshot + document";
    "Screenshot + document" -> "Map to source component";
    "Map to source component" -> "For each page" [label="next page"];
    "Map to source component" -> "Write playbooks" [label="all pages done"];
    "Write playbooks" -> "Save app-map.md + component-map.md";
    "Save app-map.md + component-map.md" -> "Done";
}

Step 1: Credential Check

Derive a project slug from the current workspace basename (lowercase, replace non-alphanumeric characters with -) and read the memory file at ~/.codex/memories/<project-slug>/reference_local_auth.md.

If it exists, extract: Email, Password, App URL, Login path.

If it does NOT exist, ask the user:

"I need login credentials for the local dev environment. Please provide:

1. Email address
2. Password
3. App URL (default: http://localhost:5173)
4. Login path (default: /login)

Use a local or test-only account with minimum permissions. Do not provide production or personal credentials.

These will be saved to your project memory for future use with owner-only file permissions."

Save their response to ~/.codex/memories/<project-slug>/reference_local_auth.md:

mkdir -p ~/.codex/memories/<project-slug>
chmod 700 ~/.codex/memories/<project-slug>

---
name: local-auth-credentials
description: Local dev login credentials and app URL for Playwright verification
type: reference
---

- Email: <user-provided>
- Password: <user-provided>
- App URL: <user-provided, default http://localhost:5173>
- Login path: <user-provided, default /login>

After writing the file, restrict it to the current user:

chmod 600 ~/.codex/memories/<project-slug>/reference_local_auth.md

No separate memory index file is required. Only reuse saved credentials when the saved App URL matches the current local or test target.

Step 2: Preflight -- Dev Server Check

Run:

curl -s -o /dev/null -w "%{http_code}" <App URL> 2>/dev/null || echo "unreachable"

If unreachable, tell the user:

"The dev server at isn't reachable. You'll need to start it. Start your development server (e.g., npm run dev, pnpm run dev). Start your API server if needed.

Want me to start it for you, or will you handle it?"

If user authorizes, start the server. Otherwise, wait for user confirmation that it's running, then re-check.

Step 3: Login via Browser

Use Playwright MCP tools:

1. mcp__playwright__browser_navigate to <App URL><Login path>
2. mcp__playwright__browser_snapshot to see the login form
3. mcp__playwright__browser_fill_form with email and password fields
4. mcp__playwright__browser_click on the submit/login button
5. mcp__playwright__browser_wait_for with text set to a known post-login element (e.g., a dashboard heading or username)
6. mcp__playwright__browser_snapshot to confirm logged-in state

If the page redirects through an SSO/OAuth provider or shows an organization selector, follow the redirects and select the first organization.

If login fails, ask the user to verify credentials and update the memory file.

Step 4: Navigate & Map

For each top-level navigation route (sidebar items, nav bar links):

1. mcp__playwright__browser_click on the nav item
2. mcp__playwright__browser_wait_for with text set to a key element on the target page
3. mcp__playwright__browser_snapshot to capture the page structure
4. mcp__playwright__browser_take_screenshot with filename set to an absolute path, e.g., <repo>/docs/verification/app-navigator/screenshots/<page-slug>.png
5. Record: URL, page title, key elements visible, available interactions

To map discovered routes back to source components, dispatch a subagent with a concise prompt containing the route list. The subagent should use Grep and Glob to search src/ for route definitions and component files.

Step 5: Write Playbooks

Write three markdown playbooks under docs/verification/app-navigator/playbooks/ based on what was discovered:

playbooks/auth.md -- Document the exact MCP tool call sequence to log in:

• Which URL to navigate to
• Which form fields exist (their ref values from snapshots)
• What to fill in each field
• Which button to click
• What to wait for after submission (specific text)
• How to handle SSO/OAuth redirects or org selector if present

playbooks/navigation.md -- For each mapped page:

• The nav element to click (with ref or text description)
• The URL it navigates to
• What text to wait for to confirm the page loaded
• Key landmark elements on the page

playbooks/interactions.md -- Common interaction patterns discovered:

• How to open modals (which buttons trigger them)
• How to fill forms (common form patterns)
• How to create/delete items
• How to use dropdowns, date pickers, etc.

Step 6: Save Documentation

Write docs/verification/app-navigator/app-map.md with this structure:

# App Map

**Generated:** YYYY-MM-DD
**App URL:** <url>

## Routes

### [Page Name]
- **URL:** /path
- **Purpose:** What this page does
- **Key Elements:** List of important UI elements
- **Interactions:** What you can do on this page
- **Screenshot:** ./screenshots/<page-slug>.png
- **Source Component:** src/path/to/Component.tsx

Write docs/verification/app-navigator/component-map.md:

# Component Map

| Route | URL | Component | File |
|-------|-----|-----------|------|
| Page Name | /path | ComponentName | src/path.tsx |

Cleanup

After all mapping is complete, close the browser with mcp__playwright__browser_close.

Red Flags

• Never hardcode credentials in SKILL.md or playbooks. Always read from memory.
• Never use production credentials. Browser mapping stores reusable local secrets; use local/test-only accounts with minimum permissions.
• Never run services without asking. Check first, ask permission, then start.
• Don't map parametric sub-pages (like /users/:id). Stick to top-level nav routes.
• Don't screenshot behind auth walls you can't pass. If a page requires special permissions, note it and skip.

After Setup: What's Next

When setup completes, print a summary of what was created, then offer:

Ready to verify a feature branch? Run /trust-but-verify to check that your UI implementation matches the plan. It uses the app map and playbooks you just created to:

1. Read your ExecPlan + git diff + PR description
2. Build a verification checklist of what to test
3. Login and navigate the app with Playwright
4. Test happy paths, edge cases, error states, and responsive layouts
5. Produce a report at docs/verification/ with findings and screenshots

You can run it anytime on any feature branch. Type /trust-but-verify to start.

If the user says yes, invoke the trust-but-verify skill.

Integration

• Used by: trust-but-verify and generate-tests (read docs/verification/app-navigator/)
• Credentials shared with: Any skill that reads ~/.codex/memories/<project-slug>/reference_local_auth.md