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