README.md

# APODICTIC Development Editor

Developmental editing that listens before diagnosing.

AI-powered developmental editing framework for fiction, narrative nonfiction, and persuasive/argument-shaped nonfiction (policy briefs, op-eds, testimony — via the Nonfiction Argument Engine). Diagnoses structural issues in manuscripts through systematic passes, genre-calibrated analysis, and specialized audits.

## Installation

The generated local Codex install path is workspace-based:

1. From the repo root, run:
   ```bash
   node scripts/build-codex.mjs
   ```
2. Open the generated `codex/` folder as your Codex workspace root.
3. In Codex, open the Plugins view and install `APODICTIC` from the local marketplace.
4. Start a fresh thread and run `apodictic-start`.

If the plugin does not appear, make sure Codex is opened on the generated `codex/` directory, not the repo root.

## OpenAI Directory Package

The same build creates `dist/apodictic-openai-plugin.zip` for the OpenAI plugin
submission portal. Its archive root is the plugin root, with skills, command
references, scripts, schemas, and assets. The marketplace ZIP above is for local
workspace installation; use the standalone ZIP for directory submission.

This is a skills-only package. It has no MCP connection or author-operated
backend. Start with `apodictic-start` or a plain-language manuscript intake
request. Shell checks and exports require host execution support; independent
pass agents require delegation; saved-project resume requires persistent file
storage. SETEC supplements require a separate compatible installation. Hosts
without shell execution use the documented inline checks where supported;
they cannot record those checks as mechanically executed or promise scripted
exports. In-app installation and workflow parity must be tested in the target
host. See the repository's [submission guide](https://github.com/anotherpanacea-eng/apodictic/blob/main/docs/openai-skills-only-plugin.md).

## Quick Start In Codex

If you're new to the plugin, start with a plain-language request:

- "Use APODICTIC to tell me what kind of manuscript help I need."
- "Use APODICTIC to diagnose the structural problems in this draft."
- "Use APODICTIC to help me plan revisions without rewriting prose."

If you already know the entrypoint you want, invoke the namespaced workflow directly:

- `apodictic-start`
- `apodictic-audit shelf`
- `apodictic-coach`

The plugin is designed to feel natural in chat, so plain-language requests and named `apodictic-*` entrypoints should both work.

## What It Does

The Development Editor works like a human developmental editor: it reads a manuscript, infers what it's trying to do, and diagnoses where it succeeds or struggles. The system listens first — inferring authorial intent from the text — before measuring the work against that intent.

**Key design principle:** The editor predicts the manuscript's contract (genre, reader promise, controlling idea) from the text alone. Misalignments between the inferred contract and the author's stated intent are diagnostically valuable — they reveal where the text doesn't communicate what the author intended.

**The Firewall:** The system diagnoses problems and identifies classes of solution. It never invents content (new plot events, characters, dialogue, imagery). The author creates; the system analyzes.

## What This Plugin Does and Does Not Do

**It does:**
- Diagnose structural problems in fiction and narrative nonfiction manuscripts
- Identify where a manuscript succeeds or struggles relative to its own implied contract (genre, reader promise, controlling idea)
- Provide genre-calibrated analysis across literary fiction, horror, mystery, thriller, science fiction, fantasy, romance, and cross-genre hybrids
- Track continuity, pacing, character arcs, reveal economy, emotional dynamics, and thematic coherence across 11 systematic passes
- Run specialized audits for specific craft concerns (scene function, shelf positioning, AI-prose detection, worldbuilding integration, force delivery, and more)
- Diagnose argument-shaped nonfiction with the **Nonfiction Argument Engine** — argument spine, support, and warrant, plus Red-Team, Persuasion, and Evidence companions
- Maintain a **Legal Risk Register** that flags possible defamation, privacy, and rights exposure for a lawyer's review — it flags, never adjudicates, and is never legal advice
- **Triage feedback** and build a **beta-reader instrument** — sort and prioritize beta-reader/editor notes, and turn a diagnosis into targeted reader questions
- Render **manuscript-structure visualizations** and offer **Diagnostic-Vocabulary** and **Editor-Scaffolding** operator modes
- Keep projects addressable and resumable (`apodictic-projects`, state-driven resume), including **Retcon Planning** and **State Cards**
- Generate editorial letters, revision checklists, and diagnostic state that persists across revision rounds
- Guide pre-draft writers from idea to draftable structure

**It does not:**
- Rewrite prose, generate new scenes, invent characters, or produce creative content (the Firewall)
- Line edit, copyedit, or proofread
- Replace a human developmental editor's judgment — it provides analytical scaffolding, not verdicts
- Guarantee commercial viability, publication readiness, or literary merit
- Add telemetry, analytics, or a server of its own. Diagnostic state stays in your host's project workspace when persistent file tools are available. Your host provider governs its processing and storage. The optional `apodictic-research` and citation-checking modes query public scholarly services (Crossref, OpenAlex, Semantic Scholar, Unpaywall, CORE, PubMed, and the Wayback Machine) with a DOI, title, short search query, or URL; see [PRIVACY.md](./PRIVACY.md).

