Trail

Session continuity through structured handoffs and freeform logs.

<when_to_use>

• End of session — create handoff for continuity

• During research — capture findings in logs

• Subagent work — preserve context with parent session linking

• Any time you need to leave a trail for future sessions

</when_to_use>

Commands

Command Purpose

/trail:handoff

Create structured handoff note for session continuity

/trail:log <slug>

Create freeform timestamped log note

/trail:read [options]

Read recent trail notes

Handoff Format

Handoffs are the atomic unit of session continuity. Create one at the end of each session.

Handoff

YYYY-MM-DD HH:MM · Session <short-id>

Done

• Completed item 1
• Completed item 2

State

Current state of work:

• What's in progress
• What's blocked
• Key decisions made

Next

• First priority task
• Second priority task
• Lower priority item

Handoff Principles

• Done: Past tense, concrete accomplishments

• State: Present tense, current situation

• Next: Checkboxes for actionable items

• Scannable: Someone should grasp the session in 30 seconds

• Honest: Note blockers, uncertainties, and open questions

Log Format

Logs are freeform notes for capturing anything worth preserving.

Title Derived From Slug

YYYY-MM-DD HH:MM · Session <short-id>

[Freeform content - research findings, technical discoveries, meeting notes, ideas, observations, etc.]

Log Use Cases

• Research findings and documentation

• Technical discoveries and gotchas

• Meeting notes and decisions

• Ideas and observations

• Debugging sessions and root causes

Log Principles

• Descriptive slug: Will become the title if none provided

• Tag liberally: Use frontmatter tags for discoverability

• Link context: Reference issues, PRs, or other notes

• Future-proof: Write for someone (including future you) with no context

Subagent Context

When working as a subagent, pass the parent session ID to group related notes:

Handoff with parent context

bun ${CLAUDE_PLUGIN_ROOT}/skills/trails/scripts/handoff.ts
--session "$CHILD_SESSION"
--parent "$PARENT_SESSION"

Log with parent context

bun ${CLAUDE_PLUGIN_ROOT}/skills/trails/scripts/log.ts
--slug "api-findings"
--session "$CHILD_SESSION"
--parent "$PARENT_SESSION"

This creates notes in a subdirectory: .trail/notes/YYYY-MM-DD/<parent-session>/

Reading Notes

Today's notes (all types)

/trail:read

Just handoffs

/trail:read --type handoff

Just logs

/trail:read --type log

Last 3 days

/trail:read --days 3

Limit output

/trail:read --lines 100

Directory Structure

.trail/ ├── notes/ │ └── YYYY-MM-DD/ │ ├── handoff-YYYYMMDDhhmm-<session>.md │ ├── YYYYMMDDhhmm-<slug>.md │ └── <parent-session>/ # Subagent notes │ ├── handoff-YYYYMMDDhhmm-<child>.md │ └── YYYYMMDDhhmm-<slug>.md ├── plans/ # Implementation plans └── artifacts/ # Research, ADRs, etc.

Filename Convention

Pattern: [prefix-]YYYYMMDDhhmm[-suffix].md

Type Prefix Suffix Example

Handoff handoff

session ID handoff-202601221430-f4b8aa3a.md

Log none slug 202601221430-api-research.md

The timestamp (YYYYMMDDhhmm ) is the anchor — files remain sortable and portable even if moved.

Session Start Ritual

When resuming work:

• Run /trail:read --type handoff to see recent handoffs

• Check the Next section for pending tasks

• Continue where the previous session left off

Session End Ritual

Before ending a session:

• Run /trail:handoff to create a handoff note

• Fill in Done, State, and Next sections

• Be specific enough that a fresh session can continue seamlessly