Skip to content

jovesun-lab/whetstone / handoff-skill/throughline/skills/throughline

throughline

Verified

Throughline keeps the thread of work intact on work that's big enough to drift or that outlives one sitting. Two linked habits: (1) TASK TRACK — an emoji-tagged task list with exactly one ⭐️ MAIN goal anchor, so you can see at a glance whether you're still solving the main thing or have drifted; (2) HANDOFF — compact a session into a plain-markdown handoff doc the next agent (any agent) can pick up cleanly. Reach for it when: a long or many-step task is at real risk of losing the thread, you catch yourself drifting off the original goal, you're wrapping up or running low on context, you're switching agents or sessions, or you're explicitly asked to 'hand this off' / 'write a handoff' / 'summarize for the next session' / 'compact this' / 'pick up where we left off' / 'resume'. Do NOT reach for it on short, self-contained tasks that finish in one pass — the full protocol is overhead there. Capability-agnostic and cross-platform — works as a skill or a plain paste-in prompt.

Throughline

Keep the thread — Task Track within a session, Handoff across them.

For any AI agent reading this file. The frontmatter uses Claude's skill format; the body is plain markdown. It works the same for Claude, OpenAI, Gemini, Cursor, Cline, Aider, or a local model — paste the body in as a prompt if your platform has no skill system. Assume nothing about your host's capabilities; everything here degrades gracefully (see "Capability-agnostic by design" below).

What this is

Long or multi-agent work fails in two predictable ways, and this skill is two habits that each kill one of them:

  • Within a session, reasoning drifts off the goal. You solve a small problem, which surfaces another, which pulls you somewhere adjacent to what you started on. Every step is locally reasonable; together they bend the trajectory. Task Track makes that drift visible by keeping one ⭐️ MAIN goal anchor in front of you.
  • Across sessions, the thread is dropped. A fresh run (or a different agent) starts cold, re-derives what was already known, or trusts a stale summary. Handoff carries the thread forward as a plain-text artifact any agent can pick up.

The correlation — the load-bearing point. The ⭐️ MAIN tag is the shared goal anchor. Task Track holds it within a run; Handoff carries it (plus state) across runs. One sentence: don't lose the thread — within a session or between them. The same anti-drift purpose runs through both, which is why they ship together.

