cowriter 0.1.0

package/templates/init/.codex/skills/cowriter/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: cowriter
+description: Work inside local Cowriter book projects from Codex.app. Use when the user mentions Cowriter, a manuscript, chapters, story bible, synopsis, characters, outline, continuity, selected prose, or wants Codex to draft/revise long-form fiction in a local book workspace.
+compatibility: Requires Node.js, an installed `cowriter` CLI or local checkout, and browser access to localhost for the workspace UI.
+metadata:
+  author: Cowriter
+  allowed-tools: Bash(cowriter *), Bash(npx cowriter *), Bash(curl http://localhost:*)
+  user-invocable: true
+---
+
+# Cowriter
+
+Cowriter is a local book-writing workspace for Codex.app. Codex is the interview and collaboration surface; the localhost UI is the manuscript and story-material workspace.
+
+## First Step
+
+Check project and app context:
+
+```bash
+cowriter info -o json
+```
+
+If the CLI is installed globally or from npm, this is equivalent:
+
+```bash
+npx cowriter info -o json
+```
+
+Use JSON output for all data-returning commands.
+
+## Core Workflow
+
+1. Run `info -o json` from the book folder, or with `--path`.
+2. If the app is not running for this book, tell the writer to run `npx cowriter serve --open` from the book folder and open the reported localhost URL in Codex Browser. Do not start the long-running serve process yourself unless the writer explicitly asks.
+3. If there is no book folder yet, ask whether the writer has a title, a synopsis, or an existing folder.
+4. Initialize the project with `init`, or ask the writer to serve the existing folder with `serve --path`.
+5. Inspect the current book context before making writing suggestions.
+6. Interview in short turns when the book is empty.
+7. If the writer refers to selected text and the text is not already available in chat or file context, use the selection context API when it would materially improve the response.
+8. When discussing a specific manuscript passage, call the Cowriter highlight API so the UI selects that passage for the writer.
+9. Edit the book files directly when changes are approved.
+10. Save approved project changes immediately as the work progresses.
+11. Commit book changes at sensible creative checkpoints and when the work session is complete.
+
+## Commands
+
+```bash
+cowriter info -o json
+cowriter serve --path /absolute/path/to/book --open
+cowriter init /absolute/path/to/book -o json
+cowriter upgrade --path ~/Writing/Book -o json
+cowriter inspect --path ~/Writing/Book -o json
+cowriter diagnose prose --path ~/Writing/Book --chapter chapters/001-opening.md -o json
+```
+
+Prefer `cowriter` or `npx cowriter` inside book projects. Use the local `node scripts/cowriter-ai.mjs` form only when working inside the Cowriter repository.
+
+Expected local setup from a new book folder:
+
+```bash
+mkdir my-book && cd my-book
+npx cowriter init
+npx cowriter serve --open
+```
+
+Then add that folder as the active Codex project. Each `serve` process represents one book folder, chooses an available port starting at `47891`, reports the localhost URL, and remains running in its terminal.
+
+If Codex Browser is not already open at the reported localhost URL, or it is open on a different localhost port, open or navigate Codex Browser to that exact URL for the writer.
+
+## Selection Context API
+
+The web workspace publishes the current manuscript selection for the served book. If the writer asks about "this", "the selected text", or a selected passage and the selected text is not already in the conversation or local file context, you may retrieve it from the workspace:
+
+```bash
+curl -sS "$COWRITER_URL/api/cowriter/selection"
+```
+
+The response is shaped like:
+
+```json
+{
+  "activeProjectPath": "/absolute/path/to/book",
+  "selection": {
+    "source": "manuscript",
+    "selectedText": "exact selected manuscript text",
+    "chapterPath": "chapters/001-opening.md",
+    "chapterTitle": "Opening",
+    "range": { "from": 42, "to": 96 },
+    "activePage": 0,
+    "surroundingText": "nearby manuscript context",
+    "updatedAt": 1760000000000
+  }
+}
+```
+
+Use this endpoint only when it gives needed context. If `selection` is `null`, stale, or not useful, continue from the available project files or ask the writer for the passage.
+
+## UI Highlight API
+
+When talking about a specific manuscript passage with the writer, ask the Cowriter web UI to highlight that passage. Derive the base URL from `cowriter info -o json` at `app.url`, then call:
+
+```bash
+curl -sS -X POST "$COWRITER_URL/api/cowriter/codex" \
+  -H 'content-type: application/json' \
+  --data '{"command":"highlight","text":"exact passage text","chapterPath":"chapters/001-opening.md"}'
+```
+
+Use the exact quoted passage text when possible. Include `chapterPath` when you know the chapter file, and include `occurrence` when the same passage appears more than once. If the workspace is not open or the highlight is not found, continue the writing conversation normally.
+
+## Onboarding
+
+When there is no book folder yet, or `inspect` returns `bookIsEmpty: true`, ask:
+
+> What do you know about the book right now: a title, a synopsis, or an existing folder?
+
+Ask one onboarding question at a time. Wait for the writer's answer before asking the next question; do not bundle premise, protagonist, setting, ending, and folder questions into a single turn unless the user explicitly asks for a checklist. After each answer, save accepted stable details when appropriate, then ask the next most useful question. Stop interviewing when there is enough context to draft or revise the next page, or when the writer wants to start writing.
+
+If the writer has a title:
+
+1. Ask for the working title and local folder.
+2. Initialize the folder with `cowriter init /path --title "Working Title" -o json`.
+3. Interview for a rough one-paragraph synopsis, one question at a time.
+4. Save accepted synopsis text directly to `story.yaml`.
+5. Do not demand detailed fields before synopsis exists.
+
+If the writer has a synopsis:
+
+1. Ask for the synopsis and local folder.
+2. Generate a working title and say it is editable.
+3. Initialize the folder with `cowriter init /path --title "Working Title" --synopsis "..." -o json`.
+4. Ask at most three focused interview questions, one at a time: protagonist pressure, setting constraint, and ending or emotional promise.
+5. Save accepted story fields, character notes, and outline beats directly to the project files.
+
+If the writer has an existing project:
+
+1. Tell the writer to run `cowriter serve --path /absolute/path/to/book --open`.
+2. Inspect it.
+3. Summarize the current book state.
+4. Recommend the next concrete writing task.
+
+## Direct File Editing
+
+Codex should edit Cowriter project files directly. The localhost web workspace watches the book folder and refreshes when these files change.
+
+Primary files:
+
+- `chapters/*.md` for manuscript chapters.
+- `story.yaml` for title, synopsis, setting, themes, genre, tone, perspective, and continuity.
+- `characters/*.yaml` for character records.
+- `outline.yaml` for outline beats.
+- `.cowriter/project.yaml` for project metadata.
+
+Do not use action envelopes or temporary JSON files for writing edits. The current workflow is direct file editing.
+
+After editing files, run:
+
+```bash
+cowriter inspect --path /absolute/path/to/book -o json
+```
+
+Use `git diff -- chapters story.yaml characters outline.yaml .cowriter` when you need to show exactly what changed.
+
+## Local Prose Diagnostics
+
+Use deterministic prose diagnostics when the writer asks for a prose check, style scan, AI-ish wording scan, rhythm check, or a review of a whole chapter before revision. This is advisory only; it does not rewrite manuscript text.
+
+Run diagnostics for a chapter:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md -o json
+```
+
+The command reports metrics and findings for repetition, long paragraphs, sentence rhythm, dialogue percentage, filler or AI-ish terms, mixed quote styles, and em dash density.
+
+When the writer asks to save the review, write a report artifact:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md --write-report -o json
+```
+
+`--write-report` creates `.cowriter/reports/*.md`, which `cowriter inspect -o json` lists under `project.reports`. Do not run `--write-report` by default; use it only when the writer asks for a saved review or when creating an approved checkpoint report.
+
+After writing a diagnostics report, run:
+
+```bash
+cowriter inspect --path /absolute/path/to/book -o json
+```
+
+For selected-passage feedback, prefer reading selected text or the relevant chapter context and responding in chat. The diagnostics command is chapter-level only.
+
+## Iterative Writing Workflows
+
+Infer the workflow from the writer's request and the current project state. Keep work scoped to the selected passage, active scene, current chapter, or relevant story material.
+
+Use these workflow references when they match the task:
+
+- `context priming`: gather the smallest useful context packet before drafting or reviewing.
+- `scene planning`: turn the next outline beat into a concrete scene task.
+- `title brainstorming`: propose grouped title candidates; update `story.yaml.title` only after the writer chooses one.
+- `prose review`: review selected prose or a chapter for craft issues; use diagnostics as one optional input.
+- `continuity review`: compare manuscript and story materials for contradictions.
+- `character voice review`: sharpen dialogue and character-specific language.
+- `state updates`: extract stable facts after an approved scene or chapter checkpoint.
+- `existing manuscript import`: help convert existing drafts into Cowriter chapters and story materials.
+
+All workflow outputs are advisory until the writer approves a file edit. Reports in `.cowriter/reports/*.md` are project artifacts, not manuscript source. Stable story facts may be saved to `story.yaml`, `characters/*.yaml`, or `outline.yaml` only after approval.
+
+## Save-As-You-Go Rule
+
+Cowriter projects are live writing workspaces. Do not merely discuss or stage planned manuscript/story changes in chat.
+
+- When the writer approves a change, immediately edit the relevant Markdown/YAML file.
+- After applying, run `inspect -o json` to confirm the project reflects the change.
+- Keep each saved change narrow and reversible; do not wait until the end of the conversation to write a batch of unrelated changes.
+- If the writer is still deciding, ask before writing. Once they decide, save it.
+- Still commit at sensible checkpoints and at the end of the work session, but do not treat committing as a substitute for saving.
+
+## Commit Checkpoints
+
+Commit when a coherent writing unit is complete, not after every keystroke and not only at the end of a long session.
+
+Good commit moments:
+
+- After accepted onboarding material is saved: synopsis, initial story fields, first character records, or first outline.
+- After a scene/chapter draft or revision pass is saved.
+- After a continuity/story-bible update that records stable facts.
+- Before switching to a different kind of task, such as moving from manuscript prose to character development.
+- Before pausing, ending the work session, or handing control back after meaningful file changes.
+
+Before committing:
+
+1. Run `git status --short`.
+2. Review the relevant diff, usually `git diff -- chapters story.yaml characters outline.yaml .cowriter`.
+3. Stage only Cowriter book files changed for this writing unit.
+4. Use a concise book-focused message, such as `Develop opening scene`, `Refine synopsis`, or `Update continuity notes`.
+
+Do not commit unrelated user edits, generated build output, or work-in-progress alternatives the writer has not accepted.
+
+## Skill Upgrades
+
+When the user asks to update Cowriter skills, run:
+
+```bash
+cowriter upgrade --path /absolute/path/to/book -o json
+```
+
+This refreshes `.codex/skills/cowriter` and updates the project-local Cowriter instruction block in `AGENTS.md`.
+
+## Writing Rules
+
+- Keep the manuscript and story materials as the center of gravity.
+- Infer the writing workflow from context; do not make the writer choose a skill.
+- Treat generated titles as working titles.
+- Record stable story facts in `story.yaml`; record guesses as tentative notes or questions.
+- Save approved story and manuscript changes to the project files as soon as they are accepted.
+- Prefer narrow edits to whole-chapter rewrites unless the user explicitly asks for a rewrite.
+- Preserve point of view, tense, tone, and continuity unless asked to change them.
+- Commit at sensible creative checkpoints and after work sessions, staging only relevant book files.
+
+## References
+
+- `references/project-model.md`
+- `references/actions.md`
+- `references/onboarding.md`
+- `references/prose-diagnostics.md`
+- `references/context-priming.md`
+- `references/scene-planning.md`
+- `references/title-brainstorming.md`
+- `references/prose-review.md`
+- `references/continuity-review.md`
+- `references/character-voice.md`
+- `references/state-updates.md`
+- `references/import-existing.md`

package/templates/init/.codex/skills/cowriter/references/actions.md

@@ -0,0 +1,52 @@
+# Cowriter File Editing
+
+Cowriter now uses direct file edits instead of action envelopes for normal writing work.
+
+Edit these files directly:
+
+```text
+chapters/*.md
+story.yaml
+characters/*.yaml
+outline.yaml
+.cowriter/project.yaml
+.cowriter/reports/*.md
+```
+
+Use `.cowriter/reports/*.md` for approved review artifacts such as prose, continuity, character voice, or session-summary reports. Do not treat reports as manuscript source; they are advisory project artifacts that `cowriter inspect` can list for Codex and the workspace.
+
+For deterministic chapter prose diagnostics, run:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md -o json
+```
+
+Only add `--write-report` when the writer asks to save the diagnostics as a report artifact.
+
+After a direct edit, inspect the project:
+
+```bash
+cowriter inspect --path /absolute/path/to/book -o json
+```
+
+Use git diff to review file changes:
+
+```bash
+git diff -- chapters story.yaml characters outline.yaml .cowriter
+```
+
+Do not route edits through legacy action JSON. Current Cowriter skills should use direct Markdown/YAML edits and then inspect the project.
+
+When selected manuscript text is needed and not already available, retrieve optional selection context from the served workspace:
+
+```bash
+curl -sS "$COWRITER_URL/api/cowriter/selection"
+```
+
+For UI-only passage highlighting, call the served workspace instead of editing files:
+
+```bash
+curl -sS -X POST "$COWRITER_URL/api/cowriter/codex" \
+  -H 'content-type: application/json' \
+  --data '{"command":"highlight","text":"exact passage text","chapterPath":"chapters/001-opening.md"}'
+```

package/templates/init/.codex/skills/cowriter/references/character-voice.md

@@ -0,0 +1,23 @@
+# Character Voice Review
+
+Use character voice review when the writer asks whether dialogue sounds distinct, wants a character sharpened, or needs a voice pass on selected prose.
+
+Inputs:
+
+- the selected passage or relevant chapter
+- the character record in `characters/*.yaml`
+- story tone, perspective, and continuity constraints
+- dialogue excerpts where the character appears
+
+Output:
+
+- voice fingerprint: diction, sentence shape, evasions, tells, and pressure habits
+- places where the character sounds generic or inconsistent
+- suggested lines or small edits when requested
+- possible updates to desire, conflict, role, or notes
+
+Allowed writes after approval:
+
+- update the relevant `characters/*.yaml`
+- patch selected manuscript dialogue
+- write an advisory character voice report

package/templates/init/.codex/skills/cowriter/references/context-priming.md

@@ -0,0 +1,15 @@
+# Context Priming
+
+Use context priming before drafting, revising, or reviewing when the writer's request depends on book state that is not already in the conversation.
+
+Gather the smallest useful packet:
+
+- `cowriter inspect --path /absolute/path/to/book -o json`
+- active chapter or selected passage when relevant
+- current `story.yaml` fields that affect the request
+- relevant character records and outline beats
+- recent advisory reports only when they directly apply
+
+Then summarize the operative context in a few lines and proceed with the requested work. Do not make the writer choose a workflow name.
+
+If context is missing, ask one focused question or name the assumption before drafting. Save only approved changes.

package/templates/init/.codex/skills/cowriter/references/continuity-review.md

@@ -0,0 +1,22 @@
+# Continuity Review
+
+Use continuity review when the writer asks whether the manuscript contradicts itself, whether a scene still fits the book, or what facts should be remembered.
+
+Check:
+
+- timeline order and elapsed time
+- character knowledge boundaries
+- location transitions
+- object possession
+- relationship state
+- world rules, setting constraints, and promises in `story.yaml`
+- contradictions between manuscript, outline, characters, and reports
+
+Output blockers first, then warnings, then open questions. Include file or chapter references when possible.
+
+Allowed writes after approval:
+
+- update `story.yaml.continuity`
+- update relevant `characters/*.yaml` notes
+- update `outline.yaml` if a beat has changed
+- write an advisory report under `.cowriter/reports/*.md`

package/templates/init/.codex/skills/cowriter/references/import-existing.md

@@ -0,0 +1,16 @@
+# Existing Manuscript Import
+
+Use existing manuscript import when the writer has drafts outside Cowriter and wants help turning them into a Cowriter book project.
+
+Start by inspecting the folder and asking what should be treated as manuscript source. Keep imports transparent and reversible.
+
+Useful steps:
+
+- identify candidate chapter files
+- propose a chapter naming scheme under `chapters/*.md`
+- extract or ask for a working title and synopsis
+- propose initial `story.yaml` fields
+- propose initial character records and outline beats
+- preserve the original source files unless the writer asks otherwise
+
+Do not silently overwrite existing Cowriter chapters or story materials. Ask before moving, converting, or replacing files.

package/templates/init/.codex/skills/cowriter/references/onboarding.md

@@ -0,0 +1,45 @@
+# Cowriter Onboarding
+
+The first interaction should be small and writer-centered. Ask one onboarding question at a time, wait for the answer, and then choose the next most useful question. Do not bundle premise, character, setting, ending, and folder questions into one turn unless the writer asks for a checklist.
+
+Prompt:
+
+> What do you know about the book right now: a title, a synopsis, or an existing folder?
+
+## Title Path
+
+Ask for:
+
+- working title
+- local folder
+
+Create the project. Then ask for a rough one-paragraph synopsis before requesting detailed story fields.
+Interview toward that synopsis one question at a time.
+
+## Synopsis Path
+
+Ask for:
+
+- one-paragraph synopsis
+- local folder
+
+Generate a working title, create the project, and save the synopsis. Make clear the title is editable.
+
+Interview with no more than three focused questions, asked one at a time:
+
+- Who is under the most pressure?
+- What setting or world rule makes the story harder?
+- What ending direction or emotional promise should the book move toward?
+
+Then propose concrete edits to `story.yaml`, `characters/*.yaml`, and `outline.yaml`. When the writer accepts them, write those files directly.
+
+## Existing Folder Path
+
+Open and inspect the folder. Summarize:
+
+- title
+- synopsis status
+- chapter count and active chapter
+- character count
+- outline beat count
+- next writing task

package/templates/init/.codex/skills/cowriter/references/project-model.md

@@ -0,0 +1,45 @@
+# Cowriter Project Model
+
+A Cowriter book is a local git-backed folder:
+
+```text
+chapters/*.md
+story.yaml
+characters/*.yaml
+outline.yaml
+.cowriter/project.yaml
+.cowriter/reports/*.md
+```
+
+`story.yaml` contains:
+
+- `title`
+- `synopsis`
+- `setting`
+- `themes`
+- `genre`
+- `tone`
+- `perspective`
+- `continuity`
+
+Each character file contains:
+
+- `id`
+- `name`
+- `role`
+- `desire`
+- `conflict`
+- `notes`
+
+`outline.yaml` contains:
+
+```yaml
+beats:
+  - id: opening-beat
+    title: ""
+    summary: ""
+```
+
+Codex should edit book files directly with conservative path handling, then run `cowriter inspect` to confirm the project shape still loads.
+
+`.cowriter/reports/*.md` files are readable Cowriter report artifacts. They may contain optional YAML frontmatter with `type`, `title`, `status`, `createdAt`, and `chapter`. Current review workflows may write reports there only when the writer has approved generating a review artifact.

package/templates/init/.codex/skills/cowriter/references/prose-diagnostics.md

@@ -0,0 +1,33 @@
+# Cowriter Prose Diagnostics
+
+Cowriter includes a deterministic chapter-level prose diagnostics command. Use it when the writer asks for a prose check, style scan, AI-ish wording scan, rhythm check, or an advisory review before revision.
+
+Run diagnostics:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md -o json
+```
+
+The command is read-only unless `--write-report` is passed. It returns:
+
+- chapter path
+- metrics: word count, paragraph count, sentence count, dialogue percent, average sentence words, and em dash count
+- findings with `info`, `warning`, or `issue` severity
+
+Current deterministic checks cover:
+
+- repeated nearby words
+- paragraphs over 120 words
+- unusually uniform sentence rhythm
+- dialogue percentage that is very low or very high in longer chapters
+- filler or AI-ish terms
+- mixed straight and curly double quotes
+- em dash density
+
+To save an approved report artifact:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md --write-report -o json
+```
+
+Saved reports live in `.cowriter/reports/*.md` and are advisory project artifacts, not manuscript source. Do not use diagnostics as a pass/fail gate, and do not rewrite the manuscript unless the writer approves a specific edit.

package/templates/init/.codex/skills/cowriter/references/prose-review.md

@@ -0,0 +1,22 @@
+# Prose Review
+
+Use prose review when the writer asks for craft feedback on selected prose, a page, a scene, or a chapter.
+
+Review for:
+
+- repetition and over-explanation
+- sentence rhythm and paragraph length
+- dialogue balance and subtext
+- weak filtering, abstraction, or filler
+- cliche or generic diction
+- point-of-view, tense, and tone drift
+
+For whole chapters, the deterministic diagnostics command can provide a first pass:
+
+```bash
+cowriter diagnose prose --path /absolute/path/to/book --chapter chapters/001-opening.md -o json
+```
+
+Use `--write-report` only when the writer asks for a saved review artifact.
+
+Default output is advisory findings ordered by importance. Offer narrow patch suggestions only when useful. Rewrite manuscript text only after the writer approves a specific edit.

package/templates/init/.codex/skills/cowriter/references/scene-planning.md

@@ -0,0 +1,28 @@
+# Scene Planning
+
+Use scene planning when the writer asks what to write next, wants to shape an outline beat, or needs a concrete scene task.
+
+Inputs:
+
+- synopsis, genre, tone, and perspective
+- active or next outline beat
+- relevant character desire, conflict, and knowledge
+- continuity constraints
+- desired chapter or scene target if the writer gives one
+
+Output a focused scene plan with:
+
+- scene goal
+- obstacle or pressure
+- turn, reveal, or reversal
+- emotional movement
+- exit image or handoff into the next beat
+- continuity facts to preserve
+
+Allowed writes after approval:
+
+- update `outline.yaml`
+- update relevant `characters/*.yaml` notes
+- update `story.yaml.continuity`
+
+Keep the plan usable for the next writing step. Do not draft the scene unless the writer asks.

package/templates/init/.codex/skills/cowriter/references/state-updates.md

@@ -0,0 +1,22 @@
+# State Updates
+
+Use state updates after an approved scene, chapter, or revision checkpoint. The goal is to keep story materials aligned with the manuscript.
+
+Extract only stable facts:
+
+- timeline events
+- character location, knowledge, relationship, desire, or conflict changes
+- object and setting state
+- decisions the writer confirmed
+- continuity constraints introduced by the new prose
+
+Propose the updates before writing them. Keep guesses as questions or tentative notes.
+
+Allowed writes after approval:
+
+- `story.yaml.continuity`
+- `characters/*.yaml`
+- `outline.yaml`
+- advisory report under `.cowriter/reports/*.md`
+
+Run `cowriter inspect --path /absolute/path/to/book -o json` after saving.

package/templates/init/.codex/skills/cowriter/references/title-brainstorming.md

@@ -0,0 +1,27 @@
+# Title Brainstorming
+
+Use title brainstorming when the writer asks for titles, alternatives to the current title, subtitles, series-title ideas, or title direction.
+
+Inputs:
+
+- synopsis
+- genre, tone, themes, and perspective
+- protagonist, setting, and central conflict
+- writer preferences, comparable titles, title styles to avoid, and forbidden words
+
+Output grouped candidates with short rationales. Useful groups include:
+
+- literary
+- commercial
+- genre-forward
+- character-focused
+- setting-focused
+- thematic
+- short and punchy
+
+Rules:
+
+- Treat every generated title as a working title.
+- Do not replace the project title automatically.
+- Update `story.yaml.title` only after the writer explicitly chooses a title.
+- If the writer chooses one, save the exact chosen title and run `cowriter inspect --path /absolute/path/to/book -o json`.

package/templates/init/.cowriter/project.yaml

@@ -0,0 +1,3 @@
+title: {{metadataTitle}}
+author: {{author}}
+createdAt: {{createdAt}}

package/templates/init/.cowriter/reports/.gitkeep

@@ -0,0 +1 @@
+Reports generated by Cowriter review workflows live here.