@shiyuphan/follow-me 0.2.0 → 0.4.0

package/skills/follow-me/SKILL.md

@@ -1,93 +1,23 @@
 ---
 name: follow-me
-description: Split the current branch's net change into fine, story-ordered commits that read like the author's thought process, then hand them to a human for hunk-by-hunk review. Also plans a narrated walk-through of someone else's branch for a reviewer. Use when the user asks to clean up, reorder, split or "tell the story" of a branch's commits, to walk through or review a branch, or to act on a follow-me review or code review.
+description: Review a branch with the user, hunk by hunk in a local page, and carry the review to the merge request. Use when the user asks to review, split, clean up or reorder a branch's commits, to read someone else's branch, or to post a follow-me review to GitLab or GitHub.
 ---
-
 # follow-me
-
-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 to run it.
-
-## First pass
-
-1. `follow-me extract [--base main]` snapshots the diff from the base branch to the tip.
-2. `follow-me prompt` prints your instructions and every unit (hunk, file or mode change) with an id.
-   Read all of it. It names the exact path to write, `.follow-me/<slug>/draft.json`.
-3. Write that draft. Order commits so scaffolding and types come before their uses, a failing test
-   comes before its fix, renames come before edits, and each commit carries one idea. Commits need
-   not compile. Every change line is used exactly once, and the last commit must cover every unit.
-4. `follow-me check` validates the draft and prints every issue at once. Fix the draft and re-run
-   until it is green. Do not edit around an issue by hand-waving it; unassigned and duplicate
-   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. 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
-
-When the user says they finished reviewing:
-
-1. `follow-me feedback` prints the review as markdown. Every comment has an id like `c_abc234`.
-2. `follow-me prompt` now includes the previous plan and the open comments. Write a new draft that
-   changes the plan where you agree and lists one entry per comment in `responses`:
-   `{ "comment": "c_abc234", "status": "addressed" | "declined" | "deferred", "note": "..." }`.
-   Say why when you decline. Do not leave a comment unanswered.
-3. `follow-me check`, repair until green, then `follow-me apply`, and ask the user to review again.
-
-## 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, 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. 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 --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
-plan reviews only.
-
-## Rules
-
-- The draft is the only file you write. Never run `git rebase`, `reset` or `commit` for this.
-- Use unit ids exactly as printed. `h_x:0-3,7` takes change lines 0 to 3 and 7 of that hunk.
-  A bare `h_x` takes whatever lines no other commit claimed.
-- `f_` and `m_` units are whole; they never take line lists.
-
-## 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.
+follow-me is interactive. After it launches the review page, keep running `follow-me` until it prints the report. Each run waits up to 90 seconds for the reviewer.
+Do not stop, do not summarise, and do not ask the user whether to continue. The user is on the page.
+
+The user never types a follow-me command. If `follow-me` is not on PATH, tell them to run `npm i -g @shiyuphan/follow-me`; otherwise you run everything. They use the page, press Submit, and ask you to post the review.
+1. From the repo root run `follow-me`. It does the next missing thing, prints what happened, and ends with a `next:` line. Do what it says, then run `follow-me` again.
+2. When it says to write `.follow-me/<slug>/draft.json` from `prompt.md`, read the prompt, write the draft, and run `follow-me` (it checks the draft, prints every issue, and applies when valid). Put the why in each commit body.
+3. When it prints the review page URL, tell the user once and keep running `follow-me`. Each call listens up to 90 seconds and prints what the user flagged or asked, with comment ids, the moment they post it.
+4. Answer a question in place with `follow-me reply <id> --body "<markdown>" [--diagram file]` (Mermaid source for a picture). Start a thread yourself with `follow-me explain [--commit n] [--unit id] [--lines a-b] --body "..."`.
+5. When the user asks for a code change, make it on the original branch and commit it there. Then run `follow-me`. It carries the plan over, asks you to place any new units in the draft, and swaps the open page to the new code with the thread kept. Then `follow-me reply <id>` on that comment saying what changed and where (file and line), and run `follow-me` again.
+6. Repeat until it prints the report and `next: done`. Fix each issue in the code, or say why you decline. On someone else's branch you only report.
+7. Never run `git rebase` or `reset` for this, and never touch the `-split` branch. The only commits you make are the requested fixes on the original branch.
+## Porting a review
+Only when the user asks to post it.
+1. `follow-me report --json` prints items with `path`, `oldPath`, `newLine`, `oldLine`, `startNewLine`, `startOldLine`, `severity`, `kind`, `body` (markdown, ready to post), `thread`, `resolved`, `excluded`. Skip `excluded: true`. Lines are the branch tip's, or the base's for a removed line. Tell the user the count and first lines, ask which merge request or pull request, and never post without a yes.
+2. Fetch the target with `glab mr view <iid> --output json` (`diff_refs`) or `gh pr view <n> --json headRefOid,baseRefName`. Its head must equal the tip on the first line of `follow-me status`; if not, say so and stop, because the line numbers would be wrong.
+3. GitHub: post one review with `gh api repos/{owner}/{repo}/pulls/<n>/reviews --input review.json`, `"event": "COMMENT"`, each item in `comments[]` as `path`, `body`, and `line`+`side` (`newLine` with `RIGHT`, or `oldLine` with `LEFT`), plus `start_line` and `start_side` for a range; items without `path` go in the review `body`. Never APPROVE or REQUEST_CHANGES unless asked.
+4. GitLab: one discussion per item with `glab api --method POST projects/:id/merge_requests/<iid>/discussions` and `position[position_type]=text`, `base_sha`, `start_sha`, `head_sha` from `diff_refs`, and `new_path`, `old_path`, `new_line` (added), `old_line` (removed) or both (context) from the item. Items without `path`: `glab mr note`.
+5. Report what was posted with links and what failed; do not retry blindly. follow-me never holds a token; `gh` and `glab` do, and you run them.

package/dist/src/anthropic.js

@@ -1,133 +0,0 @@
-import Anthropic from "@anthropic-ai/sdk";
-export const DEFAULT_MODEL = "claude-opus-5-5";
-const MAX_TOKENS = 64000;
-export class PlanRequestError extends Error {
-    failure;
-    constructor(failure, message) {
-        super(message);
-        this.name = "PlanRequestError";
-        this.failure = failure;
-    }
-}
-const optionalText = { anyOf: [{ type: "string" }, { type: "null" }] };
-const concern = {
-    type: "object",
-    properties: {
-        severity: { type: "string", enum: ["blocker", "major", "minor"] },
-        kind: { type: "string", enum: ["bug", "missing-test", "naming", "risk"] },
-        text: { type: "string" },
-        lines: { anyOf: [{ type: "array", items: { type: "integer" } }, { type: "null" }] },
-    },
-    required: ["severity", "kind", "text", "lines"],
-    additionalProperties: false,
-};
-const concerns = { anyOf: [{ type: "array", items: concern }, { type: "null" }] };
-const annotatedUnit = {
-    type: "object",
-    properties: {
-        unit: { type: "string" },
-        narration: optionalText,
-        diagram: optionalText,
-        concerns,
-    },
-    required: ["unit", "narration", "diagram", "concerns"],
-    additionalProperties: false,
-};
-const unitList = { type: "array", items: { anyOf: [{ type: "string" }, annotatedUnit] } };
-/**
- * Mirrors PlanFile on the wire. Structured outputs need every property required and closed
- * objects, so narration, diagram, concerns and a response's `at` are nullable instead of
- * optional; the plan parser reads null as none.
- */
-export const PLAN_SCHEMA = {
-    type: "object",
-    properties: {
-        schema: { type: "string", enum: ["follow-me/plan@1"] },
-        base: { type: "string" },
-        tip: { type: "string" },
-        commits: {
-            type: "array",
-            items: {
-                type: "object",
-                properties: {
-                    message: { type: "string" },
-                    narration: optionalText,
-                    diagram: optionalText,
-                    concerns,
-                    units: unitList,
-                },
-                required: ["message", "narration", "diagram", "concerns", "units"],
-                additionalProperties: false,
-            },
-        },
-        responses: {
-            type: "array",
-            items: {
-                type: "object",
-                properties: {
-                    comment: { type: "string" },
-                    status: { type: "string", enum: ["addressed", "declined", "deferred", "answered"] },
-                    note: { type: "string" },
-                    at: {
-                        anyOf: [
-                            {
-                                type: "object",
-                                properties: { commit: { type: "integer" }, unit: optionalText },
-                                required: ["commit", "unit"],
-                                additionalProperties: false,
-                            },
-                            { type: "null" },
-                        ],
-                    },
-                },
-                required: ["comment", "status", "note", "at"],
-                additionalProperties: false,
-            },
-        },
-    },
-    required: ["schema", "base", "tip", "commits", "responses"],
-    additionalProperties: false,
-};
-const sendWithAnthropic = async ({ model, prompt }) => {
-    const client = new Anthropic();
-    // Streaming because a 64k-token reply outlives the SDK's non-streaming timeout.
-    const stream = client.beta.messages.stream({
-        model,
-        max_tokens: MAX_TOKENS,
-        output_config: { effort: "high", format: { type: "json_schema", schema: PLAN_SCHEMA } },
-        betas: ["server-side-fallback-2026-07-01"],
-        fallbacks: "default",
-        messages: [{ role: "user", content: prompt }],
-    });
-    const message = await stream.finalMessage();
-    const text = message.content.flatMap((block) => (block.type === "text" ? [block.text] : []));
-    return {
-        stopReason: message.stop_reason,
-        text: text.join(""),
-        refusalExplanation: message.stop_details?.explanation ?? null,
-    };
-};
-/**
- * Asks the model for a plan and returns the parsed JSON. The caller validates it as a plan,
- * because a schema-conforming reply can still name units that do not exist.
- */
-export async function requestPlan(prompt, opts = {}) {
-    const send = opts.send ?? sendWithAnthropic;
-    const reply = await send({ model: opts.model ?? DEFAULT_MODEL, prompt });
-    if (reply.stopReason === "refusal") {
-        const why = reply.refusalExplanation ? `: ${reply.refusalExplanation}` : "";
-        throw new PlanRequestError("refusal", `the model declined to write a plan${why}`);
-    }
-    if (reply.stopReason === "max_tokens") {
-        throw new PlanRequestError("truncated", `the plan did not fit in ${MAX_TOKENS} tokens; try a smaller diff`);
-    }
-    if (reply.text.trim() === "") {
-        throw new PlanRequestError("empty", "the model returned no text");
-    }
-    try {
-        return JSON.parse(reply.text);
-    }
-    catch {
-        throw new PlanRequestError("not-json", "the model's reply was not valid JSON");
-    }
-}