Imported from wunsir/writer-copilot (AGENTS.md). Install upstream with npx skills add wunsir/writer-copilot. Copyright stays with the author.

Writer Copilot Agent Guide

Project Status

This repository now has an initial Next.js Studio scaffold with sample data, domain validation, YAML export, and a mock full-flow Studio UI. Treat repo files as the source of truth. If project docs, tests, lint, CI, or directory-level AGENTS.md files are added later and conflict with this file, follow the more specific checked-in rule.

Product Direction

Writer Copilot is an AI Adaptation Studio, not a simple novel-to-YAML converter.

The intended product helps users import 3+ chapters of novel text, understand the source, retrieve source evidence, explore adaptation directions, build an Adaptation Brief, generate Scene Blueprints, export schema-validated screenplay YAML, revise individual scenes, and compare creative versions.

Core product capabilities:

• Source Import for pasted text, .txt, and eventually .docx.
• Source Intelligence for story diagnosis, characters, locations, events, hooks, and adaptation risks.
• Lightweight Source RAG using source chunks and retrievable source references.
• Knowledge Packs for adaptation principles and screenplay craft guidance.
• Direction Explorer with dynamic, source-grounded adaptation options.
• Adaptation Brief as the controllable intermediate asset.
• Scene Blueprint before final screenplay output.
• Structured screenplay JSON as the canonical generated data.
• Real YAML generation from validated JSON.
• Schema Validation that checks actual references and structure.
• Scene Revision for local natural-language edits to one selected scene.
• Creative Versioning with checkpoints, timeline, compare, and restore.
• Adaptation Harness with step orchestration, JSON validation, repair, and trace.
• Three-panel Studio UI: 作品目录, stage-specific Adaptation Canvas, 依据与检查 / 选择详情.

Current Studio Baseline

The current UI baseline is acceptable as of the Stage 2 interaction pass and the Microcopy + Action Semantics pass. Do not continue structural UI refactors, color tuning, font tuning, or shadow tuning unless the user explicitly asks.

Current implemented state:

• Product shell uses a modern minimal visual system.
• Left panel is labeled 作品目录.
• Center canvas changes by stage: source reader, diagnosis report, direction lanes, brief document, scene board, screenplay preview, compare view.
• Right panel is labeled 依据与检查 / 选择详情 and follows the selected source chunk, direction, scene, or version.
• Real pasted-text and .txt source import are connected.
• Chapter parsing, stable source chunks, basic keyword/name extraction, and lightweight source search are connected.
• Knowledge pack markdown files, metadata, selection reasons, and Inspector display are connected.
• Local JSON-first harness preview and trace recording are connected without external API calls.
• DashScope/OpenAI-compatible provider config, API route, and UI entry for API-backed direction generation are connected. Live calls require ignored local env configuration.
• UI copy should use natural Chinese adaptation-workbench language, not engineering labels.
• API-backed story diagnosis, brief, blueprint, screenplay generation, .docx import, durable persistence, source-ref jumping, and settings save are not connected yet and should stay visibly marked as 待接入 until implemented.

Studio Interaction Direction

The UI should feel like a real creative studio, not a static form page.

• The left 作品目录 is an entry and control surface. Its items should be able to expand, focus, or enter a deeper creation mode instead of only toggling flat settings.
• The center Adaptation Canvas is the main working surface. It changes by stage and should make the current creative asset feel primary: source map, diagnosis, direction exploration, brief, blueprint, screenplay, compare.
• The right 依据与检查 panel provides context, evidence, YAML, validation, timeline, trace, and selected-item details without stealing the main workflow.
• Direction Explorer, Adaptation Brief, and Scene Blueprint must appear early in the product shell, even before real AI is connected.
• Prefer progressive disclosure, focused editing states, and stage transitions over dense all-at-once panels.
• Do not make a landing page as the first screen. The first screen should be the usable Studio.

Hard Rules

• Do not reduce the product to one prompt that directly converts a novel into YAML.
• AI output must be structured JSON first. The app generates YAML from validated JSON.
• YAML validation must be real, not a decorative "passed" label.
• Scene outputs should preserve source_refs whenever the scene is grounded in imported text.
• Keep source-grounding visible in the UI and data model.
• Keep Adaptation Brief and Scene Blueprint as first-class assets.
• Keep Harness Trace visible enough for demo and debugging.
• Prefer a complete vertical product architecture implemented in staged slices over a tiny MVP that omits core product concepts.

Non-Goals Unless Explicitly Requested

• Production login or account system.
• Payment or billing.
• Multi-user collaboration.
• Cloud database as a default requirement.
• Heavy vector database.
• Complex external agent framework.
• Full rich-text screenplay editor.
• Direct AI-generated YAML as the main pipeline.

Planning And Execution

Use a lightweight, risk-based workflow:

• For planning work, update specs/001-ai-adaptation-studio/ first.
• For implementation work, keep diffs small and reviewable.
• Prefer compact product vertical slices that can be verified end to end.
• Treat detailed task lists as checklists inside slices, not as a reason to stretch development into excessive process.
• Do not add production dependencies without approval.
• Do not modify .env files unless explicitly asked.
• Do not commit secrets.
• Ask before destructive actions, public API changes, database schema changes, auth, billing, deployment, CI, or broad architecture changes.

Current Commands

• npm run dev
• npm test
• npm run typecheck
• npm run lint
• npm run build

Verification Expectations

Before claiming implementation work is complete, run fresh relevant checks and report the exact commands and results.

Expected checks will depend on the stack once scaffolded. Until then, documentation-only changes should be verified by reading the created files and checking git status.

Future implementation should include checks for:

• TypeScript typecheck.
• Lint.
• Tests for domain validation and source parsing.
• Build.
• Browser verification for UI flows.
• Sample novel to valid screenplay YAML flow.