zhougz520/novel-architect

Novel Architect — Skill de Creación de Novelas Web Comerciales

Versión 3.0.0. El objetivo es que el Agente, mediante una combinación híbrida de "guardias de estado de script + juicio literario del modelo", complete de forma estable la apertura, continuación, revisión, corrección y mantenimiento a largo plazo de novelas web chinas comerciales.

0. Principios Generales

Trata este skill como un flujo de trabajo autoejecutable; no transfieras la lista de comandos CLI al usuario.

• El usuario proporciona los objetivos creativos de alto nivel, género, plataforma, preferencias, limitaciones y decisiones direccionales importantes.
• El Agente debe leer este SKILL.md, y cuando sea necesario, references/, llamar al CLI novel_architect por sí mismo, leer los productos generados, generar JSON / texto / correcciones, y avanzar hasta un punto de parada válido.
• El CLI de Python es la capa de herramientas deterministas, encargada del estado del proyecto, índices, contabilidad, compuertas, señales, hash y almacenamiento en disco; no es un manual de instrucciones para que el usuario lo ejecute manualmente.
• El modelo se encarga del juicio literario y la producción creativa: market pack, selección de beats, escritura del texto, señales del modelo, corrección de texto, diagnóstico de retroalimentación.
• Solo pregunta al usuario cuando falten herramientas de shell/archivos, la ruta del proyecto sea desconocida y no se pueda deducir, o se necesite una decisión real de dirección creativa.

Los únicos puntos de parada válidos son: capítulo con gate.passed=true y commit realizado; fallo en la revisión de los primeros tres capítulos que requiera reescribir el inicio o rehacer el market pack; falta de entrada necesaria que imposibilite continuar; permisos de herramienta insuficientes; necesidad de que el usuario elija entre múltiples direcciones creativas importantes.

1. Convención de Ejecución de Comandos

Ejecuta los comandos en un espacio de trabajo donde se pueda importar novel_architect. Prioriza el uso del directorio raíz del repositorio del proyecto:

uv run python -m novel_architect <comando> ...

Si el entorno actual no tiene uv pero el paquete está instalado, usa:

python -m novel_architect <comando> ...

Si el script de consola está disponible, también se puede usar:

novel-architect <comando> ...

Antes de ejecutar, determina la ruta del proyecto: si el usuario proporciona la ruta, úsala; si el usuario dice "este libro / continúa", primero verifica los directorios comunes projects/<nombre_del_libro>/ y project.json; si hay múltiples candidatos y no se puede determinar, pregunta al usuario.

Comandos como review, save-first3-review que devuelven un código distinto de cero generalmente indican que la compuerta no se ha pasado, no que el programa haya fallado. En ese caso, lee el JSON de salida, gate.json o repair.json, corrige y reintenta.

2. Contrato de Ejecución Autónoma del Agente

Acciones que debe realizar por sí mismo

Cuando la tarea implique abrir un libro, continuar, revisar, corregir, cambiar la estructura, reconstruir, diagnosticar retroalimentación o verificar el estado, el Agente debe llamar al CLI por sí mismo, leer la salida, escribir archivos y continuar con el flujo.

No te limites a responder:

Ejecuta python -m novel_architect prepare ...

Debes ejecutar realmente el comando, inspeccionar los productos y luego continuar con el siguiente paso. Solo cuando el entorno carezca de permisos de shell/archivos, proporciona el comando al usuario.

Los prompts exportados son elementos de trabajo del Agente

Estos comandos exportan archivos de prompt o input. El Agente debe leerlos y generar el JSON/texto correspondiente por sí mismo, y luego llamar al comando de guardado o actualizar el archivo.

Comando de exportación	Producto	Siguiente paso del Agente
market-open	editorial/market_pack_prompt.md, market_pack_input.json	Generar JSON estricto, llamar a market-save
beat-candidates	editorial/chXXXX/beat_competition_prompt.md, beat_competition_input.json, beat_options.json	Seleccionar/generar el mejor plan, llamar a beat-select, luego apply-beat-selection
export-signal-prompts	12 JSON de prompts de señal	Generar JSON de señal del modelo uno por uno, llamar a save-model-signal
first3-review	data/reviews/first3_review_prompt.md, first3_review_input.json	Generar un veredicto que contenga review_input_hash y 8 puntuaciones, llamar a save-first3-review
feedback-diagnose	data/feedback/chXXXX_diagnosis_prompt.md, input	Generar diagnóstico; si es necesario guardar, escribir el diagnóstico en diagnosis del JSON de retroalimentación y luego llamar a save-feedback
export-title-review-prompt / export-intro-review-prompt	Prompts de revisión de título/introducción	Generar diagnóstico, actualizar market_pack.json, candidatos de título/introducción o materiales de apertura del libro si es necesario

