End-to-end project setup for Claude Code and Claude app.

# Project Instructions

## Project goal

This repo is an end-to-end product project. Claude should help with product planning, design, implementation, SEO, QA, launch, and iteration.

## Workflow owner

Default engineering workflow:
- Use Superpowers for planning, implementation, testing, and review.
- Use Caveman for concise communication during coding.
- Do not use Caveman Ultra for design, UX, copywriting, product strategy, legal review, or marketing strategy.
- Use Cavecrew only for focused investigation, review, or isolated edits.

## Skill routing

### Product and planning
Use product-discovery or project docs when defining:
- target user
- problem
- MVP
- feature scope
- launch plan

### Design
Use frontend-design and selected design skills when working on:
- landing pages
- dashboards
- UI components
- visual hierarchy
- spacing, typography, color, layout
- mobile responsiveness

Before coding major UI, produce a compact design plan:
- audience
- page job
- visual direction
- typography
- palette
- layout
- key components
- anti-generic critique

### Development
Use Superpowers as the main workflow for:
- feature implementation
- refactors
- tests
- architecture decisions
- debugging

### Image generation
Claude Code has no native image tool. Use gpt-image-bridge, which shells out to the codex CLI (OpenAI gpt-image-2, ChatGPT subscription, no API key).

Call it directly:
`~/.claude/skills/gpt-image-bridge/bin/gpt-image-2 "<dense art-directed prompt>" <absolute-output-path.png> [--size WxH]`

Rules:
- Output path must be absolute. Throwaways in /tmp, kept assets in design/.
- Calls take 4-6 minutes. Set the Bash timeout to 600000 ms or run it in the background.
- Read the PNG back into context after it is generated, before coding against it.
- Omit --size unless a specific aspect ratio is required.
- Do not use it for 1px placeholders, solid colors, or charts. Write those in code.

For art direction, drive it through brandkit (identity), imagegen-frontend-web (one image per landing section), or imagegen-frontend-mobile (app screens).

### Browser QA
Use Vercel agent-browser whenever UI behavior or visual correctness matters.
Verify changes in a real browser before claiming completion.

Setup:
`npm install -g agent-browser && agent-browser install`
`npx skills add vercel-labs/agent-browser`

It is also the right tool for accessibility audits (axe-core), Web Vitals, React introspection, and isolated parallel sessions.

Playwright MCP is the fallback. If it fails to start with "Chromium distribution 'chrome' is not found", install real Google Chrome and fully restart Claude Code (an MCP reconnect is not enough) — or just stay on agent-browser.

### SEO
Use claude-seo for:
- technical SEO
- metadata
- schema
- content quality
- local SEO
- international SEO
- launch audits

Use marketingskills for:
- conversion
- copywriting
- landing page persuasion
- funnel improvements
- analytics/event ideas

### Legal and compliance
Do not give final legal conclusions.
Use legal-risk-review only to identify issues to verify:
- privacy
- cookies
- terms
- refunds
- user data
- regulated claims
- AI-generated content
- open-source licenses

### Social and launch content
Use social/content skills for:
- launch posts
- LinkedIn content
- newsletter drafts
- content repurposing
- voice consistency

## Conflict rule

User request > project CLAUDE.md > active slash command > skill defaults.

Only one high-level workflow should own the task at a time.
If two skills overlap, choose based on the routing above.

## Output expectations

For every substantial task:
- state what changed
- mention files edited
- mention tests or browser checks run
- mention remaining risks or TODOs

# Ongoing Project Retrofit Instructions

## First task before changing code

Before implementing new features, audit the existing project.

Produce:
- docs/project/current-state.md
- docs/project/architecture.md
- docs/project/risk-list.md
- docs/project/setup-notes.md

## Audit checklist

Inspect:
- framework and package manager
- app routes/pages
- data model and persistence
- auth and permissions
- environment variables, without reading secrets directly
- deployment setup
- tests and scripts
- styling system
- SEO metadata
- analytics/tracking
- error handling
- accessibility and responsive behavior

## Rules

- Do not rewrite the architecture unless there is a clear reason.
- Prefer small, reversible changes.
- Preserve existing conventions unless they are actively harmful.
- Before editing, explain the smallest safe plan.
- After editing, run the relevant checks.
- If UI is changed, verify in the browser with agent-browser (Playwright MCP as fallback).

