document the writing pipeline and record Phase 2
CLAUDE.md gains the writing/ layout, the voice-sheet pipeline and its direction of truth, the sync commands, and a pointer that Ground Truth must never be copied into this repo. The writer-owned/code-owned table now covers writing/. The restructure plan records Phase 2 as executed, and closes its first open question: the writing handbook does exist, in the Obsidian vault, so STYLE.md became a digest with pointers rather than the reconstruction the plan assumed. Also noted there: the vault's opening-scene spec records SC-101's tone check as BLOCKED on a one-page Voice Sheet that was never written. STYLE.md now holds that sheet with four fields explicitly unset. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
Claude Opus 5
@@ -17,7 +17,9 @@ to fix — it is the checkout path). The Unity project is a **subdirectory**:
|
||||
/Users/lennart/Dev/nightlcub-arcadia/ # git root
|
||||
├── CLAUDE.md, AGENTS.md # this reference
|
||||
├── docs/ # design + plan docs (markdown)
|
||||
├── writing/ # writer-facing context — see §4
|
||||
├── tools/YarnCheck/ # .NET 9 Yarn compiler/player, no Unity needed
|
||||
├── tools/writing/ # voice-sheet sync (md <-> skill_bible.json)
|
||||
├── .gitignore # macOS / IDE / toolchain rules
|
||||
└── NightclubArcadia/ # ← the Unity project (-projectPath)
|
||||
├── .gitignore # Unity rules (anchored, must stay here)
|
||||
@@ -49,7 +51,7 @@ AI Navigation 2.0.14, ProBuilder 6.1.2, Test Framework 1.7.0. Yarn Spinner is an
|
||||
mode while the Editor has it open — a single instance at a time. Always check before
|
||||
any `-batchmode` invocation (§3.1).
|
||||
4. **Prefer YarnCheck over Unity for dialogue validation.** It is seconds, not minutes,
|
||||
and needs no Editor lock (§5.3).
|
||||
and needs no Editor lock (§5.4).
|
||||
5. **Do not commit on the user's behalf** unless asked. Unity writes to tracked files
|
||||
(`ProjectSettings/*`, `.meta`, scenes) as a side effect of simply being open, so
|
||||
`git status` noise is expected and is not always yours.
|
||||
@@ -174,6 +176,25 @@ NightclubArcadia/Assets/Dialogue/
|
||||
└── Objects/ Chair
|
||||
```
|
||||
|
||||
The writer-facing context sits at the repo root, outside `Assets/` so it gets no `.meta` files:
|
||||
|
||||
```
|
||||
writing/
|
||||
├── README.md session entry point
|
||||
├── STYLE.md register, tone moves, ban list, branching rules ← read first
|
||||
├── YARN-PRIMER.md the one page of syntax a writer needs
|
||||
├── GLOSSARY.md in-world and project vocabulary
|
||||
├── voices/ the eleven skill voices, one sheet each (generated — see §4.7)
|
||||
├── characters/ named NPCs, dialogue-facing
|
||||
├── scenes/ per-scene briefs: intent, beats, checks, constraints
|
||||
└── lore/ candidates.md — the three identity readings and their hard rules
|
||||
```
|
||||
|
||||
Design material deeper than this lives in Obsidian, not the repo:
|
||||
`~/Obsidian-Vaults/obsidian-vault/Projects/Active/NightclubArcadia/`. **`Ground Truth.md` there
|
||||
is the solution document — never copy, quote, or summarise it into this repo**, including into
|
||||
commit messages. The game's premise is that the protagonist's identity never resolves.
|
||||
|
||||
**Dialogue is already plain text in the repo.** It is authored in `.yarn` files, not inside
|
||||
the Unity Editor, and any new `.yarn` file dropped anywhere under `Assets/Dialogue/` is picked
|
||||
up automatically by the `**/*.yarn` glob in the `.yarnproject`. Adding a scene or a character
|
||||
@@ -249,13 +270,41 @@ candidates.json → Tools ▸ Nightclub Arcadia ▸ (CandidateSystemSetup)
|
||||
Those setup scripts also register a `[DidReloadScripts]` callback, so in practice the assets
|
||||
regenerate on script reload too. The JSON is the source of truth either way.
|
||||
|
||||
### 4.6 Code-owned vs writer-owned
|
||||
### 4.6 The voice-sheet pipeline
|
||||
|
||||
The Skill Bible prose used to live as a `\n`-escaped string inside `skill_bible.json`, which no
|
||||
writer could comfortably read or revise. It now lives in `writing/voices/*.md`, and truth flows
|
||||
in opposite directions for the two halves of each sheet:
|
||||
|
||||
```
|
||||
PROSE writing/voices/<id>.md -> skill_bible.json -> Skills/Definitions/*.asset
|
||||
MACHINE skill_bible.json -> the "Machine fields" table in the .md
|
||||
```
|
||||
|
||||
```bash
|
||||
python3 tools/writing/sync_voices.py --check # verify; exit 1 on drift
|
||||
python3 tools/writing/sync_voices.py --to-json # fold edited prose into the bible
|
||||
python3 tools/writing/sync_voices.py --to-md # refresh the machine table from the bible
|
||||
```
|
||||
|
||||
`tools/writing/voicelib.py` does the parsing and guarantees `notes -> dict -> notes` is identity
|
||||
for all eleven skills. `--to-json` on unchanged sheets is byte-identical, so it is safe to run
|
||||
at any time.
|
||||
|
||||
`VoiceSheetSyncTests` (EditMode) enforces the same invariant, so drift fails the build instead
|
||||
of silently shipping a voice that no longer matches the sheet the next scene is written against.
|
||||
It deliberately does not reimplement the markdown parser in C# — it asserts the shipped prose
|
||||
appears verbatim in the sheet, which catches drift in either direction with no second parser to
|
||||
keep in step.
|
||||
|
||||
### 4.7 Code-owned vs writer-owned
|
||||
|
||||
| Writer-owned (edit freely, no Unity) | Code-owned (needs an engineer) |
|
||||
|---|---|
|
||||
| `Assets/Dialogue/**/*.yarn` | `Assets/Scripts/**/*.cs` |
|
||||
| `<<declare>>` lines in `Common.yarn` | `Assets/Editor/**/*.cs` |
|
||||
| `Assets/Skills/skill_bible.json` (prose fields) | Yarn command/function *implementations* |
|
||||
| `writing/**` | `Assets/Scripts/**/*.cs` |
|
||||
| `Assets/Dialogue/**/*.yarn` | `Assets/Editor/**/*.cs` |
|
||||
| `<<declare>>` lines in `Common.yarn` | Yarn command/function *implementations* |
|
||||
| `writing/voices/*.md` (prose → the bible, §4.6) | `Assets/Skills/skill_bible.json` (machine fields) |
|
||||
| `Assets/Candidates/candidates.json` (`status`, `sceneId`, `notes`, `unlockFlag`) | `.asset`, `.prefab`, `.unity`, `.meta` |
|
||||
| `docs/` writing docs | `ProjectSettings/**` |
|
||||
|
||||
@@ -278,11 +327,19 @@ or a branch.** If a writing task requires either, that is a pipeline bug — fil
|
||||
`$self_lean_*` / `$found_*` in any `.yarn` file resolves to a real id in `CandidateDatabase`.
|
||||
It is a tripwire, not a proof.
|
||||
|
||||
### 5.2 One-click in-Editor run
|
||||
### 5.2 Voice-sheet sync
|
||||
|
||||
```bash
|
||||
python3 tools/writing/sync_voices.py --check
|
||||
```
|
||||
|
||||
Seconds, no Unity. Run it after touching `writing/voices/*.md` or `skill_bible.json` (§4.6).
|
||||
|
||||
### 5.3 One-click in-Editor run
|
||||
|
||||
`Tools ▸ Nightclub Arcadia ▸ Run Skill EditMode Tests` (`Assets/Editor/SkillSystemTestRunner.cs`).
|
||||
|
||||
### 5.3 YarnCheck — validate dialogue without Unity ⭐
|
||||
### 5.4 YarnCheck — validate dialogue without Unity ⭐
|
||||
|
||||
`tools/YarnCheck` is a .NET 9 console app that compiles **and plays** the Yarn scripts using
|
||||
the exact Yarn Spinner DLLs shipped in `Packages/dev.yarnspinner.unity/Runtime/DLLs`, so it
|
||||
|
||||
Reference in New Issue
Block a user