Skip to content

Commit 8ad7946

Browse files
sonpiazclaude
sonpiaz
and
claude
committed
docs: trim CLAUDE.md from 264 to 130 lines, add Design System V2 rule
- Added Rule 1: V2 semantic tokens with mapping table (prevents zinc-* regression) - Added Quality Gate: grep check for zinc-* classes - Removed duplicated Quick Reference, verbose code examples, informational suggestions - Condensed all rules to 1-2 lines, linked separate docs for details Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 9093109 commit 8ad7946

File tree

1 file changed

+68
-202
lines changed

1 file changed

+68
-202
lines changed

‎CLAUDE.md‎

Lines changed: 68 additions & 202 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
11
# EVOX Mission Control — Agent Rules
22

3-
Auto-loaded every Claude Code session. Last updated: Feb 5, 2026.
4-
5-
## Constitution
6-
7-
**Read First:** [docs/VISION.md](docs/VISION.md) — The organizational DNA, values, and genius thinking framework.
3+
Auto-loaded every Claude Code session. Last updated: Feb 6, 2026.
84

95
## Project
106

117
| Key | Value |
128
|-----|-------|
13-
| App | EVOX Mission Control — AI agent orchestration dashboard |
14-
| Stack | Next.js 14 App Router + Convex + Tailwind + shadcn/ui |
9+
| Stack | Next.js 14 App Router + Convex + Tailwind v4 + shadcn/ui |
1510
| Deploy | Vercel → evox-ten.vercel.app |
1611
| Repo | github.com/sonpiaz/evox |
12+
| Design System | V2 — [docs/EVOX-DESIGN-SYSTEM.md](docs/EVOX-DESIGN-SYSTEM.md) |
13+
14+
**Read First:** [docs/VISION.md](docs/VISION.md) — Org DNA. [docs/CULTURE.md](docs/CULTURE.md) — How we work.
1715

1816
## Team Territories
1917

@@ -24,240 +22,108 @@ Auto-loaded every Claude Code session. Last updated: Feb 5, 2026.
2422
| Quinn | QA | `*.test.ts`, `e2e/`, code review |
2523
| Max | PM | Linear docs, planning, coordination |
2624

27-
**Rule:** Territories are guidelines, not walls. Cross-territory edits allowed — just report in #dev.
28-
29-
## Agent Instructions
30-
- Sam: [Linear Doc](https://linear.app/affitorai/document/sam-instructions-backend-agent-a0ad2c23626a)
31-
- Leo: [Linear Doc](https://linear.app/affitorai/document/leo-instructions-frontend-agent-c84654462a4d)
32-
- Quinn: [Linear Doc](https://linear.app/affitorai/document/quinn-operating-rules-e12df74361ab)
33-
34-
## Team Culture
35-
**Read:** [docs/CULTURE.md](docs/CULTURE.md) — How we communicate, collaborate, and share learnings.
36-
37-
---
38-
39-
## Playbooks
40-
41-
| Playbook | When | Link |
42-
|----------|------|------|
43-
| Session Start | Every new session | [docs/playbooks/SESSION-START.md](docs/playbooks/SESSION-START.md) |
44-
| Pre-Commit | Before every commit | [docs/playbooks/PRE-COMMIT.md](docs/playbooks/PRE-COMMIT.md) |
45-
| Task Complete | After finishing any ticket | [docs/playbooks/TASK-COMPLETE.md](docs/playbooks/TASK-COMPLETE.md) |
46-
47-
---
48-
49-
## Patterns
50-
51-
| Pattern | Problem | Link |
52-
|---------|---------|------|
53-
| Display IDs | Never show raw Convex `_id` | [docs/patterns/DISPLAY-IDS.md](docs/patterns/DISPLAY-IDS.md) |
54-
| Status Colors | Use exhaustive maps, not ternaries | [docs/patterns/STATUS-COLORS.md](docs/patterns/STATUS-COLORS.md) |
55-
| Attribution | Agent name from caller, not API key | [docs/patterns/ATTRIBUTION.md](docs/patterns/ATTRIBUTION.md) |
56-
| Convex Actions | When to use actions vs mutations | [docs/patterns/CONVEX-ACTIONS.md](docs/patterns/CONVEX-ACTIONS.md) |
57-
58-
---
59-
60-
## Quick Reference
61-
62-
### Session Start
63-
```
64-
1. Read CLAUDE.md → Rules
65-
2. Read DISPATCH.md → Task queue
66-
3. Read SOUL.md → Identity
67-
4. Read WORKING.md → Last session context
68-
5. Check @mentions → Anyone need me?
69-
6. Act or report HEARTBEAT_OK
70-
```
71-
72-
### Pre-Commit
73-
```bash
74-
npx next build # Must pass
75-
git status # No untracked files
76-
git diff --stat HEAD # Review changes
77-
```
78-
79-
### Task Complete
80-
```bash
81-
git commit -m "closes AGT-XX: description" && git push
82-
npx convex run agentActions:completeTask '{"agent":"sam","ticket":"AGT-XX","action":"completed","summary":"..."}'
83-
./scripts/linear-report.sh AGT-XX "Done. [summary]. Files: [list]."
84-
```
25+
Cross-territory edits allowed — just report in #dev.
8526

8627
---
8728

88-
## Architecture Rules (MANDATORY — Feb 5, 2026)
29+
## Architecture Rules (MANDATORY)
8930

90-
These rules exist because we found 30-40% of the codebase is duplicate or dead code.
91-
**Every agent MUST follow these rules. Violations will be rejected in review.**
31+
### Rule 1: Design System V2 Tokens — No Raw Color Classes
9232

93-
### Rule 1: No New Files Without Search
33+
All UI code MUST use semantic V2 tokens. **Never use `zinc-*`, `gray-*`, `slate-*` for theming.**
9434

95-
Before creating ANY new file, search for existing files that do the same thing:
96-
```bash
97-
# Before creating a new component
98-
grep -rn "ActivityFeed\|activity.*feed" components/ --include="*.tsx" -l
99-
# Before creating a new convex function
100-
grep -rn "getMessages\|sendMessage" convex/ --include="*.ts" -l
101-
```
102-
**If a similar file exists → EDIT it. Do NOT create a new one.**
35+
| Instead of | Use |
36+
|-----------|-----|
37+
| `bg-zinc-950` | `bg-base` |
38+
| `bg-zinc-900` | `bg-surface-1` |
39+
| `bg-zinc-800` | `bg-surface-4` |
40+
| `border-zinc-800` | `border-border-default` |
41+
| `text-zinc-400` | `text-secondary` |
42+
| `text-zinc-500` | `text-tertiary` |
43+
| `text-zinc-300` | `text-primary` |
10344

104-
We currently have 7 dashboard variants and 4 feed variants because agents kept creating instead of editing.
45+
Full token reference: [docs/EVOX-DESIGN-SYSTEM.md](docs/EVOX-DESIGN-SYSTEM.md). Tokens defined in `app/globals.css` `@theme inline` block.
10546

106-
### Rule 2: Agent Identity — Use String Names, NOT Convex IDs
47+
### Rule 2: No New Files Without Search
10748

108-
The canonical agent identifier is the **lowercase string name**: `"sam"`, `"leo"`, `"max"`, `"quinn"`.
49+
Before creating ANY new file, search for existing ones. `grep -rn "Name" components/ --include="*.tsx" -l`
50+
**If similar exists → EDIT it.** We have 7 dashboard variants from agents creating instead of editing.
10951

110-
| Context | Use | Example |
111-
|---------|-----|---------|
112-
| API params | `v.string()` | `agentName: "sam"` |
113-
| DB storage (new tables) | `v.string()` | `fromAgent: "sam"` |
114-
| DB storage (legacy tables) | `v.id("agents")` | Resolve with `resolveAgentIdByName()` |
115-
| Comparing DB field to name | **ALWAYS resolve first** | `resolveAgentNameById(msg.to) === "sam"` |
52+
### Rule 3: Agent Identity — String Names, NOT Convex IDs
11653

117-
**NEVER compare `v.id("agents")` directly with a string name. They are different types.**
54+
Canonical identifier: `"sam"`, `"leo"`, `"max"`, `"quinn"`. Never compare `v.id("agents")` with string names — resolve with `resolveAgentNameById()` first.
11855

119-
```typescript
120-
// WRONG — will always fail
121-
if (message.to !== agentName) { ... }
56+
### Rule 4: Single Source of Truth
12257

123-
// CORRECT — resolve ID to name first
124-
const recipientName = await resolveAgentNameById(ctx.db, message.to);
125-
if (recipientName !== agentName) { ... }
126-
```
58+
| Constant | Source |
59+
|----------|--------|
60+
| Agent list/valid agents | `convex/agentRegistry.ts` |
61+
| Status codes/SLA/labels | `convex/messageStatus.ts` |
12762

128-
### Rule 3: Single Source of Truth
63+
**Never hardcode agent lists like `["sam", "leo", "max"]`.**
12964

130-
These constants must be imported, never duplicated:
65+
### Rule 5: One Messaging Table
13166

132-
| Constant | Source File | What |
133-
|----------|------------|------|
134-
| Agent list | `convex/agentRegistry.ts` | `AGENT_ID_MAP` — all agents |
135-
| Valid agents | `convex/agentRegistry.ts` | `VALID_AGENTS` array |
136-
| Status codes | `convex/messageStatus.ts` | `MessageStatus` enum (0-5) |
137-
| SLA timers | `convex/messageStatus.ts` | `SLA` object |
138-
| Status labels | `convex/messageStatus.ts` | `StatusLabels` map |
67+
All new code → `unifiedMessages`. Legacy tables (`agentMessages`, `messages`, `meshMessages`) are read-only.
13968

140-
**NEVER hardcode agent lists like `["sam", "leo", "max"]` in random files.**
69+
### Rule 6: No New Schema Tables Without CEO Approval
14170

142-
### Rule 4: One Messaging Table
71+
48 tables already. Check if existing table can be extended first.
14372

144-
All new messaging code MUST use `unifiedMessages` table.
73+
### Rule 7: Proof of Work
14574

146-
| Table | Status | Action |
147-
|-------|--------|--------|
148-
| `unifiedMessages` | **ACTIVE — use this** | All new code |
149-
| `agentMessages` | Legacy (Loop depends on it) | Read-only until migrated |
150-
| `messages` | Legacy | Do not use |
151-
| `meshMessages` | Legacy | Do not use |
75+
Ticket "Done" requires: commit hash + files changed + build passes. **No commit = not done.**
15276

153-
### Rule 5: No New Schema Tables Without CEO Approval
77+
### Rule 8: Delete Dead Code
15478

155-
We have 48 tables. Most MVPs have 10-15.
79+
Replace = delete old file + remove imports + verify build. Don't leave code "just in case."
15680

157-
**Before adding a table:**
158-
1. Check if an existing table can be extended
159-
2. Document why a new table is needed
160-
3. Get CEO approval via EVOX
81+
### Rule 9: Max File Size
16182

162-
**Tables that probably should be merged:**
163-
- `activities` + `activityEvents` + `activityLogs` → 1 table
164-
- `learnings` + `orgLearnings` + `agentLearnings` → 1 table
165-
- `executionLogs` + `engineLogs` → 1 table
166-
167-
### Rule 6: Proof of Work
168-
169-
Marking a ticket "Done" requires:
170-
```
171-
1. Commit hash (git log --oneline -1)
172-
2. Files changed (git diff --stat HEAD~1)
173-
3. Build status (npx next build → pass/fail)
174-
```
175-
**No commit hash = not done.** EVOX will verify.
176-
177-
### Rule 7: Delete Dead Code
178-
179-
When replacing a component or function:
180-
1. **Delete the old file** — don't leave it "just in case"
181-
2. **Remove imports** referencing the old file
182-
3. **Verify build passes** after deletion
183-
184-
If unsure whether code is used: `grep -rn "ComponentName" . --include="*.tsx" --include="*.ts" | grep -v node_modules`
185-
186-
### Rule 8: Max File Size
187-
188-
| File Type | Max Lines | Action if exceeded |
189-
|-----------|-----------|-------------------|
190-
| Convex function file | 500 | Split into queries + mutations |
191-
| React component | 300 | Extract sub-components |
192-
| HTTP routes | 500 | Split by domain (agents, tasks, messaging) |
193-
194-
**Current violators:** `http.ts` (3,396), `schema.ts` (1,411), `tasks.ts` (1,210), `agentActions.ts` (922)
83+
Components: 300 lines. Convex files: 500 lines. Split if exceeded.
19584

19685
---
19786

19887
## Quality Gates
19988

200-
| Rule | Check |
201-
|------|-------|
202-
| No raw `_id` in UI | `grep -rn "\._id" app/ components/ --include="*.tsx" \| grep -v "key="` |
89+
| Check | Command |
90+
|-------|---------|
20391
| Build passes | `npx next build` |
204-
| All files committed | `git status` |
205-
| Case-insensitive status | Always `.toLowerCase()` |
206-
| Attribution correct | Use `completeTask` API, not direct DB writes |
207-
| No duplicate files | Search before creating (Rule 1) |
208-
| Agent identity correct | String names, resolve IDs (Rule 2) |
209-
| No hardcoded agent lists | Import from `agentRegistry.ts` (Rule 3) |
210-
| Proof of work | Commit hash + files + build status (Rule 6) |
92+
| No raw `_id` in UI | `grep -rn "\._id" app/ components/ --include="*.tsx" \| grep -v "key="` |
93+
| No zinc-* classes | `grep -rn "zinc-" app/ components/ --include="*.tsx"` |
94+
| All committed | `git status` |
21195

21296
---
21397

98+
## Playbooks
99+
100+
| When | Link |
101+
|------|------|
102+
| Session start | [docs/playbooks/SESSION-START.md](docs/playbooks/SESSION-START.md) |
103+
| Pre-commit | [docs/playbooks/PRE-COMMIT.md](docs/playbooks/PRE-COMMIT.md) |
104+
| Task complete | [docs/playbooks/TASK-COMPLETE.md](docs/playbooks/TASK-COMPLETE.md) |
105+
106+
## Patterns
107+
108+
| Pattern | Link |
109+
|---------|------|
110+
| Display IDs | [docs/patterns/DISPLAY-IDS.md](docs/patterns/DISPLAY-IDS.md) |
111+
| Status Colors | [docs/patterns/STATUS-COLORS.md](docs/patterns/STATUS-COLORS.md) |
112+
| Attribution | [docs/patterns/ATTRIBUTION.md](docs/patterns/ATTRIBUTION.md) |
113+
| Convex Actions | [docs/patterns/CONVEX-ACTIONS.md](docs/patterns/CONVEX-ACTIONS.md) |
114+
214115
## Architecture Decisions
215116

216-
| ADR | Decision |
217-
|-----|----------|
218-
| [ADR-001](docs/decisions/ADR-001.md) | External persistent state for agent memory |
219-
| [ADR-002](docs/decisions/ADR-002.md) | Hierarchical memory (SOUL/WORKING/daily) |
220-
| [ADR-003](docs/decisions/ADR-003.md) | Shared communication via Convex |
221-
| [ADR-004](docs/decisions/ADR-004.md) | Scheduler-driven agent activation |
222-
| [ADR-005](docs/decisions/ADR-005.md) | Permission levels and human oversight |
223-
| [ADR-006](docs/decisions/ADR-006.md) | Headless agent authentication via tmux |
117+
ADR-001 through ADR-006: [docs/decisions/](docs/decisions/)
224118

225119
---
226120

227121
## Security Rules
228122

229-
1. **KHÔNG hardcode secrets** — API keys, tokens, passwords phải ở `.env.local`
230-
2. **Pre-commit check** — Grep for secrets trước khi commit
231-
3. **Review LESSONS.md** — Học từ sai lầm trước
123+
1. **No hardcoded secrets** — API keys, tokens, passwords → `.env.local` only
124+
2. **Pre-commit** — Grep for secrets before every commit
125+
3. **Review** [docs/LESSONS.md](docs/LESSONS.md) — Learn from past mistakes
232126

127+
## Session End Protocol
233128

234-
---
235-
236-
## Session End Protocol (MANDATORY)
237-
238-
Trước khi restart session, PHẢI chạy:
239-
```bash
240-
./scripts/restart-agent.sh <agent>
241-
```
242-
243-
Script sẽ tự động:
244-
1. Capture terminal output
245-
2. Hỏi agent 3 lessons learned
246-
3. Log to `docs/sessions/YYYY-MM-DD-<agent>.md`
247-
4. Post to Convex activity
248-
5. THEN restart
249-
250-
**KHÔNG được restart bằng cách khác!**
251-
252-
### Lessons Format
253-
```markdown
254-
1. **Keyword** — Giải thích ngắn gọn, actionable
255-
2. **Keyword** — Specific, không generic
256-
3. **Keyword** — Có thể apply cho agents khác
257-
```
258-
259-
### Org-wide Lessons
260-
Nếu lesson quan trọng cho tất cả agents:
261-
1. Copy vào `docs/LESSONS.md`
262-
2. Thêm date và context
263-
3. Commit với message: `docs: Add lesson - [keyword]`
129+
Run `./scripts/restart-agent.sh <agent>` before restarting. Script captures output, collects lessons, logs session. **No other restart method allowed.**

0 commit comments

Comments
 (0)