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):

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:

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

Configuration

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)