Session Workflow Management

Structured workflows for starting, checkpointing, and completing coding sessions. Ensures context survives compaction and work is never stranded.

Session Start

1. Orient

bd prime              # Load workflow context
bd ready --json       # Find unblocked work

2. Understand Current State

If continuing existing work:

bd list --status in_progress   # What was I working on?
bd show <id>                   # Get full context

If starting fresh:

bd ready                       # Pick highest priority unblocked issue
openspec list                  # Check for active OpenSpec changes

3. Announce Intent

bd update <id> --status in_progress

Session Checkpoint

Run periodically, especially before:

• Asking user for input
• Context getting large (>70% tokens)
• Switching to a different task
• Taking a break

Quick Checkpoint

# Capture current state
bd update <id> --add-note "CHECKPOINT: <what was done>, <what's next>"

# Sync to git
bd sync

Full Checkpoint

# Update issue notes with full context
bd update <id> --add-note "CHECKPOINT $(date):
COMPLETED: <list of completed items>
IN PROGRESS: <current item and state>
DECISIONS: <any key decisions made>
BLOCKERS: <any blockers discovered>
NEXT: <what to do next>"

# If code changed, verify build
.\build.ps1

# Sync tracking
bd sync

# Commit work-in-progress (optional but recommended)
git add -A
git commit -m "wip: checkpoint - <brief description>"
git push

Landing the Plane (Session End)

MANDATORY workflow. Work is NOT complete until git push succeeds.

Step 1: File Issues for Discovered Work

# Bugs found
bd create "Bug: <description>" -t bug -p 1 -d "<full context>"

# TODO items
bd create "TODO: <description>" -t task -p 2 -d "<full context>"

# Technical debt
bd create "Tech debt: <description>" -t tech-debt -p 3 -d "<full context>"

Step 2: Run Quality Gates

# Build
.\build.ps1

# Test (if applicable)
.\test.ps1

# Whitespace check
.\Build\Agent\check-and-fix-whitespace.ps1

# Commit message validation
.\Build\Agent\commit-messages.ps1

File P0 issues if builds/tests are broken.

Step 3: Update All Tracking

Beads:

# Completed work
bd close <id> --reason "Completed: <summary>"

# Partial progress
bd update <id> --status in_progress --add-note "SESSION END: <what remains>"

# Add context for future sessions
bd update <id> --add-note "HANDOFF: <key context for next session>"

OpenSpec tasks.md (if applicable):

• Mark completed tasks: - [x] Task description
• Add notes for partial progress

Agent Mail (if multi-agent):

send_message(
  thread_id="bd-<id>",
  subject="[bd-<id>] Session end",
  body_md="## Session Summary\n<what was done>\n\n## Remaining\n<what's left>"
)
release_file_reservations()

Step 4: Sync and Push (MANDATORY)

# Sync Beads to git
bd sync

# Stage, commit, push
git add -A
git commit -m "chore: session end - <summary>"
git pull --rebase
git push

# VERIFY - must be clean and pushed
git status

Step 5: Verify Final State

bd list --status open    # Review open issues
bd ready                 # Show what's ready for next session
git status               # MUST be clean and pushed

Step 6: Handoff

Provide context for next session:

## Session Handoff

### Completed This Session
- <list of completed items>

### Current State
- **Active Epic**: <id and title>
- **In Progress**: <id and title> (or "none")
- **Ready Work**: `bd ready` shows N issues

### Key Decisions
- <decision 1 and rationale>
- <decision 2 and rationale>

### Blockers
- <blocker 1> (waiting on: <what>)

### Next Session Priorities
1. <first priority>
2. <second priority>

### Important Context
- <anything the next session needs to know>

Critical Rules

Rule	Why
Work is NOT complete until git push succeeds	Local-only work is stranded work
NEVER stop before pushing	Leaves work invisible to others
NEVER say "ready to push when you are"	YOU must push, not the user
ALWAYS run bd sync before committing	Captures issue changes in git
If push fails, resolve and retry	Don't give up on pushes

Emergency Procedures

Context About to Compact

# Immediate dump of current state
bd update <id> --add-note "EMERGENCY CHECKPOINT:
$(Get-Date -Format 'yyyy-MM-dd HH:mm')
Working on: <current task>
Progress: <what's done>
Next steps: <what was about to happen>
Key files: <list of modified files>
Test status: <pass/fail/not run>"

bd sync
git add -A
git commit -m "wip: emergency checkpoint before compaction"
git push

Lost Context After Compaction

# Recover from beads
bd list --status in_progress
bd show <id>                    # Read the notes!

# Check git for recent changes
git log --oneline -10
git diff HEAD~3

# Check Agent Mail inbox
fetch_inbox(urgent_only=true)

Integration Points

With OpenSpec

• Use openspec:change-name as thread_id and label
• Keep tasks.md in sync with bd issues
• Archive change when all issues closed

With TodoWrite

• TodoWrite for immediate tactical work (this hour)
• Beads for persistent tracking (this week/month)
• Update Beads notes with TodoWrite outcomes