feat: Case format and skill drafts
- Case format: YAML schema for investigation cases - title, briefing, evidence, suspects - Truth separated to truth.enc (base64 encoded) - Images: path or URL - Two skills: - detective-play: Play investigation cases - detective-create: Create new cases - Folder structure: - ~/.hermes/detective/cases/ for all cases - Each case: case.yaml + truth.enc + images/ - Truth protection: base64 encoded, decode only after playing
This commit is contained in:
205
docs/case-format-draft.md
Normal file
205
docs/case-format-draft.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# Case Format (YAML Schema) — Draft v1
|
||||
|
||||
**Date:** 2026-04-19
|
||||
**Status:** Draft
|
||||
**Purpose:** Define structure for investigation cases
|
||||
|
||||
---
|
||||
|
||||
## Case File Structure
|
||||
|
||||
```yaml
|
||||
case:
|
||||
id: "easy-01"
|
||||
title: "The Missing Heirloom"
|
||||
difficulty: easy
|
||||
difficulty_description: "A straightforward case with obvious clues"
|
||||
|
||||
# Case metadata
|
||||
version: "1.0"
|
||||
author: "Hermes Team"
|
||||
created_at: "2026-04-19"
|
||||
|
||||
# What the Chief sees at the start
|
||||
briefing:
|
||||
narrative: |
|
||||
The Hartwell family heirloom—a ruby brooch passed down
|
||||
for generations—has vanished from the family vault.
|
||||
The vault was locked, and only three people had access.
|
||||
suspects_count: 2
|
||||
|
||||
# Evidence available from the start
|
||||
evidence:
|
||||
- id: "evidence-01"
|
||||
name: "Crime Scene Photo"
|
||||
type: photo
|
||||
file: "images/evidence-01.jpg"
|
||||
description: "The open vault in the family study"
|
||||
triggers_witness: false # Available immediately
|
||||
hint_level: too_obvious # How hidden the clue is
|
||||
|
||||
- id: "evidence-02"
|
||||
name: "Security Log"
|
||||
type: document
|
||||
file: "images/evidence-02.jpg"
|
||||
description: "Digital log of vault access"
|
||||
triggers_witness: false
|
||||
hint_level: barely_obvious
|
||||
|
||||
- id: "evidence-03"
|
||||
name: "Witness Testimony"
|
||||
type: document
|
||||
file: "images/evidence-03.jpg"
|
||||
description: "Maid's statement to police"
|
||||
triggers_witness: true # Only available after this is examined
|
||||
hint_level: not_too_obvious
|
||||
|
||||
# Suspects
|
||||
suspects:
|
||||
- id: "suspect-01"
|
||||
name: "Eleanor Hartwell"
|
||||
photo: "images/suspect-01.jpg"
|
||||
description: |
|
||||
The eldest daughter. Had keys to the vault.
|
||||
Recently denied inheritance due to family dispute.
|
||||
examined: false # Initially not examined
|
||||
|
||||
- id: "suspect-02"
|
||||
name: "James Butler"
|
||||
photo: "images/suspect-02.jpg"
|
||||
description: |
|
||||
The family butler. Has served for 20 years.
|
||||
Seen near the vault that morning.
|
||||
examined: false
|
||||
|
||||
# How evidence links to truth
|
||||
truth:
|
||||
# What the creator intended
|
||||
summary: |
|
||||
Eleanor Hartwell took the brooch because she was denied
|
||||
inheritance. She hid it in the garden shed to claim insurance.
|
||||
|
||||
# Criteria for alignment scoring
|
||||
criteria:
|
||||
- id: "criterion-01"
|
||||
description: "Identified Eleanor as main suspect"
|
||||
weight: 40
|
||||
|
||||
- id: "criterion-02"
|
||||
description: "Understood motive (inheritance dispute)"
|
||||
weight: 30
|
||||
|
||||
- id: "criterion-03"
|
||||
description: "Found the hiding spot (garden shed)"
|
||||
weight: 30
|
||||
|
||||
# Evidence that supports each criterion
|
||||
evidence_map:
|
||||
criterion-01:
|
||||
supporting: ["evidence-01", "suspect-01"]
|
||||
criterion-02:
|
||||
supporting: ["evidence-02", "evidence-03"]
|
||||
criterion-03:
|
||||
supporting: ["evidence-03"] # Hidden in testimony
|
||||
|
||||
# Witness appearance rules
|
||||
witness:
|
||||
mode: "default" # "default" | "triggered" | "manual"
|
||||
|
||||
# For "triggered" mode - which evidence triggers witness
|
||||
triggers:
|
||||
- evidence_id: "evidence-03"
|
||||
testimony: |
|
||||
"I remember now—Miss Eleanor was arguing with her father
|
||||
about the inheritance just last week. She seemed furious.
|
||||
And this morning, I saw her walking toward the garden..."
|
||||
|
||||
# Case settings
|
||||
settings:
|
||||
witness_always_talks: true # If true, Witness describes everything. If false, only what Chief asks.
|
||||
allow_skip: true # Can skip evidence
|
||||
max_turns: 10 # Soft limit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Field Explanations
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `case.id` | Unique identifier (slug) |
|
||||
| `case.title` | Display name |
|
||||
| `case.difficulty` | easy, medium, hard, hardcore, impossible |
|
||||
| `case.briefing` | Initial narrative + suspect count |
|
||||
| `case.evidence` | List of evidence items |
|
||||
| `case.suspects` | List of suspects |
|
||||
| `case.truth` | Creator's intended story + criteria |
|
||||
|
||||
### Evidence Types
|
||||
|
||||
| Type | Kimi Sees |
|
||||
|------|-----------|
|
||||
| `photo` | Visual analysis |
|
||||
| `document` | Text extraction + analysis |
|
||||
| `video` | Frame-by-frame (if supported) |
|
||||
| `audio` | Transcription + analysis |
|
||||
|
||||
### Hint Levels
|
||||
|
||||
| Level | Meaning |
|
||||
|-------|---------|
|
||||
| `too_obvious` | Player will find it easily |
|
||||
| `barely_obvious` | Requires some exploration |
|
||||
| `not_too_obvious` | Hidden, requires attention |
|
||||
|
||||
### Witness Modes
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|---------|
|
||||
| `default` | Witness appears with all triggered evidence |
|
||||
| `triggered` | Witness only appears when evidence triggers |
|
||||
| `manual` | Chief must explicitly request witness |
|
||||
|
||||
---
|
||||
|
||||
## Example Evidence Item
|
||||
|
||||
```yaml
|
||||
- id: "evidence-01"
|
||||
name: "Crime Scene Photo"
|
||||
type: photo
|
||||
file: "images/evidence-01.jpg"
|
||||
description: "The open vault in the family study"
|
||||
triggers_witness: false
|
||||
hint_level: too_obvious
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Questions / Decisions Needed
|
||||
|
||||
1. **Witness modes** — Do we need all three? Or simplify?
|
||||
2. **Criteria weights** — Should they always sum to 100%?
|
||||
3. **Evidence linking** — Is `evidence_map` the right approach for alignment?
|
||||
4. **Optional fields** — What should be required vs optional?
|
||||
5. **Images** — How to reference? Path? URL?
|
||||
|
||||
---
|
||||
|
||||
## Starter Case Example
|
||||
|
||||
For the first proof-of-concept, we could create:
|
||||
|
||||
```
|
||||
easy-01: "The Missing Heirloom"
|
||||
- 3 evidence items
|
||||
- 2 suspects
|
||||
- 3 criteria
|
||||
- Simple truth: Someone stole something for a reason
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Does this format make sense? What should we add/remove?**
|
||||
82
docs/skills/detective-create/SKILL.md
Normal file
82
docs/skills/detective-create/SKILL.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: detective-create
|
||||
description: Create mystery investigation cases for Hermes Detective Agency
|
||||
---
|
||||
|
||||
# Detective Case Creator
|
||||
|
||||
Help users create mystery investigation cases.
|
||||
|
||||
## Case Structure
|
||||
|
||||
Create a folder in `~/.hermes/detective/cases/<case-name>/`
|
||||
|
||||
Each case needs:
|
||||
```
|
||||
<case-name>/
|
||||
├── case.yaml # Case data
|
||||
├── truth.enc # Encoded truth
|
||||
└── images/ # Evidence images
|
||||
```
|
||||
|
||||
## Case YAML Format
|
||||
|
||||
```yaml
|
||||
title: "Case Title Here"
|
||||
|
||||
briefing:
|
||||
narrative: |
|
||||
The opening story. Set the scene for the investigation.
|
||||
|
||||
evidence:
|
||||
- id: "evidence-01"
|
||||
name: "Evidence Name"
|
||||
image: "images/evidence-01.jpg"
|
||||
description: "Brief description"
|
||||
|
||||
- id: "evidence-02"
|
||||
name: "Another Evidence"
|
||||
image: "images/evidence-02.jpg"
|
||||
description: "Brief description"
|
||||
|
||||
suspects:
|
||||
- id: "suspect-01"
|
||||
name: "Suspect Name"
|
||||
photo: "images/suspect-01.jpg"
|
||||
description: "Background info"
|
||||
```
|
||||
|
||||
## How to Encode Truth
|
||||
|
||||
The truth must be encoded to `truth.enc`:
|
||||
|
||||
```python
|
||||
import base64
|
||||
|
||||
truth = """---
|
||||
summary: |
|
||||
What actually happened in the case.
|
||||
key_points:
|
||||
- "Key point 1"
|
||||
- "Key point 2"
|
||||
---"""
|
||||
|
||||
encoded = base64.b64encode(truth.encode()).decode()
|
||||
# Write encoded to truth.enc
|
||||
```
|
||||
|
||||
## Creating Images
|
||||
|
||||
Images can be:
|
||||
- Real photos or documents
|
||||
- AI-generated (use Pollinations or similar)
|
||||
- Clear and readable
|
||||
- JPG or PNG format
|
||||
- Not too large (under 1MB each)
|
||||
- Named clearly (evidence-01.jpg, suspect-01.jpg)
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Case should be solvable with the evidence provided
|
||||
- Truth should align with evidence (no hidden info)
|
||||
- Include 2-4 evidence items and 2-3 suspects for Easy
|
||||
52
docs/skills/detective-play/SKILL.md
Normal file
52
docs/skills/detective-play/SKILL.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: detective-play
|
||||
description: Play mystery investigation cases powered by Kimi Vision
|
||||
---
|
||||
|
||||
# Detective Play
|
||||
|
||||
You are a detective agency assistant. Help the user play mystery investigation cases.
|
||||
|
||||
## Cases Location
|
||||
|
||||
All cases are stored in:
|
||||
```
|
||||
~/.hermes/detective/cases/
|
||||
```
|
||||
|
||||
Each case is a folder containing:
|
||||
- `case.yaml` — Evidence, suspects, briefing (NO truth)
|
||||
- `truth.enc` — Encoded solution
|
||||
- `images/` — Evidence images
|
||||
|
||||
## How to Play
|
||||
|
||||
1. Look at available cases in `~/.hermes/detective/cases/`
|
||||
2. Tell the user what cases are available
|
||||
3. User picks a case
|
||||
4. Load the case.yaml from that folder
|
||||
5. Present the briefing narrative
|
||||
6. Let the user examine evidence (show images from images/ folder)
|
||||
7. Use Kimi Vision to analyze images when asked
|
||||
8. Help theorize based on evidence
|
||||
9. When user is ready, help them build and submit their theory
|
||||
|
||||
## When User Asks About Truth
|
||||
|
||||
Only reveal truth AFTER user has formed and submitted their theory.
|
||||
|
||||
To decode truth:
|
||||
```python
|
||||
import base64
|
||||
with open('truth.enc', 'r') as f:
|
||||
encoded = f.read().strip()
|
||||
decoded = base64.b64decode(encoded.encode()).decode()
|
||||
print(decoded)
|
||||
```
|
||||
|
||||
## Important
|
||||
|
||||
- NEVER read truth.enc before the user is done investigating
|
||||
- Case format: case.yaml (evidence + suspects only)
|
||||
- Images are in the images/ subfolder
|
||||
- Kimi Vision can analyze images when you call it
|
||||
Reference in New Issue
Block a user