Skip to content

feat(cdt): add HANDOFF.md session artifact to wrap-up #111

@rube-de

Description

@rube-de

Part of #104

Context

CDT's auto-task wrap-up (auto-task.md:104) cleans up branch state: rm -rf ".claude/$BRANCH/". No session artifact is preserved. Each new session starts cold — decisions, context, and rationale from prior runs are lost.

Elite practice: every session ends with a structured handoff documenting decisions made, rationale, open questions, and context the next session needs. This compounds knowledge across sessions instead of restarting cold each time.

Task

Add a HANDOFF.md step to auto-task wrap-up (before cleanup) and dev-workflow wrap-up that writes a structured session artifact to .claude/files/.

Acceptance Criteria

  • VERIFY: Auto-task writes HANDOFF.md to .claude/files/handoff-$TIMESTAMP.md before cleaning up branch state
  • VERIFY: HANDOFF.md includes: task summary, key decisions with rationale, files changed, open questions, and what a future session should know
  • VERIFY: HANDOFF.md is written before rm -rf ".claude/$BRANCH/" (line 104)
  • VERIFY: Dev-workflow wrap-up (line 290) also writes HANDOFF.md (for non-auto-task runs)
  • VERIFY: HANDOFF.md references the plan path and dev report path

Implementation Guide

Files to Modify

  • plugins/cdt/commands/auto-task.md — Add HANDOFF.md step before cleanup (before line 104)
  • plugins/cdt/skills/cdt/references/dev-workflow.md — Add HANDOFF.md step before wrap-up (before line 299)

Approach

  1. In auto-task.md, Wrap Up section (before line 104 cleanup), add:
    5a. Write session handoff to `.claude/files/handoff-$TIMESTAMP.md`:
    
        # Session Handoff
    
        **Task**: [original task description]
        **Date**: [date]  **Branch**: [branch name]
    
        ## Decisions Made
        [Key architectural and implementation decisions with rationale — WHY, not just WHAT]
    
        ## Files Changed
        [List of all modified/created files]
    
        ## Plan & Report
        - Plan: [plan path]
        - Dev Report: [dev report path]
    
        ## Open Questions
        [Anything unresolved, deferred, or uncertain]
    
        ## Context for Next Session
        [What a future session working in this area should know]
    
  2. In dev-workflow.md, add the same template before the Wrap Up section (line 290), so non-auto-task flows also produce handoffs
  3. Ensure the handoff uses $TIMESTAMP from Step 2 for naming consistency

Patterns to Follow

  • The dev report template (dev-workflow.md:260-288) follows a similar structured format
  • .claude/files/ is already used for dev reports (dev-workflow.md:253)

Scope

In Scope

  • Adding HANDOFF.md write step to auto-task.md and dev-workflow.md
  • Defining the handoff template

Out of Scope

  • Reading previous handoffs at session start (future enhancement)
  • Adding handoff to plan-workflow.md (plan artifacts are the handoff for the plan phase)

Dependencies

  • Blocked by: None
  • Blocks: None

Definition of Done

  • Implementation complete
  • bun scripts/validate-plugins.mjs passes
  • PR approved and merged
  • Epic checklist updated

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions