class-ai-agent 1.4.1 → 1.5.1

package/.agent/README.md

@@ -1,19 +1,20 @@
-# Agent continuity (`.agent/`)
+# Agent continuity and Antigravity rules (`.agent/`)
 
-Committed handoff state so **Cursor**, **Claude Code**, and **Kiro** agents can continue the same work without re-discovering context.
+Committed handoff state so **Cursor**, **Claude Code**, **Kiro**, and **Antigravity** agents can continue the same work without re-discovering context.
 
 ## Files
 
-| File | Purpose |
-|------|---------|
+| File / folder | Purpose |
+|---------------|---------|
 | **`SESSION.md`** | Live handoff — read at session start, update at session end |
 | **`SESSION.template.md`** | Schema reference (do not edit for handoff; copy to `SESSION.md` on fresh install) |
+| **`rules/`** | Antigravity supplement rules (synced from `.cursor/rules/`; see `GEMINI.md`) |
 | **`history/`** | _(optional)_ milestone snapshots, e.g. `2025-06-02-feature-x.md` |
 
 ## Workflow
 
 1. **Start** — Run `/resume` (or read `SESSION.md` first). Then `tasks/todo.md`, then linked `SPEC.md`.
-2. **Work** — Follow `.cursor/`, `.claude/`, or `.kiro/` workflow (`/build`, etc.).
+2. **Work** — Follow your tool's hub (`.cursor/`, `.claude/`, `.kiro/`, or `GEMINI.md` / `/build`, etc.).
 3. **End** — Run `/handoff` to refresh `SESSION.md` before closing the chat or switching tools.
 
 ## What to put in `SESSION.md`
@@ -31,3 +32,7 @@ Committed handoff state so **Cursor**, **Claude Code**, and **Kiro** agents can
 ## Commit to git
 
 `SESSION.md` is meant to be **committed** so the whole team and any IDE can resume. Keep it concise and current.
+
+## Antigravity note
+
+Antigravity also reads **`.agent/rules/*.md`** as supplement rules (after `AGENTS.md` and `GEMINI.md`). Workflows and skills live in **`.agents/`** — see **`GEMINI.md`**.

package/.agent/rules/agent-continuity.md

@@ -0,0 +1,44 @@
+---
+trigger: always_on
+description: "Agent session continuity — cross-tool handoff via .agent/SESSION.md"
+---
+
+# Agent continuity
+
+Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Cursor, Claude Code, and Kiro agents share this file.
+
+## Session start
+
+1. If **`.agent/SESSION.md`** exists, read it **before** planning or editing code.
+2. When the user says **continue**, **resume**, or **pick up**, use **`.agents/workflows/resume.md`** (or equivalent in `.agents/` / `.agents/`).
+3. Then read **`tasks/todo.md`** and linked **SPEC** paths from SESSION **Pointers**.
+
+**Do not** call `codegraph_context` with `query` / `limit` for session resume — that tool requires **`task`** and is for code symbols, not handoff state. For continuity, **Read** `.agent/SESSION.md` (and `tasks/todo.md`); use `codegraph_context` only when you need structural code context for the work described in SESSION.
+
+## Session end and phase changes
+
+1. Update **`.agent/SESSION.md`** before ending a session or switching tools — use **`.agents/workflows/handoff.md`** when possible.
+2. Keep **Done**, **In progress**, and **Next** accurate; do not leave stale **In progress** items.
+3. Sync **`tasks/todo.md`** checkboxes when tasks change.
+
+## Security (SESSION.md)
+
+**Never** store in `.agent/SESSION.md`:
+
+- API keys, passwords, tokens, credentials
+- PII or customer data
+
+Use issue links, commit SHAs, and file paths instead.
+
+## Workflow integration
+
+| Phase | SESSION `phase` value |
+|-------|------------------------|
+| Spec | `spec` |
+| Plan | `plan` |
+| Build | `build` |
+| Test | `test` |
+| Review | `review` |
+| Debug | `debug` |
+
+Set **Meta → Tool** to `cursor`, `claude`, or `kiro` as appropriate.

package/.agent/rules/antigravity-overview.md

@@ -0,0 +1,38 @@
+---
+trigger: always_on
+description: "Antigravity agent workflow, principles, and where project guidance lives"
+---
+
+# Antigravity agent — project workflow
+
+This repo mirrors Cursor's `.cursor/` layout into Antigravity-native paths: **`.agents/`** (workflows, skills, agents) and **`.agent/rules/`** (supplement rules).
+
+## Development workflow
+
+Use the same phase order as in `GEMINI.md`:
+
+1. **Define** — `/spec` workflow (`.agents/workflows/spec.md`)
+2. **Plan** — `/plan` workflow
+3. **Build** — `/build` workflow (TDD: `.agents/skills/tdd/`)
+4. **Verify** — `/test` workflow
+5. **Review** — `/review` workflow (five-axis: `.agents/skills/code-review/`)
+6. **Ship** — `/deploy` workflow
+
+Supporting workflows: `debug`, `simplify`, `fix-issue`, `handoff`, `resume` in `.agents/workflows/`. Maintainers: `publish-npm` (say **push to npm repo** to draft README release notes and publish).
+
+**Agent continuity:** committed **`.agent/SESSION.md`** — read at session start (`/resume`), update at end (`/handoff`). See **`.agent/rules/agent-continuity.md`**.
+
+## Mandatory standards
+
+- Follow **`.agent/rules/`** (`*.md` with YAML frontmatter). **`security.md`**, **`codegraph.md`**, and **`agent-continuity.md`** use `trigger: always_on`; others often use `trigger: glob`.
+- Prefer **tests first** and **small vertical slices** (see `.agents/skills/incremental-implementation/`).
+- Use **`.agents/references/`** for checklists (security, testing, performance, accessibility).
+- For **structural** code questions, prefer **CodeGraph** MCP tools per **`.agent/rules/codegraph.md`**.
+
+## Agents (personas)
+
+Specialized instructions live in **`.agents/agents/`**. Reference files in chat (paste or attach).
+
+## Relation to `.cursor/`, `.claude/`, and `.kiro/`
+
+Keep all four trees aligned when you change workflows or standards. After editing `.cursor/`, run `npm run sync:all`.

package/.agent/rules/api-conventions.md

@@ -0,0 +1,85 @@
+---
+trigger: glob
+globs: {ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}
+description: "API Conventions"
+---
+
+# API Conventions
+
+## REST API Design Standards
+
+### URL Structure
+- Use **kebab-case** for URL paths: `/api/user-profiles`
+- Use **plural nouns** for resource collections: `/api/users`, `/api/products`
+- Nest related resources: `/api/users/:id/orders`
+- API version prefix: `/api/v1/...`
+
+### HTTP Methods
+| Method | Usage |
+|--------|-------|
+| GET | Read resources (idempotent) |
+| POST | Create new resource |
+| PUT | Replace entire resource |
+| PATCH | Partial update |
+| DELETE | Remove resource |
+
+### HTTP Status Codes
+| Code | Meaning |
+|------|---------|
+| 200 | OK — Successful GET/PUT/PATCH |
+| 201 | Created — Successful POST |
+| 204 | No Content — Successful DELETE |
+| 400 | Bad Request — Invalid input |
+| 401 | Unauthorized — Not authenticated |
+| 403 | Forbidden — No permission |
+| 404 | Not Found |
+| 409 | Conflict |
+| 422 | Unprocessable Entity — Validation failed |
+| 500 | Internal Server Error |
+
+### Request/Response Format
+```json
+// Success response
+{
+  "success": true,
+  "data": { ... },
+  "message": "Optional message"
+}
+
+// Error response
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human readable message",
+    "details": [ ... ]
+  }
+}
+
+// Paginated list response
+{
+  "success": true,
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### Naming Conventions
+- Request/response body fields: **camelCase**
+- Query parameters: **camelCase**
+- Always return consistent field names
+
+### Filtering & Pagination
+```
+GET /api/users?page=1&limit=20&sortBy=createdAt&order=desc
+GET /api/products?category=electronics&minPrice=100
+```
+
+### Documentation
+- Every endpoint MUST have JSDoc/Swagger annotations
+- Include request body schema, response schema, and error codes

package/.agent/rules/clean-code.md

@@ -0,0 +1,211 @@
+---
+trigger: glob
+globs: {ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}
+description: "Clean Code — JavaScript Rules"
+---
+
+# Clean Code — JavaScript Rules
+> Source: [clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript) by Ryan McDermott
+
+## 📦 Variables
+
+### ✅ Use meaningful, pronounceable names
+```js
+// ❌ Bad
+const yyyymmdstr = moment().format('YYYY/MM/DD');
+
+// ✅ Good
+const currentDate = moment().format('YYYY/MM/DD');
+```
+
+### ✅ Same vocabulary for same type
+```js
+// ❌ getUserInfo(), getClientData(), getCustomerRecord()
+// ✅ getUser()
+```
+
+### ✅ Use searchable names (no magic numbers)
+```js
+// ❌ setTimeout(blastOff, 86400000);
+const MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000;
+setTimeout(blastOff, MILLISECONDS_PER_DAY); // ✅
+```
+
+### ✅ Use explanatory variables
+```js
+// ❌ Bad
+saveCityZipCode(address.match(regex)[1], address.match(regex)[2]);
+
+// ✅ Good
+const [_, city, zipCode] = address.match(cityZipCodeRegex) || [];
+saveCityZipCode(city, zipCode);
+```
+
+### ✅ Avoid mental mapping — be explicit
+```js
+// ❌ locations.forEach(l => { dispatch(l); });
+// ✅ locations.forEach(location => { dispatch(location); });
+```
+
+### ✅ Don't add redundant context
+```js
+// ❌ const Car = { carMake, carModel, carColor }
+// ✅ const Car = { make, model, color }
+```
+
+### ✅ Use default parameters
+```js
+// ❌ const name = name || 'Default';
+// ✅ function create(name = 'Default') {}
+```
+
+---
+
+## 🔧 Functions
+
+### ✅ 2 arguments or fewer — use object destructuring for more
+```js
+// ❌ function createMenu(title, body, buttonText, cancellable) {}
+// ✅ function createMenu({ title, body, buttonText, cancellable }) {}
+```
+
+### ✅ Functions should do ONE thing
+```js
+// ❌ emailClients() — fetches DB + checks active + sends email
+// ✅ emailActiveClients() calls isActiveClient() separately
+```
+
+### ✅ Function names should say what they do
+```js
+// ❌ addToDate(date, 1)     → unclear what is added
+// ✅ addMonthToDate(1, date) → crystal clear
+```
+
+### ✅ One level of abstraction per function
+```js
+// ❌ parseBetterJSAlternative() — tokenizes + parses + AST walks in one function
+// ✅ parseBetterJSAlternative() → calls tokenize() → calls parse()
+```
+
+### ✅ Remove duplicate code — extract shared logic
+### ✅ No flag parameters — split into separate functions
+```js
+// ❌ function createFile(name, isTemp) { if (isTemp) ... }
+// ✅ function createFile(name) {}
+//    function createTempFile(name) {}
+```
+
+### ✅ Avoid Side Effects
+- Don't mutate global state
+- Don't mutate function arguments (use copies)
+```js
+// ✅ Return new array instead of mutating
+function addItemToCart(cart, item) {
+  return [...cart, { item, date: Date.now() }];
+}
+```
+
+### ✅ Favor functional programming
+```js
+// ❌ for loop with mutations
+// ✅ filter(), map(), reduce()
+const totalOutput = programmerOutput
+  .filter(p => p.linesOfCode > 0)
+  .reduce((acc, p) => acc + p.linesOfCode, 0);
+```
+
+### ✅ Encapsulate conditionals
+```js
+// ❌ if (fsm.state === 'fetching' && isEmpty(listNode)) {}
+// ✅ if (shouldShowSpinner(fsmInstance, listNodeInstance)) {}
+```
+
+### ✅ Avoid negative conditionals
+```js
+// ❌ if (!isNotDOMNodePresent(node)) {}
+// ✅ if (isDOMNodePresent(node)) {}
+```
+
+### ✅ Remove dead code immediately
+
+---
+
+## 🏛️ Classes
+
+### ✅ Prefer ES6 classes
+### ✅ Use method chaining (builder pattern)
+```js
+class QueryBuilder {
+  select(fields) { this.fields = fields; return this; }
+  from(table) { this.table = table; return this; }
+  build() { return `SELECT ${this.fields} FROM ${this.table}`; }
+}
+new QueryBuilder().select('*').from('users').build();
+```
+
+### ✅ Prefer composition over inheritance
+> "Favor has-a over is-a"
+
+---
+
+## 🧱 SOLID Principles
+
+| Principle | Rule |
+|-----------|------|
+| **S** — Single Responsibility | One class = one job. Never combine unrelated concerns |
+| **O** — Open/Closed | Open for extension, closed for modification |
+| **L** — Liskov Substitution | Subclasses must be substitutable for their base class |
+| **I** — Interface Segregation | Clients shouldn't depend on interfaces they don't use |
+| **D** — Dependency Inversion | Depend on abstractions, not concretions |
+
+```js
+// ✅ D — Dependency Inversion
+class InventoryService {
+  constructor(inventoryRequester) { // inject the dependency
+    this.inventoryRequester = inventoryRequester;
+  }
+  requestItems(customer) {
+    return this.inventoryRequester.requestItem(customer.purchaseHistory);
+  }
+}
+```
+
+---
+
+## ⚡ Concurrency
+
+### ✅ Use Promises over callbacks
+### ✅ Use async/await over Promises
+```js
+// ✅ Clearest form
+async function getCleanCodeArticle() {
+  try {
+    const response = await request.get(cleanCodeUrl);
+    await fs.writeFile('article.html', response);
+  } catch (err) {
+    console.error(err);
+  }
+}
+```
+
+---
+
+## 🗒️ Comments
+
+### ✅ Only comment business logic complexity
+### ❌ Never leave commented-out code
+### ❌ No journal comments (use git log instead)
+### ❌ No positional markers (`/////`)
+```js
+// ✅ Good comment — explains WHY
+// We retry 3x because OAuth2 tokens can have clock skew
+const MAX_RETRIES = 3;
+```
+
+---
+
+## 📐 Formatting
+
+- Use consistent capitalization (camelCase for vars/fns, PascalCase for classes, UPPER_SNAKE for constants)
+- Keep callers and callees close in the file
+- Related code should appear together

package/.agent/rules/code-style.md

@@ -0,0 +1,92 @@
+---
+trigger: glob
+globs: {ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}
+description: "Code Style Guide"
+---
+
+# Code Style Guide
+
+## General Principles
+- **Clarity over cleverness** — Write code that is easy to read and understand
+- **Consistency** — Follow existing patterns in the codebase
+- **DRY** — Don't Repeat Yourself, but don't over-abstract
+
+## JavaScript / TypeScript
+
+### Formatting
+- Indentation: **2 spaces** (no tabs)
+- Max line length: **100 characters**
+- Use **single quotes** for strings
+- Always use **semicolons**
+- Trailing commas in multi-line structures
+
+### Naming
+```js
+// Variables and functions: camelCase
+const userProfile = {};
+function getUserById(id) {}
+
+// Classes and interfaces: PascalCase
+class UserService {}
+interface UserRepository {}
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://api.example.com';
+
+// Files: kebab-case
+// user-service.js, auth-middleware.js
+```
+
+### Functions
+```js
+// ✅ Good — Arrow functions for simple operations
+const double = (x) => x * 2;
+
+// ✅ Good — Named functions for complex logic
+function processUserData(user) {
+  // ...
+}
+
+// ❌ Avoid — Functions longer than 30 lines (extract helpers)
+```
+
+### Async/Await
+```js
+// ✅ Always use async/await over raw promises
+async function fetchUser(id) {
+  try {
+    const user = await userRepository.findById(id);
+    return user;
+  } catch (error) {
+    throw new AppError('User not found', 404);
+  }
+}
+
+// ❌ Avoid promise chains
+fetchUser(id).then(...).catch(...);
+```
+
+### Imports
+```js
+// Order: 1. Node built-ins, 2. External deps, 3. Internal modules
+import path from 'path';
+import express from 'express';
+import { UserService } from './user-service.js';
+```
+
+## Comments
+```js
+// ✅ Explain WHY, not WHAT
+// We retry 3 times because the external API has transient failures
+const MAX_RETRIES = 3;
+
+// ❌ Avoid obvious comments
+// Set x to 5
+const x = 5;
+```
+
+## File Organization
+- One class/service per file
+- Group related files in feature folders
+- Index files for clean imports

