Throughline

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:

Put the emoji in the task's title (the always-visible spot), not just in a description field — if your task UI renders badges, use those too, but the title is the reliable channel.

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. It is the single source of truth for a handoff's structure; do not invent your own sections. The core sections:
   • Header — which session wrote this (session name + id): every claim traces back.
   • ⭐️ Goal — the one thing the next session is for (carry the MAIN forward, frozen title).
   • State — where things stand now; mark anything unverified.
   • Done — what got completed (briefly), each goal closed with an explicit verdict — LANDED (with evidence) / PARTIAL / NOT-LANDED (with where it's carried). Silence is not a verdict.
   • Decisions — what the human confirmed, numbered, append-only ("none" if none).
   • Open / Next — open threads + recommended next move, in priority order.
   • Re-derive on pickup — what the next agent must reconcile against ground truth before trusting this doc: each check named, with its expected result.
   • Suggested next steps / tools / skills — concrete next actions and capabilities to reach for.
   • References — point to plans, specs, issues, commits, diffs, docs by path/URL.
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 top Open / Next item 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:

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

License

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