When to use

  • A long or many-step task at real risk of losing the thread → set up Task Track. (For a short, self-contained task that finishes in one pass, skip it — the overhead isn't worth it.)
  • You notice the work has wandered → re-read the ⭐️ MAIN and decide if you've drifted.
  • Wrapping up, running low on context, or switching agents → write a Handoff.
  • Beginning a session that has a prior handoff → run the Resume flow.

Part 1 — Task Track (the within-session half)

Keep a task list where exactly one task is the ⭐️ MAIN — the goal anchor — and every other task carries a leading emoji marking where it came from, so drift reads at a glance:

TagMeaning
⭐️ MAINThe session's primary task / goal anchor. Exactly one at a time. Re-read it before any load-bearing step: "am I still solving the MAIN, or something it slid into?"
🌶️ CriticalA critical bug or big-impact task — an origin by impact; whether it serves the MAIN is marked by 🔸.
🍏 Temp this sessionSurfaced mid-session, not in any plan. A transient. If it balloons past the MAIN's scope → stop and re-confirm with the human, don't let it silently become the main line.
🍋 Logged + recurred / pulled-inA previously-logged task that came back, OR a logged task not planned for this session but worth doing now.
🔸 SubtaskA part of the current MAIN, worked one by one; the MAIN is LANDED only when every 🔸 is done. Icons stack: membership, origin, then an optional kind icon (🔍 🐛 📋 🤝 🗂 ⏳ 📖) — 🔸🍋🐛.

Put the emoji in the task's title — and make sure the title is the channel your task UI actually renders. Some UIs carry a second display field that supersedes the title while a task is in progress (a "currently doing…" spinner text); a title-only marker goes invisible exactly during the phase where drift happens. When a UI offers such an extra display field, omit it rather than mirror the marker into it: an omitted field falls back to the title, which this rule already governs, while a mirrored field is a second copy you must keep in sync by hand. (Known instance, 2026-09: the optional activeForm field in Claude-family task tools — leave it empty.) Badges are fine as extras, but never only the badge.

The discipline, not the decoration: the value isn't the emoji, it's that the trajectory becomes legible. At any moment you can scan the list and see whether the work is still on the main line or chasing transients. When a 🍏 keeps growing, that's the signal to stop and check it against the ⭐️ MAIN. A 🍏 that proves valuable and gets logged is promoted to 🍋 — visible scope management instead of silent absorption.

Four rules keep the anchor honest over time:

  • The MAIN's title freezes when it's confirmed, and it closes under that same name. A goal renamed into whatever actually happened makes "done" unfalsifiable. A MAIN that became something else is a redirect, not a rename: the original takes an honest not-landed close, the new direction becomes its own new entry. Redirects append; they never rewrite.
  • One boot = one session. However many wrap-ups happen inside a conversation, it stays one session — a new task after a wrap is the same session's second MAIN, not a new session. Anything that counts sessions (trend tables, numbered handoffs) counts boots.
  • Name the session early. Give it a short stable name when the task crystallizes — alongside the ⭐️ MAIN, not at wrap time — and keep it visible; the handoff carries it.
  • Checklist rows get two boxes: built and verified. verified ticks only after the named check actually ran — "done" and "checked" are different claims and must not travel in one checkbox.

Full rationale, examples, and how it pairs with Handoff: references/task-track.md.


Part 2 — Handoff (the across-session half)

When wrapping up, write a plain-markdown handoff the next agent can pick up cold. The doc — not a file, not a tool, not your platform — is the universal interface: any agent and any human can read plain markdown.

Writing a handoff (the handoff operation — see commands/handoff.md):

  1. Fill the shared template templates/handoff.template.md (at the plugin root, beside skills/). It is the single source of truth for a handoff's structure, and the same sections as rules/task-rules.json; do not invent your own (a project with its own heading names adds · Throughline: <name> at the end instead). The sections:
    • Machine fields — session id and number, agent, model, host, times in UTC, a verdict line per MAIN (a copy of Done), a file-hash table.
    • ⭐️ Goal — the next session's MAIN, a proposal the human confirms at the next start; the same text as Next actions #1.
    • Where this session stopped — a short summary; mark anything unverified.
    • Done — each MAIN under its frozen title with an explicit verdict (LANDED with evidence / PARTIAL / NOT-LANDED) and its 🔸 subtasks — done, carried → a row, or dropped on the human's words. LANDED needs every subtask done. Silence is not a verdict.
    • Next actions — ranked, one line each, each pointing at its durable row.
    • Waiting on others — what the human and other agents owe.
    • Project state — the project's own facts (versions, hashes, last check); "none" allowed.
    • Rulings not yet home — this session's decisions in full until each reaches its home file, each with its row; "none" if none.
    • Re-derive on pickup — what the next agent must reconcile against ground truth before trusting this doc: each check named, with its expected result.
  2. Reference, don't duplicate. If a fact already lives in a plan, issue, commit, or diff, link it — don't copy it. Copies go stale; references stay single-source.
  3. Redact secrets. No API keys, tokens, passwords, or personal data. Sweep before saving.
  4. Keep it bounded. A handoff is the latest state plus pointers — not a running log of every session. If the project keeps a longer history, link to it; don't grow the handoff into a second log.
  5. Save it where the next agent will look — if you can write files, the OS temp dir or an agreed handoff path; if you can't, just emit the doc inline in your reply.
  6. The wrap is atomic with the end of the work. If more work lands after the handoff was written, the snapshot is stale — re-run the wrap. A stale handoff misleads the next session worse than none.

Resuming from a handoff (the resume operation — see commands/resume.md):

  1. Read the handoff and restate the ⭐️ Goal back, so the human sees you've oriented. A gap in the handoff is a finding — a missing doc, stale date, or absent verdict is evidence about how the last session ended; say it out loud, don't silently patch around it. That report is what makes a skipped wrap step get caught instead of compounding.
  2. Re-derive before trusting. Follow the doc's "Re-derive on pickup" section: re-read the named artifacts, re-run the named check, re-confirm cited facts are still current. A snapshot trusted blindly is exactly how stale state causes drift.
  3. Set up Task Track with the carried-forward ⭐️ MAIN (frozen title), then end your orientation by proposing the ⭐️ Goal (Next actions #1) as a concrete action for a one-word confirm — queue visible, no open-ended "what should we work on?". The proposal is a default, not a lock.

When several agents work the project in parallel (two substrates, a swarm, an auditor): every shared artifact gets exactly one writer; non-owners keep their own progress notes and the owner folds them in at its wrap; the workstream's owner writes its own work-package docs; and the docs — not anyone's chat history — are the coordination channel. Details: references/handoff.md.

Full protocol, the seven anti-drift mechanisms, and why each exists: references/handoff.md.


Companion: strain (when to wrap)

Throughline is how to keep and hand off the thread; its companion skill strain is when — a session-strain meter that reads how loaded the conversation has become and says when to wrap. The two meet in the middle: strain's cleanest behavioural counts come from the task track this skill maintains (one anchored MAIN, origin-tagged side tasks), and the wrap strain calls for is the handoff this skill writes. Each stands alone; together the loop closes.

Capability-agnostic by design

The next agent may be on any platform, so assume no specific function exists. Each capability has a graceful fallback:

If you have…use it for…If you don't…
File-system writesaving the handoff to a known pathemit the handoff inline in your reply — the doc is the deliverable, not the file
Live access (web, repo, tools)re-deriving state against ground truthre-derive from the artifacts you were handed; flag what you couldn't verify
Code executionthe optional tools/handoff.py validatorskip it — the prompt does the whole job without it
A task-list toolthe ⭐️ MAIN and its 🔸 subtasks live where the human sees them (the host's task list and plan pane), from the confirm instantthe board or file the human watches, written at the confirm instant — not at the wrap
A skill / slash-command systeminvoking handoff / resume as commandspaste the relevant section in as a plain prompt

The two reasoning disciplines — the ⭐️ MAIN goal anchor and re-derive-don't-trust — have zero capability dependency, so they hold at the lowest common denominator.

Optional helper (code-capable environments only)

tools/handoff.py is a single-file, zero-dependency (Python stdlib) helper that does only the mechanizable half — it never summarizes:

python3 tools/handoff.py new                 # scaffold a blank handoff from the template
python3 tools/handoff.py check HANDOFF.md    # validate: sections present, one ⭐️ MAIN,
                                             # re-derive note present, secret-pattern sweep

It reads the required sections from the shared template at runtime, so the validator and the prompt can never drift on structure. It's optional — if you can't run code, the skill is complete without it.

Files in this skill

FilePurpose
SKILL.mdThis file — the two habits and how they connect.
commands/handoff.mdThe write operation (drop-in slash command + paste-in prompt).
commands/resume.mdThe read / pick-up operation.
templates/handoff.template.mdThe handoff's sections (plugin root); the same sections as rules/task-rules.json.
rules/task-rules.jsonThe rules as data — what tools/handoff.py checks and the prose explains.
references/task-track.mdThe within-session discipline, in depth.
references/handoff.mdThe across-session protocol (the seven anti-drift mechanisms + the multi-agent rules), in depth.
examples/example-handoff.mdA filled-in handoff to copy the shape from.
tools/handoff.pyOptional stdlib scaffold/validate helper.
assets/logic-flow.svgDiagram of how the two halves connect.

License

MIT. Free to use, modify, embed, redistribute. Attribution appreciated.

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: 469kUpdated 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