⚔️ Storm the Keep

A gamified developer onboarding experience that teaches new team members about your repository through an RPG-style adventure.

📥 Install into Your Repo!

Get Storm the Keep running in your repository in two simple steps:

1. Add Storm the Keep — Install as a git submodule (recommended) or download as a directory

   git submodule add https://github.com/gaming-microsoft/stormthekeep.git stormthekeep

   👉 Full Installation Guide

2. Define Agents & Quests — Create your .stk-config/ directory with agents and quests

   your-repo/
   ├── stormthekeep/       # The app (git submodule)
   └── .stk-config/        # Your configuration
       ├── config.json     # Repository metadata
       ├── AGENTS.md       # AI agent personalities
       └── quests/         # Onboarding quests
   

   👉 Configuration Guide

---

🎮 Overview

Storm the Keep transforms the daunting task of learning a new codebase into an engaging adventure. New developers ("players") complete quests to learn about the repository while unlocking AI agent "party members" who assist them in their development journey.

The Party Members (AI Agents)

Agent	Role	Teaches
📚 The Lorekeeper	Code understanding & Q&A	Research phase of R.P.I.
🔨 The Blacksmith	PR creation & testing	Implementation & code quality
😴 The Bored Guy	Repetitive tasks	Unit tests & scaffolding
🌟 The Protégé	Full feature development	Task delegation & workflows
🧙 The Wizard	Architecture & orchestration	Full R.P.I. with team delegation

R.P.I. Method

Research, Plan, Implement - The core methodology taught throughout the onboarding:

1. Research - Understand the problem, explore the codebase, gather requirements
2. Plan - Design your solution, break it into tasks, outline the approach
3. Implement - Write code, create tests, ship your changes

🚀 Quick Start

# Install dependencies
npm install

# Start development server (runs both frontend and backend)
npm run dev

The app will be available at http://localhost:7053.

By default, the development server will automatically open your browser. To disable this behavior, set the SKIP_BROWSER_LAUNCH environment variable:

SKIP_BROWSER_LAUNCH=true npm run dev

📦 Installation as Submodule

To add Storm the Keep to your repository:

# Add as a git submodule
git submodule add https://github.com/gaming-microsoft/stormthekeep.git stormthekeep

# Initialize and update
git submodule init
git submodule update

🔧 Configuration

Storm the Keep uses a two-tier configuration system that separates core agent behavior (managed centrally) from repository-specific customization (managed by you).

Two-Tier Configuration

1. Root Configuration (.stk-root-config/ - in this repo)

   • Core agent instructions and safety guidelines
   • Agent permissions and capabilities
   • Generic role definitions
   • Cannot be overridden by downstream repos

2. Repository Configuration (.stk-config/ - in your repo)

   • Custom agent names and personalities
   • Repository-specific context
   • Quests and unlock messages
   • Inherits all core instructions from root

This ensures consistent safety and behavior while allowing full customization of personality and context.

Create a .stk-config directory in your repository root with the following structure:

your-repo/
├── .stk-config/            # Configuration directory
│   ├── config.json         # Main configuration
│   ├── AGENTS.md           # Agent definitions (optional)
│   └── quests/             # Quest definitions
│       ├── lorekeeper/     # Quests for The Lorekeeper
│       │   ├── 01-welcome.json
│       │   └── 02-research.json
│       ├── blacksmith/     # Quests for The Blacksmith
│       ├── boredguy/       # Quests for The Bored Guy
│       ├── protege/        # Quests for The Protégé
│       └── wizard/         # Quests for The Wizard
└── stormthekeep/           # This app (git submodule)

config.json

{
  "repo": {
    "name": "Your Repository Name",
    "description": "A brief description of your repository",
    "welcomeMessage": "Welcome message shown to new developers",
    "techStack": ["TypeScript", "React", "Node.js"],
    "repoUrl": "https://github.com/your-org/your-repo"
  },
  "agents": {
    "lorekeeper": {
      "unlockMessage": "Custom message when Lorekeeper is unlocked"
    }
  },
  "progression": {
    "questsPerAgent": 5,
    "allowSkip": false,
    "showLockedQuests": true
  },
  "aiIntegration": {
    "provider": "roocode"
  }
}

AGENTS.md (Optional)

Customize agent personalities and add repository-specific context. Your customizations will be merged with the core agent instructions.

---
name: Lorekeeper
description: Your custom description
prompt: |
  # Repository-Specific Personality
  
  You are The Lorekeeper of OUR SPECIFIC codebase.
  Special context about OUR repository goes here.
  
  ## Our Conventions
  - We use X pattern for Y
  - Our testing strategy is Z
