Idelrpg

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:

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

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:

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.

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:

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.

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.