Walkthrough 2 (#52)

Author: orta

README.md

@@ -151,20 +151,25 @@ CODIFF_CLAUDE_PATH=/absolute/path/to/claude codiff --agent claude -w
 Claude Code rides your existing `claude` login (subscription or `ANTHROPIC_API_KEY`); run `claude`
 once and complete `/login` if you have not already.
 
-To seed a walkthrough with the agent conversation that produced the change, install its skill from
-the application menu (`Install Codex Skill` or `Install Claude Code Skill`), then invoke it from the
-agent:
+To drive Codiff from your agent, install its skills from the application menu (`Install Codex Skill`
+or `Install Claude Code Skill`). Each action installs both bundled skills for that agent — `codiff`
+and `walkthrough` — so you only install once, and Codiff updates keep them current. Invoke them from
+the agent:
 
 ```text
-$codiff   # Codex
-/codiff   # Claude Code
+$codiff       /codiff        # open Codiff seeded with the current session
+$walkthrough  /walkthrough   # author a narrative walkthrough of the change
 ```
 
-The skill opens Codiff with `codiff -w --codex-session <id>` (or `--agent claude --claude-session
+`codiff` opens Codiff with `codiff -w --codex-session <id>` (or `--agent claude --claude-session
 <id>`). Codiff then generates its normal diff digest and runs the walkthrough prompt seeded with
 that session's conversation, so the walkthrough sees the original context without a lossy summary
 handoff.
 
+`walkthrough` asks Codiff for the current authoring guide (`codiff --walkthrough-guide`), writes a
+narrative walkthrough JSON to a temporary file, and opens Codiff on it with `--walkthrough-file`.
+Because the guidance lives in Codiff, the installed skill stays a thin shim.
+
 ## Development
 
 ```bash

bin/arguments.js

@@ -43,6 +43,17 @@ export const flagDefinitions = [
     name: 'walkthrough-context',
     type: 'string',
   },
+  {
+    argument: '<file>',
+    description: 'Open a pre-authored narrative walkthrough JSON file.',
+    name: 'walkthrough-file',
+    type: 'string',
+  },
+  {
+    description: 'Print the narrative walkthrough authoring guide and schema, then exit.',
+    name: 'walkthrough-guide',
+    type: 'boolean',
+  },
 ];
 
 export const usageExamples = [
@@ -267,6 +278,8 @@ export const parseArguments = (args) => {
   let sourceCandidate = null;
   const walkthroughContextPath =
     typeof values['walkthrough-context'] === 'string' ? values['walkthrough-context'] : null;
+  const walkthroughFilePath =
+    typeof values['walkthrough-file'] === 'string' ? values['walkthrough-file'] : null;
 
   for (let index = 0; index < positionals.length; index += 1) {
     const arg = positionals[index];
@@ -323,6 +336,8 @@ export const parseArguments = (args) => {
     requestedPath: resolve(requestedPath ?? process.cwd()),
     version: values.version === true,
     walkthrough: values.walkthrough === true,
+    ...(values['walkthrough-guide'] === true ? { walkthroughGuide: true } : {}),
     ...(walkthroughContextPath ? { walkthroughContextPath: resolve(walkthroughContextPath) } : {}),
+    ...(walkthroughFilePath ? { walkthroughFilePath: resolve(walkthroughFilePath) } : {}),
   };
 };

bin/codiff-app

@@ -40,6 +40,7 @@ show_help() {
   printf '  %-22s%s%s%s\n' "--version, -v" "$gray" "Show version number and exit." "$reset"
   printf '  %-22s%s%s%s\n' "--walkthrough, -w" "$gray" "Start with an LLM-generated review walkthrough." "$reset"
   printf '  %-22s%s%s%s\n' "--walkthrough-context <file>" "$gray" "Seed a walkthrough with Codex conversation context JSON." "$reset"
+  printf '  %-22s%s%s%s\n' "--walkthrough-guide" "$gray" "Print the narrative walkthrough authoring guide and schema, then exit." "$reset"
   printf '\n'
   printf '%s\n' "${blue_bold}Examples:${reset}"
   printf '  %-22s%s%s%s\n' "codiff" "$gray" "Review staged and unstaged changes." "$reset"
@@ -164,6 +165,18 @@ for arg in "$@"; do
       printf 'codiff v%s\n' "$(codiff_version)"
       exit 0
       ;;
+    --walkthrough-guide)
+      # The guide is pure text assembled by the Node entry; run it with the
+      # bundled Electron as Node so no separate node install is required.
+      electron_exec="$(ls "$app_path/Contents/MacOS/" 2>/dev/null | head -n 1)"
+      if [ -n "$electron_exec" ] && [ -f "$script_dir/codiff.js" ]; then
+        ELECTRON_RUN_AS_NODE=1 "$app_path/Contents/MacOS/$electron_exec" \
+          "$script_dir/codiff.js" --walkthrough-guide
+      else
+        cat "$script_dir/walkthrough-guide.md"
+      fi
+      exit 0
+      ;;
     --walkthrough|-w)
       walkthrough=1
       ;;

bin/codiff.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import electron from 'electron';
@@ -10,6 +11,17 @@ import { formatHelpText, parseArguments, resolvePullRequestUrl } from './argumen
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
+// Assemble the narrative walkthrough authoring guide: the prose, then the live
+// schema object serialized inline (single-sourced from the validator — no copy).
+const buildWalkthroughGuide = () => {
+  const require = createRequire(import.meta.url);
+  const { narrativeWalkthroughSchema } = require(
+    resolve(root, 'electron/narrative-walkthrough.cjs'),
+  );
+  const guide = readFileSync(resolve(root, 'bin/walkthrough-guide.md'), 'utf8').trimEnd();
+  return `${guide}\n\n\`\`\`json\n${JSON.stringify(narrativeWalkthroughSchema, null, 2)}\n\`\`\`\n`;
+};
+
 const run = () => {
   const parsedArguments = parseArguments(process.argv.slice(2));
 
@@ -23,6 +35,11 @@ const run = () => {
     return;
   }
 
+  if (parsedArguments.walkthroughGuide) {
+    process.stdout.write(buildWalkthroughGuide());
+    return;
+  }
+
   const {
     agentBackend,
     branchRef,
@@ -33,6 +50,7 @@ const run = () => {
     requestedPath,
     walkthrough,
     walkthroughContextPath,
+    walkthroughFilePath,
   } = parsedArguments;
   let { pullRequestUrl } = parsedArguments;
 
@@ -63,6 +81,7 @@ const run = () => {
       CODIFF_REPOSITORY_PATH: requestedPath,
       CODIFF_WALKTHROUGH: walkthrough ? '1' : '',
       CODIFF_WALKTHROUGH_CONTEXT: walkthroughContextPath ?? '',
+      CODIFF_WALKTHROUGH_FILE: walkthroughFilePath ?? '',
     },
     stdio: 'ignore',
   });

bin/walkthrough-guide.md

@@ -0,0 +1,78 @@
+# Narrative walkthrough — authoring guide
+
+This is Codiff's guidance for authoring a **narrative walkthrough**: a story-shaped
+review of a change. Unlike Codiff's built-in walkthrough (which only orders files), a
+narrative walkthrough tells the _story_ of the change — ordered stops grouped into
+chapters, each pinned to a specific slice of the diff, with your narration and the prior
+conversation attached so Codiff can answer follow-up questions.
+
+You — the agent — author a JSON document conforming to the schema printed at the end of
+this guide. Write it to a **temporary file outside the repository** (e.g. a unique path in
+the system temp directory) so it never clutters the working tree; pass that path to Codiff
+with `--walkthrough-file`. Set the document's `"$schema"` to
+`https://raw.githubusercontent.com/nkzw-tech/codiff/main/src/walkthrough/narrative-walkthrough.schema.json`
+for editor validation.
+
+Default to the **staged** diff (`git diff --staged`). If the user named a target (a commit,
+`HEAD`, a PR, a path), use that. If nothing is staged, fall back to the working tree
+(`git diff`) and say so.
+
+## The shape, and why it's shaped this way
+
+The document separates **segments** (order-independent slices of the diff) from **orders**
+(reading views over them). The same segment can lead one order and sit in another order's
+"rest". This is what lets one changeset present as both _key-changes-first_ and
+_results-first_ without duplicating data.
+
+- **`segments[]`** — the order-independent atoms. Each is one addressable slice of the diff:
+  - `id` — stable within the document, e.g. `"s1"`.
+  - `path`, `oldPath?`, `status` (`added` | `deleted` | `modified` | `renamed` | `untracked`).
+  - `granularity` — `line` | `hunk` | `file`. Choose per stop: pull out a single `line` for a
+    one-line bug, a `hunk` for a focused change, a whole `file` for a new test that reads as a
+    spec.
+  - `added`, `deleted` — line counts for the slice.
+  - `anchor` — where it points into the live diff: `display` (e.g. `"src/App.tsx:311"`),
+    optional `sectionId` (`<path>:staged` for staged diffs, `<path>:unstaged` for working-tree
+    edits), `sectionKind`, `side` (`additions` | `deletions` | `both`), and `startLine`/`endLine`
+    for `line`/`hunk` granularity (omit for `file`). Codiff repairs anchors against the live diff,
+    so a missing or slightly-off `sectionId` is fine — it's pinned to a real section on load.
+  - `title?`, `summary?` — default framing; an order's stop may override the title.
+  - `comments?` — review comments to seed, anchored by `side` + `lineNumber` (+ optional range).
+
+- **`orders[]`** — one or more reading views over the segments. Each has:
+  - `id` (e.g. `"keys"`, `"results"`), `label`, `tagline`.
+  - `phases[]` — named chapters, each with an `icon` (`bug` | `wrench` | `path` | `flask` |
+    `beaker` | `doc` | `gear`) and a `blurb`.
+  - `sequence[]` — the ordered stops. Each is `{ segmentId, phaseId, importance, prose, title? }`.
+  - `rest[]` — files changed alongside the work but kept off the narrative path, each
+    `{ segmentId, reason, note? }`. Group by `reason` (e.g. `Generated`, `Lockfile`, `Snapshot`,
+    `Mechanical`).
+  - `restLabel`, `restBlurb` — how "the rest" is presented.
+
+- **`defaultOrder`** — the order id Codiff opens first. Choose `results` when the change has a
+  strong test/snapshot/contract that previews it well; otherwise `keys`.
+
+- **`context`** — a compact summary of the originating conversation (objective, decisions,
+  risks, validation, a few key messages), so Codiff can answer questions without you. Use the
+  `WalkthroughContext` shape (`version: 1`, `source: { type: "claude-session" | "codex-session", generatedAt }`).
+
+## How to think about it
+
+- Order stops by **review leverage and story**, not by file path. It is good for the arc to
+  cross files and return to an earlier one (the bug, the fix, the refactor, the proof).
+- Write `prose` as the agent's voice explaining _why this matters now_. It may use inline
+  markdown / code. Keep review comments separate (`comments[]`), not baked into prose.
+- Use `importance: "critical"` sparingly — only the genuine root cause or the defining test.
+- Push generated files, lockfiles, and snapshots into each order's `rest[]` with a `reason`. In
+  a results-first order you may instead promote a signal-bearing one (a snapshot, a widened
+  contract) to a lead stop.
+
+- Provide **two orders** when both make sense (`keys` and `results`); one is fine for small
+  changes. Do not invent bugs or produce review findings — describe what changed and why.
+- Every `segmentId` referenced by a `sequence` or `rest` entry must exist in `segments[]`, and
+  every segment `path` should be a file in the diff. Codiff drops dangling references on load,
+  but a clean document renders best.
+
+## The schema
+
+The document must conform to the following JSON schema:

claude/skills/walkthrough/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: walkthrough
+description: Author a narrative Codiff walkthrough JSON from the current change and open it in Codiff. Use when the user writes "/walkthrough", "make a walkthrough", "walk me through this change", or asks to review the staged work as a guided narrative in Codiff.
+metadata:
+  short-description: Generate a narrative walkthrough and open Codiff
+---
+
+# Walkthrough
+
+Author a **narrative walkthrough** of the current change as a JSON document, then open
+Codiff pointed at it. You — the agent running this skill — write the JSON yourself, because
+you already hold the conversation that produced the change.
+
+Codiff owns the format and the authoring guidance, so it stays current as Codiff updates.
+This skill is just the handoff: fetch the guide, author the document, open Codiff.
+
+## Workflow
+
+1. **Get the current guidance from Codiff.** It explains the data model, how to think about
+   the document, and prints the JSON schema:
+
+   ```bash
+   node scripts/open-codiff.mjs --guide
+   ```
+
+   Follow what it says. (Everything below is just the handoff around it.)
+
+2. **Pick the change.** Default to the **staged** diff (`git diff --staged`). If the user named
+   a target (a commit, `HEAD`, a PR, a path), use that. If nothing is staged, fall back to the
+   working tree (`git diff`) and say so.
+
+3. **Author the JSON** per the guide and write it to a **temporary file outside the
+   repository** (so it never clutters the working tree). Pick a unique absolute path in the
+   system temp directory — e.g. `/tmp/codiff-walkthrough-<id>.json` (use `$TMPDIR` on macOS).
+   Remember that path for the next step.
+
+4. **Open Codiff** with that file:
+
+   ```bash
+   node scripts/open-codiff.mjs --file /tmp/codiff-walkthrough-<id>.json
+   ```
+
+   Forward an explicit target after the flag if the user gave one:
+
+   ```bash
+   node scripts/open-codiff.mjs --file /tmp/codiff-walkthrough-<id>.json HEAD
+   node scripts/open-codiff.mjs --file /tmp/codiff-walkthrough-<id>.json /path/to/repository
+   ```
+
+   The launcher passes `CLAUDE_SESSION_ID` to Codiff with `--agent claude` so follow-up
+   questions reuse this conversation. Codiff validates and repairs the document against the
+   live diff, so anchors that drift are pinned to a real section rather than dropped.
+
+Emit JSON only into the file. Do not summarize the conversation back to the user; the skill
+is a handoff into Codiff.