@jarrodmedrano/claude-skills 1.0.2 → 1.0.3

package/.claude/skills/level-design/procedural-handmade.md

@@ -0,0 +1,271 @@
+# Procedural and Handmade Level Design Integration
+
+Based on Chapter 11: "Integrating Procedural and Handmade Level Design" by Mark R. Johnson.
+
+## The Two Approaches
+
+### Procedural Content Generation (PCG)
+Algorithmic creation of game content: levels, items, enemies, stories.
+
+**Strengths:**
+- Massive replay value
+- Reduced development time per unit content
+- Surprise even for developers
+- Adaptive difficulty potential
+
+**Weaknesses:**
+- Can feel same-y across generations
+- Difficult to guarantee specific experiences
+- Narrative hard to generate
+- Quality floors vary
+
+### Handmade Content
+Designer-crafted levels and experiences.
+
+**Strengths:**
+- Precise control over experience
+- Guaranteed quality
+- Narrative coherence
+- Specific memorable moments
+
+**Weaknesses:**
+- Time-intensive
+- Limited replay value
+- Players eventually memorize content
+- Scaling difficult
+
+---
+
+## Why Integrate?
+
+Neither approach alone serves all needs. Integration strategies leverage strengths of both.
+
+### What PCG Struggles With
+- Coherent multi-step narratives
+- Meaningful puzzle design
+- Guaranteed dramatic moments
+- Consistent thematic experience
+
+### What Handmade Adds
+- Narrative anchors
+- Quality guarantees
+- Specific gameplay challenges
+- Memorable set pieces
+
+---
+
+## Two Integration Models
+
+### Vertical Integration
+A handmade thread runs *through* procedural content.
+
+**Characteristics:**
+- Linear progression of handmade elements
+- Procedural content surrounds the thread
+- Players encounter handmade content in sequence
+- Thread spans significant portion of game
+
+**Best for:**
+- Narrative sequences
+- Multi-step puzzles
+- Quest chains
+- Story progression
+
+**Examples:**
+- FTL: Quest nodes distributed through procedural star map
+- Spelunky: Secret item chain requiring precise sequence
+
+### Horizontal Integration
+Procedural and handmade content are *interchangeable* in the same slot.
+
+**Characteristics:**
+- Either type can appear in any given location
+- Modular substitution
+- No linear progression requirement
+- Same slot, different fill
+
+**Best for:**
+- Room-by-room variety
+- Guaranteed gameplay instances
+- Quality floors
+- Encounter variation
+
+**Examples:**
+- Dungeon Crawl Stone Soup: Vaults among procedural rooms
+- Ultima Ratio Regum: Handmade variants mixed with procedural
+
+---
+
+## Case Study: FTL (Vertical)
+
+### Structure
+- Nodes on a star map
+- Most nodes procedural
+- Some nodes are quest-specific (handmade)
+- Quest nodes appear in sequence across sectors
+
+### Integration
+- Procedural: Combat encounters, shops, empty space
+- Handmade: Multi-part quests, story events, special encounters
+
+### Player Experience
+- Procedural nodes provide variety
+- Quest nodes provide narrative progression
+- Players choose path but hit quest nodes as they progress
+
+---
+
+## Case Study: Dungeon Crawl Stone Soup (Horizontal)
+
+### Structure
+- Procedurally generated dungeon floors
+- "Vaults" are handmade rooms/areas
+- Vaults appear among procedural content
+
+### Integration
+- Procedural: Standard dungeon rooms, corridors
+- Handmade: Vaults with curated enemy/loot combinations
+
+### Visibility
+DCSS makes the difference **obvious**:
+- Vaults visually distinct
+- Players recognize human design
+- Creates risk/reward choice ("explore vault?")
+
+### Purpose
+- Visual variety
+- Gameplay pacing
+- Optional challenge/reward
+
+---
+
+## Case Study: Spelunky (Vertical)
+
+### Structure
+- Procedurally generated platformer levels
+- Hidden secret sequence spans entire game
+- Specific items must be collected in order
+
+### The Secret Chain
+1. Find key + chest in Mines → get Udjat Eye
+2. Udjat Eye reveals Black Market → get Ankh
+3. Die with Ankh near Moai → get Hedjet
+4. Kill Anubis → get Scepter
+5. Use Scepter in Temple → access City of Gold
+6. Get Book of Dead → reveals Hell entrance
+
+### Integration
+- Procedural: Level geometry, enemy placement, item locations
+- Handmade: The sequence itself, specific item interactions
+
+### Player Experience
+- Most players never see the secret
+- Skilled players work toward it
+- Each step is procedurally placed but handmade in design
+
+---
+
+## Case Study: Ultima Ratio Regum (Horizontal, Hidden)
+
+### Philosophy
+Blur the line between procedural and handmade so players can't tell which is which.
+
+### Implementation
+- Most systems can output procedural OR handmade content
+- Same slot might get generated altar or preset altar
+- Player cannot distinguish source
+
+### Goals
+1. Handmade might be perceived as procedural (quality validation)
+2. Procedural perceived as handmade (quality achievement)
+3. Guaranteed interesting content without telegraphing it
+
+### Example: Buildings
+- Cathedrals: Highly procedural (few constraints, sprawling)
+- Mansions: More handmade (many required rooms, specific layouts)
+- Constraint level determines procedural/handmade ratio
+
+---
+
+## Key Design Questions
+
+### Should Players Know?
+
+**Make it obvious (DCSS approach):**
+- Visual variety
+- Risk/reward signaling
+- Gameplay pacing tool
+- Player can choose engagement level
+
+**Hide it (URR approach):**
+- Seamless experience
+- Quality perception uniform
+- No "content type" metagaming
+- Procedural must meet handmade quality bar
+
+### What Should Be Handmade?
+
+**Vertical model uses handmade for:**
+- Narrative threads
+- Puzzle sequences
+- Story progression
+
+**Horizontal model uses handmade for:**
+- Quality guarantees
+- Specific gameplay moments
+- Variety injection
+
+---
+
+## Practical Considerations
+
+### Procedural Constraints
+The more constraints on generation, the more similar outputs become.
+
+**High constraints = handmade-like results**
+- May need to shift toward handmade
+- Example: Mansions require many rooms → layouts converge
+
+**Low constraints = high variety**
+- Procedural works well
+- Example: Cathedrals with few requirements → high variety
+
+### Development Timeline
+- Procedural systems: High upfront cost, low marginal cost
+- Handmade content: Linear cost per unit
+- Integration requires both investments
+
+### Testing Considerations
+- Procedural needs testing across many generations
+- Handmade needs testing of specific content
+- Integration needs testing of transitions/interactions
+
+---
+
+## Future Directions
+
+### What's Hard to Generate
+- Multi-node narratives
+- Complex puzzles
+- Coherent story progression
+
+These remain primarily handmade.
+
+### What's Improving
+- Room-level generation
+- Enemy placement
+- Loot distribution
+- Environmental variety
+
+Integration will likely expand as generation quality improves.
+
+---
+
+## Summary
+
+1. **Neither pure approach is sufficient** — Integration leverages both
+2. **Vertical integration** — Handmade thread through procedural space (narrative, quests)
+3. **Horizontal integration** — Interchangeable modules (rooms, encounters)
+4. **Visibility is a design choice** — Obvious vs hidden integration serves different goals
+5. **Constraints determine ratio** — More constraints → more handmade needed
+6. **Quality bars matter** — Procedural must meet handmade standards for hidden integration