package/.agent/rules/codegraph.md

@@ -0,0 +1,47 @@
+---
+trigger: always_on
+description: "CodeGraph MCP usage guide — when to use which tool"
+---
+ 
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "See several related symbols' source at once" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Tool parameters (do not mix)
+
+| Tool | Required arg | Optional cap | Wrong args → error |
+|------|--------------|--------------|-------------------|
+| `codegraph_search` | **`query`** (symbol name) | `limit` (default 10) | — |
+| `codegraph_context` | **`task`** (feature/bug description) | `maxNodes` (default 20) | `query` / `limit` → **`task must be a non-empty string`** |
+
+`codegraph_context` is for **code structure** around a task — not for loading **`.agent/SESSION.md`** or `/resume` handoff (use **Read** + `.agents/workflows/resume.md`).
+
+### Rules of thumb
+
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*

package/.agent/rules/database.md

@@ -0,0 +1,66 @@
+---
+trigger: glob
+globs: {ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}
+description: "Database Rules"
+---
+
+# Database Rules
+
+## General Rules
+- **Never** write raw SQL strings directly in business logic
+- Always use an ORM (Prisma/Sequelize/TypeORM) or query builder
+- All database calls must be inside try/catch blocks
+- Use **transactions** for multi-step operations
+
+## Connection Management
+```js
+// ✅ Use connection pooling
+const pool = new Pool({ max: 10, idleTimeoutMillis: 30000 });
+
+// ❌ Never create a new connection per request
+```
+
+## Query Best Practices
+```js
+// ✅ Select only needed fields
+const user = await db.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true }
+});
+
+// ❌ Avoid SELECT *
+const user = await db.user.findUnique({ where: { id } });
+
+// ✅ Use pagination for lists
+const users = await db.user.findMany({
+  take: limit,
+  skip: (page - 1) * limit,
+  orderBy: { createdAt: 'desc' }
+});
+```
+
+## Transactions
+```js
+// ✅ Use transactions for atomic operations
+await db.$transaction(async (tx) => {
+  const order = await tx.order.create({ data: orderData });
+  await tx.inventory.update({ where: { id: productId }, data: { stock: { decrement: 1 } } });
+  return order;
+});
+```
+
+## Migrations
+- Always use migration files, never modify the database schema directly
+- Migration files are version-controlled and immutable
+- Run migrations in CI/CD before deploying
+
+## Naming Conventions
+- Tables: **snake_case** plural (`user_profiles`, `order_items`)
+- Columns: **snake_case** (`created_at`, `user_id`)
+- Indexes: `idx_[table]_[column]`
+- Foreign keys: `fk_[table]_[referenced_table]`
+
+## Security
+- Never log query results containing sensitive data (passwords, tokens)
+- Use parameterized queries — never string concatenation
+- Apply row-level security where applicable