puzzle-design-kb/AGENTS.md

Agent Instructions

Repository Purpose

This is a documentation-only knowledge base built with mdbook that captures mechanical puzzle design patterns from classic point-and-click adventure games. The handbook documents how information is conveyed and what player actions solve puzzles—pattern-based, not narrative-based.

Directory Structure

Path	Contents
/src/puzzles/	Markdown documents defining puzzle type patterns with mechanical analysis and game examples
/src/docs/	Style guides and validation checklists for contributing pattern documentation
/src/SUMMARY.md	Navigation structure for mdbook
/src/walkthroughs/	Source walkthrough documents used as reference material for pattern extraction
/book/	Generated HTML documentation (after mdbook build)
/src/mdbook.template	Template file that converts patterns into puzzle design questions usable by LLMs

Handbook Structure Compliance

All content must align with the target handbook structure. When creating or updating pages, follow these conventions:

Introduction: Hook material showcasing masterful puzzles and their mechanical appeal.

Inspiration: Puzzle analyses from 30+ games using Problem/Why It Works/Solution/Steps format. Link every example to its puzzle type in the Playbook.

Playbook Pages (in /src/puzzles/): Each page must include:

• ## Core Mechanic: Three sentences max explaining what this pattern achieves
• ## Solution Chain: Numbered list of specific player actions
• ## Examples: Exactly 3 game examples with "Why It's This Type" analysis
• ## Related Types: Table differentiating from at least 2 similar types

FAQ Pages (in /src/docs/): Actionable solutions to common design problems. Reference playbook patterns where applicable.

Primary Goals

1. Establish a puzzle design playbook: Help designers understand puzzle type structures independent of plot and setting
2. Enable LLM-assisted design: Provide concrete critique criteria grounded in proven patterns so LLMs can avoid generating generic "find key, open door" slop
3. Document reference implementations: Catalog specific puzzle applications from games like Monkey Island (MI1/MI2) and King's Quest VI (KQVI)

Target Audience & Goals Alignment

When creating content, keep in mind:

• Readers want reproducible mechanical patterns, not narrative analysis
• Examples should illustrate the pattern, not obscure it with story details
• Every puzzle type must be setting-independent to match the playbook goal
• Game source code abbreviations (MI1, MI2, KQVI) signal we're documenting reference implementations

What Agents Should Do

When Creating Puzzle Type Documentation

1. Extract patterns that are mechanic-oriented, not story-oriented. The pattern should apply across settings regardless of narrative context
2. Use game source code abbreviations (MI1, MI2, KQVI)—not full game names
3. Include exactly 3 illustrative examples per puzzle type
4. Create a ## Related Types section that differentiates from at least 2 similar types using the table format below
5. Write a Core Mechanic section of no more than three sentences
6. Use numbered lists for Solution Chain with specific actions (never "solve puzzle")
7. Target no more than 1,000 words per page
8. Use kebab-case filenames matching the document title

When Analyzing Walkthroughs

Load the adventure-puzzle-analyzer skill before:

• Converting walkthrough text into structured puzzle documentation
• Extracting patterns from game walkthrough files in /src/walkthroughs/

Task Management with TODOS.md

Creating and Managing Todos

All tasks must be tracked in todos/TODOS.md using a hierarchical structure where tasks can have subtasks. Use this format:

# TODO List

- [ ] **Top-level task**
  - [ ] Subtask one
  - [ ] Subtask two with more detail about what needs to be done
  - [ ] Subtask three
- [ ] Another top-level task
  - [ ] Nested subtask

Task Completion Workflow

1. Before starting any multi-step work: Create or update todos/TODOS.md with a hierarchical task list
2. After completing each subtask: Update its status to [x] in TODOS.md
3. After marking ANY task or subtask complete: Commit the changes immediately with a message describing what was completed
4. When user requests a top-level task: Do not stop until ALL subtasks are complete. Use subagents for parallel work where appropriate

Top-Level Task Execution Protocol

When a user asks to complete a top-level task:

1. Break it down into subtasks and record them in TODOS.md
2. Execute subtasks sequentially or use subagents for independent work streams
3. After each subtask completes, mark it [x] and commit
4. Only report completion when ALL subtasks under that top-level item are done
5. If a task requires multiple specialized skills, delegate to appropriate subagents

Commit Rules for Task Completion

• Every time a task or subtask is marked complete in TODOS.md, create a git commit
• Commit message should reference the completed task: "Complete: <task description>"
• Do not batch multiple task completions into a single commit

Style & Formatting Requirements

Frontmatter: None required (no YAML headers)

Link format: Relative links using puzzles/file.md in SUMMARY.md and docs

Tables: Use for comparisons, requirement summaries, quick-reference matrices, and Related Types sections

Lists:

• Numbered lists for sequential steps or solution chains
• Bullet lists for enumerations without order

Emphasis: Bold (**text**) for field labels like Setup, Solution Chain, key terms

Code blocks: Use triple-backticks with markdown for example structures showing game flows

Tone: Mechanical and precise. Avoid vague terms ("clever," "creative"). Describe how not just that.

Related Types Format

Every new puzzle type must include:

## Related Types

| Type | Similarity | Distinction |
|------|------------|-------------|
| Multi-Faceted Plan | Both gather across sources | MFP = different categories, not unified system |

Common Pitfalls to Avoid

Agents should explicitly distinguish between:

Pattern Learning vs Observation Replay: Pattern learning teaches a system with reusable rules. Observation replay memorizes a sequence to reproduce verbatim.

Multi-Faceted Plan vs Meta-Construction:

• MFP: Multiple requirements gathered in any order, synthesized at the end
• Meta-Construction: Sequential chain where step N's output enables step N+1

Brokerage vs Sensory Exploitation: Brokerage = trade network (item for item). Sensory = exploit NPC perception weakness directly.

Validation Checklist

Before considering documentation complete, verify:

• Core Mechanic is no more than three sentences
• Solution Chain uses numbered list with specific actions (not "solve puzzle")
• "Why It's This Type" explicitly connects example to core mechanic
• Related Types section differentiates from at least 2 similar types
• Game source code used (MI1, MI2, KQVI) — not full game name
• Filename matches kebab-case of document title
• Page targets no more than 1,000 words

Build & Validation Commands

# Build static HTML documentation
mdbook build

# Serve with auto-reload during editing
mdbook serve --open

# Validate markdown syntax
npx -y remark-cli src/*.md src/puzzles/*.md src/docs/*.md

Skill Integration

The .opencode/skills/adventure-puzzle-analyzer/ directory contains:

• SKILL.md — Full agent workflow for analyzing walkthroughs
• examples.md — Concrete formatting examples

Agents must load the adventure-puzzle-analyzer skill when:

• Analyzing game walkthroughs to extract puzzle patterns
• Converting walkthrough text into structured puzzle documentation

Task Execution

When possible, use subagents to complete work. For complex multi-step tasks (analyzing walkthroughs, creating new puzzle type documentation from scratch), delegate appropriately rather than attempting all steps in a single agent session.

For any user request: Check TODOS.md first, then update cross-references after each task completion before committing.

Always refer to @README.md, as it has the overall structure of this project.