sprngr/rubber-duck / skills/duck-adventure
duck-adventure
UnverifiedStandalone easter-egg rogue game. Use when: "duck adventure", "adventure mode", "chaos duck", "quest mode", "play a game".
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 5.8 KB |
| SKILL.md | skill md | 5.2 KB |
| assets/encounters.md | markdown | 2.8 KB |
| assets/events.md | markdown | 1.1 KB |
| assets/lore.md | markdown | 1.3 KB |
| assets/quests.md | markdown | 1.7 KB |
| hooks/adventure.py | script | 25.2 KB |
| references/ENGINE.md | markdown | 2.6 KB |
| references/GUARDRAILS.md | markdown | 757 B |
| references/PARSER.md | markdown | 1.9 KB |
| references/STATE_SCHEMA.md | markdown | 1.5 KB |
README.md
View on GitHub# duck-adventure: Easter-Egg Rogue Game π¦π²
Standalone opt-in game skill: multi-turn dungeon crawls with dice combat, random merchants, loot, and condition-tied achievements. Pure play β no productivity coupling, no handoff to work flows. Explicit opt-in ("duck adventure") and explicit exit ("done").
## Why It Exists
A cozy rogue RPG for engineers. The duck is not here to be understood; the duck is here so decisions feel less lonely. Derived from [chaos-duck](https://github.com/BreezeButter/chaos-duck) (MIT), adapted and extended for the rubber-duck harness.
## Gameplay
- **Scripted engine** (`hooks/adventure.py`): floors 1-8, d20/d6 dice combat, merchant trade, loot rolls, run-end banking. Deterministic mechanics live in code; the LLM narrates only.
- **Room-graph navigation**: position is a room name, not coordinates β no map drift. Rooms: Entrance, Guard Post, Vault, Merchant Stall, Odd Clearing, Boss Chamber, Stairs Down, Storage Room, Shrine, Trap Room (hazard), Healing Spring (free heal), Treasure Hoard (guaranteed loot).
- **Two victories**: floor 5 Duck King (Crown of the Duck King) or floor 8 Duck Emperor (Emperor's Gilded Feather).
- **Achievements**: tied to run events β won combat, opened chest, bought item, fled a fight, reached floor 3, defeated a boss.
- **Rogue-lite persistence**: permanent collection (gold hoard, inventory, achievements, quest log) survives death/reset; voluntary exit preserves the run for resume.
## Commands
MUD-style verbs, parsed per `references/PARSER.md`:
- **Movement:** `north`/`n` | `south`/`s` | `east`/`e` | `west`/`w`
- **Descend:** `descend` β only from Stairs Down; floor +1, full HP restore, new floor
- **Look:** `look` / `look <object>` / `look <monster>`
- **Inventory:** `inventory` / `i`
- **Objects:** `take <object>` / `drop <object>` / `open <container>`
- **Combat:** `attack <monster>` / `flee`
- **Merchant:** `merchant` (show stock) / `merchant buy <item>` / `merchant sell <item>`
- **Rest:** `rest` β heal 1d6, 30% ambush chance
- **Use:** `use <item>` β potions, elixirs, Lucky Pebble
- **Meta:** `map` | `status` | `help` | `exit`/`quit` (preserve run for resume)
- **Narrative:** `say "<text>"` / `emote <text>` β LLM-only, no script call
Unknown input: `I don't understand "<input>". Type "help" for commands.`
## Quick Start
1. Install manually (not in installer extras): `npx skills add --skill duck-adventure`
2. Say `duck adventure` β the skill requests one-time approval for the state-file scope (`.duck-adventure/state.json` + `state.md`).
3. Play. `exit` preserves your run; death or victory banks gold and resets the run.
4. Say `done` when finished.
Requires `python3` at play time (in the standard toolchain).
## File Layout
```
src/skills/duck-adventure/
SKILL.md β skill definition (Method: opt-in gate, state
approval, run setup, turn loop, combat, merchant,
events, run end)
hooks/adventure.py β deterministic engine (17 subcommands, JSON state)
assets/
lore.md β duck lore (narrative)
events.md β random events (narrative)
quests.md β quest frames + choice paths (narrative)
encounters.md β duck/merchant/wizard encounters (narrative)
references/
ENGINE.md β mirror of script-owned tables (rooms, monsters,
loot, items, merchant stock, achievements)
PARSER.md β verb surface + command semantics
STATE_SCHEMA.md β state.json schema v3
GUARDRAILS.md β shared guardrails (injected)
evals/evals.json β behavior evaluations
```
Runtime state (not committed):
```
<project>/.duck-adventure/
.gitignore β `*` (auto-created by script)
state.json β script-owned state (schema v3)
state.md β LLM-rendered summary at run end
```
## State Model
`.duck-adventure/state.json` is script-owned (schema v3): `permanent` (gold hoard, inventory, achievements, quest log) survives death/reset; `run` (quest, flags, HP, floor, room, run gold, diagram) resets on death, preserves on exit. Full schema in `references/STATE_SCHEMA.md`.
## Security
- State writes require one-time execution approval at game start (scope: state.json + state.md + `.gitignore`).
- Redaction before every write: secrets/PII rejected; mask-in-place (`<REDACTED>`) only on explicit confirmation.
- No other files written. No persistence beyond `.duck-adventure/`.
## Attribution
Adapted from **Chaos Duck** by BreezeButter β https://github.com/BreezeButter/chaos-duck (MIT license). Original concept: a whimsical AI personality that turns conversations into tiny RPG moments before helping with real decisions.
This skill preserves the spirit (cozy nonsense, dramatic micro-quests, magical bureaucracy) but reworks the mechanics:
- **Quest loop** β scripted rogue engine (deterministic dice, state, run-end semantics)
- **Choice templates** β deduplicated quest frames (12) + mechanical room variety
- **Content libraries** β narrative assets (lore, events, encounters) kept as LLM-flavor, tables moved to code
- **"Then help the user clearly"** β dropped: this is pure play with explicit exit, no productivity handoff
Changes are substantial: mechanics, structure, and integration are new. Upstream content (lore incidents, event types, encounter variants, quest frames) is deduplicated and extended under the same MIT license.
## References
- `references/ENGINE.md` β script-owned data tables (source of truth: `hooks/adventure.py`)
- `references/PARSER.md` β full verb surface and semantics
- `references/STATE_SCHEMA.md` β state.json schema v3
- `hooks/adventure.py` β the engine; `python3 hooks/adventure.py --help` for subcommandsRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |