@virsanghavi/axis-server 1.1.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,2 +1,31 @@
|
|
|
1
|
-
# Project Context
|
|
1
|
+
# Axis — Project Context
|
|
2
2
|
|
|
3
|
+
## Overview
|
|
4
|
+
Axis is a distributed orchestration layer for parallel AI coding agents. It enables multiple agents (Cursor, Claude Code, Windsurf, Codex, Antigravity, etc.) to work on the same codebase simultaneously without collisions or context drift.
|
|
5
|
+
|
|
6
|
+
The core value proposition: **agents that coordinate like a team, not individuals who overwrite each other.**
|
|
7
|
+
|
|
8
|
+
## Architecture
|
|
9
|
+
- **Frontend**: Next.js 14 (App Router) deployed on Vercel. Tailwind CSS, Framer Motion. Auth via Supabase.
|
|
10
|
+
- **Backend**: Next.js API routes + Supabase (Postgres, RLS, RPC functions). Stripe for billing.
|
|
11
|
+
- **MCP Server**: `@virsanghavi/axis-server` — an npm package that exposes Axis tools via the Model Context Protocol. Runs locally in each agent's IDE.
|
|
12
|
+
- **State**: All shared state (locks, jobs, notepad, sessions, embeddings) lives in Supabase, scoped per project. The MCP server syncs local state with the remote API.
|
|
13
|
+
- **File structure**:
|
|
14
|
+
- `shared-context/frontend/` — the web app (dashboard, billing, docs, auth)
|
|
15
|
+
- `shared-context/packages/axis-server/` — the MCP server package
|
|
16
|
+
- `shared-context/supabase/` — schema, migrations, RPC functions
|
|
17
|
+
- `.axis/instructions/` — soul files read by all agents via MCP
|
|
18
|
+
|
|
19
|
+
## Core Features
|
|
20
|
+
1. **Job Board**: Agents post, claim, and complete tasks. Priority-based, dependency-aware. Prevents duplicate work.
|
|
21
|
+
2. **File Locking**: Atomic, per-file locks with 30-minute TTL. Agents call `propose_file_access` before editing. Prevents merge conflicts.
|
|
22
|
+
3. **Live Notepad**: Real-time shared memory. Agents log progress so others know what's happening. Cleared on `finalize_session`.
|
|
23
|
+
4. **Context Mirroring**: `get_project_soul` returns this file + conventions to ground agents in project reality.
|
|
24
|
+
5. **RAG Search**: `search_codebase` and `search_docs` for semantic search over indexed files and documentation.
|
|
25
|
+
6. **Session Management**: `finalize_session` archives the notepad, clears locks, resets for new work.
|
|
26
|
+
7. **Billing**: Stripe-based Pro tier ($25/mo) with API key management, usage tracking, and retention flow.
|
|
27
|
+
|
|
28
|
+
## Deployment
|
|
29
|
+
- Frontend: Vercel (auto-deploy from `shared-context/frontend/`)
|
|
30
|
+
- Database: Supabase (hosted Postgres)
|
|
31
|
+
- MCP Server: Published to npm, run locally via `npx @virsanghavi/axis-server`
|
|
@@ -1,2 +1,62 @@
|
|
|
1
|
-
# Coding Conventions
|
|
1
|
+
# Axis — Coding Conventions & Agent Norms
|
|
2
2
|
|
|
3
|
+
## Language Standards
|
|
4
|
+
- **TypeScript** for all frontend and API code. Strict mode. No `any` unless absolutely necessary.
|
|
5
|
+
- **SQL** for Supabase migrations. Use `IF NOT EXISTS` / `IF EXISTS` for idempotency.
|
|
6
|
+
- **HTML/CSS/JS** for standalone tools (e.g. sandbox apps). Single-file, no frameworks, no build step.
|
|
7
|
+
|
|
8
|
+
## Styling
|
|
9
|
+
- Tailwind CSS exclusively. No custom CSS files unless for animations.
|
|
10
|
+
- Dark theme: `bg-[#050505]`, `text-white`, `border-white/5`. Light panels: `bg-white/95`, `text-neutral-900`.
|
|
11
|
+
- Typography: `lowercase` class on page wrappers. `font-mono` for technical content. `tracking-tight` default.
|
|
12
|
+
- Components: Minimal, no component library. Custom components in `components/`.
|
|
13
|
+
|
|
14
|
+
## Testing
|
|
15
|
+
- Manual testing via browser and MCP tool calls.
|
|
16
|
+
- Health endpoint at `/api/health` checks Supabase and Stripe connectivity.
|
|
17
|
+
|
|
18
|
+
## Code Patterns
|
|
19
|
+
- API routes use `getSessionFromRequest` for auth, `getClientIp` + `rateLimit` for rate limiting.
|
|
20
|
+
- Supabase queries use `.ilike('email', ...)` for case-insensitive email matching.
|
|
21
|
+
- Stripe customer IDs come from DB (`profiles.stripe_customer_id`). Never hardcode customer IDs.
|
|
22
|
+
- All Stripe routes have "no such customer" self-healing: look up by email, update DB, retry.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Agent Behavioral Norms
|
|
27
|
+
|
|
28
|
+
### Plan Before Write — The Core Invariant
|
|
29
|
+
|
|
30
|
+
**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
|
|
31
|
+
|
|
32
|
+
On non-trivial tasks (2+ files, new features, refactors):
|
|
33
|
+
1. Break work into jobs → `post_job`
|
|
34
|
+
2. Claim before editing → `claim_next_job`
|
|
35
|
+
3. Lock before writing → `propose_file_access` with a **descriptive intent**
|
|
36
|
+
4. Complete when done → `complete_job` with outcome
|
|
37
|
+
|
|
38
|
+
Direct edits without a job are allowed only for:
|
|
39
|
+
- Single-line fixes, typos, config tweaks
|
|
40
|
+
- Clearly scoped changes the user asked for directly
|
|
41
|
+
|
|
42
|
+
### Force Unlock Policy
|
|
43
|
+
|
|
44
|
+
`force_unlock` is a **last resort, not a convenience tool.**
|
|
45
|
+
|
|
46
|
+
Rules:
|
|
47
|
+
1. **Never** call `force_unlock` on a file you didn't lock unless:
|
|
48
|
+
- The lock has been held for >25 minutes (close to TTL expiry), AND
|
|
49
|
+
- The locking agent is clearly not responding or has crashed
|
|
50
|
+
2. **Always** provide a specific reason (e.g. "Agent claude-code crashed 20 minutes ago, lock on auth.ts is blocking progress")
|
|
51
|
+
3. **Never** force-unlock to skip coordination. If another agent holds a lock, work on something else.
|
|
52
|
+
4. Prefer waiting for TTL expiry (30 min) over force-unlocking.
|
|
53
|
+
|
|
54
|
+
### Lock Hygiene
|
|
55
|
+
- Always provide descriptive `intent` when locking (e.g. "Refactor auth middleware to use JWT validation" — not "editing file")
|
|
56
|
+
- Release locks early by completing jobs when done
|
|
57
|
+
- Call `finalize_session` at end of session to clean up all locks
|
|
58
|
+
|
|
59
|
+
### Shared Memory
|
|
60
|
+
- Call `update_shared_context` after completing meaningful steps
|
|
61
|
+
- Log decisions, not just actions (e.g. "Chose JWT over session tokens because...")
|
|
62
|
+
- Other agents read the notepad in real-time — write for them
|