richie/Parsons
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add cross-tool workflow: AGENTS.md, Antigravity workflows, documentation

Browse Source 
- 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:
Richie
2026-04-06 11:10:32 +10:00
parent 68889af9c2
commit 4af684ec8f
10 changed files with 621 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
CLAUDE.md
View File

@@ -1,113 +1,45 @@
# FA 2.0 Design System
# Claude Code — FA 2.0 Design System
## Project overview
Follow all rules in `AGENTS.md`. This file contains Claude-specific behaviour only.
Rebuilding the Funeral Arranger (funeralarranger.com.au) design system using a
code-first approach. Parsons (H.Parsons Funeral Directors) is the client. FA is
an Australian funeral planning platform — the design language must be warm,
professional, trustworthy, and calm. Users are often in distress.
## Session startup (automatic)
## Tech stack
At the start of every session, automatically:
1. Read `docs/memory/session-log.md`, `decisions-log.md`, `component-registry.md`
2. Check `docs/reference/retroactive-review-plan.md` for pending review tiers
3. If reviews remain, run the next step (~30-60 min) before the user's main request
4. Report findings, then shift to whatever the user wants to work on
- React 18 + TypeScript
- Material UI (MUI) v5
- Storybook 8+ with autodocs
- Style Dictionary for token transformation
- W3C DTCG token format (2025.10 stable spec)
- Chromatic for Storybook hosting (later)
## Architecture
**Source of truth:** Token JSON files in `tokens/` (DTCG format)
**Flow:** Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
### Token tiers
1. **Primitives** (`tokens/primitives/`): Raw values — hex, px, font names, scales
2. **Semantic** (`tokens/semantic/`): Design intent — `color.text.primary`, `color.surface.default`
3. **Component** (`tokens/component/`): Per-component — `button.background.default`
### Component tiers (atomic design)
1. **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
2. **Molecules** (`src/components/molecules/`): SearchBar, PriceCard, ServiceOption, FormField
3. **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation
## Critical rules
1. **Every component MUST consume the MUI theme** — never hardcode colours, spacing, typography, or shadows
2. **Every token MUST have a `$description`** — this is how agents maintain context about design intent
3. **Always read docs/design-system.md** before creating or modifying anything
4. **Always check docs/memory/** before starting work — these files contain decisions and state from previous sessions
5. **Always update docs/memory/** after completing work — log what was done, decisions made, and open questions
6. **Run `npm run build:tokens`** after any token JSON change
7. **Verify in Storybook** before marking any component done
8. **Follow the component lifecycle** — see `docs/reference/component-lifecycle.md` for the full quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
9. **Commit and push after completing each unit of work** — see Git workflow below
## Git workflow
**Remote:** Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git` (credentials stored via git credential helper)
**After completing each unit of work** (a component, a token change, a bug fix, etc.):
1. Stage the changed files (`git add` — prefer naming specific files over `git add -A`)
2. Commit with a clear message describing what was done
3. Push to origin (`git push`)
This is **not optional** — the user relies on the git history for rollback safety. Each commit should represent a coherent, working state (Storybook builds, TypeScript compiles). Do not batch multiple unrelated changes into a single commit.
**Commit message format:**
```
Short summary (imperative mood, <70 chars)
- Bullet points with detail if needed
- Reference decision IDs (D001, D002...) when relevant
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```
**Branch strategy:** All work on `main` for now. Feature branches when the project grows.
This is "morning housekeeping" — the user has approved this and expects it.
## Memory system
This project uses structured markdown files for cross-session memory.
Before starting any work, read:
- `docs/memory/decisions-log.md` — all design decisions with rationale
- `docs/memory/component-registry.md` — status of every component
- `docs/memory/token-registry.md` — all tokens with values and usage notes
- `docs/memory/session-log.md` — recent sessions; older in `docs/memory/archive/`
**Before starting any work, read these files:**
- `docs/memory/decisions-log.md` — All design decisions with rationale
- `docs/memory/component-registry.md` — Status of every component (planned/in-progress/done)
- `docs/memory/token-registry.md` — All tokens with their current values and usage notes
- `docs/memory/session-log.md` — Recent sessions (last 2-3); older sessions in `docs/memory/archive/`
**Session startup — proactive review pass (do this automatically):**
Check `docs/reference/retroactive-review-plan.md` for the current review state. If
there are tiers or components that haven't been reviewed yet, run the next review
step (typically `/normalize {tier}` or `/audit {component}`) at the start of the
session before the user's main request. Keep this to ~30-60 min, then report
findings and shift to whatever the user wants to work on. This is "morning
housekeeping" — the user has approved this and expects it to happen without asking.
**After completing work, update:**
- The relevant memory files with what changed
- `docs/memory/session-log.md` with a summary of what was accomplished and next steps
After completing work, update the relevant memory files and `session-log.md`.
## MCP servers
- **Figma remote MCP** (`figma-remote-mcp`): Read FA 1.0 designs, extract design context
- **Storybook MCP** (`storybook`): Query component library for available components and props
- **Figma remote MCP** — read FA 1.0 designs, extract design context
- **Storybook MCP** — query component library for available components and props
Setup instructions in `docs/reference/mcp-setup.md`.
Setup instructions: `docs/reference/mcp-setup.md`
## File conventions
## Commit co-author
- Component folders: PascalCase (`Button/`, `PriceCard/`)
- Token files: camelCase (`colours.json`, `typography.json`)
- Each component folder contains: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
- CSS custom properties prefix: `--fa-` (e.g., `--fa-color-brand-primary`)
- MUI theme paths: follow MUI conventions (`palette.primary.main`)
Append to every commit message:
```
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```
## Naming conventions for tokens
## Cross-tool workflow
See `docs/conventions/token-conventions.md` for the full specification.
This project uses both Claude Code and Google Antigravity.
See `docs/reference/cross-tool-workflow.md` for task routing and coordination.
Quick reference:
- Primitives: `color.blue.500`, `spacing.4`, `fontSize.base`
- Semantic: `color.text.primary`, `color.surface.default`, `color.interactive.default`
- Component: `button.background.default`, `button.background.hover`
Claude Code owns: component building, token creation, code quality, memory updates, git.
Antigravity owns: visual QA, browser-based verification, page-level review screenshots.