trails

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:

1. Run /trail:read --type handoff to see recent handoffs
2. Check the Next section for pending tasks
3. Continue where the previous session left off

Session End Ritual

Before ending a session:

1. Run /trail:handoff to create a handoff note
2. Fill in Done, State, and Next sections
3. Be specific enough that a fresh session can continue seamlessly