@agilemonster/mcp-server 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# @agilemonster/mcp-server & Agent Orchestrator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Model Context Protocol (MCP) Server and Autonomous Agent Orchestrator for **Agile Monster** ([https://app.agilemonster.com](https://app.agilemonster.com)).
+
+Seamlessly connects your Agile Monster boards with your favorite developer AI agents:
+- **Cursor**
+- **Claude Code**
+- **Antigravity / Gemini Code Assist**
+- **Codex**
+- **Hermes Agent**
+- **Windsurf / Aider**
+
+---
+
+## ⚡ Quick Start: Adding to your AI Agent
+
+Generate a **Personal API Key** in Agile Monster ([https://app.agilemonster.com](https://app.agilemonster.com) -> Profile -> API Keys). Your key will look like `am_live_...`.
+
+### 1. Cursor (`.cursor/mcp.json` or Global Settings)
+```json
+{
+  "mcpServers": {
+    "agilemonster": {
+      "command": "npx",
+      "args": ["-y", "@agilemonster/mcp-server"],
+      "env": {
+        "AGILEMONSTER_API_KEY": "am_live_your_token_here",
+        "AGILEMONSTER_API_URL": "https://api.agilemonster.com"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Code CLI
+```bash
+claude mcp add agilemonster npx -y @agilemonster/mcp-server \
+  -e AGILEMONSTER_API_KEY="am_live_your_token_here" \
+  -e AGILEMONSTER_API_URL="https://api.agilemonster.com"
+```
+
+### 3. Antigravity / Gemini
+Add to your Antigravity MCP directory (`~/.gemini/antigravity/mcp/agilemonster` or project settings):
+```json
+{
+  "mcpServers": {
+    "agilemonster": {
+      "command": "node",
+      "args": ["/path/to/agilemonster/packages/mcp-server/bin/mcp.js"],
+      "env": {
+        "AGILEMONSTER_API_KEY": "am_live_your_token_here",
+        "AGILEMONSTER_API_URL": "https://api.agilemonster.com"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📁 1-Click Project Initialization (`init`)
+
+To automatically bind your repository to an Agile Monster board and generate operational instructions for your AI agents in one command, run:
+
+```bash
+npx @agilemonster/mcp-server init
+```
+
+This generates:
+1. `.agilemonster.json` — Binds the local repository to the board UUID, list columns, and default agent provider.
+2. `AGENTS.md` — Codified operational rules for autonomous agents (Cursor, Claude Code, Antigravity, etc.) so they know when to claim tasks, ask clarifying questions, log progress, and submit work for human testing.
+
+---
+
+## 🛠️ Available MCP Tools
+
+Agents have access to 8 purpose-built lifecycle tools:
+
+| Tool | Purpose |
+| :--- | :--- |
+| `agilemonster_get_context` | Inspects board, columns, and active tasks. Auto-detects project from `.agilemonster.json` or directory name. |
+| `agilemonster_init_project` | Binds current repo to an Agile Monster board and creates `AGENTS.md`. |
+| `agilemonster_list_my_tasks` | Lists cards assigned to the AI agent (`queued`, `in_progress`, `waiting_for_input`, `review`). |
+| `agilemonster_claim_task` | Claims a task, marking it `in_progress` on the board before code edits start. |
+| `agilemonster_ask_question` | Posts a question comment on the card and marks status as `waiting_for_input` so the user is alerted. |
+| `agilemonster_add_progress` | Logs implementation progress notes to task comments. |
+| `agilemonster_submit_for_review` | Marks work complete, moves card to Review column, reassigns to human member for confirmation, and posts test instructions. |
+| `agilemonster_create_followup_tasks` | Creates follow-up cards (e.g. "Deploy to Test", "Deploy to Production", "Write integration tests"). |
+
+---
+
+## 💡 MCP Native Prompts & Resources
+
+The server exposes Model Context Protocol **Prompts** and **Resources** so agents can automatically load operational instructions into their context:
+
+### Prompts
+- `agilemonster_agent_protocol`: System instructions explaining the full task lifecycle protocol.
+- `agilemonster_work_on_task`: Guided workflow prompt for an agent to claim, investigate, implement, test, submit for review, and propose follow-up tasks for a specific card ID.
+
+### Resources
+- `agilemonster://guidelines/agents`: Live markdown text of the official Agent Guidelines (`text/markdown`).
+- `agilemonster://project/context`: Current repository board, list structure, and active agent tasks as live JSON (`application/json`).
+
+---
+
+## 🤖 The Autonomous Agent Orchestrator CLI
+
+Use the built-in orchestrator to monitor tasks, dispatch work, or run a background watcher:
+
+```bash
+# Check current tasks assigned to agents for this project
+npx @agilemonster/mcp-server status
+
+# Watch for newly assigned tasks in real-time
+npx @agilemonster/mcp-server watch
+
+# Claim a task
+npx @agilemonster/mcp-server claim <card_id>
+
+# Submit for user testing & confirmation
+npx @agilemonster/mcp-server review <card_id> "Implemented dark mode toggle" "Test via Settings screen"
+
+# Ask the user a question
+npx @agilemonster/mcp-server question <card_id> "Should we support OAuth tokens as well?"
+```
+
+---
+
+## 📚 REST API Reference
+
+For developers building custom scripts, CI/CD bots, or proprietary agent orchestrators, refer to the full REST API specification in [`docs/AGENT-API.md`](../../docs/AGENT-API.md).

package/bin/mcp.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { runStdioServer } from '../dist/server.js';
+
+const cliCommands = new Set([
+  'bootstrap',
+  'setup',
+  'init',
+  'status',
+  'check',
+  'list',
+  'watch',
+  'daemon',
+  'claim',
+  'review',
+  'question',
+  'help',
+  '--help',
+  '-h',
+]);
+
+const firstArg = process.argv[2];
+if (firstArg && cliCommands.has(firstArg)) {
+  // Delegate to orchestrator CLI
+  await import('./orchestrator.js');
+} else {
+  runStdioServer().catch((error) => {
+    console.error('Fatal MCP Server Error:', error);
+    process.exit(1);
+  });
+}

package/bin/orchestrator.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { AgileMonsterOrchestrator } from '../dist/orchestrator.js';
+import { AgileMonsterClient } from '../dist/client.js';
+
+const client = new AgileMonsterClient();
+const orchestrator = new AgileMonsterOrchestrator(client);
+
+const args = process.argv.slice(2);
+const command = args[0] || 'status';
+
+async function main() {
+  switch (command) {
+    case 'status':
+    case 'check':
+    case 'list':
+      await orchestrator.printDashboard();
+      break;
+
+    case 'watch':
+    case 'daemon':
+      await orchestrator.runDaemon({
+        intervalMs: 10000,
+      });
+      break;
+
+    case 'bootstrap':
+    case 'setup':
+    case 'init': {
+      const ideArg = args.find((a) => a.startsWith('--ide='))?.split('=')[1] || args[1];
+      await orchestrator.initInteractive({ ide: ideArg });
+      break;
+    }
+
+    case 'claim': {
+      const cardId = args[1];
+      if (!cardId) {
+        console.error('Usage: agilemonster-orchestrator claim <cardId> [provider]');
+        process.exit(1);
+      }
+      const provider = args[2] || client.loadProjectConfig()?.provider || 'antigravity';
+      const result = await client.claimTask(cardId, provider);
+      console.log(`✅ Claimed task: ${result.title} (${result.id})`);
+      break;
+    }
+
+    case 'review': {
+      const cardId = args[1];
+      const summary = args[2];
+      if (!cardId || !summary) {
+        console.error('Usage: agilemonster-orchestrator review <cardId> "<summary>" [verificationSteps]');
+        process.exit(1);
+      }
+      const verificationSteps = args[3];
+      const provider = client.loadProjectConfig()?.provider || 'antigravity';
+      const result = await client.submitReview(cardId, provider, summary, verificationSteps);
+      console.log(`✅ Submitted task for review & testing: ${result.title} (${result.id})`);
+      break;
+    }
+
+    case 'question': {
+      const cardId = args[1];
+      const question = args[2];
+      if (!cardId || !question) {
+        console.error('Usage: agilemonster-orchestrator question <cardId> "<question>"');
+        process.exit(1);
+      }
+      const provider = client.loadProjectConfig()?.provider || 'antigravity';
+      const result = await client.askQuestion(cardId, provider, question);
+      console.log(`✅ Question posted to task: ${result.title}`);
+      break;
+    }
+
+    default:
+      console.log(`
+Agile Monster Agent Orchestrator CLI
+
+Commands:
+  agilemonster-orchestrator (or status)      Show active agent tasks and project binding
+  agilemonster-orchestrator watch             Run background daemon to watch for newly queued tasks
+  agilemonster-orchestrator init              Bind current directory to an Agile Monster board
+  agilemonster-orchestrator claim <id>        Claim a task and mark it in-progress
+  agilemonster-orchestrator review <id> "..." Submit task for user review & confirmation
+  agilemonster-orchestrator question <id> "..." Ask the user a clarifying question
+      `);
+      break;
+  }
+}
+
+main().catch((err) => {
+  console.error('Orchestrator Error:', err.message || err);
+  process.exit(1);
+});

package/bin/worker.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { AgileMonsterWorker } from '../dist/worker.js';
+import { AgileMonsterClient } from '../dist/client.js';
+
+const client = new AgileMonsterClient();
+const worker = new AgileMonsterWorker(client);
+
+const args = process.argv.slice(2);
+
+function getArg(prefix, fallback) {
+  const found = args.find((a) => a.startsWith(prefix));
+  if (found) {
+    return found.split('=')[1];
+  }
+  return fallback;
+}
+
+const hasFlag = (flag) => args.includes(flag);
+
+if (hasFlag('--help') || hasFlag('-h')) {
+  console.log(`
+Agile Monster Autonomous Agent Worker
+
+Usage:
+  agilemonster-worker [options]
+
+Options:
+  --runner=<engine>         Execution engine: simulated (default), aider, claude, shell
+  --command="<cmd>"         Shell command to execute when runner=shell
+  --provider=<agent>        Target agent provider: antigravity (default), cursor, aider, etc.
+  --interval=<seconds>      Polling interval in seconds (default: 15)
+  --heartbeat=<seconds>     Heartbeat progress update interval (default: 30)
+  --max-budget=<usd>        Circuit-breaker USD budget limit per task (default: 5.00)
+  --max-tokens=<count>      Circuit-breaker token limit per task (default: 200000)
+  --no-branch               Do not create an isolated git branch for the task
+  --once                    Process at most one queued task and exit
+  --help, -h                Show this help screen
+  `);
+  process.exit(0);
+}
+
+const runner = getArg('--runner', 'simulated');
+const customCommand = getArg('--command', undefined);
+const provider = getArg('--provider', undefined);
+const intervalSec = parseInt(getArg('--interval', '15'), 10);
+const heartbeatSec = parseInt(getArg('--heartbeat', '30'), 10);
+const maxBudgetUsd = parseFloat(getArg('--max-budget', '5.0'));
+const maxTokens = parseInt(getArg('--max-tokens', '200000'), 10);
+const gitBranch = !hasFlag('--no-branch');
+const once = hasFlag('--once');
+
+async function main() {
+  await worker.start({
+    runner,
+    customCommand,
+    provider,
+    intervalMs: intervalSec * 1000,
+    heartbeatMs: heartbeatSec * 1000,
+    maxBudgetUsd,
+    maxTokens,
+    gitBranch,
+    once,
+  });
+}
+
+main().catch((err) => {
+  console.error('Fatal Worker Error:', err.message || err);
+  process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import { AgileMonsterProjectConfig, Card, ContextResponse } from './types.js';
+export declare class AgileMonsterClient {
+    private apiKey;
+    private baseUrl;
+    private cwd;
+    private cachedConfig;
+    constructor(options?: {
+        apiKey?: string;
+        baseUrl?: string;
+        cwd?: string;
+    });
+    private resolveApiKey;
+    getApiKey(): string;
+    setApiKey(key: string): void;
+    loadProjectConfig(): AgileMonsterProjectConfig | null;
+    saveProjectConfig(config: AgileMonsterProjectConfig, dir?: string): string;
+    static saveGlobalConfig(data: {
+        api_key?: string;
+    }): string;
+    private request;
+    me(): Promise<{
+        id: string;
+        email: string;
+        first_name?: string;
+        last_name?: string;
+    }>;
+    getContext(projectName?: string, boardId?: string): Promise<ContextResponse>;
+    listAssigned(provider?: string, status?: string, boardId?: string, workspaceId?: string): Promise<{
+        provider: string;
+        cards: Card[];
+    }>;
+    claimTask(cardId: string, provider: string, runRef?: string): Promise<Card>;
+    askQuestion(cardId: string, provider: string, question: string): Promise<Card>;
+    addProgress(cardId: string, provider: string, update: string, tokensUsed?: number, costUsd?: number): Promise<Card>;
+    recordSpend(cardId: string, provider: string, tokens: number, costUsd: number, note?: string): Promise<Card>;
+    setBudget(cardId: string, maxBudgetUsd?: number | null, maxTokens?: number | null): Promise<Card>;
+    submitReview(cardId: string, provider: string, summary: string, verificationSteps?: string, targetList?: string, assignToUserId?: string): Promise<Card>;
+    completeTask(cardId: string, provider: string, comment?: string): Promise<Card>;
+    blockTask(cardId: string, provider: string, comment?: string): Promise<Card>;
+    createFollowupTasks(cardId: string, provider: string, tasks: Array<{
+        title: string;
+        description?: string;
+        list_id?: string;
+        agent_provider?: string;
+    }>): Promise<{
+        tasks: Card[];
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,245 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class AgileMonsterClient {
+    apiKey = '';
+    baseUrl;
+    cwd;
+    cachedConfig = undefined;
+    constructor(options) {
+        this.cwd = options?.cwd || process.cwd();
+        this.baseUrl = (options?.baseUrl ||
+            process.env.AGILEMONSTER_API_URL ||
+            'https://api.agilemonster.com').replace(/\/+$/, '');
+        this.apiKey = options?.apiKey || this.resolveApiKey();
+    }
+    resolveApiKey() {
+        // 1. Process environment variables
+        if (process.env.AGILEMONSTER_API_KEY && process.env.AGILEMONSTER_API_KEY.trim() !== '') {
+            return process.env.AGILEMONSTER_API_KEY.trim();
+        }
+        if (process.env.AM_API_KEY && process.env.AM_API_KEY.trim() !== '') {
+            return process.env.AM_API_KEY.trim();
+        }
+        // 2. Project config (.agilemonster.json)
+        const projectConfig = this.loadProjectConfig();
+        if (projectConfig?.api_key && projectConfig.api_key.trim() !== '') {
+            return projectConfig.api_key.trim();
+        }
+        // 3. Local .env file in cwd
+        try {
+            const envPath = path.join(this.cwd, '.env');
+            if (fs.existsSync(envPath)) {
+                const envContent = fs.readFileSync(envPath, 'utf8');
+                const match = envContent.match(/(?:AGILEMONSTER_API_KEY|AM_API_KEY)\s*=\s*["']?([a-zA-Z0-9_-]+)["']?/);
+                if (match && match[1]) {
+                    return match[1].trim();
+                }
+            }
+        }
+        catch {
+            // Ignore .env read error
+        }
+        // 4. Global developer config (~/.agilemonster/config.json)
+        try {
+            const homedir = process.env.HOME || process.env.USERPROFILE || '';
+            if (homedir) {
+                const globalConfigPath = path.join(homedir, '.agilemonster', 'config.json');
+                if (fs.existsSync(globalConfigPath)) {
+                    const globalRaw = fs.readFileSync(globalConfigPath, 'utf8');
+                    const parsed = JSON.parse(globalRaw);
+                    if (parsed.api_key && typeof parsed.api_key === 'string') {
+                        return parsed.api_key.trim();
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore global config read error
+        }
+        return '';
+    }
+    getApiKey() {
+        return this.apiKey;
+    }
+    setApiKey(key) {
+        this.apiKey = key;
+    }
+    loadProjectConfig() {
+        if (this.cachedConfig !== undefined) {
+            return this.cachedConfig;
+        }
+        try {
+            let currentDir = this.cwd;
+            while (currentDir !== path.parse(currentDir).root) {
+                const configPath = path.join(currentDir, '.agilemonster.json');
+                if (fs.existsSync(configPath)) {
+                    const content = fs.readFileSync(configPath, 'utf8');
+                    this.cachedConfig = JSON.parse(content);
+                    return this.cachedConfig;
+                }
+                currentDir = path.dirname(currentDir);
+            }
+        }
+        catch {
+            // Ignore reading error
+        }
+        this.cachedConfig = null;
+        return null;
+    }
+    saveProjectConfig(config, dir) {
+        const targetDir = dir || this.cwd;
+        const configPath = path.join(targetDir, '.agilemonster.json');
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+        this.cachedConfig = config;
+        return configPath;
+    }
+    static saveGlobalConfig(data) {
+        const homedir = process.env.HOME || process.env.USERPROFILE || '';
+        if (!homedir)
+            throw new Error('Cannot locate home directory');
+        const dir = path.join(homedir, '.agilemonster');
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const configPath = path.join(dir, 'config.json');
+        let existing = {};
+        try {
+            if (fs.existsSync(configPath)) {
+                existing = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            }
+        }
+        catch { }
+        const merged = { ...existing, ...data };
+        fs.writeFileSync(configPath, JSON.stringify(merged, null, 2), 'utf8');
+        return configPath;
+    }
+    async request(endpoint, options = {}) {
+        if (!this.apiKey) {
+            throw new Error('Missing AGILEMONSTER_API_KEY. Generate a Personal API Key in Agile Monster (Profile -> API Keys) and set it in your environment or MCP config.');
+        }
+        const url = `${this.baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(options.headers || {}),
+        };
+        const res = await fetch(url, {
+            ...options,
+            headers,
+        });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // Not JSON
+        }
+        if (!res.ok) {
+            const msg = json?.message || json?.error || `HTTP ${res.status}: ${text.slice(0, 150)}`;
+            throw new Error(`Agile Monster API Error: ${msg}`);
+        }
+        return json;
+    }
+    async me() {
+        return this.request('/api/agent/me');
+    }
+    async getContext(projectName, boardId) {
+        const params = new URLSearchParams();
+        if (projectName)
+            params.set('project_name', projectName);
+        if (boardId)
+            params.set('board_id', boardId);
+        const qs = params.toString();
+        return this.request(`/api/agent/context${qs ? `?${qs}` : ''}`);
+    }
+    async listAssigned(provider = 'any', status, boardId, workspaceId) {
+        const params = new URLSearchParams();
+        if (provider)
+            params.set('provider', provider);
+        if (status)
+            params.set('status', status);
+        if (boardId)
+            params.set('board_id', boardId);
+        if (workspaceId)
+            params.set('workspace_id', workspaceId);
+        const qs = params.toString();
+        return this.request(`/api/agent/assigned${qs ? `?${qs}` : ''}`);
+    }
+    async claimTask(cardId, provider, runRef) {
+        return this.request(`/api/agent/cards/${cardId}/claim`, {
+            method: 'POST',
+            body: JSON.stringify({ provider, run_ref: runRef }),
+        });
+    }
+    async askQuestion(cardId, provider, question) {
+        return this.request(`/api/agent/cards/${cardId}/ask-question`, {
+            method: 'POST',
+            body: JSON.stringify({ provider, question }),
+        });
+    }
+    async addProgress(cardId, provider, update, tokensUsed, costUsd) {
+        return this.request(`/api/agent/cards/${cardId}/progress`, {
+            method: 'POST',
+            body: JSON.stringify({
+                provider,
+                update,
+                tokens_used: tokensUsed,
+                cost_usd: costUsd,
+            }),
+        });
+    }
+    async recordSpend(cardId, provider, tokens, costUsd, note) {
+        return this.request(`/api/agent/cards/${cardId}/spend`, {
+            method: 'POST',
+            body: JSON.stringify({
+                provider,
+                tokens,
+                cost_usd: costUsd,
+                note,
+            }),
+        });
+    }
+    async setBudget(cardId, maxBudgetUsd, maxTokens) {
+        return this.request(`/api/agent/cards/${cardId}/budget`, {
+            method: 'POST',
+            body: JSON.stringify({
+                max_budget_usd: maxBudgetUsd,
+                max_tokens: maxTokens,
+            }),
+        });
+    }
+    async submitReview(cardId, provider, summary, verificationSteps, targetList, assignToUserId) {
+        return this.request(`/api/agent/cards/${cardId}/submit-review`, {
+            method: 'POST',
+            body: JSON.stringify({
+                provider,
+                summary,
+                verification_steps: verificationSteps,
+                target_list: targetList,
+                target_list_id: targetList,
+                target_list_name: targetList,
+                assign_to_user_id: assignToUserId,
+            }),
+        });
+    }
+    async completeTask(cardId, provider, comment) {
+        return this.request(`/api/agent/cards/${cardId}/complete`, {
+            method: 'POST',
+            body: JSON.stringify({ provider, comment }),
+        });
+    }
+    async blockTask(cardId, provider, comment) {
+        return this.request(`/api/agent/cards/${cardId}/block`, {
+            method: 'POST',
+            body: JSON.stringify({ provider, comment }),
+        });
+    }
+    async createFollowupTasks(cardId, provider, tasks) {
+        return this.request(`/api/agent/cards/${cardId}/followup-tasks`, {
+            method: 'POST',
+            body: JSON.stringify({ provider, tasks }),
+        });
+    }
+}

package/dist/guidelines.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_GUIDELINES_MARKDOWN = "# Autonomous AI Agent Operational Guidelines (Agile Monster)\n\nThis document provides mandatory operational protocols for AI coding assistants (**Cursor, Claude Code, Antigravity, Codex, Hermes Agent, Windsurf, Aider**) working inside repositories integrated with **Agile Monster** (https://app.agilemonster.com).\n\n---\n\n## \uD83E\uDDED Core Principles\n\n1. **The Agile Monster Board is the Source of Truth**: \n   All non-trivial feature additions, bug fixes, refactors, and deployments must correspond to a task on the project's Agile Monster board.\n2. **One Active Assignee**: \n   Work on cards assigned specifically to your agent provider (`cursor`, `claude_code`, `antigravity`, `codex`, `hermes`, `windsurf`, `aider`, or `custom`). Never claim or alter tasks assigned to other agents or human teammates without explicit user direction.\n3. **No Hallucinated Requirements**: \n   When a specification, API schema, or environment variable is ambiguous, stop and ask the user rather than guessing.\n4. **Human Verification Gate**: \n   Autonomous agents must **never** close a task directly to `Done`. You must submit work for human testing and verification using `agilemonster_submit_for_review`.\n\n---\n\n## \uD83D\uDD04 Task Lifecycle Protocol\n\nFollow this exact sequential protocol when working on any task:\n\n1. **Context & Discovery**:\n   - Inspect `.agilemonster.json` in the project root if present.\n   - Run `agilemonster_get_context` to retrieve the board ID, list columns (`Backlog`, `In Progress`, `Review`, `Done`), and active tasks.\n\n2. **Task Intake**:\n   - Check which tasks are queued for your agent using `agilemonster_list_my_tasks({ \"status\": \"queued\" })`.\n   - Confirm the card is assigned to your provider before proceeding.\n\n3. **Claiming the Task**:\n   - Before editing files or running build tools, claim the task:\n     `agilemonster_claim_task({ \"card_id\": \"<card_uuid>\" })`\n   - This moves the card status to `in_progress` and logs an activity event on the board.\n\n4. **Implementation, Questions & Progress**:\n   - **When Blocked or Unclear**: Call `agilemonster_ask_question({ \"card_id\": \"<card_uuid>\", \"question\": \"...\" })`. This sets status to `waiting_for_input` so the user is alerted.\n   - **Logging Progress**: For non-trivial milestones, call `agilemonster_add_progress({ \"card_id\": \"<card_uuid>\", \"update\": \"...\", \"tokens_used\": 1500, \"cost_usd\": 0.003 })`.\n   - **Cost Safeguards**: Use `agilemonster_set_budget` and `agilemonster_record_spend` to protect against runaway billing loops.\n\n5. **Submission for Human Review & Testing**:\n   - When code is implemented, compiled, and tested locally:\n   - Call `agilemonster_submit_for_review({ \"card_id\": \"<card_uuid>\", \"summary\": \"...\", \"verification_steps\": \"...\" })`.\n   - This automatically moves the card to the board's **Testing / QA / Review** column, reassigns the card back to the human who requested it, sets `agent_status` to `review`, and posts step-by-step verification instructions.\n   - Never mark the card directly as \"Done\". The user will verify your test steps and sign off.\n\n6. **Suggest Follow-Up Tasks**:\n   - Proactively suggest follow-up cards (deploy to test/staging, deploy to production, add integration tests) using:\n     `agilemonster_create_followup_tasks({ \"card_id\": \"<card_uuid>\", \"tasks\": [...] })`.\n";

package/dist/guidelines.js

@@ -0,0 +1,51 @@
+export const AGENT_GUIDELINES_MARKDOWN = `# Autonomous AI Agent Operational Guidelines (Agile Monster)
+
+This document provides mandatory operational protocols for AI coding assistants (**Cursor, Claude Code, Antigravity, Codex, Hermes Agent, Windsurf, Aider**) working inside repositories integrated with **Agile Monster** (https://app.agilemonster.com).
+
+---
+
+## 🧭 Core Principles
+
+1. **The Agile Monster Board is the Source of Truth**: 
+   All non-trivial feature additions, bug fixes, refactors, and deployments must correspond to a task on the project's Agile Monster board.
+2. **One Active Assignee**: 
+   Work on cards assigned specifically to your agent provider (\`cursor\`, \`claude_code\`, \`antigravity\`, \`codex\`, \`hermes\`, \`windsurf\`, \`aider\`, or \`custom\`). Never claim or alter tasks assigned to other agents or human teammates without explicit user direction.
+3. **No Hallucinated Requirements**: 
+   When a specification, API schema, or environment variable is ambiguous, stop and ask the user rather than guessing.
+4. **Human Verification Gate**: 
+   Autonomous agents must **never** close a task directly to \`Done\`. You must submit work for human testing and verification using \`agilemonster_submit_for_review\`.
+
+---
+
+## 🔄 Task Lifecycle Protocol
+
+Follow this exact sequential protocol when working on any task:
+
+1. **Context & Discovery**:
+   - Inspect \`.agilemonster.json\` in the project root if present.
+   - Run \`agilemonster_get_context\` to retrieve the board ID, list columns (\`Backlog\`, \`In Progress\`, \`Review\`, \`Done\`), and active tasks.
+
+2. **Task Intake**:
+   - Check which tasks are queued for your agent using \`agilemonster_list_my_tasks({ "status": "queued" })\`.
+   - Confirm the card is assigned to your provider before proceeding.
+
+3. **Claiming the Task**:
+   - Before editing files or running build tools, claim the task:
+     \`agilemonster_claim_task({ "card_id": "<card_uuid>" })\`
+   - This moves the card status to \`in_progress\` and logs an activity event on the board.
+
+4. **Implementation, Questions & Progress**:
+   - **When Blocked or Unclear**: Call \`agilemonster_ask_question({ "card_id": "<card_uuid>", "question": "..." })\`. This sets status to \`waiting_for_input\` so the user is alerted.
+   - **Logging Progress**: For non-trivial milestones, call \`agilemonster_add_progress({ "card_id": "<card_uuid>", "update": "...", "tokens_used": 1500, "cost_usd": 0.003 })\`.
+   - **Cost Safeguards**: Use \`agilemonster_set_budget\` and \`agilemonster_record_spend\` to protect against runaway billing loops.
+
+5. **Submission for Human Review & Testing**:
+   - When code is implemented, compiled, and tested locally:
+   - Call \`agilemonster_submit_for_review({ "card_id": "<card_uuid>", "summary": "...", "verification_steps": "..." })\`.
+   - This automatically moves the card to the board's **Testing / QA / Review** column, reassigns the card back to the human who requested it, sets \`agent_status\` to \`review\`, and posts step-by-step verification instructions.
+   - Never mark the card directly as "Done". The user will verify your test steps and sign off.
+
+6. **Suggest Follow-Up Tasks**:
+   - Proactively suggest follow-up cards (deploy to test/staging, deploy to production, add integration tests) using:
+     \`agilemonster_create_followup_tasks({ "card_id": "<card_uuid>", "tasks": [...] })\`.
+`;