Skip to content

michael-denyer/pstack-claude / plugins/pstack/skills/reflect

reflect

Verified

Mine the active transcript for durable learnings and route each to a concrete edit on an existing skill. Use when the user says reflect.

FileKindSize
SKILL.mdskill md3.0 KB
scripts/claude-project-dir.mjsscript4.8 KB
scripts/find-transcript.mjsexecutablescript7.8 KB

scripts/find-transcript.mjs

View on GitHub
#!/usr/bin/env node
// Locate the transcript whose opening user prompt carries a fragment.
//
//   node find-transcript.mjs <transcripts-dir> <opening-prompt-fragment> [workspace]
//
// Prints the newest matching path, or exits 1 with "no transcript". Covers
// Claude Code's three layouts under one per-project directory (flat
// <id>.jsonl, nested <id>/<id>.jsonl, subagent <id>/subagents/<child>.jsonl)
// Pi's <iso>_<id>.jsonl under its per-cwd sessions directory, and GitHub
// Copilot's <id>/events.jsonl under its session-state directory, told apart by
// Pi's session header line and Copilot's session.start event. Each candidate is
// streamed line by line; a Claude Code or Copilot transcript is abandoned at its
// first typed user record. Copilot searches compare the session header's cwd
// with the workspace (the current directory by default) before reading user
// messages. A Pi session is read to its last entry to find
// the active branch. A Codex rollout is refused by name rather than read as an
// empty Claude transcript.
import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
import { isAbsolute, join } from "node:path";
import process from "node:process";
import { fileURLToPath } from "node:url";

// readline also breaks on U+2028 and U+2029, which JSON leaves unescaped.
async function* jsonlLines(stream) {
  let rest = "";
  for await (const chunk of stream) {
    const parts = (rest + chunk).split("\n");
    rest = parts.pop();
    yield* parts;
  }
  if (rest) yield rest;
}

// Session cleanup can delete a transcript or its session directory while a
// search runs. Anything under the root that vanishes after it was listed is
// skipped; a missing root still throws.
export function rethrowUnlessRemoved(error) {
  if (error.code !== "ENOENT") throw error;
}

export function candidates(projectsDir, maxDepth = 2, { includeCompressed = false } = {}) {
  const files = [];
  const walk = (dir, depth) => {
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      const full = join(dir, entry.name);
      if (entry.isFile() && (entry.name.endsWith(".jsonl") || (includeCompressed && entry.name.endsWith(".jsonl.zst")))) files.push(full);
      else if (entry.isDirectory() && depth < maxDepth) {
        try {
          walk(full, depth + 1);
        } catch (error) {
          rethrowUnlessRemoved(error);
        }
      }
    }
  };
  walk(projectsDir, 0);
  return files
    .flatMap((path) => {
      const stat = statSync(path, { throwIfNoEntry: false });
      return stat ? [{ path, mtime: stat.mtimeMs }] : [];
    })
    .sort((a, b) => b.mtime - a.mtime);
}

function text(content) {
  if (typeof content === "string") return content;
  if (Array.isArray(content)) {
    return content
      .filter((block) => typeof block?.text === "string")
      .map((block) => block.text)
      .join("\n");
  }
  return null;
}

// `user` records Claude Code writes for a local command (/clear, !cmd) and its
// output, not a prompt the user typed. A skill invocation leads with
// <command-message> and is kept: its <command-args> carry what the user typed.
const LOCAL_COMMAND = /^\s*<(?:command-name|local-command-stdout|bash-input)>/u;

// A Pi session opens with this header line; Claude Code transcripts never do.
const isPiHeader = (record) =>
  record?.type === "session" && Number.isInteger(record.version) && typeof record.cwd === "string";
// A Codex rollout opens with its session metadata.
const isCodexHeader = (record) => record?.type === "session_meta";

// A Copilot events.jsonl opens with this event and records each prompt the
// user typed as a `user.message` event.
const isCopilotHeader = (record) => record?.type === "session.start" && typeof record.data === "object";

