Add cross-tool workflow: AGENTS.md, Antigravity workflows, documentation
- Create AGENTS.md (90 lines) as shared foundation for Claude Code + Antigravity - Slim CLAUDE.md from 113 to 45 lines (Claude-specific only, references AGENTS.md) - Slim GEMINI.md from 58 to 26 lines (Antigravity-specific only, references AGENTS.md) - Add 6 Antigravity workflows in .agent/workflows/ (session-start, preflight, token-sync, visual-qa, build-component, page-review) - Add docs/reference/cross-tool-workflow.md with task routing, quality gates, file ownership, error mitigation - Zero content overlap between CLAUDE.md and GEMINI.md (was ~80%) - File ownership boundaries defined for current phase and future backend work Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
184
docs/reference/cross-tool-workflow.md
Normal file
184
docs/reference/cross-tool-workflow.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user