@virsanghavi/axis-server 1.2.0 → 1.3.0

package/.axis/instructions/conventions.md

@@ -23,40 +23,35 @@
 
 ---
 
-## Agent Behavioral Norms
+## Agent Behavioral Norms (MANDATORY)
 
-### Plan Before Write — The Core Invariant
+These norms apply to all AI coding agents. They are not optional or suggestive — execute them autonomously.
 
-**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
+### Autonomous Execution
 
-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
+- **NEVER** wait for the user to say "use Axis" or "post a job" or "lock the file." Just do it.
+- **NEVER** pause after analysis to ask permission to proceed. Identify issues → start fixing immediately.
+- **NEVER** leave locks or jobs dangling. Complete jobs and finalize sessions without being told.
+- **IMMEDIATELY** call `get_project_soul` as the first action in any session.
 
-Direct edits without a job are allowed only for:
-- Single-line fixes, typos, config tweaks
-- Clearly scoped changes the user asked for directly
+### Plan Before Write
 
-### Force Unlock Policy
+**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
 
-`force_unlock` is a **last resort, not a convenience tool.**
+On non-trivial tasks (2+ files, new features, refactors):
+1. `post_job` — break into trackable jobs (do this IMMEDIATELY, not after being asked)
+2. `claim_next_job` — claim before starting
+3. `propose_file_access` — lock with a **descriptive intent**
+4. `complete_job` — report outcome when done (this releases the lock)
 
-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.
+Skip jobs ONLY for: single-line fixes, typos, config tweaks.
 
 ### 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
+- Descriptive `intent` when locking (not "editing file").
+- Release locks IMMEDIATELY by completing jobs. Never hold a lock while doing unrelated work.
+- `force_unlock` is a **last resort** — only for locks >25 min old from a crashed agent. Always give a reason.
+
+### Session Cleanup (MANDATORY)
+- `complete_job` after EVERY finished task — do not accumulate incomplete jobs.
+- `update_shared_context` after meaningful steps — log decisions, not just actions.
+- `finalize_session` when the user's request is fully complete — this is required, not optional.

package/dist/mcp-server.mjs

@@ -1286,23 +1286,26 @@ can work on the same codebase without conflicts.
 - Tailwind CSS for styling; no raw CSS unless unavoidable.
 - Functional React components; prefer server components in Next.js App Router.
 
-## Agent Behavioral Norms
+## Agent Behavioral Norms (MANDATORY)
+
+### Autonomous Execution
+Agents MUST execute the full Axis workflow without being told:
+- NEVER wait for the user to say "use Axis" or "post a job." Just do it.
+- NEVER pause after analysis to ask permission. Identify issues \u2192 start fixing immediately.
+- NEVER leave locks or jobs dangling. Complete jobs and finalize sessions automatically.
+- IMMEDIATELY call get_project_soul as the first action in every session.
 
 ### 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.
+Every non-trivial task MUST follow: post_job \u2192 claim_next_job \u2192 propose_file_access \u2192 (edit) \u2192 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.
+### Session Cleanup (MANDATORY)
+- complete_job IMMEDIATELY after finishing each task.
+- update_shared_context after meaningful steps.
+- finalize_session when the user's request is fully complete \u2014 do not wait to be told.
 
-### 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.
+### Force-Unlock Policy
+force_unlock is a LAST RESORT \u2014 only for locks >25 min old from a crashed agent. Always give a reason.
 `],
         ["activity.md", "# Activity Log\n\n"]
       ];
@@ -1458,7 +1461,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Decision & Orchestration ---
     {
       name: "propose_file_access",
-      description: "**CRITICAL: REQUEST FILE LOCK**.\n- **MUST** be called *before* editing any file to prevent conflicts with other agents.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (what you are doing).\n- Note: Locks expire after 30 minutes. Use `force_unlock` only if you are certain a lock is stale and blocking progress.",
+      description: "**CRITICAL: REQUEST FILE LOCK** \u2014 call this before EVERY file edit, no exceptions.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (descriptive \u2014 e.g. 'Refactor auth to use JWT', NOT 'editing file').\n- Locks expire after 30 minutes. Use `force_unlock` only as a last resort for crashed agents.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1485,18 +1488,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Permanent Memory ---
     {
       name: "finalize_session",
-      description: "**END OF SESSION HOUSEKEEPING**.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Call this when the user says 'we are done' or 'start fresh'.",
+      description: "**MANDATORY SESSION CLEANUP** \u2014 call this automatically when the user's request is fully complete.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Do NOT wait for the user to say 'we are done.' When all tasks are finished, call this yourself.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
     {
       name: "get_project_soul",
-      description: "**HIGH-LEVEL INTENT**: Returns the 'Soul' of the project.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- Use this at the *start* of a conversation to ground yourself in the project's reality.",
+      description: "**MANDATORY FIRST CALL**: Returns the project's goals, architecture, conventions, and active state.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- You MUST call this as your FIRST action in every new session or task \u2014 before reading files, before responding to the user, before anything else.\n- Skipping this call means you are working without context and will make wrong decisions.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
     // --- Job Board (Task Orchestration) ---
     {
       name: "post_job",
-      description: "**CREATE TICKET**: Post a new task to the Job Board.\n- Use this when you identify work that needs to be done but *cannot* be done right now (e.g., refactoring, new feature).\n- Supports `dependencies` (list of other Job IDs that must be done first).\n- Priority: low, medium, high, critical.",
+      description: "**CREATE TICKET**: Post a new task to the Job Board.\n- Call this IMMEDIATELY when you receive a non-trivial task (2+ files, new features, refactors). Do not wait to be asked.\n- Break work into trackable jobs BEFORE you start coding.\n- Supports `dependencies` (list of other Job IDs that must be done first).\n- Priority: low, medium, high, critical.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1534,7 +1537,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "claim_next_job",
-      description: "**AUTO-ASSIGNMENT**: Ask the Job Board for the next most important task.\n- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).\n- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.\n- Use this when you are idle and looking for work.",
+      description: "**CLAIM WORK**: Claim the next job from the Job Board before starting it.\n- You MUST claim a job before editing files for that job.\n- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).\n- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.\n- Call this immediately after posting jobs, and again after completing each job to pick up the next one.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1545,7 +1548,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "complete_job",
-      description: "**CLOSE TICKET**: Mark a job as done.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.",
+      description: "**CLOSE TICKET**: Mark a job as done and release file locks.\n- Call this IMMEDIATELY after finishing each job \u2014 do not accumulate completed-but-unclosed jobs.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.\n- Leaving jobs open holds locks and blocks other agents.",
       inputSchema: {
         type: "object",
         properties: {

package/package.json

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