async function copilotOpening(head, records, workspace) {
  if (workspace !== undefined) {
    const cwd = head.data?.context?.cwd;
    if (typeof cwd !== "string" || !isAbsolute(cwd)) return null;
    try {
      if (realpathSync(cwd) !== realpathSync(workspace)) return null;
    } catch {
      // A removed or inaccessible workspace cannot identify this session.
      return null;
    }
  }
  for await (const record of records) {
    if (record?.type !== "user.message") continue;
    const prompt = text(record.data?.content);
    if (prompt) return prompt;
  }
  return null;
}

async function* parsed(lines) {
  for await (const line of lines) {
    try {
      yield JSON.parse(line);
    } catch {}
  }
}

async function* prepend(head, rest) {
  yield head;
  yield* rest;
}

// A Claude Code transcript opens with the first prompt the user typed.
async function claudeOpening(records) {
  for await (const record of records) {
    if (record?.type !== "user" || record.isMeta) continue;
    const prompt = text(record.message?.content);
    if (prompt && !LOCAL_COMMAND.test(prompt)) return prompt;
  }
  return null;
}

// Pi branches in place: every entry is appended to one file and linked to its
// parent by id, and the last entry is the current leaf. The opening prompt is
// the first user message on the path from that leaf to its root, which may not
// be the first one in file order.
async function piOpening(records) {
  const entries = new Map();
  let leaf = null;
  for await (const record of records) {
    if (typeof record?.id !== "string") continue;
    const isUser = record.type === "message" && record.message?.role === "user";
    entries.set(record.id, { parentId: record.parentId ?? null, prompt: isUser ? text(record.message.content) || null : null });
    leaf = record.id;
  }
  let prompt = null;
  const seen = new Set();
  for (let id = leaf; entries.has(id) && !seen.has(id); id = entries.get(id).parentId) {
    seen.add(id);
    prompt = entries.get(id).prompt ?? prompt;
  }
  return prompt;
}

// Readers by opening record. Claude Code writes no header, so its row is last
// and takes every file the others do not claim.
const READERS = [
  [isPiHeader, (head, rest) => piOpening(rest)],
  [isCopilotHeader, (head, rest, path, workspace) => copilotOpening(head, rest, workspace)],
  [isCodexHeader, (head, rest, path) => {
    throw new Error(`${path} is a Codex rollout, which find-transcript does not read; pass the session digest instead`);
  }],
  [() => true, (head, rest) => claudeOpening(prepend(head, rest))],
];

export async function openingPrompt(path, workspace) {
  const stream = createReadStream(path, { encoding: "utf8" });
  try {
    const records = parsed(jsonlLines(stream));
    const { value: head, done } = await records.next();
    if (done) return null;
    const [, read] = READERS.find(([matches]) => matches(head));
    return await read(head, records, path, workspace);
  } finally {
    stream.destroy();
  }
}

export async function findTranscript(projectsDir, fragment, workspace = process.cwd()) {
  for (const { path } of candidates(projectsDir)) {
    try {
      const prompt = await openingPrompt(path, workspace);
      if (prompt?.includes(fragment)) return path;
    } catch (error) {
      rethrowUnlessRemoved(error);
    }
  }
  return null;
}

async function main(argv) {
  const [projectsDir, fragment, workspace] = argv;
  if (!projectsDir || !fragment || argv.length > 3) {
    console.error("usage: find-transcript.mjs <transcripts-dir> <opening-prompt-fragment> [workspace]");
    return 2;
  }
  const path = await findTranscript(projectsDir, fragment, workspace);
  if (!path) {
    console.error(`no transcript under ${projectsDir} opens with ${JSON.stringify(fragment)}`);
    return 1;
  }
  console.log(path);
  return 0;
}

// node leaves argv[1] unresolved and may set it to a non-file (`node -e ... arg`).
function invokedDirectly() {
  if (!process.argv[1]) return false;
  try {
    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
  } catch {
    return false;
  }
}

if (invokedDirectly()) {
  process.exitCode = await main(process.argv.slice(2));
}
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall