feat: add Jira integration as issue tracker provider

.husky/pre-commit

@@ -1,3 +1,10 @@
+#!/bin/sh
+# Set up PATH for pnpm if not already in PATH
+if ! command -v pnpm >/dev/null 2>&1; then
+  export PNPM_HOME="${PNPM_HOME:-$HOME/.local/share/pnpm}"
+  export PATH="$PNPM_HOME:$PATH"
+fi
+
 # Run linting
 pnpm run lint
 

DEBUGGING_MCP.md

@@ -0,0 +1,178 @@
+# Debugging iloom MCP Servers
+
+When you see "issue_management · ✘ failed" in Claude Code, it means the MCP server isn't starting properly. Here's how to debug it:
+
+## 1. Check MCP Server Logs
+
+The MCP server logs errors to stderr. To see them:
+
+```bash
+# Navigate to your project with iloom configured
+cd /path/to/your/project
+
+# Start a loom (this generates the MCP config)
+il start YOUR-ISSUE-123
+
+# The MCP server is launched by Claude Code
+# Check Claude Code's output panel for errors
+```
+
+## 2. Test MCP Server Manually
+
+You can test the MCP server directly:
+
+```bash
+# Set required environment variables for Jira
+export ISSUE_PROVIDER=jira
+export JIRA_HOST="https://yourcompany.atlassian.net"
+export JIRA_USERNAME="your.email@company.com"
+export JIRA_API_TOKEN="your-api-token"
+export JIRA_PROJECT_KEY="PROJ"
+
+# Optional: transition mappings
+export JIRA_TRANSITION_MAPPINGS='{"In Review":"Start Review"}'
+
+# Run the MCP server
+node dist/mcp/issue-management-server.js
+```
+
+The server should start and output:
+```
+Starting Issue Management MCP Server...
+Environment validated
+Issue management provider: jira
+```
+
+## 3. Common Issues
+
+### Missing Environment Variables
+
+**Error:** `Missing required environment variables for Jira provider: ...`
+
+**Solution:** Ensure all required Jira settings are in your `.iloom/settings.local.json`:
+
+```json
+{
+  "issueManagement": {
+    "jira": {
+      "apiToken": "your-api-token-here"
+    }
+  }
+}
+```
+
+And in `.iloom/settings.json`:
+```json
+{
+  "issueManagement": {
+    "provider": "jira",
+    "jira": {
+      "host": "https://yourcompany.atlassian.net",
+      "username": "your.email@company.com",
+      "projectKey": "PROJ"
+    }
+  }
+}
+```
+
+### Invalid Provider
+
+**Error:** `Invalid ISSUE_PROVIDER: ... Must be 'github', 'linear', or 'jira'`
+
+**Solution:** Check that `issueManagement.provider` in your settings is set to one of the supported values.
+
+### API Authentication Failure
+
+**Error:** `Jira API error (401): ...`
+
+**Solution:** 
+1. Verify your Jira API token is correct
+2. Generate a new token at: https://id.atlassian.com/manage-profile/security/api-tokens
+3. Ensure the token has proper permissions
+
+**Error:** `Jira API error (403): ...`
+
+**Solution:** Your user account may not have permission to access the Jira project. Contact your Jira administrator.
+
+## 4. Check MCP Configuration
+
+iloom generates MCP configuration that Claude Code uses. You can inspect it:
+
+```bash
+# Check what MCP config iloom would generate
+il start --help  # This won't actually start, but shows the config
+
+# Or manually test config generation:
+node -e "
+const { generateIssueManagementMcpConfig } = require('./dist/utils/mcp.js');
+const { loadSettings } = require('./dist/lib/SettingsManager.js');
+
+(async () => {
+  const settings = await loadSettings();
+  const config = await generateIssueManagementMcpConfig(
+    'issue',
+    null,
+    'jira',
+    settings
+  );
+  console.log(JSON.stringify(config, null, 2));
+})();
+"
+```
+
+## 5. Verbose Logging
+
+To see more detailed logs, set the DEBUG environment variable before starting Claude Code:
+
+```bash
+# On macOS/Linux
+export DEBUG=iloom:*
+
+# On Windows (PowerShell)
+$env:DEBUG="iloom:*"
+
+# Then start Claude Code
+```
+
+## 6. Test Jira Connection
+
+Test that iloom can connect to Jira:
+
+```bash
+# This will attempt to fetch an issue
+il start PROJ-123
+
+# If successful, you should see:
+# ✓ Issue found: PROJ-123
+```
+
+## 7. Claude Code MCP Settings
+
+Check that Claude Code is configured to use iloom's MCP servers. The config should be in `~/.claude/settings.json` or your project's `.claude/settings.local.json`.
+
+Look for:
+```json
+{
+  "mcpServers": {
+    "issue_management": {
+      "transport": "stdio",
+      "command": "node",
+      "args": ["/path/to/iloom/dist/mcp/issue-management-server.js"],
+      "env": {
+        "ISSUE_PROVIDER": "jira",
+        "JIRA_HOST": "...",
+        // ...other Jira env vars
+      }
+    }
+  }
+}
+```
+
+## 8. Still Having Issues?
+
+If the MCP server still isn't working:
+
+1. **Check iloom version:** Run `il --version` and ensure you have the latest version
+2. **Reinstall dependencies:** `cd /path/to/iloom && pnpm install && pnpm build`
+3. **Check Node version:** MCP servers require Node.js 18 or later
+4. **File an issue:** Include the full error output and your (redacted) settings

README.md

@@ -439,12 +439,61 @@ Integrations
 
 ### Issue Trackers
 
-iloom supports the tools you already use. Unless you use JIRA.
+iloom supports multiple issue tracking providers to fit your team's workflow.
 
 | **Provider** | **Setup** | **Notes** |
 |--------------|-----------|-----------|
 | **GitHub**   | `gh auth login` | Default. Supports Issues and Pull Requests automatically. |
 | **Linear**   | `il init` | Requires API token. Supports full read/write on Linear issues. |
+| **Jira**     | Configure in `.iloom/settings.json` | Atlassian Cloud. Requires API token. See [Jira Setup](#jira-setup) below. |
+
+### Jira Setup
+
+To use Jira as your issue tracker, add this configuration:
+
+**.iloom/settings.json (Committed)**
+```json
+{
+  "issueManagement": {
+    "provider": "jira",
+    "jira": {
+      "host": "https://yourcompany.atlassian.net",
+      "username": "your.email@company.com",
+      "projectKey": "PROJ",
+      "boardId": "123",
+      "doneStatuses": ["Done", "Closed"],
+      "transitionMappings": {
+        "In Review": "Start Review"
+      }
+    }
+  }
+}
+```
+
+**.iloom/settings.local.json (Gitignored - Never commit this file)**
+```json
+{
+  "issueManagement": {
+    "jira": {
+      "apiToken": "your-jira-api-token-here"
+    }
+  }
+}
+```
+
+**Generate a Jira API Token:**
+1. Visit https://id.atlassian.com/manage-profile/security/api-tokens
+2. Click "Create API token"
+3. Copy the token to `.iloom/settings.local.json`
+
+**Configuration Options:**
+- `host`: Your Jira Cloud instance URL
+- `username`: Your Jira email address
+- `apiToken`: API token (store in settings.local.json only!)
+- `projectKey`: Jira project key (e.g., "PROJ", "ENG")
+- `boardId`: (Optional) Board ID for sprint/workflow operations
+- `doneStatuses`: (Optional) Status names to exclude from `il issues` lists (default: `["Done"]`). Set to match your Jira workflow, e.g., `["Done", "Closed", "Verified"]`
+- `transitionMappings`: (Optional) Map iloom states to your Jira workflow transition names
 
 
 ### IDE Support

docs/iloom-commands.md

@@ -1242,6 +1242,8 @@ il issues [options] [project-path]
 |------|-------------|---------|
 | `--json` | Output as JSON (default behavior) | `true` |
 | `--limit <n>` | Maximum number of items to return (combined issues + PRs) | `100` |
+| `--sprint <name>` | **Jira only:** filter by sprint name (e.g., `"Sprint 17"`) or `"current"` for the active sprint | - |
+| `--mine` | **Jira only:** show only issues assigned to the authenticated user | `false` |
 
 **Output Format:**
 ```json
@@ -1279,6 +1281,11 @@ il issues [options] [project-path]
 - Works from worktrees (resolves settings from the correct project root)
 - For issues on GitHub: uses `gh issue list` with `--search sort:updated-desc`
 - For issues on Linear: uses `@linear/sdk` with team key filter from settings
+- For issues on Jira: uses Jira REST API with JQL, excluding statuses listed in `doneStatuses` (default: `["Done"]`)
+- `--sprint` and `--mine` flags are Jira-only. When used with other providers, a warning is logged and the flags are ignored.
+- `--sprint current` uses Jira's `openSprints()` JQL function to match the active sprint
+- `--sprint "Sprint 17"` filters to a specific named sprint
+- `--mine` uses Jira's `currentUser()` JQL function to filter by the authenticated user
 - For PRs: uses `gh pr list --state open` with draft filtering
 
 **Examples:**
@@ -1298,6 +1305,18 @@ il issues | jq '.[] | select(.type == "pr")'
 
 # Filter to only issues using jq
 il issues | jq '.[] | select(.type == "issue")'
+
+# Jira: show issues in the current sprint
+il issues --sprint current
+
+# Jira: show issues in a specific sprint
+il issues --sprint "Sprint 17"
+
+# Jira: show only my issues
+il issues --mine
+
+# Jira: my issues in the current sprint
+il issues --sprint current --mine
 ```
 
 **Notes:**

package.json

@@ -73,6 +73,7 @@
     "deepmerge": "^4.3.1",
     "dotenv-flow": "^4.1.0",
     "execa": "^8.0.1",
+    "extended-markdown-adf-parser": "^2.4.0",
     "fast-glob": "^3.3.3",
     "fs-extra": "^11.1.1",
     "handlebars": "^4.7.8",