No hagas que el usuario pegue estos prompts a otro modelo, a menos que el usuario solicite explícitamente este modo de colaboración manual.

3. Referencia Rápida de Tareas

Intención del usuario	Flujo principal que debe ejecutar el Agente
Abrir un nuevo libro	init → market-open → market-save → Reforzar fuentes de verdad → first-10-retention / save-first10-plan → Producción de prueba de los primeros 3 capítulos
Continuar escribiendo el siguiente capítulo	status → prepare → Competencia de beats → Escribir texto → review → Señales del modelo → review → Ciclo de corrección → commit
Reparar este capítulo	Leer editorial/chXXXX/repair.json y gate.json → Modificar texto → review → Señales del modelo necesarias → review de nuevo → Si pasa, commit
Revisión de primeros 3 capítulos	Después de commit de los capítulos 1-3, ejecutar first3-review → Generar veredicto → save-first3-review
Cambiar estructura/configuración	Modificar src/*.json (fuentes de verdad) → rebuild → status → Si es necesario, re-ejecutar review de los capítulos afectados
Examen por lotes / de volumen	batch-review, volume-review, benchmark, status
Retroalimentación de plataforma	save-feedback → feedback-diagnose → Generar diagnóstico → Actualizar planificación continua / market pack / notas de capítulo
Modelado de libro deconstruido	learn --sample-dir <dir>, luego convertir las conclusiones en ajustes ejecutables de género/ritmo/planificación de capítulos

gen-prompt solo se usa cuando el usuario solicita explícitamente "exportar un prompt independiente para un modelo de escritura externo / Claude Code". Para la continuación normal, no uses gen-prompt como reemplazo del flujo principal prepare → beat → writing_task → review → commit.

4. Flujo de Apertura de un Nuevo Libro

Al abrir un nuevo libro, no empieces a escribir el Capítulo 1 directamente. Primero establece el posicionamiento de mercado y las fuentes de verdad.

4.1 Inicializar el Proyecto

python -m novel_architect init --project <directorio_proyecto> --title <título> --genre <género> --platform <plataforma> --premise <premisa> --core-hook <gancho_central> --protagonist <nombre>

La inicialización genera project.json, src/, manuscript/, data/, editorial/ y otros directorios. La inicialización solo proporciona el esqueleto, no significa que la planificación del libro esté completa.

4.2 Generar y Guardar el Market Pack

Ejecuta market-open, lee el prompt/input exportado, genera el JSON estricto por ti mismo, y luego ejecuta market-save.

El market pack debe contener al menos:

• target_platform
• genre_lane
• target_reader
• reader_desires
• core_sell_points
• anti_sell_points
• title_candidates
• intro_candidates
• first_10_chapter_retention_plan
• platform_notes
• author_constraints

Cada capítulo en el plan de los primeros 10 capítulos debe tener chapter, hook, visible_payoff, drop_off_risk. No escribas frases vacías como "aumentar el conflicto" o "mejorar la satisfacción" que no sean ejecutables.

4.3 Reforzar las Fuentes de Verdad

src/ es la fuente de verdad confirmada manualmente. Después de abrir el libro, verifica y refuerza:

• src/blueprint.json: Premisa, gancho central, conflicto central, objetivo del protagonista.
• src/characters.json: Identidad del personaje, deseos, miedos, debilidades, arco, slug.
• src/character_voice_bible.json: Reglas de voz del personaje, tonos prohibidos, preferencias de acción, puntos de fuga emocional. La estructura es {"schema_version":1,"characters":{"nombre_del_personaje":{...}}}; si el archivo sigue siendo un esqueleto o el personaje tiene needs_completion=true, complétalo antes de escribir el texto formal.
• src/world.json: Reglas del mundo/industria/poder, conserva solo los ajustes que sirven al conflicto y la satisfacción.
• src/taboos.json: Tramas que absolutamente no se pueden tocar, sabor a IA, antimodelos del género.
• src/volumes.json: Objetivos a nivel de volumen y borradores de capítulos en evolución. No escribas cada capítulo de una vez.
• src/genre_config.json: Estrategia de género; el soporte incorporado prioriza xianxia, fantasía urbana, estrategia histórica, suspense. Otros géneros necesitan depender más del market pack y de un genre_config personalizado.

Después de modificar las fuentes de verdad, ejecuta:

python -m novel_architect rebuild --project <directorio_proyecto>
python -m novel_architect status --project <directorio_proyecto>

No modifiques manualmente los libros de contabilidad o el estado derivado en data/ para "arreglar" la trama; las correcciones semánticas a largo plazo se escriben en src/ledger_overrides.json o en los src/*.json correspondientes, y luego se reconstruyen.

4.4 Plan de Retención de los Primeros Diez Capítulos

Usa first-10-retention para exportar/generar el plan; si es necesario, refínalo y luego guárdalo con save-first10-plan. Los primeros diez capítulos son el embudo de entrada; la planificación debe ser específica para cada capítulo: hook, beneficio visible, riesgo de abandono y qué no hacer.

5. Flujo Estándar para Continuar con el Siguiente Capítulo

Cada capítulo debe completar un ciclo completo. No escribas el texto directamente basándote en el contexto del chat.

5.1 Verificación de Estado

Primero ejecuta:

python -m novel_architect status --project <directorio_proyecto>

Determina el número de capítulos completados, el estado de la compuerta, la salud del índice y los riesgos pendientes. No confíes en la memoria del chat para determinar el número del siguiente capítulo.

5.2 PREPARE

python -m novel_architect prepare --project <directorio_proyecto> --query "<requisitos creativos de alto nivel para este capítulo>"

Producto: editorial/chXXXX/writing_task.json. Este es el paquete de tareas autocontenido para la fase de escritura, debe ser leído. Contiene writer_brief, narrative_context, ranuras narrativas, campos de retención comercial, voz del personaje, promesas al lector, formato de salida y reglas estrictas.

A partir del Capítulo 4, prepare verificará la revisión especial de los primeros tres capítulos. No uses --force-after-first3-fail para libros nuevos normales; este parámetro solo se usa para migración de proyectos antiguos o depuración.

5.3 Competencia de Beats

Los capítulos 1-10 deben ejecutar la competencia de beats; después del capítulo 10, también se recomienda por defecto, a menos que el usuario solicite explícitamente un borrador rápido.

python -m novel_architect beat-candidates --project <directorio_proyecto> --chapter <n>

Lee el prompt exportado, genera o selecciona el plan con la estrategia más sólida, guárdalo y aplícalo:

python -m novel_architect beat-select --project <directorio_proyecto> --chapter <n> --file <selection.json>
python -m novel_architect apply-beat-selection --project <directorio_proyecto> --chapter <n>

Criterios de selección: el punto de satisfacción visible más claro, la pérdida del enemigo más concreta, el botón del personaje más distintivo, la razón más fuerte para querer continuar leyendo al final del capítulo, el menor riesgo de abandono. Después de aplicar, vuelve a leer el writing_task.json actualizado.

5.4 ESCRIBIR

Escribe el texto según writing_task.json y guárdalo en manuscript/CapítuloXXX-Título.md. El título debe tener gancho; no lo guardes solo como CapítuloXXX.md.

El texto debe cumplir estrictamente con writing_task.output_format.field_template:

1. # CapítuloXXX-Título
2. ## Información del Capítulo
3. ## Esquema de este Capítulo
4. ## Texto
5. ## Escritura de Retroalimentación de Memoria

Requisitos clave:

• El texto no debe tener menos de 2000 caracteres, objetivo 2000-2500 caracteres.
• Usa comillas curvas chinas “”.
• El primer párrafo debe continuar el gancho del capítulo anterior; para el Capítulo 1, establece rápidamente la presión, el deseo del protagonista y la oportunidad visible.
• Cada capítulo debe tener un punto de satisfacción visible que un lector común pueda parafrasear en 5 segundos.
• Los procesos/términos profesionales deben traducirse en ganancias o pérdidas de dinero, poder, prestigio, identidad, relaciones, secretos, capacidad de combate, recursos o seguridad.
• El diálogo de los personajes debe reflejar character_voice_bible; está prohibido que todos los personajes usen el mismo tono de resumen estratégico.
• Si se crean nuevas expectativas del lector, se deben completar las nuevas promesas al lector en la escritura de retroalimentación de memoria; si se cumplen las expectativas, se deben completar el ID de cumplimiento y la evidencia visible.

5.5 REVISIÓN Primera Ronda

python -m novel_architect review --project <directorio_proyecto> --chapter <n>

Si devuelve un código distinto de cero, lee editorial/chXXXX/gate.json y repair.json, no lo omitas.

5.6 Evaluación de Señales del Modelo

Exporta los prompts de señal:

python -m novel_architect export-signal-prompts --project <directorio_proyecto> --chapter <n>

Para los primeros 10 capítulos, inicio de volumen, final de volumen, clímax, giros, capítulos previos a la publicación: genera las 12 señales y guarda las señales del modelo.

Durante el período estable, como mínimo cubre:

• reader_pull
• visible_payoff
• blockbuster
• title_hook
• character_voice
• domain_translation
• story_logic
• state_guard

Guarda cada señal del modelo:

python -m novel_architect save-model-signal --project <directorio_proyecto> --chapter <n> --signal <tipo_senal> --file <senal.json>

Las señales del modelo deben ser JSON estrictos. Si la puntuación es inferior a 7, no se debe escribir pass. El pass del modelo no puede sobrescribir un warn/fail heurístico; la fusión final utiliza el resultado más estricto.

5.7 REVISIÓN Segunda Ronda y Ciclo de Corrección

Después de guardar las señales del modelo, vuelve a ejecutar:

python -m novel_architect review --project <directorio_proyecto> --chapter <n>

Solo se puede hacer commit si gate.json tiene passed=true. Si passed=false, lee repair.json, modifica el texto y repite el ciclo review/señal del modelo/review hasta que pase o se alcance un punto de parada válido.

5.8 COMMIT

python -m novel_architect commit --project <directorio_proyecto> --chapter <n>

Solo se ejecuta después de que la compuerta haya pasado. commit avanza el estado, reconstruye el índice, actualiza el libro de contabilidad, maneja la creación/cumplimiento/vencimiento de promesas al lector. No hagas commit de capítulos fuera de orden; no modifiques manualmente gate.json o las señales para forzar el pase.

6. Compuerta Especial de los Primeros Tres Capítulos

Los capítulos 1-3 de un libro nuevo son la fase de producción de prueba. Después de que los capítulos 1, 2 y 3 hayan completado prepare → beat → write → review → model signals → review → commit, se debe ejecutar:

python -m novel_architect first3-review --project <directorio_proyecto>

Lee data/reviews/first3_review_prompt.md y first3_review_input.json, genera el JSON del veredicto y luego guárdalo:

python -m novel_architect save-first3-review --project <directorio_proyecto> --file <first3_verdict.json>

Para permitir continuar con el Capítulo 4, se deben cumplir simultáneamente:

• verdict == "continue"
• bulk_continue_allowed == true
• Incluir el review_input_hash actual tal como está
• Las 8 puntuaciones deben estar presentes: title_intro_click_score, first_chapter_hook_score, protagonist_desire_score, conflict_speed_score, first_payoff_speed_score, enemy_or_pressure_score, setting_clarity_score, continuation_score
• Todas las puntuaciones son números del 1 al 10, y todas >= 7

Si el resultado es rewrite_opening, primero corrige los primeros tres capítulos; si es redo_market_pack, primero rehaz el market pack, el título/la introducción y el plan de los primeros diez capítulos. No uses --force-after-first3-fail para avanzar normalmente en un libro nuevo.

Después de que cambien el texto de los primeros tres capítulos, el market pack o los datos de entrada iniciales, el first3_review antiguo bloqueará la producción a partir del Capítulo 4 debido a que el hash caduca; se debe volver a ejecutar first3-review y guardar el nuevo veredicto.

7. Compuerta y las 12 Señales

review genera 12 señales, veredicto, compuerta, reparación. Cada revisión vuelve a ejecutar la señal heurística; la señal del modelo fresco se guarda como variante .model.json y participa en la fusión más estricta; la señal final toma el resultado más estricto.

Señal	Qué detecta	Manejo de fallo
anti_ai	Frases hechas de IA, densidad abstracta, párrafos vacíos, comillas rectas	hard, debe corregirse
story_logic	POV, fuente de información, lógica de poder/negocio, infodump	hard, debe corregirse
state_guard	Ganchos, consecuencias, línea del enemigo, elementos necesarios, zonas prohibidas, promesas al lector vencidas	hard/quality, debe corregirse
emotion	Arco emocional, dinámica de relaciones, consecuencias	quality, no se puede hacer commit si falla
blockbuster	Arco de satisfacción de cuatro partes: presión/contraataque/cumplimiento/consecuencia	quality, no se puede hacer commit si falla
visible_payoff	Ganancias/pérdidas de dinero, poder, prestigio, identidad, relaciones, secretos, habilidad, recursos, seguridad	quality, no se puede hacer commit si falla
reader_pull	Gancho de apertura, suspenso intermedio, deseo de continuar al final del capítulo, ciclo de adicción	quality, no se puede hacer commit si falla
title_hook	Poder de clic del título del capítulo, consistencia título/nombre de archivo, gancho al final del capítulo	quality, no se puede hacer commit si falla
character_voice	Diferencias de voz del personaje, tonos prohibidos, atribución de diálogo	quality, no se puede hacer commit si falla
domain_translation	Si la configuración profesional se traduce en ganancias/pérdidas visibles para el lector común	quality, no se puede hacer commit si falla
novelty	Repetición de estructura/método de capítulo/patrón final	market, el fallo también bloquea
continuity	Continuidad de ganchos, consecuencias, hilo del enemigo	market, el fallo también bloquea

Regla simple: solo mira gate.passed. passed=true para hacer commit; passed=false para corregir.

8. Mantenimiento a Largo Plazo

• Cada capítulo: ejecuta completamente prepare → beat → write → review → model signals → review → repair → commit.
• Cada 3 capítulos: ejecuta status, verifica promesas al lector activas/vencidas, cambios en la compuerta, salud del índice.
• Cada 5 capítulos: ejecuta batch-review --start <a> --end <b>, verifica debilidades continuas y patrones repetitivos.
• Cada 10 capítulos o en hitos clave: ejecuta volume-review, benchmark, actualiza volumes.json y la planificación de los próximos 5-10 capítulos de forma dinámica.
• Al final de cada volumen: verifica los objetivos del volumen, las pérdidas del enemigo, el cumplimiento de promesas al lector, el gancho para el siguiente volumen.
• Después de la publicación: usa save-feedback para registrar datos y comentarios, usa feedback-diagnose para convertirlos en sugerencias experimentales para la siguiente ronda. Cuando la muestra sea muy pequeña, no sobreajustes basándote en un solo comentario.

9. Fuentes de Verdad y Reglas de Directorio

Estructura del proyecto:

projects/<nombre_del_libro>/
├── project.json
├── src/                  # Fuentes de verdad, configuración y planificación confirmadas manualmente
├── manuscript/           # Capítulos de texto .md
├── data/                 # Estado derivado, se puede reconstruir, no modificar manualmente
├── editorial/            # Brief / writing_task / signals / gate / repair por capítulo
└── exports/

Reglas importantes:

• src/ y manuscript/ son las entradas de verdad (truth input).
• data/, editorial/ son productos de tiempo de ejecución/derivados; no los modifiques manualmente para eludir las compuertas.
• Para cambiar la configuración, el esquema del volumen o los personajes, modifica src/*.json y luego ejecuta rebuild.
• Para cambiar el texto, modifica manuscript/CapítuloXXX-Título.md y luego ejecuta review.
• Las correcciones manuales a largo plazo del libro de contabilidad se escriben en src/ledger_overrides.json y luego se ejecuta rebuild.

10. Prohibiciones

No hagas lo siguiente:

• No transfieras el trabajo CLI al usuario para que lo ejecute manualmente.
• No escribas capítulos formales directamente sin prepare.
• No omitas la competencia de beats para escribir los primeros 10 capítulos.
• No hagas commit o continúes con el siguiente capítulo si gate.passed=false.
• No uses --force-after-first3-fail para libros nuevos normales.
• No consideres que la calidad comercial es suficiente solo con guardar la revisión heurística; los capítulos clave deben tener señales del modelo.
• No modifiques manualmente gate.json, las señales o data/ledgers para simular un pase.
• No permitas que los capítulos no tengan título o se llamen solo CapítuloXXX.md.
• No permitas que la escritura de retroalimentación de memoria esté siempre en "ninguno", especialmente en lo que respecta a las promesas al lector.
• No escribas procesos profesionales como actas de reuniones, registros de autorización o listas de verificación, sin traducirlos a ganancias/pérdidas visibles para el lector.
• No prometas imitar palabra por palabra el estilo lingüístico de un autor específico o de una obra existente.

11. Archivos de Referencia para Leer

Lee según sea necesario, evita saturar el contexto con toda la información de una sola vez.

Archivo	Cuándo leerlo
references/pipeline-spec.md	Cuando tengas dudas sobre PREPARE/WRITE/REVIEW/COMMIT, recuperación, hash, frescura
references/review-spec.md	Cuando manejes las 12 señales, señales del modelo, veredicto, compuerta, reparación
references/story-spec.md	Cuando no estés seguro del formato del capítulo, modos de capítulo, variantes de ritmo, campos de escritura de retroalimentación de memoria
references/state-spec.md	Cuando modifiques el estado, el libro de contabilidad, las promesas al lector, las anulaciones del libro de contabilidad (ledger overrides), rebuild
references/genre-spec.md	Cuando trabajes con estrategias de género, genre_config, marcadores de género, playbook incorporado
references/learning-spec.md	Cuando realices aprendizaje de libros deconstruidos y aprendizaje de estructura de muestras
references/longrun-spec.md	Cuando realices comprobaciones de estabilidad de lotes/volúmenes/benchmark y de novelas largas

Si hay conflicto entre el comportamiento de implementación, el README y las referencias, prevalece el comportamiento actual del Python CLI, y se debe sincronizar la documentación durante las tareas de mantenimiento.

12. Lista de Comandos Comunes

python -m novel_architect --help
python -m novel_architect init --project <dir> --title <título> --genre <género> [--platform <plataforma>] [--premise <texto>] [--core-hook <texto>] [--protagonist <nombre>]
python -m novel_architect market-open --project <dir> [--platform <plataforma>] [--genre-hint <género>] [--seed-idea <idea>] [--author-intent <intención>] [--constraint <texto>] [--stdout]
python -m novel_architect market-save --project <dir> --file <market_pack.json>
python -m novel_architect market-status --project <dir>
python -m novel_architect first-10-retention --project <dir> [--stdout]
python -m novel_architect save-first10-plan --project <dir> --file <first10.json>
python -m novel_architect status --project <dir>
python -m novel_architect prepare --project <dir> [--query <texto>]
python -m novel_architect beat-candidates --project <dir> --chapter <n>
python -m novel_architect beat-select --project <dir> --chapter <n> --file <selection.json>
python -m novel_architect apply-beat-selection --project <dir> --chapter <n>
python -m novel_architect review --project <dir> --chapter <n>
python -m novel_architect export-signal-prompts --project <dir> --chapter <n>
python -m novel_architect save-model-signal --project <dir> --chapter <n> --signal <tipo> --file <senal.json>
python -m novel_architect commit --project <dir> --chapter <n>
python -m novel_architect resume --project <dir> --chapter <n> [--query <texto>]
python -m novel_architect first3-review --project <dir>
python -m novel_architect save-first3-review --project <dir> --file <first3_verdict.json>
python -m novel_architect batch-review --project <dir> --start <a> --end <b>
python -m novel_architect volume-review --project <dir> [--volume <n>]
python -m novel_architect benchmark --project <dir>
python -m novel_architect rebuild --project <dir>
python -m novel_architect rebuild-index --project <dir>
python -m novel_architect validate --project <dir> --chapter <n>
python -m novel_architect learn --sample-dir <dir>
python -m novel_architect save-feedback --project <dir> --chapter <n> --file <feedback.json>
python -m novel_architect feedback-diagnose --project <dir> --chapter <n>
python -m novel_architect feedback-summary --project <dir>
python -m novel_architect gen-prompt --project <dir> [--outline-file <ruta>] [--stdout]