# IDEL RPG
<img width="2528" height="1696" alt="idelrpg" src="https://github.com/user-attachments/assets/453b8c6f-19aa-4b41-ad4b-b7101dc80c78" />

IDEL RPG is a local-first RPG layer for agent-assisted software development. This repository starts with the CLI prototype: create a quest, validate real work, claim XP, and grow a tiny engineering guild.

## How the Game Works

IDEL RPG turns real software work into quests. The player is a `Guild Commander`, starts with the `Patchling` companion, and earns progress only when a quest has a real passing validation result. The central rule is:

> No meaningful validation, no meaningful reward.

The normal loop is:

1. Initialize repo-local game state.
2. Create or sync a quest before implementation.
3. Start the quest.
4. Do the work manually or with an agent.
5. Run a real validation command, such as tests, lint, typecheck, or CI.
6. Claim the reward after validation passes.
7. Check profile or dashboard stats for progress.

Agents should use the same discipline: create a quest before implementation, submit validation results only after running real checks, and claim rewards only after a passing validation.

State is stored locally in `.ide-rpg/ide-rpg.sqlite` at the Git repository root. Source code does not need to leave the machine for the local CLI, MCP server, or webhook MVP.

### Quest Model

Each quest has:

- `title`: short human-readable task name.
- `type`: one of `bug_hunt`, `feature_expedition`, `test_forge`, `refactor_ruins`, `lint_cleanup`, or `docs_revival`.
- `goal`: the larger intent. If omitted, the title is used.
- `doneCriteria`: one or more concrete completion checks.
- `validationCommand`: the command that proves the work is ready for reward.
- `difficulty`: one of `trivial`, `small`, `medium`, `large`, or `epic`.
- `risk`: `low`, `medium`, or `high`; currently inferred for synced work and stored for dashboards.
- `source`: `manual`, GitHub, or Linear.

Quest status moves through this lifecycle:

```text
created -> active -> validating -> validated -> claimed
                  \-> active, if validation fails
```

Synced GitHub and Linear items become local quests. If no validation command is configured, IDEL RPG creates a blocking placeholder command so the item cannot accidentally award XP without proof.

### Rewards and Levels

Rewards are intentionally simple in the MVP:

| Difficulty | Hero XP |
| --- | ---: |
| `trivial` | 30 |
| `small` | 120 |
| `medium` | 240 |
| `large` | 500 |
| `epic` | 800 |

Claiming a validated quest also gives Patchling one third of the hero XP and awards a `Local Green` token. Hero and companion levels are calculated as `floor(xp / 100) + 1`. A quest can only be claimed once.

## Quick Start

```bash
pnpm install
pnpm build
pnpm idelrpg init --name "Your Name"
pnpm idelrpg quest create --title "First Green" --type bug_hunt --done "Validation passes" --validation "echo ok"
pnpm idelrpg quest start <quest-id>
pnpm idelrpg validate
pnpm idelrpg claim
pnpm idelrpg profile
```

Useful CLI commands:

```bash
pnpm idelrpg quest list
pnpm idelrpg sync github --url "https://github.com/owner/repo/issues/123" --validation "pnpm test" --start
pnpm idelrpg sync linear --issue ENG-123 --validation "pnpm test" --start
```

## MCP Server

Build the workspace, then run the stdio MCP server from any repo you want IDEL RPG to track:

```bash
pnpm build
pnpm idelrpg:mcp
```

For Codex or another MCP client, configure a stdio server with:

```json
{
  "mcpServers": {
    "idelrpg": {
      "command": "node",
      "args": [
        "/absolute/path/to/IDELRPG/packages/mcp-server/dist/index.js"
      ]
    }
  }
}
```

Available tools:

- `initialize`
- `create_quest`
- `list_quests`
- `start_quest`
- `get_current_quest`
- `sync_github_item`
- `sync_linear_issue`
- `submit_validation_result`
- `claim_reward`
- `show_profile`
- `show_stats`

Available resources:

- `idelrpg://profile`
- `idelrpg://quests/current`
- `idelrpg://quests`
- `idelrpg://dashboard/stats`

`idelrpg://dashboard/stats` is intended for dashboards and IDE surfaces. It returns aggregate JSON for quest counts, quest status/type/difficulty breakdowns, validation pass rate, earned XP, earned tokens, profile state, companions, and recent activity. The CLI remains useful for local visibility, but dashboards should consume the MCP resource or the `show_stats` tool instead of asking developers to run extra commands during normal work.

### MCP Agent Instructions

When connected through MCP, agents should:

1. Call `initialize` if the repo has no local profile yet.
2. Call `create_quest`, `sync_github_item`, or `sync_linear_issue` before making changes.
3. Call `start_quest` when implementation begins.
4. Run the actual validation command in the workspace.
5. Call `submit_validation_result` with the real command, status, exit code, duration, and relevant output.
6. Call `claim_reward` only after a passing validation is recorded.

Use `show_profile`, `show_stats`, and the resources for visibility instead of asking developers to run extra commands during normal agent work.

