mantis-manager

What this skill does

# Mantis Manager Skill (Enhanced)

## 🔐 Base URL & Token Resolution

### Base URL Resolution
Base URL precedence (highest to lowest):
1. `temporary_base_url` — one-time use URL for specific operations
2. `user_base_url` — user-defined URL for the current session
3. `MANTIS_BASE_URL` — environment default URL

This allows you to:
- Switch between multiple Mantis instances dynamically
- Test against staging/production environments
- Work with different client instances without changing config

**Example:**
```
// Default: uses MANTIS_BASE_URL from environment
GET {{resolved_base_url}}/issues

// Override for one operation:
temporary_base_url = "https://mantis-staging.example.com/api/rest"
GET {{resolved_base_url}}/issues

// Override for session:
user_base_url = "https://client-mantis.example.com/api/rest"
GET {{resolved_base_url}}/issues
```

### Token Resolution
Token precedence (highest to lowest):
1. `temporary_token` — one-time use token for specific operations
2. `user_token` — user-defined token for the current session
3. `MANTIS_API_TOKEN` — environment default token

Environment variables are handled via standard OpenClaw metadata: `requires.env` declares **required** variables (`MANTIS_BASE_URL`, `MANTIS_API_TOKEN`). Any other environment variables you use for Mantis should be treated as normal process env vars and are not modeled as special OpenClaw metadata fields.

### Authentication Headers
**All API requests must include:**

```
Authorization: Bearer {{resolved_token}}
Content-Type: application/json
```

**Note:** The `{{resolved_base_url}}` and `{{resolved_token}}` are determined at runtime based on the precedence rules above.

---

## 📌 Notation Used in Examples

Throughout this documentation:
- `{{MANTIS_BASE_URL}}` refers to the **resolved base URL** (could be temporary_base_url, user_base_url, or env MANTIS_BASE_URL)
- `{{resolved_token}}` refers to the **resolved token** (could be temporary_token, user_token, or env MANTIS_API_TOKEN)
- All endpoints use the pattern: `{{MANTIS_BASE_URL}}/resource/path`

**Important:** Always use the resolution logic to determine the actual URL and token at runtime.

---

## 🔄 Context Management

> The `temporary_*` and `user_*` names here are **runtime context variables used by the skill logic**, not OpenClaw metadata fields. OpenClaw does **not** define an `optional.context` metadata key; context is resolved dynamically at runtime as described below.

### Setting Temporary Values (One-Time Use)

**User queries:**
- "Use https://staging.mantis.com/api/rest for this request"
- "Connect to production instance for this operation"
- "Use token ABC123 just this once"

**Action:**
```
Set temporary_base_url = "https://staging.mantis.com/api/rest"
Set temporary_token = "ABC123"
... perform operation ...
Clear temporary_base_url
Clear temporary_token
```

**Behavior:** Temporary values are automatically cleared after one use.

### Setting Session Values (Current Session)

**User queries:**
- "Switch to client XYZ's Mantis instance"
- "Use my personal API token for all requests"
- "Connect to staging environment"

**Action:**
```
Set user_base_url = "https://client-xyz.mantis.com/api/rest"
Set user_token = "personal_token_123"
... perform multiple operations ...
// Values persist for the entire session
```

**Behavior:** Session values persist until explicitly cleared or session ends.

### Clearing Context Values

**User queries:**
- "Reset to default Mantis instance"
- "Clear my custom token"
- "Go back to environment defaults"

**Action:**
```
Clear user_base_url
Clear user_token
// Now uses MANTIS_BASE_URL and MANTIS_API_TOKEN from environment
```

### Viewing Current Context

**User queries:**
- "What Mantis instance am I connected to?"
- "Show current API configuration"
- "Which token am I using?"

**Response should show:**
```
Current Context:
- Base URL: https://client-xyz.mantis.com/api/rest (user_base_url)
- Token: user_t***123 (user_token)
- Fallback Base URL: https://default.mantis.com/api/rest (MANTIS_BASE_URL)
- Fallback Token: env_t***789 (MANTIS_API_TOKEN)
```

### Use Cases

#### Multi-Instance Management
```
// Check production issue
Set temporary_base_url = "https://prod.mantis.com/api/rest"
Get issue 123

// Check staging issue  
Set temporary_base_url = "https://staging.mantis.com/api/rest"
Get issue 123

// Compare results
```

#### Client Switching
```
// Switch to Client A
Set user_base_url = "https://clienta.mantis.com/api/rest"
Set user_token = "clienta_token"
List all projects
Get issues for project 5

// Switch to Client B
Set user_base_url = "https://clientb.mantis.com/api/rest"
Set user_token = "clientb_token"
List all projects
Get issues for project 3
```

#### Admin Operations with Impersonation
```
// Connect to main instance as admin
Set user_token = "admin_token"

// Perform operation as specific user
Set temporary header: X-Impersonate-User = "john.doe"
Get user issues

// Back to admin
Clear temporary header
```

---

## 🐞 ISSUES Operations

### List Issues
**User queries:**
- "List all issues"
- "Get issues for project 5"
- "Get issues matching filter 10"
- "Show issues assigned to me"
- "Get unassigned issues"

**Actions:**
```
GET {{MANTIS_BASE_URL}}/issues
```

**Query Parameters:**
- `page_size` — number of issues per page (default: 50)
- `page` — page number (1-indexed)
- `filter_id` — ID of saved filter to apply
- `project_id` — filter by specific project
- `select` — comma-separated fields to return (e.g., "id,summary,status")

**Special endpoints:**
```
GET {{MANTIS_BASE_URL}}/issues?filter_id={{filter_id}}
GET {{MANTIS_BASE_URL}}/projects/{{project_id}}/issues
```

### Get Single Issue
**User queries:**
- "Show issue 123"
- "Get details for bug 456"

**Action:**
```
GET {{MANTIS_BASE_URL}}/issues/{{id}}
```

### Create Issue
**User queries:**
- "Create issue with summary 'Login bug' and description 'Cannot login'"
- "Create bug in project 5 with priority high"
- "Create issue with attachments"

**Action:**
```
POST {{MANTIS_BASE_URL}}/issues
```

**Minimal body:**
```json
{
  "summary": "Issue summary",
  "description": "Detailed description",
  "category": {"name": "General"},
  "project": {"id": 1}
}
```

**Full body (optional fields):**
```json
{
  "summary": "Issue summary",
  "description": "Detailed description",
  "steps_to_reproduce": "1. Do this\n2. Do that",
  "additional_information": "Extra info",
  "category": {"id": 1, "name": "General"},
  "project": {"id": 1},
  "priority": {"id": 30, "name": "normal"},
  "severity": {"id": 50, "name": "minor"},
  "status": {"id": 10, "name": "new"},
  "reproducibility": {"id": 10, "name": "always"},
  "handler": {"id": 5},
  "tags": [{"name": "bug"}, {"name": "ui"}],
  "custom_fields": [{"field": {"id": 1}, "value": "custom value"}],
  "due_date": "2026-12-31T23:59:59+00:00",
  "version": {"name": "1.0"},
  "target_version": {"name": "2.0"}
}
```

**Create with attachments:**
```
POST {{MANTIS_BASE_URL}}/issues
```
Include `files` array in body with base64-encoded content.

### Update Issue
**User queries:**
- "Update issue 123 status to resolved"
- "Change priority of bug 456 to high"
- "Assign issue 789 to user 10"

**Action:**
```
PATCH {{MANTIS_BASE_URL}}/issues/{{id}}
```

**Example body:**
```json
{
  "status": {"name": "resolved"},
  "handler": {"id": 10},
  "priority": {"name": "high"},
  "summary": "Updated summary"
}
```

### Delete Issue
**User queries:**
- "Delete issue 123"
- "Remove bug 456"

**Action:**
```
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}
```

### Monitor/Unmonitor Issue
**User queries:**
- "Monitor issue 123"
- "Stop monitoring bug 456"
- "Add user 10 as monitor on issue 789"

**Actions:*