The system diagnoses structure. The author creates content. After diagnosis, you can either stay inside APODICTIC's coaching/editor workflows or switch to a general writing session outside the diagnostic firewall.

## Intended Audience

**Primary audience:** Fiction writers working on novels, novellas, and story collections. The plugin also supports narrative nonfiction, memoir, and creative nonfiction with genre-appropriate calibrations. Writers of persuasive, argument-shaped nonfiction — policy briefs, op-eds, and testimony — are a real audience too: the revision-coaching layer triggers on those forms and the Nonfiction Argument Engine diagnoses their argument structure.

**Secondary audience:** Human developmental editors seeking analytical scaffolding, and writing groups using diagnostic vocabulary for structured feedback.

The plugin assumes its user is an adult working on a creative project. Its outputs are structural diagnoses, editorial letters, and revision recommendations — analytical documents, not fiction.

## Components

### Workflows

- **Development Edit** — The main workflow: intake protocol, 11 analysis passes, synthesis, revision rounds, genre calibration
- **Pre-Writing Pathway** — Guides writers from idea to draftable structure (no manuscript required). Writer mode calibration, seed inventory, readiness gates, option architecture, complexity budget, prospective contract, re-entry diff protocol.
- **Plot Coaching** — Plot structure diagnosis (50 spines across 12 families), selection coaching, fantasy & series architecture
- **Specialized Audits** — 38 available audits (3 universal, 20 craft, 10 genre, 5 tag), including 3 primary tags (cozy, philosophical, erotic content) and 2 companion intimacy audits; plus 6 internet-enabled research modes. A small catalog dispatches to five owning skills: narrative craft, genre/reader expectations, argument analysis, research/verification, and prose measurements
- **Nonfiction Argument Engine** — Diagnoses argument-shaped nonfiction (op-eds, policy briefs, testimony, academic arguments, legal briefs, regulatory comments): argument spine, support, and warrant, with Red-Team, Persuasion, Evidence, and Adversarial Evidence companions, Field Reconnaissance and Citation Verifier research modes, argument pre-draft, and an optional AIF argument-map export
- **Legal Risk Register** — Flags possible defamation, privacy, and rights exposure for counsel to review. It flags, never adjudicates — not legal advice
- **Feedback Triage & Beta-Reader Instrument** — Sort, cluster, and prioritize beta-reader/editor feedback, and turn a diagnosis into targeted beta-reader questions
- **Projects** — Addressable, resumable editing projects (`apodictic-projects`, state-driven resume), with Retcon Planning and State Cards
- **Revision Coaching** — Post-diagnostic coaching: session planning, stuck-point help, momentum tracking, deadline management
- **Manuscript-structure visualizations** and **Diagnostic-Vocabulary / Editor-Scaffolding** operator modes

### Entrypoints

In this Codex build, the legacy workflows are exposed as namespaced compatibility skills. Invoke them by name or by plain-language request.

**Start here:**
- `apodictic-start` — I have a manuscript — what should I do with it?
- `apodictic-index` — What can this plugin do? Where do I start?

**Diagnostic workflows:**
- `apodictic-ready` — Is this ready to submit?

**Focused tools:**
- `apodictic-audit` — Run a specific deep-dive analysis.
- `apodictic-research` — I need internet-assisted verification.
- `apodictic-coach` — I have a diagnosis — how do I revise?
- `apodictic-plot-coach` — Is my plot structure working?
- `apodictic-legal-risk` — Flag legal exposure (defamation, privacy, rights) for a lawyer's review.
- `apodictic-triage-feedback` — Sort and prioritize beta-reader / editor feedback.
- `apodictic-reader-questions` — Turn my diagnosis into targeted beta-reader questions.

**Setup:**
- `apodictic-pre-writing` — I have an idea but no manuscript yet.
- `apodictic-new-project` — Set up a new editing project.
- `apodictic-projects` — List, resume, and tidy my editing projects.

### Selection Guide

- See `AUDIT_SELECTION_MATRIX.md` for a practical routing chart of core passes, full passes, Pass 11 sub-passes, specialized audits, tag audits, and research modes.
- See `overview-dashboard.html` for a visual map of workflows, pass blocks, and audit families.
- See `project-dashboard.html` for an at-a-glance **snapshot** of your projects — paste the registry payload `apodictic-projects` produces and see where each project stands on the lifecycle rail plus its launch command. Render-only (a viewer/launcher, not a live monitor).

## Usage

### Getting Started
```
apodictic-start
```
The intake router asks what you have (idea, fragments, partial draft, complete draft, series, or an argument-shaped piece), what you need (draft, diagnose/fix, submission readiness, AI cleanup), and any modifiers (deadline, AI-assisted text, nonfiction, editing for someone else, co-authoring). Routes you to the right workflow automatically. All other namespaced entrypoints remain available as direct shortcuts.

### Full Development Edit
```
apodictic-start path/to/manuscript.md
```
Answer "complete draft" + "diagnose/fix" and the router runs intake, core passes (reverse outline, reader experience, structural mapping, character audit, reveal economy), and synthesis. Outputs an editorial letter, revision checklist, and diagnostic state.

