Parsons/docs/reference/cross-tool-workflow.md

# Cross-Tool Workflow: Claude Code + Google Antigravity

## How the tools work together

**Claude Code** (terminal) — code generation, refactoring, quality analysis, memory
management. Has 18 custom skills, 3 agents, MCP access (Figma, Storybook).
Strengths: deep code reasoning, multi-file refactors, token architecture, grief-sensitive
copy review, git operations.

**Antigravity** (IDE) — visual verification, browser interaction, page-level review.
Has 6 custom workflows in `.agent/workflows/`. Strengths: built-in browser for
Storybook verification, screenshot comparison across breakpoints, multi-agent
parallelism via Manager View.

**Both read:** `AGENTS.md` (shared rules), `docs/memory/` (shared state), all source files.

---

## Task routing

### Always Claude Code

- Creating new components (`/build-atom`, `/build-molecule`, `/build-organism`)
- Token creation and architecture (`/create-tokens`, `/sync-tokens`)
- Code quality analysis (`/audit`, `/critique`, `/harden`, `/normalize`)
- Writing tests and stories (`/write-tests`, `/write-stories`)
- Visual polish skills (`/polish`, `/typeset`, `/adapt`, `/quieter`, `/clarify`)
- Memory file updates (decisions-log, component-registry, session-log)
- Git operations (commit, push)
- Multi-file refactors
- Figma MCP interactions (design extraction)

### Always Antigravity

- Browser-based visual QA (`/fa-visual-qa` workflow)
- Screenshot comparison across breakpoints (375/768/1280px)
- Page-level visual review (`/fa-page-review` workflow)
- Storybook visual regression checks

### Either tool (user's choice)

- Preflight checks (Claude: `/preflight` | Antigravity: `/fa-preflight`)
- Token sync rebuild (Claude: `/sync-tokens` | Antigravity: `/fa-token-sync`)
- Session status report (Claude: `/status` | Antigravity: `/fa-session-start`)
- Reading and analysing existing code
- Copy and content review

---

## The sandwich workflow

Every significant change should follow a three-step pattern that uses both tools.

### For new components or features

1. **Plan (Claude Code):** Read memory files, check registry, design the approach
2. **Build (Claude Code):** Implement — component, tokens, stories, tests
3. **Verify (Antigravity):** Open in Storybook, screenshot at 3 breakpoints, report issues

### For page tweaking (current phase)

1. **Assess (Antigravity):** Run `/fa-page-review`, screenshot current state, identify issues
2. **Fix (Claude Code):** Make targeted fixes to spacing, copy, alignment, responsive
3. **Verify (Antigravity):** Re-run `/fa-visual-qa`, confirm fixes, screenshot final state

The sandwich ensures no change goes live without both code quality AND visual verification.

---

## Quality gates

The 10-stage component lifecycle (`docs/reference/component-lifecycle.md`) applies
regardless of which tool does the work.

| Stage | Primary tool | Gate |
|-------|-------------|------|
| 1. BUILD | Claude Code | — |
| 2. STORIES | Claude Code | — |
| 3. INTERNAL QA | Claude Code (`/audit`, `/critique`, `/harden`) | P0 = blocking |
| 4. FIX | Claude Code | Until P0/P1 = 0 |
| 5. POLISH | Claude Code (`/polish`, `/typeset`, `/adapt`) | — |
| 6. PRESENT | Antigravity (`/fa-visual-qa`) | Visual sign-off |
| 7. ITERATE | Both (Claude fixes, Antigravity verifies) | User approves |
| 8. NORMALIZE | Claude Code (`/normalize`) | — |
| 9. PREFLIGHT | Either (`/preflight` or `/fa-preflight`) | Critical = blocking |
| 10. COMMIT | Claude Code | — |

**Enforcement:** No component moves past PRESENT without Antigravity visual sign-off.
No component moves to COMMIT without preflight passing.

---

## File ownership boundaries

### Current phase (frontend only)

| Scope | Claude Code | Antigravity |
|-------|------------|-------------|
| `src/components/**/*.tsx` | write | read only |
| `src/components/**/*.stories.tsx` | write | read only |
| `src/components/**/index.ts` | write | read only |
| `tokens/**/*.json` | write | read only |
| `src/theme/**` | write | read only |
| `docs/memory/**` | write | read only |
| `docs/conventions/**`, `docs/reference/**` | write | read only |
| `.agent/workflows/*.md` | read only | write (own workflows) |
| `AGENTS.md` | write (coordinate first) | write (coordinate first) |
| `CLAUDE.md` | write | never |
| `GEMINI.md` | never | write |

### When backend starts (Payload CMS)

- **Backend agent writes:** `src/payload/**`, `src/api/**`, database schemas, server config
- **Frontend agents never touch:** anything in `src/payload/` or `src/api/`
- **Backend agent never touches:** `src/components/**`, `tokens/**`, `src/theme/**`
- **Shared contract:** `documentation/flow-definition.yaml` is the interface between
  frontend and backend. Field names, step IDs, and visibility rules in that file
  dictate both component props and API data shapes. Changes require both sides
  to acknowledge.

### Conflict resolution

- If two agents need to edit the same file: **STOP**, flag it in `docs/memory/session-log.md`,
  let the user decide who proceeds.
- If agents produce conflicting output: `docs/memory/decisions-log.md` is the tiebreaker.
  Whoever's approach matches a logged decision wins.

---

## Error mitigation

### Pre-flight checklist (before any agent work)

- [ ] Read `docs/memory/session-log.md` — is another agent mid-task?
- [ ] Read `docs/memory/component-registry.md` — is the target component in-progress by someone else?
- [ ] Confirm file ownership — am I allowed to write these files?
- [ ] Storybook running? (`localhost:6006`)
- [ ] Git clean? No uncommitted changes from a previous session

### Memory file update protocol

1. Read the file before writing (always)
2. Append, do not overwrite existing entries
3. Use the established format (each file documents its own format)
4. Include decision IDs (D001, D002...) for traceability
5. Log agent name and date in every session-log entry

### Verification after every change

- TypeScript compiles: `npx tsc --noEmit`
- Storybook renders the specific story (not just builds)
- Visual check: at least desktop breakpoint for small changes, all three for layout changes
- Token sync: if tokens changed, run `npm run build:tokens` and verify output

### When agents produce conflicting output

1. Check `docs/memory/decisions-log.md` for a prior decision
2. If a decision exists: follow it, flag the conflict in session-log
3. If no decision exists: **STOP**, do not proceed, ask the user
4. Never silently override another agent's work

### Common failure modes and recovery

| Failure | Symptom | Recovery |
|---------|---------|----------|
| Stale tokens | Generated files older than source JSON | Run `npm run build:tokens` |
| Hardcoded values | Hex colours in `.tsx` files | Run preflight scan, replace with theme refs |
| Memory drift | Session log not updated | Always update session-log as last step |
| Story rendering failure | Component changed but stories broken | Run `/write-stories` to regenerate |
| File ownership violation | Two agents edited same file | `git diff` to see both changes, manually merge |

---

## Adapting for backend work

When Payload CMS implementation begins:

1. Add a `## Backend (Payload CMS)` section to `AGENTS.md` with Payload-specific rules
2. Add backend file ownership to the boundaries above
3. `documentation/flow-definition.yaml` becomes the API contract — field names, step IDs,
   and visibility rules dictate both frontend props and backend data shapes
4. Backend agent reads `documentation/flow-definition.yaml` and `documentation/steps/*.yaml`
   as its primary specifications
5. Frontend agents continue unchanged — the boundary is the data interface, not the UI