Session Branch

Branch your current coding session into a new conversation without losing context.

When to Use

• Current conversation is getting long and context compression is degrading quality
• You want to start a new task on the same project but keep full context
• You need to fork your work into a parallel direction
• User says: "支线任务" / "开个支线" / "分叉"

Privacy & Consent

Before executing any step, the agent MUST:

1. Warn the user that this skill will write a file to the project directory (e.g., docs/session-handoff.md)
2. Ask for explicit consent before scanning any IDE-specific identity, memory, or configuration files
3. Never harvest env var values — only record variable names and whether they are configured (yes/no)
4. Use project-relative paths in all generated documents — never absolute paths containing usernames or home directories

Execution Flow

Step 1: Analyze Current Session

Scan the current conversation and project to extract:

1. Primary request and intent — all user intents, deduplicated, numbered chronologically
2. Key technical concepts — keywords, categorized (Architecture / Tools / Patterns)
3. Files and code sections — all Read/Edit/Write operations, with change summaries and key snippets
4. Errors and fixes — recent 5-10 errors with root cause and solution
5. Problem solving — completed achievements + key decision chain (chosen vs rejected + why)
6. All user messages — original text preserved with sanitization (strip credentials/PII), truncate >500 chars with "..."
7. Conversation language — detected primary language
8. Current work — active task, unfinished Todos with status, branchable directions

Supplementary context (not token-budgeted): project identity, platform status, env var names (status only), capability boundary, knowledge file index, user preferences.

IDE-Specific Additional Scanning

Consent required: Before scanning any of the following, inform the user what files will be accessed and ask for explicit permission. Skip any category the user declines.

For WorkBuddy, also scan (with user consent):

• Identity files: ~/.workbuddy/SOUL.md, IDENTITY.md, USER.md — persona and preferences
• Memory files: .workbuddy/memory/MEMORY.md + daily logs — project memory
• Installed skills: ~/.workbuddy/skills/ — list of active skills
• Scheduled tasks: automation/cron task list and status
• Channel config: IMA knowledge base IDs, Feishu channel configuration
• MCP connectors: active MCP connector status

For TRAE SOLO, also scan (with user consent):

• Rules: .trae/rules/ — project-level rules
• Schedule: TRAE SOLO Schedule task list
• Memory system: ~/.trae-cn/memory/ — user profile, project memory, recent topics (see references/memory-guide.md for path structure)

For Cursor, also scan:

• Rules: .cursor/rules/ or .cursorrules

For Claude Code, also scan:

• Rules: CLAUDE.md in project root

Step 1.5: Apply Compression Strategy

Based on Trae IDE session-copy architecture. The handoff doc uses an 8-section fixed structure with token budget management.

8 Core Sections (token budget ~4000 total):

#	Section	Priority	Budget	Rule
1	Primary Request and Intent	P2	~300	Numbered list, deduplicated
2	Key Technical Concepts	P2	~200	Keyword list, categorized
3	Files and Code Sections	P1	~1200	Paths + changes + snippets (max 500 chars each)
4	Errors and Fixes	P1	~600	Recent 5-10 only, description + cause + fix
5	Problem Solving	P2	~300	Completed achievements + decision chain
6	All User Messages	P0	~800	Original text with sanitization (strip credentials/PII), truncate >500 chars with "..."
7	Conversation Language	P3	~10	Single field
8	Current Work	P0	~600	Active task + unfinished Todos + branchable directions with sanitization (no personal paths)

Compression priority: When content exceeds budget, compress in reverse priority order (P3 first, P0 last):

• P3 (can discard): Conversation Language is just one word
• P2 (summary only): Compress to keyword lists
• P1 (keep recent): Only recent 5-10 errors, only key code snippets
• P0 (preserve with mandatory sanitization): All user messages and current work status — strip credentials, tokens, real names, emails, and personal identifiers before preserving; replace with <REDACTED> placeholders

Supplementary sections (not budgeted): Project identity, platform status, env vars, capability boundary, knowledge index, user preferences, IDE-specific context (with consent).

Step 2: Generate Handoff Document

Use the template at references/handoff-template.md to create a structured handoff document.

Save location by IDE:

IDE	Default path	Rationale
WorkBuddy	.workbuddy/session-handoff.md	Align with memory system, keep project root clean
TRAE SOLO	docs/session-handoff.md	Standard docs location
Cursor	docs/session-handoff.md	Standard docs location
Claude Code	docs/session-handoff.md	Standard docs location

Critical rules:

• NO personal information (real names, emails, token values)
• NO project-specific secrets or credentials
• Use project-relative paths (e.g., docs/session-handoff.md), never absolute paths containing usernames or home directories
• Use generic placeholders: <project-name>, <owner>, <your-path>
• The handoff doc must be reusable as a TEMPLATE, not a one-time snapshot

Step 3: Validate with Checklist

Cross-check the generated handoff against references/checklist.md.

Every item must be covered. If something is not applicable, write "N/A" with a reason.

Step 4: Generate Startup Prompt

Use references/startup-prompts.md to generate the startup prompt for the new conversation.

The prompt must include:

1. Project-relative file paths for the new AI to read (never absolute paths with usernames)
2. A three-step flow: Load → Report → Ask
3. Clear role: "This is a continuation of an existing project, not starting from scratch"

Step 5: Present to User

Show the user:

1. The generated handoff document (key sections summary)
2. The startup prompt (ready to copy-paste)
3. List of files created and their locations
4. Ask: "Ready to open a new conversation?"

Permission Declaration

Capability	Used	Description
Network	No	No network access required
File read/write	Yes	Reads project files; writes docs/session-handoff.md (overwrites if exists). Reads IDE memory/identity files (e.g., ~/.trae-cn/memory/, ~/.workbuddy/SOUL.md) ONLY with explicit user consent — opt-in, never silent reads
Environment variables	Yes	Reads env var names (status only, never values)
subprocess	No	No subprocess calls
External API	No	No external API calls

Configuration

Setting	Default	Description
handoff_path	Auto (by IDE)	Where to save the handoff document
include_checklist	true	Whether to validate against checklist
target_ide	auto	Target IDE for startup prompt (auto/trae/workbuddy/cursor/claude-code)

References

• references/handoff-template.md — Full template for the handoff document (8 sections + supplementary context)
• references/checklist.md — Validation checklist (8 core sections + supplementary + IDE-specific)
• references/startup-prompts.md — IDE-specific startup prompt templates (5 IDEs with memory integration)
• references/memory-guide.md — TRAE memory system reference (3 layers + quick lookup guide)