Skip to content

Commit dde4c9f

Browse files
Oba-OneOba-One
authored
Feat/karma-gap-integration (#198)
- Added new dry run deployment scripts for Arbitrum and Celo networks to improve deployment flexibility. - Updated existing deployment and upgrade scripts for consistency across networks. - Enhanced Envio integration by simplifying the update process and removing unnecessary parameters. - Introduced IPFS uploader script for better handling of media uploads. - Updated contract deployment configurations and schemas to reflect recent changes in the contract structure.
2 parents 04a77b2 + 7d6aa3f commit dde4c9f

File tree

376 files changed

+35897
-13697
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

376 files changed

+35897
-13697
lines changed

‎.cursor/AGENT_SYSTEM_GUIDE.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# Green Goods Agent System Guide
2+
3+
This document provides an overview of the complete agent documentation system for Green Goods.
4+
5+
## Agent Documentation Architecture
6+
7+
```
8+
green-goods/
9+
├── .cursor/
10+
│ ├── mcp.json # MCP server configuration
11+
│ └── rules/ # Root-level MDC rules
12+
│ ├── monorepo.mdc # Always applied
13+
│ ├── deployment.mdc # Auto-attached to contracts/**
14+
│ ├── environment.mdc # Auto-attached to .env*, config.*
15+
│ └── quality.mdc # Always applied
16+
├── AGENTS.md # Root agent guide (high-level)
17+
└── packages/
18+
├── client/
19+
│ ├── AGENTS.md # Client architecture overview
20+
│ └── .cursor/rules/
21+
│ ├── offline-architecture.mdc # Job queue, sync, storage
22+
│ ├── state-management.mdc # TanStack Query, Zustand, RHF
23+
│ ├── component-patterns.mdc # Cards, forms, Radix UI
24+
│ ├── hooks-conventions.mdc # Hook naming, query keys
25+
│ ├── authentication.mdc # Passkey, Pimlico, guards
26+
│ └── testing.mdc # Vitest, Playwright MCP
27+
├── admin/
28+
│ ├── AGENTS.md # Admin architecture overview
29+
│ └── .cursor/rules/
30+
│ ├── access-control.mdc # Role-based access
31+
│ ├── state-workflows.mdc # Zustand + XState
32+
│ ├── graphql-integration.mdc # Urql subscriptions
33+
│ ├── component-workflows.mdc # Modals, forms
34+
│ └── testing.mdc # Integration tests
35+
├── indexer/
36+
│ ├── AGENTS.md # Indexer overview
37+
│ └── .cursor/rules/
38+
│ ├── envio-conventions.mdc # Entity patterns
39+
│ └── development.mdc # Workflow, Docker
40+
└── contracts/
41+
├── .cursorrules # Legacy (to be migrated)
42+
└── .cursor/rules/
43+
├── production-readiness.mdc # Manual invocation
44+
├── schema-management.mdc # Immutable schemas
45+
├── deployment-patterns.mdc # deploy.js usage
46+
├── uups-upgrades.mdc # Storage gaps
47+
├── testing-conventions.mdc # Foundry tests
48+
└── gas-optimization.mdc # Gas patterns
49+
```
50+
51+
## Rule Activation Patterns
52+
53+
### Always Applied Rules
54+
55+
These rules are always in context:
56+
- `/.cursor/rules/monorepo.mdc`
57+
- `/.cursor/rules/quality.mdc`
58+
- `/packages/indexer/.cursor/rules/development.mdc`
59+
60+
### Auto-Attached Rules
61+
62+
Rules auto-attach when working with matching files:
63+
64+
**Root-level:**
65+
- `deployment.mdc` → `packages/contracts/**`
66+
- `environment.mdc` → `**/.env*`, `**/config.*`
67+
68+
**Client:**
69+
- `offline-architecture.mdc` → `modules/job-queue/**`, `modules/work/**`
70+
- `state-management.mdc` → `providers/**`, `hooks/**`
71+
- `component-patterns.mdc` → `components/**`, `views/**`
72+
- `hooks-conventions.mdc` → `hooks/**`
73+
- `authentication.mdc` → `providers/auth.tsx`, `hooks/auth/**`
74+
- `testing.mdc` → `__tests__/**`, `**/*.test.*`
75+
76+
**Admin:**
77+
- `access-control.mdc` → `hooks/useRole.ts`, `components/Require*.tsx`
78+
- `state-workflows.mdc` → `stores/**`, `workflows/**`
79+
- `graphql-integration.mdc` → `**/*.graphql`, urql imports
80+
- `component-workflows.mdc` → `components/Garden/**`
81+
- `testing.mdc` → `__tests__/**`
82+
83+
**Indexer:**
84+
- `envio-conventions.mdc` → `schema.graphql`, `src/EventHandlers.ts`, `config.yaml`
85+
86+
**Contracts:**
87+
- `schema-management.mdc` → `config/schemas.json`, `script/*Schema*.sol`
88+
- `deployment-patterns.mdc` → `script/deploy.js`, `script/upgrade.js`
89+
- `uups-upgrades.mdc` → `src/**/*Upgradeable.sol`, `test/*Upgrade*.sol`
90+
- `testing-conventions.mdc` → `test/**`
91+
- `gas-optimization.mdc` → `src/**/*.sol`
92+
93+
### Manual Invocation
94+
95+
Invoke these with `@rulename`:
96+
97+
```bash
98+
# Invoke production readiness
99+
@production-readiness
100+
101+
# Check if contracts ready for mainnet
102+
@production-readiness: Assess readiness for Celo mainnet deployment
103+
```
104+
105+
## MCP Server Configuration
106+
107+
Project-level MCP servers configured in `.cursor/mcp.json`:
108+
109+
### Available MCP Tools
110+
111+
**Filesystem:**
112+
- Large file operations
113+
- Cross-package searches
114+
- Bulk directory analysis
115+
116+
**GitHub:**
117+
- Issue tracking
118+
- PR management
119+
- Repo queries
120+
121+
**Playwright:**
122+
- E2E test execution
123+
- Visual regression testing
124+
- Accessibility audits
125+
126+
**Vercel:**
127+
- Deployment management
128+
- Preview URLs
129+
- Build status
130+
131+
**Figma:**
132+
- UI code generation from designs
133+
- Design screenshots for documentation
134+
- Design token extraction
135+
- Component metadata access
136+
137+
### MCP Usage Guidelines
138+
139+
**Use MCP for:**
140+
```bash
141+
@github: Create issue "Add garden search" with label feature, client
142+
@playwright: Run E2E test for garden creation flow
143+
@filesystem: Find all files importing from contracts/deployments
144+
@figma: Generate component code from design [fileKey] [nodeId]
145+
```
146+
147+
**Use native tools for:**
148+
- Feature development
149+
- Component creation
150+
- Business logic implementation
151+
152+
## Critical Cross-Package Rules
153+
154+
These rules are enforced across ALL packages:
155+
156+
### 1. Root .env Only
157+
158+
**✅ DO:** Use `/Users/afo/Code/greenpill/green-goods/.env`
159+
**❌ DON'T:** Create package-specific `.env` files
160+
161+
### 2. Chain from Environment
162+
163+
**✅ DO:** Use `VITE_CHAIN_ID` via `getDefaultChain()`
164+
**❌ DON'T:** Read from wallet `chainId`
165+
166+
### 3. Deploy via deploy.js
167+
168+
**✅ DO:** `pnpm deploy:testnet` or `node script/deploy.js`
169+
**❌ DON'T:** `forge script script/Deploy.s.sol`
170+
171+
### 4. Never Modify schemas.json
172+
173+
**✅ DO:** Create `schemas.test.json` for testing
174+
**❌ DON'T:** Edit `config/schemas.json`
175+
176+
### 5. Centralized Query Keys
177+
178+
**✅ DO:** Use `queryKeys` from `hooks/query-keys.ts`
179+
**❌ DON'T:** Construct ad-hoc query keys
180+
181+
## Package-Specific Priorities
182+
183+
### Client (Highest Complexity)
184+
185+
**Focus areas:**
186+
- Offline-first architecture (job queue, sync, storage)
187+
- State management (TanStack Query, Zustand, RHF)
188+
- Component patterns (cards, forms, modals)
189+
- Authentication (passkey, smart accounts)
190+
191+
**Rule count:** 6 MDC files + AGENTS.md
192+
193+
### Admin (Medium Complexity)
194+
195+
**Focus areas:**
196+
- Role-based access control
197+
- XState workflows
198+
- GraphQL subscriptions
199+
- Modal workflows
200+
201+
**Rule count:** 5 MDC files + AGENTS.md
202+
203+
### Indexer (Low Complexity)
204+
205+
**Focus areas:**
206+
- Envio conventions
207+
- Event handlers
208+
- Multi-chain entities
209+
210+
**Rule count:** 2 MDC files + AGENTS.md
211+
212+
### Contracts (Medium Complexity)
213+
214+
**Focus areas:**
215+
- Production readiness
216+
- Schema immutability
217+
- Deployment safety
218+
- UUPS upgrades
219+
220+
**Rule count:** 6 MDC files
221+
222+
## Quality Baseline
223+
224+
All packages follow these standards:
225+
226+
- **TypeScript:** Strict mode, no `any` without justification
227+
- **Formatting:** Biome (35x faster than Prettier)
228+
- **Linting:** 0xlint (30ms on entire codebase)
229+
- **Commits:** Conventional commits (`feat:`, `fix:`, `docs:`)
230+
- **Testing:** 70%+ overall, 80%+ for critical paths
231+
- **Documentation:** Update README and rules when establishing patterns
232+
233+
## Tool Preferences
234+
235+
**Formatting & Linting:**
236+
- Biome over Prettier (performance)
237+
- 0xlint over ESLint (speed)
238+
- Solhint for Solidity
239+
240+
**Package Management:**
241+
- pnpm over npm/yarn (workspace support)
242+
243+
**Blockchain:**
244+
- Viem over ethers (TypeScript-first, smaller bundle)
245+
- Foundry over Hardhat (speed, testing)
246+
247+
**State:**
248+
- TanStack Query for server state
249+
- Zustand for UI state
250+
- React Hook Form for forms
251+
252+
## Getting Started as an Agent
253+
254+
1. Read root `AGENTS.md` for project overview
255+
2. Review root `.cursor/rules/` for cross-package standards
256+
3. Check package-specific `AGENTS.md` for architecture
257+
4. Review package `.cursor/rules/` for detailed patterns
258+
5. Use MCP tools when appropriate
259+
6. Follow conventional commits
260+
7. Update rules when establishing new patterns
261+
262+
## Agent Capabilities
263+
264+
With this documentation system, agents can:
265+
266+
- ✅ Build features following existing patterns
267+
- ✅ Understand offline-first architecture
268+
- ✅ Navigate role-based access correctly
269+
- ✅ Deploy contracts safely
270+
- ✅ Write consistent tests
271+
- ✅ Use appropriate state management
272+
- ✅ Follow code quality standards
273+
- ✅ Leverage MCP tools effectively
274+
275+
## Maintenance
276+
277+
### Updating Rules
278+
279+
When to update agent documentation:
280+
281+
- **New pattern established:** Add to relevant .mdc file
282+
- **Breaking change:** Update all affected rules
283+
- **New package added:** Create AGENTS.md and .cursor/rules/
284+
- **Major refactor:** Review and update related rules
285+
- **User feedback:** Incorporate into rule improvements
286+
287+
### Rule File Limits
288+
289+
Keep each rule under 500 lines:
290+
- Split large rules into focused files
291+
- Use multiple .mdc files per concern
292+
- Link related rules in "Reference Files" section
293+
294+
## Success Metrics
295+
296+
Agent documentation is successful when:
297+
298+
- New features follow established patterns automatically
299+
- Fewer clarification questions about architecture
300+
- Consistent code structure across contributions
301+
- Faster onboarding for human developers
302+
- Reduced rework from architectural misunderstandings
303+
304+
## Quick Reference
305+
306+
| Package | AGENTS.md | Rule Count | Focus |
307+
|---------|-----------|------------|-------|
308+
| Root | ✅ | 4 | Cross-package standards |
309+
| Client | ✅ | 6 | Offline-first, state, auth |
310+
| Admin | ✅ | 5 | Access control, workflows |
311+
| Indexer | ✅ | 2 | Envio conventions |
312+
| Contracts | ➖ | 6 | Deployment, safety |
313+
314+
**Total:** 5 AGENTS.md files, 23 MDC rule files, 1 MCP config
315+
316+
---
317+
318+
**Last Updated:** 2025-10-10
319+
**Maintained by:** Green Goods core team
320+
**For questions:** [email protected]
321+

‎.cursor/mcp.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"mcpServers": {
3+
"filesystem": {
4+
"command": "npx",
5+
"args": ["-y", "@modelcontextprotocol/server-filesystem"],
6+
"env": {
7+
"ALLOWED_DIRECTORIES": ["${workspaceFolder}"]
8+
}
9+
},
10+
"github": {
11+
"command": "docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server",
12+
"env": {
13+
"GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
14+
}
15+
},
16+
"playwright": {
17+
"command": "npx @playwright/mcp@latest"
18+
},
19+
"vercel": {
20+
"url": "https://mcp.vercel.com",
21+
"headers": {}
22+
},
23+
"Figma": {
24+
"url": "https://mcp.figma.com/mcp",
25+
"headers": {}
26+
}
27+
}
28+
}

0 commit comments

Comments
 (0)