fixes
This commit is contained in:
186
AGENTS.md
Normal file
186
AGENTS.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Agent Instructions
|
||||
|
||||
## Repository Purpose
|
||||
|
||||
This is a **documentation-only knowledge base** built with [mdbook](https://rust-lang.github.io/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 |
|
||||
| `/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 `/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:
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user