---

Important: Core safety guidelines and permissions are inherited from the root configuration and cannot be overridden. Your AGENTS.md should focus on personality and repository-specific context.

For detailed examples, see .stk-root-config/README.md and example-config/AGENTS.md.

Quest Definition

{
  "id": "unique-quest-id",
  "title": "Quest Title",
  "description": "What the player needs to do",
  "agent": "lorekeeper",
  "order": 1,
  "storyText": "Narrative text displayed in the quest",
  "objectives": [
    {
      "id": "obj-1",
      "description": "First objective description",
      "verification": {
        "type": "file",
        "config": {
          "path": "src/index.ts",
          "condition": "exists"
        }
      }
    }
  ],
  "hints": ["Hint 1", "Hint 2"],
  "resources": [
    {
      "title": "Documentation",
      "url": "https://docs.example.com",
      "type": "docs"
    }
  ],
  "verification": {
    "type": "manual",
    "config": {
      "confirmationText": "I have completed this quest"
    }
  },
  "completionMessage": "Message shown when quest is complete",
  "xpReward": 100
}

📋 Verification Types

Storm the Keep supports multiple verification methods for quest completion:

Manual

Player self-confirms completion:

{
  "type": "manual",
  "config": {
    "confirmationText": "I have completed this task"
  }
}

File

Check if a file exists or contains content:

{
  "type": "file",
  "config": {
    "path": "src/components/Button.tsx",
    "condition": "exists"
  }
}

Conditions: exists, not-exists, contains, matches

Command

Run a terminal command and check the result:

{
  "type": "command",
  "config": {
    "command": "npm test",
    "expectedExitCode": 0
  }
}

Git

Check git repository state:

{
  "type": "git",
  "config": {
    "type": "branch-exists",
    "name": "feature/my-feature"
  }
}

Git types: branch-exists, branch-current, has-commits, file-staged, clean-working-tree, remote-exists

Environment

Check environment setup:

{
  "type": "env",
  "config": {
    "type": "node-version",
    "minVersion": "18.0.0"
  }
}

Env types: node-version, npm-version, command-exists, env-var, custom

Composite

Combine multiple checks:

{
  "type": "composite",
  "config": {
    "operator": "and",
    "checks": [
      { "type": "file", "config": { "path": "src/index.ts", "condition": "exists" } },
      { "type": "command", "config": { "command": "npm test", "expectedExitCode": 0 } }
    ]
  }
}

🎨 Customization

Custom Agent Portraits

Place custom images in .stk-config/assets/agents/:

• lorekeeper.png
• blacksmith.png
• boredguy.png
• protege.png
• wizard.png

Custom Theme

Add a .stk-config/assets/custom-theme.css file to override styles.

🏗️ Development

Project Structure

stormTheKeep/
├── src/
│   ├── components/     # React components
│   ├── screens/        # Page components
│   ├── stores/         # Zustand state stores
│   ├── hooks/          # Custom React hooks
│   ├── types/          # TypeScript types
│   └── services/       # API and verification services
├── server/             # Express verification backend
├── example-config/     # Example configuration
└── public/             # Static assets

Scripts

Script	Description
npm run dev	Start development server
npm run dev:client	Start only the frontend
npm run dev:server	Start only the backend
npm run build	Build for production
npm run preview	Preview production build

Tech Stack

• Frontend: React 18, TypeScript, Tailwind CSS, Zustand, Framer Motion
• Backend: Express.js, simple-git
• Build: Vite
• Telemetry: Azure Application Insights (optional)

Telemetry (Optional)

Storm the Keep includes built-in telemetry support to track quest completion, CLI usage, and user feedback. Telemetry is completely optional and disabled by default.

To enable telemetry:

• Set up Azure Application Insights (see Telemetry Setup Guide)
• Add the connection string to your config.json under "stkTelemetry"
• Users can opt-out via the privacy banner shown on first launch

🤝 AI Integration

Storm the Keep is designed to work with AI coding assistants, particularly Roo Code. Each agent maps to specific Roo Code modes:

Agent	Primary Mode	Use Case
Lorekeeper	Ask	Understanding code
Blacksmith	Code	Writing & reviewing
Bored Guy	Code	Repetitive tasks
Protégé	Code + Orchestrator	Features & delegation
Wizard	Architect + Orchestrator	Design & coordination

📝 License

MIT

👥 Contributors

• Brandon Hush - Primary Contributor

🙏 Acknowledgments

Inspired by Block's Champion's Program and the R.P.I. methodology for AI-assisted development.