@shiyuphan/follow-me 0.1.1 → 0.3.0

package/skills/follow-me/SKILL.md

@@ -1,65 +1,19 @@
 ---
 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 --detach`,
-   which prints the page URL and returns; 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, 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.
-
-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.
-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
-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.
+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 and keep running `follow-me`: each call listens up to 60 seconds and prints what the user flagged or asked, with comment ids.
+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 "..."`. Flags the user is still collecting stay hidden from you until they press Submit.
+5. 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.
+6. Never run `git rebase`, `reset` or `commit` for this. The draft is the only file you write.
+## 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,101 +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 narratedUnit = {
-    type: "object",
-    properties: { unit: { type: "string" }, narration: { type: "string" } },
-    required: ["unit", "narration"],
-    additionalProperties: false,
-};
-const unitList = { type: "array", items: { anyOf: [{ type: "string" }, narratedUnit] } };
-/**
- * Mirrors PlanFile on the wire. Structured outputs need every property required and closed
- * objects, so commit narration is 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: { anyOf: [{ type: "string" }, { type: "null" }] },
-                    units: unitList,
-                },
-                required: ["message", "narration", "units"],
-                additionalProperties: false,
-            },
-        },
-        responses: {
-            type: "array",
-            items: {
-                type: "object",
-                properties: {
-                    comment: { type: "string" },
-                    status: { type: "string", enum: ["addressed", "declined", "deferred"] },
-                    note: { type: "string" },
-                },
-                required: ["comment", "status", "note"],
-                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");
-    }
-}