@virsanghavi/axis-server 1.1.0 → 1.1.2

package/.axis/instructions/context.md

@@ -1,2 +1,31 @@
-# Project Context
+# Axis — Project Context
 
+## Overview
+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.
+
+The core value proposition: **agents that coordinate like a team, not individuals who overwrite each other.**
+
+## Architecture
+- **Frontend**: Next.js 14 (App Router) deployed on Vercel. Tailwind CSS, Framer Motion. Auth via Supabase.
+- **Backend**: Next.js API routes + Supabase (Postgres, RLS, RPC functions). Stripe for billing.
+- **MCP Server**: `@virsanghavi/axis-server` — an npm package that exposes Axis tools via the Model Context Protocol. Runs locally in each agent's IDE.
+- **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.
+- **File structure**:
+  - `shared-context/frontend/` — the web app (dashboard, billing, docs, auth)
+  - `shared-context/packages/axis-server/` — the MCP server package
+  - `shared-context/supabase/` — schema, migrations, RPC functions
+  - `.axis/instructions/` — soul files read by all agents via MCP
+
+## Core Features
+1. **Job Board**: Agents post, claim, and complete tasks. Priority-based, dependency-aware. Prevents duplicate work.
+2. **File Locking**: Atomic, per-file locks with 30-minute TTL. Agents call `propose_file_access` before editing. Prevents merge conflicts.
+3. **Live Notepad**: Real-time shared memory. Agents log progress so others know what's happening. Cleared on `finalize_session`.
+4. **Context Mirroring**: `get_project_soul` returns this file + conventions to ground agents in project reality.
+5. **RAG Search**: `search_codebase` and `search_docs` for semantic search over indexed files and documentation.
+6. **Session Management**: `finalize_session` archives the notepad, clears locks, resets for new work.
+7. **Billing**: Stripe-based Pro tier ($25/mo) with API key management, usage tracking, and retention flow.
+
+## Deployment
+- Frontend: Vercel (auto-deploy from `shared-context/frontend/`)
+- Database: Supabase (hosted Postgres)
+- MCP Server: Published to npm, run locally via `npx @virsanghavi/axis-server`

package/.axis/instructions/conventions.md

@@ -1,2 +1,62 @@
-# Coding Conventions
+# Axis — Coding Conventions & Agent Norms
 
+## Language Standards
+- **TypeScript** for all frontend and API code. Strict mode. No `any` unless absolutely necessary.
+- **SQL** for Supabase migrations. Use `IF NOT EXISTS` / `IF EXISTS` for idempotency.
+- **HTML/CSS/JS** for standalone tools (e.g. sandbox apps). Single-file, no frameworks, no build step.
+
+## Styling
+- Tailwind CSS exclusively. No custom CSS files unless for animations.
+- Dark theme: `bg-[#050505]`, `text-white`, `border-white/5`. Light panels: `bg-white/95`, `text-neutral-900`.
+- Typography: `lowercase` class on page wrappers. `font-mono` for technical content. `tracking-tight` default.
+- Components: Minimal, no component library. Custom components in `components/`.
+
+## Testing
+- Manual testing via browser and MCP tool calls.
+- Health endpoint at `/api/health` checks Supabase and Stripe connectivity.
+
+## Code Patterns
+- API routes use `getSessionFromRequest` for auth, `getClientIp` + `rateLimit` for rate limiting.
+- Supabase queries use `.ilike('email', ...)` for case-insensitive email matching.
+- Stripe customer IDs come from DB (`profiles.stripe_customer_id`). Never hardcode customer IDs.
+- All Stripe routes have "no such customer" self-healing: look up by email, update DB, retry.
+
+---
+
+## Agent Behavioral Norms
+
+### Plan Before Write — The Core Invariant
+
+**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
+
+On non-trivial tasks (2+ files, new features, refactors):
+1. Break work into jobs → `post_job`
+2. Claim before editing → `claim_next_job`
+3. Lock before writing → `propose_file_access` with a **descriptive intent**
+4. Complete when done → `complete_job` with outcome
+
+Direct edits without a job are allowed only for:
+- Single-line fixes, typos, config tweaks
+- Clearly scoped changes the user asked for directly
+
+### Force Unlock Policy
+
+`force_unlock` is a **last resort, not a convenience tool.**
+
+Rules:
+1. **Never** call `force_unlock` on a file you didn't lock unless:
+   - The lock has been held for >25 minutes (close to TTL expiry), AND
+   - The locking agent is clearly not responding or has crashed
+2. **Always** provide a specific reason (e.g. "Agent claude-code crashed 20 minutes ago, lock on auth.ts is blocking progress")
+3. **Never** force-unlock to skip coordination. If another agent holds a lock, work on something else.
+4. Prefer waiting for TTL expiry (30 min) over force-unlocking.
+
+### Lock Hygiene
+- Always provide descriptive `intent` when locking (e.g. "Refactor auth middleware to use JWT validation" — not "editing file")
+- Release locks early by completing jobs when done
+- Call `finalize_session` at end of session to clean up all locks
+
+### Shared Memory
+- Call `update_shared_context` after completing meaningful steps
+- Log decisions, not just actions (e.g. "Chose JWT over session tokens because...")
+- Other agents read the notepad in real-time — write for them

package/dist/mcp-server.mjs

@@ -1226,8 +1226,52 @@ async function ensureFileSystem() {
       await fs4.mkdir(axisInstructions, { recursive: true }).catch(() => {
       });
       const defaults = [
-        ["context.md", "# Project Context\n\n"],
-        ["conventions.md", "# Coding Conventions\n\n"],
+        ["context.md", `# Project Context
+
+## Overview
+This project uses Axis \u2014 an open-source coordination layer for AI agents.
+Axis provides shared context, atomic file locks, a job board, and real-time
+activity feeds so that multiple agents (Cursor, Claude, Windsurf, Codex, etc.)
+can work on the same codebase without conflicts.
+
+## Architecture
+- **MCP Server**: Exposes tools (locks, jobs, context, search) via the Model Context Protocol.
+- **Supabase Backend**: Postgres for state (locks, jobs, profiles); Realtime for live feeds.
+- **Frontend**: Next.js App Router + Tailwind CSS dashboard at useaxis.dev.
+- **npm Packages**: @virsanghavi/axis-server (runtime), @virsanghavi/axis-init (scaffolding).
+
+## Core Features
+1. File Locking \u2014 atomic, cross-IDE locks with 30-min TTL.
+2. Job Board \u2014 post / claim / complete tasks with priorities and dependencies.
+3. Shared Context \u2014 live notepad visible to every agent in real time.
+4. RAG Search \u2014 vector search over the indexed codebase.
+5. Soul Files \u2014 context.md, conventions.md, activity.md define project identity.
+`],
+        ["conventions.md", `# Coding Conventions
+
+## Language & Style
+- TypeScript everywhere (strict mode).
+- Tailwind CSS for styling; no raw CSS unless unavoidable.
+- Functional React components; prefer server components in Next.js App Router.
+
+## Agent Behavioral Norms
+
+### Plan Before Write
+Every non-trivial task must follow: post_job -> claim_next_job -> propose_file_access -> (edit) -> complete_job.
+Skip only for single-line typo fixes.
+
+### Force-Unlock Policy
+force_unlock is a LAST RESORT. Before using it:
+1. Verify the lock is > 25 minutes old.
+2. Confirm the locking agent is unresponsive.
+3. Provide a specific reason string.
+Never casually unlock files \u2014 always try propose_file_access first.
+
+### Proactive Tool Usage
+Agents must use Axis MCP tools by default \u2014 do not wait for the user to say "use Axis".
+On session start, call get_project_soul or read_context to load project state.
+After significant progress, call update_shared_context.
+`],
         ["activity.md", "# Activity Log\n\n"]
       ];
       for (const [file, content] of defaults) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@virsanghavi/axis-server",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "Axis MCP Server CLI",
     "main": "dist/index.js",
     "bin": {