IDEL RPG

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:

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:

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.

Related MCP server: roadmap-skill

Quick Start

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:

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:

pnpm build
pnpm idelrpg:mcp

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

{
  "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.

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:

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.

Local Webhook Server

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

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:

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

Supported GitHub events in the local webhook MVP:

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

Optional webhook environment variables:

Development

This is a TypeScript pnpm workspace.

pnpm install
pnpm build
pnpm test
pnpm typecheck

Package layout: