@shiyuphan/follow-me 0.1.0 → 0.2.0

package/dist/ui/summary.js

@@ -0,0 +1,45 @@
+// @ts-check
+// Pure wording for the end of a review: what the reviewer is about to hand over.
+
+/**
+ * @typedef {{ anchor: { kind: string, commit?: number }, kind?: string }} SummaryComment
+ */
+
+/** @param {number} n @param {string} word */
+function count(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+/**
+ * "2 comments on 2 commits and 1 on the whole plan, 1 question for the agent, 2 kept concerns",
+ * or "No comments". Questions count apart from change requests, since the agent answers them
+ * instead of changing the plan.
+ * @param {{ comments: readonly SummaryComment[], kept: number, unresolved: number,
+ *   walk: boolean }} input
+ */
+export function endSummary({ comments, kept, unresolved, walk }) {
+  const questions = comments.filter((c) => c.kind === "question");
+  const changes = comments.filter((c) => c.kind !== "question");
+  const onCommits = changes.filter((c) => c.anchor.kind !== "plan");
+  const general = changes.length - onCommits.length;
+  const commits = new Set(onCommits.map((c) => c.anchor.commit)).size;
+  /** @type {string[]} */
+  const parts = [];
+  if (onCommits.length > 0) {
+    parts.push(`${count(onCommits.length, "comment")} on ${count(commits, "commit")}`);
+  }
+  if (general > 0) parts.push(`${general} on the whole ${walk ? "branch" : "plan"}`);
+  const sentence = [parts.join(" and ")].filter(Boolean);
+  if (questions.length > 0) sentence.push(`${count(questions.length, "question")} for the agent`);
+  if (kept > 0) sentence.push(`${count(kept, "kept concern")}`);
+  if (unresolved > 0) sentence.push(`${count(unresolved, "answer")} not marked resolved`);
+  return sentence.length === 0 ? "No comments" : sentence.join(", ");
+}
+
+/**
+ * Where the report is saved, beside the review file.
+ * @param {string} saved path of reviews/vN.json
+ */
+export function reportPath(saved) {
+  return saved.replace(/\.json$/, ".md");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiyuphan/follow-me",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Split a branch's final changes into fine, ordered commits that read like the author's thought process, review them hunk by hunk, and hand the review back to a coding agent.",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R ui dist/ui"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "0.135.0"
+    "@anthropic-ai/sdk": "0.135.0",
+    "mermaid": "12.2.0",
+    "prismjs": "1.30.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",

package/skills/follow-me/SKILL.md

@@ -8,7 +8,7 @@ description: Split the current branch's net change into fine, story-ordered comm
 follow-me rewrites a branch as small commits ordered so a reader follows your thinking. It never
 touches your working tree or index. It writes a new branch and keeps state in `.follow-me/<slug>/`.
 
-Run every command from the repo root. If `follow-me` is not on PATH, ask the user how it is installed.
+Run every command from the repo root. If `follow-me` is not on PATH, ask the user how to run it.
 
 ## First pass
 
@@ -23,7 +23,9 @@ Run every command from the repo root. If `follow-me` is not on PATH, ask the use
    lines are real mistakes.
 5. `follow-me apply` freezes the plan as the next version and writes the branch.
 6. Tell the user to run `follow-me review`. It opens a local page where they comment on messages,
-   positions, hunks and single lines.
+   positions, hunks and single lines. If you start it yourself, use `follow-me review --wait --no-open`,
+   which prints the page URL to give the user and returns once they end the review, so you can go
+   straight on to `follow-me feedback`; one server hosts every session the user has open.
 
 ## After a review
 
@@ -39,18 +41,24 @@ When the user says they finished reviewing:
 ## As a reviewer
 
 `follow-me walk` is for someone reading a branch they did not write. It plays the branch back
-commit by commit in the browser, typing each line out while it reads your narration aloud, and the
-reviewer comments on the code. Nothing is applied and no branch is written.
+commit by commit in the browser, one chunk of change at a time: it reads your narration aloud,
+then shows the lines it explains. The reviewer comments on the code. Nothing is applied and no branch is written.
 
 1. `follow-me walk [--branch <name>]` opens the session. If there is no plan yet and no API key, it
    prints two commands and stops. Run the first, `follow-me prompt --walk`, and read all of it.
 2. Write the draft it names. The order rules are the same, and every commit also gets a
    `narration`: what the author is thinking while writing it, first person, present tense, two or
    three sentences, no markdown. Give a unit narration as `{ "unit": "h_x:0-3", "narration": "..." }`
-   when the why of that hunk is not obvious from the commit's narration.
+   when the why of that hunk is not obvious from the commit's narration. Narration is spoken, so
+   it names no symbols the listener has to see spelled out and never describes a picture.
+   Optionally add a `diagram`, Mermaid source drawn beside the code, to a commit or a unit
+   (`{ "unit": "h_x", "diagram": "flowchart LR\n  a --> b" }`). Use one only for what prose
+   carries badly: data flow between modules, a state machine, a call graph, or the before and
+   after shape of a structure. Most commits need none. Its first line must name the diagram type,
+   such as `flowchart`, `sequenceDiagram` or `stateDiagram-v2`; `follow-me check` rejects others.
 3. `follow-me check` until green, then tell the user to run `follow-me walk` again. Do not apply.
 
-When you are the author's agent and `follow-me feedback` starts with `# Code review`, the review
+When you are the author's agent and `follow-me feedback --walk` prints a `# Code review`, the review
 came from a walk. It quotes each commented line as a diff excerpt with its line number on the
 branch. Address every item in the code on the branch itself, then tell the user what you changed
 and what you declined and why. Do not write a follow-me draft or `responses` for it; those answer
@@ -63,13 +71,23 @@ plan reviews only.
   A bare `h_x` takes whatever lines no other commit claimed.
 - `f_` and `m_` units are whole; they never take line lists.
 
-## Install
-
-Copy or symlink this folder into the repo you want to use it in:
-
-```sh
-mkdir -p .claude/skills
-ln -s /path/to/follow-me/skills/follow-me .claude/skills/follow-me
-```
-
-For every repo at once, link it into `~/.claude/skills/follow-me` instead.
+## Interactive loop
+
+While the review page is open the reviewer comments and asks questions live, and you answer without
+closing the page. Everything goes through the review server.
+
+1. `follow-me watch [--since <seq>] [--timeout <seconds>]` blocks until the reviewer does something and
+   prints it (`--json` for one JSON object per line, `--follow` to stream until the review ends). It
+   exits 0 with news, 2 when nothing happened, and prints the `--since` to use next. Run it again in a
+   loop; stop when it reports that the review ended.
+2. Answer a question or comment in place with `follow-me reply <commentId> --body "..."`, adding
+   `--diagram <file>` with Mermaid source when a picture explains it. This needs no new plan.
+3. When the plan itself should change, write a new draft whose `responses` answer the comments
+   (`"status": "answered"` with `"at"` for questions), `follow-me check`, then `follow-me apply`. While the
+   page is open, apply swaps it to the new version at the same URL and keeps the old comments.
+4. At the end, `follow-me report` prints one consolidated report of the issues you and the reviewer
+   raised, by file and line, with questions and answers last. It is also saved as
+   `.follow-me/<slug>/reviews/vN.md`. Give it to the author.
+
+In a walk you may also raise `concerns` (see `follow-me prompt --walk`); the reviewer keeps or dismisses
+each, and only kept ones reach the report.