## GitHub and Linear Sync

External sync creates or updates local quests from GitHub issues/PRs and Linear issues. Rewards still require a real validation result before XP can be claimed.

```bash
pnpm idelrpg sync github \
  --repo jrslyce/IDELRPG \
  --issue 123 \
  --validation "pnpm test" \
  --start

pnpm idelrpg sync github \
  --url "https://github.com/jrslyce/IDELRPG/pull/123" \
  --validation "pnpm test"

LINEAR_API_KEY=lin_api_... pnpm idelrpg sync linear \
  --issue ENG-123 \
  --validation "pnpm test" \
  --start
```

GitHub uses `GITHUB_TOKEN` or `GH_TOKEN` when present, but public issues can sync without a token. Linear requires `LINEAR_API_KEY`.

Label inference helps synced quests land in the right game bucket:

| External signal | IDEL RPG result |
| --- | --- |
| GitHub PR | `feature_expedition` |
| labels containing `bug` or `defect` | `bug_hunt` |
| labels containing `test` | `test_forge` |
| labels containing `refactor` | `refactor_ruins` |
| labels containing `lint` | `lint_cleanup` |
| labels containing `doc` | `docs_revival` |
| labels containing `tiny` or `trivial` | `trivial` difficulty |
| labels containing `medium`, `large`, `epic`, or `xl` | matching difficulty |
| labels containing `risk:medium`, `risk:high`, `breaking`, or similar text | stored quest risk |

## Webhooks and Observation Surfaces

IDEL RPG should not make developers babysit extra commands. The CLI is for local visibility and debugging; automatic game progress should come from the systems developers already use.

| Surface | Direction | Best at | XP behavior | Developer burden |
| --- | --- | --- | --- | --- |
| GitHub webhooks | GitHub pushes events to IDEL RPG | Passive observation of issues, PRs, merges, CI/check results | Can unlock or award XP when validation events pass | Low after setup; needs a reachable webhook URL |
| GitHub/Linear connectors | Codex or the CLI fetches data on demand | Agent-driven sync, manual refresh, testing without webhooks | Creates/updates quests; XP still requires validation | Medium; runs when a user or agent asks |
| MCP server | Agents and dashboards read/write local game state | Quest tools, profile/stats resources, dashboard JSON | Coordinates rewards but should not be the only proof source | Low; agents call it in the background |
| Local validation commands | Developer/agent runs normal checks like `pnpm test` | Proof that work passed locally | Unlocks XP when recorded as passing | Low if tied to commands developers already run |
| GitHub Actions/CI | CI runs on pushes/PRs | Stronger shared proof for team mode | Passing workflow/check webhook can award XP | Very low for devs once CI exists |
| CLI | Human runs `idelrpg profile`, `idelrpg quest list`, etc. | Visibility, setup, debugging, local fallback | Can claim rewards manually | Optional; should not be daily ceremony |

### Local Webhook Server

The webhook server writes to the same repo-local `.ide-rpg/ide-rpg.sqlite` database as the CLI and MCP server.

```bash
pnpm build
pnpm idelrpg:webhook
```

By default it listens on `127.0.0.1:8787`:

- `GET /health`
- `POST /webhooks/github`

For local GitHub webhook testing, expose it through a tunnel such as `ngrok` or `cloudflared`, then configure the GitHub webhook URL as:

```text
https://<your-tunnel>/webhooks/github
```

Supported GitHub events in the local webhook MVP:

| GitHub event | What IDEL RPG does |
| --- | --- |
| `issues` | Creates or updates a quest from the issue. |
| `pull_request` | Creates or updates a quest from the PR. |
| `workflow_run` | Records validation for a linked PR; passing runs can auto-claim rewards. |
| `check_suite` | Records validation for a linked PR; passing suites can auto-claim rewards. |

Use `IDELRPG_WEBHOOK_SECRET` to verify GitHub's `x-hub-signature-256` header in local or hosted deployments.

Optional webhook environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `IDELRPG_WEBHOOK_HOST` | `127.0.0.1` | Bind address for the local webhook server. |
| `IDELRPG_WEBHOOK_PORT` | `8787` | Port for the local webhook server. |
| `IDELRPG_WEBHOOK_SECRET` | unset | GitHub webhook signature verification secret. |

## Development

This is a TypeScript pnpm workspace.

```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
```

Package layout:

| Package | Purpose |
| --- | --- |
| `packages/core` | Quest lifecycle, IDs, profile types, levels, and validation state transitions. |
| `packages/scoring` | XP, companion XP, and token reward calculation. |
| `packages/storage` | Repo-local SQLite state in `.ide-rpg/ide-rpg.sqlite`. |
| `packages/validation` | Shell command runner used by `idelrpg validate`. |
| `packages/cli` | Human-facing local CLI. |
| `packages/mcp-server` | MCP tools and resources for agents and dashboards. |
| `packages/integrations` | GitHub and Linear fetch/sync helpers. |
| `packages/webhook-server` | Local GitHub webhook receiver for passive quest and validation updates. |