package/.claude/skills/level-design/themed-environments.md

@@ -0,0 +1,264 @@
+# Themed Level Environments
+
+Based on Chapter 5: "Hell, Hyboria, and Disneyland" by Scott Rogers.
+
+## The Evolution of Themed Levels
+
+Themed video game levels are environments designed to a particular subject matter, bringing together: character, location, story, enemies, mechanics, hazards, art, events, and music.
+
+> "These themed levels are the playgrounds of our dreams."
+
+---
+
+## The Ten Classic Tropes
+
+### 1. Outer Space
+**Origin:** Spacewar! (1961) and the black CRT screen
+
+**Why it works:**
+- Black screens naturally suggest space
+- Vector-drawn stars look great on CRTs
+- Simple geometric ships (no animation needed)
+- Physics-based gameplay natural
+- Infinite bounds make sense
+
+**Modern usage:** Star Fox, Geometry Wars, space stations
+
+---
+
+### 2. Fire and Ice
+**Origin:** Dragon's Lair (1983) for fire; Ghost 'N Goblins (1984) for ice
+
+**Why they work:**
+- Killing with fire = collision box + art overlay (cheap to implement)
+- Low-friction surfaces = physics tweak
+- Perfect timing puzzles (break player rhythm)
+- Wide array of thematic enemies
+- Strong color palette (red/blue) for visual distinction
+
+**Design advantages:**
+- Fire: Lava pits, flame jets, fire-breathing enemies
+- Ice: Slippery surfaces, icicle hazards, yetis, hypothermia
+
+---
+
+### 3. Dungeon/Cavern/Tomb
+**Origin:** Colossal Cave Adventure (1976), Rogue (1980)
+
+**Why it works:**
+- Tileable wall textures (memory efficient)
+- Traps without explanation needed
+- Treasure without justification needed
+- Easily repeatable art assets
+- Expected danger creates tension
+
+**Modern usage:** Every RPG ever, roguelikes, action-adventures
+
+---
+
+### 4. Factory
+**Origin:** Donkey Kong (1981), Modern Times (1936 film influence)
+
+**Why it works:**
+- Moving obstacle courses
+- Easily combined and repurposed hazards
+- Scalable difficulty through speed/complexity
+- Mechanics adaptable to any setting
+
+**Factory mechanics in non-factories:**
+- Moving platforms (tombs, space stations)
+- Conveyer belts (any industrial setting)
+- Turning gears (clockwork, machinery)
+
+**Modern usage:** Super Mario Galaxy, Little Big Planet
+
+---
+
+### 5. Jungle
+**Origin:** Pitfall! (1982)
+
+**Creation story:**
+> "I drew a stick figure... put him on a path... Where is the path? Let's put it in a jungle. Why is he running? [draw treasures, enemies]" — David Crane
+
+**Why it works:**
+- Flexibility of dungeons without dull colors
+- Exotic traps (quicksand, pits)
+- Exotic creatures (crocodiles, snakes, scorpions)
+- Colorful outdoor environment
+- Fluid movement (vines, branches, logs)
+
+**Mechanics:** Swinging vines, tree platforms, rivers with moving logs
+
+**Modern usage:** Crysis, Uncharted
+
+---
+
+### 6. Spooky
+**Origin:** Haunted House (1972 electromechanical), Ghost 'N Goblins (1984)
+
+**Why it works:**
+- Perfect for mood and story
+- Most adaptable trope
+- Combines easily with any other theme
+
+**Spooky combinations:**
+- Space + Spooky = Derelict spacecraft
+- Fire + Spooky = Hell
+- Urban + Spooky = Haunted city
+
+**The survival horror genre:** Sweet Home (1989) → Resident Evil, Silent Hill
+
+---
+
+### 7. Pirate
+**Origin:** Pirates of the Caribbean (Disneyland attraction, 1967)
+
+**Why it works:**
+- High-action gameplay ready
+- Melee combat natural
+- Treasure = clear rewards
+- Ships = interesting level geometry
+- Always pairs well with spooky (skeleton pirates)
+
+**Genre spread:** Simulation (Sid Meier's Pirates), platformer (Hook), action (Black Kat), puzzle (Zack & Wiki)
+
+---
+
+### 8. Gritty Urban
+**Origin:** Double Dragon (1987), influenced by Streets of Fire (1984)
+
+**Why it works:**
+- Real-world familiarity
+- Players understand context immediately
+- Modern stand-in for dungeon exploration
+- Can be improved or destroyed by player
+
+**The gangster game genre:** GTA, Saints Row
+- Sandbox worlds modeled on real cities
+- Player choice: improve or destroy
+
+---
+
+### 9. Space Station
+**Origin:** Major Havoc (1983)
+
+**Why it works:**
+- Sci-fi dungeon equivalent
+- Tech-based mechanics (force fields, airlocks)
+- Alien/robot enemies expected
+- Spectacular visual effects possible
+
+**Influence:** Aliens (1986 film) → System Shock, Halo, Dead Space
+
+---
+
+### 10. Sewer
+**Origin:** Mario Bros. (1983)
+
+**Creation:** Miyamoto was told his character looked more like a plumber than a carpenter. He put Mario in "a crab/turtle/firefly-infested sewer."
+
+**Why it works:**
+- Modern dungeon stand-in
+- Deadly hazards (rats, alligators, toxic water)
+- Factory mechanics (fans, platforms)
+- Pipes provide entrance/exit points
+
+**Modern usage:** Metal Gear Solid, Oblivion, Left 4 Dead
+
+---
+
+## The Mexican Pizza Technique
+
+**Definition:** Combine two different tropes to create something fresh.
+
+**Origin story:**
+> "In 2001, Taco Bell introduced the Mexican pizza... Growing up in San Diego, I knew what Mexican food was and... what pizza was. But what the heck was a Mexican pizza?"
+
+### Examples
+
+| Combination | Result |
+|-------------|--------|
+| Fire + Graveyard | Maximo: Ghosts to Glory |
+| Jungle + Urban | The Last of Us, Enslaved |
+| Pirate + Zombie | Plants vs. Zombies 2 |
+| Space + Sewer | Aliens-style vent crawling |
+| Medieval + Hell | Dante's Inferno |
+
+### Why It Works
+- Players recognize familiar elements
+- Combination creates novelty
+- Mechanics from both themes available
+- Visual distinctiveness
+
+---
+
+## The Disneyland Influence
+
+### Themed Lands Concept
+Walt Disney's park design philosophy:
+> "I don't want the public to see the real world they live in while they're in the park. I want them to feel like they are in another world."
+
+### Dark Ride Design
+Pirates of the Caribbean, Haunted Mansion:
+- Temperature-controlled environments
+- Vehicles directing view
+- Audio-animatronics synchronized to tracks
+- Complete immersion in artificial worlds
+
+### Application to Games
+- Complete thematic consistency
+- Every element supports the theme
+- Transitions between areas managed carefully
+- Player as "guest" experiencing designed journey
+
+---
+
+## The Hyboria Model
+
+Robert E. Howard's Conan world: Ancient civilizations packed into a compact continent.
+
+**Design advantages:**
+- Travel time compressed
+- Any culture accessible
+- Themed regions with distinct identities
+
+**D&D Influence:** Dungeons & Dragons adopted themed worlds → influenced video games → Gauntlet, Everquest, World of Warcraft
+
+---
+
+## Boss Enemies and Themed Levels
+
+### The Megaman Pattern
+Boss enemies' lairs match their appearances:
+- Fire Man lives in volcanic furnace
+- Ice Man lives in frigid lair
+- Bubble Man lives underwater
+
+### Design Synergy
+- Boss inspires level theme
+- Level theme supports boss mechanics
+- Player expectations set by environment
+- Thematic consistency reinforces both
+
+---
+
+## Building Believable Worlds
+
+### Sustaining Disbelief
+> "An important part about building a fantasy world is sustaining disbelief. Some of the best games... have one thing in common; you feel like the world was there despite you."
+
+### World-Building Questions
+- Why does this environment exist?
+- Who built/shaped it?
+- What happened here before the player arrived?
+- What would happen if the player never came?
+
+---
+
+## Summary
+
+1. **Classic tropes exist for practical reasons** — Technical advantages, clear mechanics
+2. **Combine tropes for freshness** — Mexican Pizza technique
+3. **Disneyland model** — Complete thematic immersion
+4. **Boss/level synergy** — Environment and enemy reinforce each other
+5. **World consistency** — Environment should feel like it exists independent of player

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarrodmedrano/claude-skills",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Reusable Claude Code skills for web development projects",
   "main": "index.js",
   "bin": {
@@ -23,6 +23,8 @@
   "files": [
     ".claude/skills/**/*",
     ".claude/commands/**/*",
+    ".claude/agents/**/*",
+    "templates/**/*",
     "scripts/**/*",
     "bin/**/*",
     "README.md"

package/scripts/install.js

@@ -38,8 +38,10 @@ function copySkills() {
 
   const skillsTargetDir = path.join(projectRoot, '.claude', 'skills');
   const commandsTargetDir = path.join(projectRoot, '.claude', 'commands');
+  const agentsTargetDir = path.join(projectRoot, '.claude', 'agents');
   const skillsSourceDir = path.join(packageRoot, '.claude', 'skills');
   const commandsSourceDir = path.join(packageRoot, '.claude', 'commands');
+  const agentsSourceDir = path.join(packageRoot, '.claude', 'agents');
 
   // Create .claude directories if they don't exist
   if (!fs.existsSync(skillsTargetDir)) {
@@ -52,7 +54,12 @@ function copySkills() {
     console.log('✓ Created .claude/commands directory');
   }
 
-  // Copy skills and commands
+  if (!fs.existsSync(agentsTargetDir)) {
+    fs.mkdirSync(agentsTargetDir, { recursive: true });
+    console.log('✓ Created .claude/agents directory');
+  }
+
+  // Copy skills, commands, and agents
   try {
     if (fs.existsSync(skillsSourceDir)) {
       copyRecursive(skillsSourceDir, skillsTargetDir);
@@ -64,6 +71,11 @@ function copySkills() {
       console.log(`✓ Commands copied to ${commandsTargetDir}`);
     }
 
+    if (fs.existsSync(agentsSourceDir)) {
+      copyRecursive(agentsSourceDir, agentsTargetDir);
+      console.log(`✓ Agents copied to ${agentsTargetDir}`);
+    }
+
     console.log('\n✓ Claude Code skills installed successfully!');
     console.log('\nAvailable skills:');
     console.log('  /new-website    - Create frontend projects');
@@ -74,6 +86,9 @@ function copySkills() {
     console.log('  /code-review    - Code review workflows');
     console.log('  /design-review  - Design review workflows');
     console.log('  /security-review - Security review workflows');
+    console.log('\nAvailable agents:');
+    console.log('  design-review        - Design review subagent');
+    console.log('  pragmatic-code-review - Code review subagent');
     console.log('\nTo update later, run: npm run update-skills');
   } catch (error) {
     console.error('Error copying skills:', error.message);

package/templates/github-actions/README.md

@@ -0,0 +1,36 @@
+# GitHub Actions Templates
+
+This directory contains GitHub Actions workflow templates for automating Claude Code reviews in your CI/CD pipeline.
+
+## Available Templates
+
+### Code Review Workflows
+
+- **`claude-code-review.yml`** - Basic Claude Code review workflow
+- **`claude-code-review-custom.yml`** - Customizable Claude Code review workflow with advanced options
+
+### Security Review Workflow
+
+- **`security.yml`** - Automated security review workflow
+
+## Usage
+
+To use these templates in your project:
+
+1. Copy the desired `.yml` file to your repository's `.github/workflows/` directory:
+   ```bash
+   cp templates/github-actions/claude-code-review.yml .github/workflows/
+   ```
+
+2. Set up required secrets in your GitHub repository settings:
+   - `CLAUDE_CODE_OAUTH_TOKEN` or `CLAUDE_API_KEY`
+
+3. Customize the workflow as needed for your project
+
+4. The workflow will automatically run on pull requests
+
+## Documentation
+
+For more information about setting up Claude Code in GitHub Actions, see:
+- [Code Review Documentation](../../.claude/commands/code-review/README.md)
+- [Security Review Documentation](../../.claude/commands/security-review/README.md)