# Design Phase Instructions

## Goal

Create interfaces that look intentional, modern, and production-ready. Avoid generic AI-generated UI.

## Use these skills

- frontend-design
- ui-design
- design-systems
- interaction-design
- visual-critique

For visual references and comps:
- imagegen-frontend-web for landing pages (one horizontal image per section, never several sections in one image)
- imagegen-frontend-mobile for app screens in phone mockups
- brandkit for logo systems and brand boards
- gpt-image-bridge underneath all of them

Store generated references in design/refs/ and Read them back before writing components.

Do not use Caveman Ultra during this phase.

## Design plan required before coding

For each major page or flow, produce:
- target audience
- page job
- emotional tone
- layout structure
- typography direction
- color palette direction
- spacing rhythm
- primary components
- mobile behavior
- one signature visual detail
- anti-generic critique

## Implementation expectations

- Use the existing design system if present.
- If no design system exists, create minimal tokens for spacing, radius, type scale, and colors.
- Make mobile excellent, not just acceptable.
- Use real copy, not lorem ipsum, when possible.
- Verify important UI states in the browser.

## Output

Create or update:
- docs/design/design-direction.md
- docs/design/component-system.md
- screenshots or browser QA notes when useful

# Launch, SEO, and Conversion Instructions

## Goal

Prepare the product for launch with clear messaging, strong technical SEO, and conversion-focused pages.

## Skill routing

Use claude-seo for:
- technical SEO
- metadata
- schema
- sitemap/robots checks
- canonical URLs
- structured data
- content quality
- local/international SEO when relevant

Use marketingskills for:
- positioning
- headlines
- offer clarity
- objections
- CTAs
- pricing page logic
- funnel improvements
- analytics/event ideas

Use agent-browser (or Playwright MCP as fallback) for:
- checking the live or local page
- screenshots
- mobile viewport review
- form and CTA verification
- console errors and failed network requests

## Required outputs

Create or update:
- docs/marketing/seo-audit.md
- docs/marketing/conversion-review.md
- docs/marketing/launch-checklist.md

## Launch checklist

Verify:
- page titles and meta descriptions
- Open Graph and social previews
- schema markup when useful
- sitemap and robots policy
- canonical URLs
- favicon and manifest
- analytics/events
- form success/error states
- mobile layout
- page speed basics
- privacy/cookie links when needed

# Image Generation and Browser Tooling

## Image generation

Claude Code has no built-in image tool. Images come from gpt-image-bridge, which shells out to the codex CLI and calls OpenAI gpt-image-2. Auth is the user's ChatGPT subscription, not an API key, so calls burn ChatGPT message quota instead of billed credits.

### Prerequisites

- codex CLI installed: `npm install -g @openai/codex` (or `brew install codex` on macOS)
- `codex login status` reports "Logged in using ChatGPT"
- image_generation feature on: `codex features list | grep image_generation`
- Works on macOS, Linux, WSL, and Windows via Git Bash

### Direct call

```
~/.claude/skills/gpt-image-bridge/bin/gpt-image-2 "<prompt>" <absolute-output-path.png> [--size WxH]
```

Rules:
- Prompt must be dense and art-directed: composition, lighting, camera/lens, mood, style reference. Terse prompts produce generic output.
- Output path must be absolute. /tmp for throwaways, design/refs/ for kept assets.
- Runtime is 4-6 minutes. Use the maximum Bash timeout (600000 ms) or run it in the background and poll.
- Read the PNG back into context before coding against it.
- Skip --size unless a specific aspect ratio is required.
- Never use it for 1px placeholders, solid-color images, or charts. Write those in code.

### Art-direction skills on top

- brandkit: logo systems, brand boards, identity decks
- imagegen-frontend-web: landing page comps, ONE horizontal image per section
- imagegen-frontend-mobile: app screens inside phone mockups
- design-taste-frontend: pulls images in when a build brief needs them

## Browser automation

The main browser tool is Vercel agent-browser: a native Rust CDP CLI with its own MCP server. No Node runtime needed, ref-based element selection (@e1, @e2) built for agents, embedded axe-core accessibility audits, Web Vitals, React introspection, multi-session isolation, and cloud browser providers (Browserbase, Browser Use, Kernel, AgentCore).

### Install

```
npm install -g agent-browser
agent-browser install
```

As a Claude Code skill (auto-fetches instructions matching the installed CLI version):
```
npx skills add vercel-labs/agent-browser
```

As an MCP server:
```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "agent-browser",
      "args": ["mcp", "--tools", "all"]
    }
  }
}
```

Tools: agent_browser_open, agent_browser_snapshot, agent_browser_click, agent_browser_fill, agent_browser_screenshot, agent_browser_eval, agent_browser_close.

### Standard QA loop

1. Start the dev server in the background.
2. agent_browser_open on the local URL.
3. agent_browser_snapshot for structure, agent_browser_screenshot for visuals.
4. Re-check at a mobile viewport width.
5. Run the accessibility audit and Web Vitals when the page is close to done.
6. Fix, reload, re-verify. Do not claim done without a verified pass.

Use `--session <name>` to keep parallel checks isolated from each other.

## Playwright MCP fallback

Only when agent-browser is unavailable, or when the task specifically needs Playwright's console/network tooling: browser_navigate, browser_click, browser_type, browser_fill_form, browser_snapshot, browser_take_screenshot, browser_console_messages, browser_network_requests, browser_evaluate, browser_resize, browser_wait_for, browser_tabs.

Known startup failure:
```
Error: Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome
Run "npx playwright install chrome"
```

The official plugin runs `npx @playwright/mcp@latest` with no args and always wants real Google Chrome. System chromium does not satisfy it. Editing pluginConfigs in settings.json does nothing — that plugin declares no user_config schema.

Fix order:
1. Install real Google Chrome (Debian/Ubuntu: the google-chrome-stable .deb; Arch: AUR google-chrome), confirm `ls /opt/google/chrome/chrome`, then fully restart Claude Code. An MCP reconnect is not enough.
2. Do not sink time into it — go back to agent-browser.

## Rule

Never claim a UI change works without a browser check. Never generate an image without reading it back first.

I am starting an end-to-end product project.

Help me define:
1. target user / ICP
2. painful problem
3. current alternatives
4. sharp positioning
5. offer
6. MVP scope
7. non-goals
8. landing page angle
9. launch channels
10. obvious legal/privacy risks to verify

Output the result as files I can later create in my repo:
- docs/product/idea.md
- docs/product/icp.md
- docs/product/positioning.md
- docs/product/offer.md
- docs/product/mvp-scope.md
- docs/marketing/content-angles.md
- docs/legal/legal-risk-notes.md

We are configuring this project for end-to-end development.

First, read the repo structure and create a compact project map.
Do not make code changes yet.

Then produce:
- docs/project/current-state.md
- docs/project/architecture.md
- docs/project/setup-notes.md
- docs/project/next-steps.md

After that, propose the smallest safe next task.
Use the CLAUDE.md routing rules for skills and workflows.

# Skill Installation Checklist

## Claude Code / terminal agent

Core:
- Superpowers
- Caveman
- Cavecrew

Design:
- Anthropic frontend-design
- Owl ui-design
- Owl design-systems
- Owl interaction-design
- Owl visual-critique

Image generation:
- gpt-image-bridge (requires codex CLI + ChatGPT login)
- brandkit
- imagegen-frontend-web
- imagegen-frontend-mobile

Execution and QA:
- Vercel agent-browser (main browser tool, plus a11y/Web Vitals/React introspection)
- Playwright MCP (fallback driver)
- playwright-chrome-not-found (troubleshooting only)

Marketing and SEO:
- marketingskills
- claude-seo

Optional later:
- claude-ads
- small custom legal-risk-review skill
- GStack in a separate test project only

## Claude app

Strategy and content:
- social-media-skills voice-builder
- social-media-skills post-writer
- social-media-skills profile-optimizer
- marketingskills

Legal/compliance review:
- claude-for-legal only when needed

Design strategy:
- frontend-design or selected design skills if useful

## Do not install by default

- Full Owl suite
- Full claude-for-legal inside every repo
- claude-ads before there is validation or campaign data
- GStack as the default workflow