### Argument-Shaped Nonfiction
```
apodictic-start path/to/op-ed.md
apodictic-audit dialectical
```
Answer "an argument-shaped piece" and the router sends op-eds, policy briefs, testimony, academic arguments, open letters, white papers, legal briefs, regulatory comments, and expert affidavits to the Nonfiction Argument Engine. It infers the claim, audience, burden of proof, and stakes, then writes an argument editorial letter and `Argument_State.md`, the shared argument record the companions read. After that, run the companions you need: `apodictic-audit argument-red-team` (strongest opposition), `apodictic-audit argument-persuasion` (audience fit), `apodictic-audit argument-evidence` (evidence chain), `apodictic-audit adversarial-evidence-review` (would each claim-evidence link survive a hostile expert), `apodictic-research field-recon` (counterevidence and literature gaps), and `apodictic-research citation-verifier` (do the sources exist and say what you claim). `apodictic-coach` plans the revision. No draft yet? `apodictic-pre-writing` builds the argument spine first. `apodictic-adjudicate` records your decisions on a reconstructed claim graph, and an optional AIF export turns `Argument_State.md` into a standard argument-map graph.

### Submission Readiness
```
apodictic-ready
```
The full "is this ready?" workflow. Runs Core DE → Synthesis → Pass 11 → Compression Test and produces a unified readiness assessment with verdict, market reality check, opening conversion gate, SR code inventory, and query/synopsis diagnostic. For deadline-constrained writers, say "I'm on a deadline" during intake to get Submission Triage (single-pass go/no-go) instead.

### Quick Diagnosis
```
apodictic-start
# then answer: diagnose/fix → name one concern, e.g. "pacing in Act II"
```
A focused check on that one concern, without the full pass sequence.

### Pre-Writing Pathway
```
apodictic-pre-writing
```
For writers with an idea but no manuscript. Calibrates writer mode (architecture-first vs. discovery-first), inventories seeds, builds a protagonist engine, offers 2–3 structural candidates, sets complexity caps, and produces a Structural Plan or Minimal Viable Plan. When the writer returns with a draft, the Re-Entry Diff Protocol compares intent against execution.

### Plot Coaching
```
apodictic-plot-coach
```
Helps choose or fix a plot structure. Works for pre-drafting planning, stuck drafts, and structural pivots.

### Specialized Audit
```
apodictic-audit character
apodictic-audit shelf
apodictic-audit
```
Run a named audit or list all 38 available audits.

### Research Mode
```
apodictic-research comp
apodictic-research fact-check
```
Internet-enabled research to validate comps, check facts, verify genre currency, or surface representation context.

## Execution Modes

APODICTIC selects its execution mode based on the available context window. On large-context frontier models, the default is **single-agent mode**: one subagent runs all passes sequentially in a single context, with the full manuscript in view throughout. This is the fastest and most token-efficient option, viable for manuscripts up to roughly 200,000 words.

For a **final-round verification pass**, request **swarm mode**: each pass runs as an independent subagent loading the full manuscript. The gain is **architectural isolation** — each pass genuinely cannot see prior analysis until reconciliation, which eliminates anchoring bias — at approximately **5x the token cost**. Best reserved for final submission prep: an earlier validation reported ~2× findings, but a 2026-06 N=1 re-test on long fiction did not reproduce a depth advantage, so swarm's dependable value is verification isolation, not everyday yield.

On standard-context models, APODICTIC falls back to per-pass subagent dispatch with three tiers: **sequential** (each pass gets the full manuscript), **hybrid** (later passes get targeted excerpts via a focus map, ~2–3x cost), and **swarm** (parallel independent subagents, ~5x cost).

**When to consider each mode:**

- **Single-agent** (default on large-context models): Most manuscripts, quick diagnostics, budget-constrained runs.
- **Swarm**: Final-round diagnostics before submission, or when prior runs produced findings that echo rather than complicate each other.
- **Sequential / Hybrid**: Automatic on standard-context models; not typically needed on large-context models unless you prefer per-pass isolation.

To invoke swarm: tell the editor "run this in swarm mode" at intake.

## Model Requirements

APODICTIC works best on high-capability models with strong instruction-following and enough context to hold large manuscript sections in memory. On weaker or smaller-context models, expect degraded severity honesty, thematic interpretation, deliberate ambiguity handling, and fix quality. If you're evaluating the framework, use the best model available in your Codex environment.

## Framework Version

Current Codex manifest version is `2.13.3`. Capabilities: 50 plot spines across 12 families, 38 available audits (3 universal, 20 craft, 10 genre, 5 tag), 6 research modes, 11 core passes, the evaluative Pass 11 gate, the pre-writing pathway, and the intake router. Includes contract-driven and finding-driven audit integration pipeline.

## License

This work is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).

You can use, adapt, and share this framework for non-commercial purposes, with attribution and under the same license. See [LICENSE](LICENSE) for details.

## Author

anotherpanacea