# How to Work with Claude Code and Antigravity

A plain-English guide for day-to-day use.

---

## The basic idea

You have two AI tools open at once. Claude Code runs in the terminal (inside
Antigravity or standalone). Antigravity is the IDE with a built-in browser and
its own AI chat panel. They each have strengths, and the setup is designed so
they don't step on each other.

Think of it like having two specialists in the room:
- **Claude Code** is the engineer — writes code, manages tokens, runs quality
  checks, handles git, keeps the project memory files up to date.
- **Antigravity** is the visual reviewer — opens Storybook in a real browser,
  takes screenshots, checks how things look at different screen sizes, spots
  spacing and alignment issues.

They share the same project files and the same set of rules (`AGENTS.md`), so
they're always on the same page about conventions.

---

## When to use Claude Code

Use the terminal (Claude Code) when you need something **built, fixed, or analysed**.

**Building things:**
- "Build me a new Button atom" → Claude Code uses `/build-atom`
- "Create tokens for this new component" → Claude Code uses `/create-tokens`
- "Write stories for the VenueCard" → Claude Code uses `/write-stories`

**Fixing things:**
- "The spacing on ProvidersStep is off" → tell Claude Code what to fix
- "This component needs to handle empty states" → Claude Code edits the code
- "Update the copy on the intro page" → Claude Code modifies the JSX

**Quality checks:**
- "Audit this component" → Claude Code runs `/audit`, `/critique`, `/harden`
- "Is this ready to commit?" → Claude Code runs `/preflight`
- "Check consistency across all atoms" → Claude Code runs `/normalize atoms`

**Project management:**
- "What did we do last session?" → Claude Code reads the memory files
- "Log this design decision" → Claude Code updates decisions-log.md
- "Commit and push" → Claude Code handles git

**Rule of thumb:** if it involves writing or changing code, tokens, or memory
files — use Claude Code.

---

## When to use Antigravity

Use the Antigravity chat panel when you need something **looked at visually**.

**Visual QA:**
- "How does the HomePage look on mobile?" → type `/fa-visual-qa HomePage` in
  Antigravity. It opens the story, checks at 375px, 768px, and 1280px, takes
  screenshots, and reports issues.

**Page review (your most common task right now):**
- "Review the CoffinsStep" → type `/fa-page-review CoffinsStep`. It reads the
  source, opens the story, runs through the review checklist (spacing, typography,
  colour, responsive, copy, interactions, edge cases), and reports findings with
  severity ratings.

**Quick checks:**
- "Does this look right?" → open Storybook in Antigravity's browser panel and
  eyeball it yourself. The built-in browser is faster than using Playwright
  screenshots through Claude Code.

**Pre-commit (either tool works):**
- `/fa-preflight` in Antigravity runs the same checks as `/preflight` in Claude
  Code. Use whichever you have open.

**Rule of thumb:** if it involves looking at something in a browser and judging
whether it looks right — use Antigravity.

---

## The typical flow for your current work (tweaking pages)

Most of your work right now is reviewing and polishing existing pages. Here's the
natural rhythm:

### 1. Start your session

In Claude Code: I automatically read the memory files and report what's pending.
Or in Antigravity: type `/fa-session-start` for the same status report.

### 2. Pick a page to work on

You say something like "let's look at the ProvidersStep."

### 3. Assess (Antigravity)

In the Antigravity chat: `/fa-page-review ProvidersStep`

It opens the page in Storybook, checks it at three screen sizes, and gives you a
list of issues — spacing inconsistencies, typography problems, copy that could be
warmer, responsive breakpoint issues.

### 4. Fix (Claude Code)

You bring the findings to me: "Fix the spacing between the filter chips and the
provider list, and tighten up the heading hierarchy."

I make the targeted changes in the code.

### 5. Verify (Antigravity)

Back in Antigravity: `/fa-visual-qa ProvidersStep`

It screenshots the page at all three breakpoints again so you can compare
before and after.

### 6. Commit (Claude Code)

Once you're happy: "commit and push." I handle git.

That's the **sandwich**: Antigravity sees the problem → Claude Code fixes it →
Antigravity confirms the fix.

---

## The flow for building new components

When you need something new built (a new atom, molecule, organism, or page):

1. **Tell Claude Code what you need.** I'll check the component registry, verify
   dependencies, and build it following the lifecycle.
2. **I run internal QA automatically** (`/audit`, `/critique`, `/harden`) before
   showing it to you.
3. **Visual sign-off in Antigravity.** Use `/fa-visual-qa ComponentName` to check
   it at all breakpoints.
4. **You give feedback.** I fix, Antigravity re-verifies. One or two rounds.
5. **Preflight and commit.** Either tool can run preflight. I handle the commit.

---

## What about the workflows?

You have six workflows available in Antigravity's chat. Type `/` followed by the
name:

| Workflow | What it does | When to use it |
|----------|-------------|----------------|
| `/fa-session-start` | Reads memory files, reports project status | Start of a session |
| `/fa-page-review` | Full review of an existing page | When tweaking/polishing pages |
| `/fa-visual-qa` | Visual check at 3 breakpoints | After any visual change |
| `/fa-preflight` | Runs all quality checks (auto-approves) | Before committing |
| `/fa-token-sync` | Rebuilds token outputs (auto-approves) | After changing token JSON |
| `/fa-build-component` | Scaffolds a new component | When building something new |

The ones marked "auto-approves" run without asking — they're safe, read-only or
deterministic operations.

---

## What not to worry about

**You don't need to keep the tools in sync.** They both read `AGENTS.md` for
shared rules. Claude Code reads `CLAUDE.md` for its extra instructions.
Antigravity reads `GEMINI.md` for its extra instructions. There's no overlap
between those two files, so nothing drifts.

**You don't need to tell both tools the same thing.** If you make a design
decision, tell Claude Code — I'll log it in `decisions-log.md`, and Antigravity
can read it from there next time.

**You don't need to worry about file conflicts.** Claude Code writes code and
memory files. Antigravity only reads those files and writes to its own workflow
directory. They don't touch each other's files.

---

## When the backend comes

When you start the Payload CMS work, the same structure holds:

- The **backend agent** (whether it runs in Antigravity or a separate Claude Code
  session) will own `src/payload/` and `src/api/`. It reads the flow-definition
  YAML files to know what API endpoints and data shapes to build.
- **Claude Code** continues owning frontend components, tokens, and theme.
- **Antigravity** continues owning visual QA.
- The **flow-definition.yaml** is the contract between frontend and backend — it
  defines the step IDs, field names, branching logic, and visibility rules that
  both sides reference.

We'll add a backend section to `AGENTS.md` when that starts. For now, the
boundaries are already defined so the transition will be smooth.

---

## Quick reference card

| I want to... | Use |
|--------------|-----|
| Build a component | Claude Code |
| Fix spacing/copy/alignment | Claude Code |
| Check how something looks | Antigravity (`/fa-visual-qa`) |
| Review a whole page | Antigravity (`/fa-page-review`) |
| Run quality checks | Either (`/preflight` or `/fa-preflight`) |
| Rebuild tokens | Either (`/sync-tokens` or `/fa-token-sync`) |
| Commit and push | Claude Code |
| Log a design decision | Claude Code |
| Check project status | Either (`/status` or `/fa-session-start`) |
| Extract from Figma | Claude Code (has Figma MCP) |
