PWA-mystery v0.1.2

LLM-powered mystery novel writing agent. Five-phase pipeline (truth → world → plan → write → review) with hard file-system isolation to prevent spoiler leaks. Built on pi-agent-core.

Core invariant: the Writer agent never reads truths/. Access is enforced at the tool level — not prompt etiquette.

Features

• 5-phase pipeline: truth design → world-building → chapter planning → prose generation → final review
• Hard file-system isolation: access matrix prevents each agent from reading forbidden directories
• reviewPolish v3: per-chapter AI-pattern scanning (scan_ai_patterns, scan_repetition, scan_density), paragraph-level rewriting via apply_patch with staging + atomic rename
• Targeted revision: /phase:write --revise reads finalReview.fixes[] and applies precise patches across chapters without full rewrites
• Self-reflection: every phase runs a consistency check after generation (name cross-references, timeline coherence, spoiler leakage prevention)
• Batch final review: processes chapters in batches of 3 to avoid context overflow; 70% reader perspective + 30% editor
• Snapshot-based rollback: /rewind N --force resets drafts/state from chapter N onward
• TUI with pi logo: gradient ASCII art header, model selector, phase-aware footer

Install

npm install -g @cooper-zygao/pwa-mystery

Requires Node.js 20+. Dependencies (@mariozechner/pi-*, chalk, yaml) auto-installed.

Quick Start

mkdir my-novel && cd my-novel
PWA-mystery .

Describe your novel in the TUI:

I want an English short mystery, ~20,000 words, 4 chapters.
Setting: Shanghai + New York, 2025, cyberpunk.

The assistant creates config.md. Then run phases:

/phase:truth     # Design the mystery
/phase:world     # Build reader-facing world
/phase:plan      # Per-chapter outlines
/phase:write     # Write prose + auto-polish
/phase:review    # Full-book review → fixes[]

Or: /auto --confirm

After review: /phase:write --revise to apply fixes. Repeat review → revise until satisfied.

Commands

| Command | Purpose | |---|---| | /phase:truth | Design killer, motive, method, clues | | /phase:world | Build reader-facing world (no spoilers) | | /phase:plan | Per-chapter plan JSON | | /phase:write [N] [M] [--revise] | Write chapters or apply review fixes | | /phase:review | Full-book review → structured fixes[] | | /auto [--from X] [--through Y] [--confirm] | Run phases sequentially | | /interrogate | Independent reviewer session | | /rewind N --force | Roll back from chapter N | | /model <spec> | Set/view writer model | | /model-reviewer <spec> | Set/view reviewer model | | /status | Project state | | /help | All commands |

Project Layout

my-novel/
├── config.md                  ← Author brief (deleted after /phase:truth)
├── .pwa-mystery/state.json    ← Phase state
├── truths/                    ← God's-eye view (WRITER CANNOT READ)
├── world/
│   ├── meta.json              ← language, title, chapterCount, wordsPerChapter
│   ├── language.md / scene.md
│   └── structure/chapter-N.md
├── plan/chapter-N.json
├── drafts/chapter-N.md
├── state/chapter-N-state.json
├── reviews/final.json
└── sessions/<role>/messages.jsonl

Model Configuration

~/.pwa-mystery/models.json:

{
  "schemaVersion": 2,
  "writer": "minimax/MiniMax-M3-highspeed",
  "reviewer": "deepseek-v4-flash",
  "providers": {
    "opencode-go-minimax": {
      "baseUrl": "https://opencode.ai/zen/go/v1",
      "apiKey": "sk-...",
      "api": "anthropic-messages",
      "models": [{ "id": "MiniMax-M3-highspeed", "name": "MiniMax M3" }]
    }
  }
}

Share with coding-agent: ln -s ~/.pi/agent/models.json ~/.pwa-mystery/models.json

Architecture

See overview.md for detailed architecture documentation (tools, access matrix, rendering pipeline, test suite).