puzzle-design-kb/AGENTS.md

Puzzle Design Knowledge Base

A handbook documenting puzzle design patterns from classic point-and-click adventure games (King's Quest VI, Monkey Island series). This repository captures mechanical patterns—how information is conveyed and what player actions solve puzzles.

Agent Instructions

Repository Purpose

This is a documentation-only knowledge base. No code, no tests, no build process.

• /puzzles/ — Markdown documents defining puzzle type patterns
• /walkthroughs/ — Source walkthrough text for game analysis (empty placeholder)
• /README.md — Master index with table of contents linking all puzzle types

Adding New Content

When analyzing a new game walkthrough:

1. Extract each puzzle's solution from walkthrough text
2. For each, identify: what info was needed, how it was conveyed, what action solved it
3. Match against existing types in /README.md table OR create new type document
4. Add example to relevant .md file in /puzzles/ under ## Game Examples
5. If creating new type: update /README.md table of contents (increment number, add link)

File naming: Use kebab-case (multi-faceted-plan.md, pattern-learning.md)

Game source codes: KQVI (King's Quest VI), MI1 (Monkey Island 1), MI2 (Monkey Island 2)

Document Structure Template

Each puzzle type follows this standard format:

# [Type Name]

**Information Architecture**: How player discovers puzzle structure.

**Player Action Pattern**:
1. Step one
2. Step two
3. Solution

**Core Mechanic**: Single sentence explaining underlying logic.

**Variations**: Brief list of possible manifestations

---

## Game Examples

### [Game]: [Puzzle Name]

**Setup**: Brief context description.

**Solution Chain**:
1-5. Actions with discoveries...

**Why It's This Type**: Explicit connection to core mechanic above.

---

## Related Types

| Type | Similarity | Distinction |

Style & Formatting Guidelines

Frontmatter: None required (no YAML headers)

Link format: Relative links using ./puzzles/file.md

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

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.

Cross-Referencing Rules

Every new puzzle type must include a ## Related Types section linking to:

• Most similar existing types (explain what they share)
• Easily confused types (explain the distinction)

Use table format for related types:

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

Validation Checklist

When adding content, ensure:

• Core Mechanic is exactly one sentence
• 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

Common Pitfalls

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.

Workflow Commands

No build/lint/test commands exist. Quality assurance is manual review against guidelines above.

To validate markdown syntax:

# Install a markdown linter locally (optional)
npx -y remark-cli README.md puzzles/*.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 should load the adventure-puzzle-analyzer skill when working with this repository.