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?**
|
||||
Reference in New Issue
Block a user