Context Continuity - Claude Code Edition

Transfer development context between Claude Code sessions with high fidelity, preserving code state, git context, and running services.

Core Concept

When development work needs to transfer between Claude Code sessions, this skill creates structured artifacts that capture:

• Code Context - Files being worked on, functions/classes modified, pending changes
• Git State - Branch, commits, staged/unstaged changes, merge status
• Environment State - Running services, ports, environment variables, dependencies
• Development Decisions - Technical choices made, alternatives rejected, tradeoffs
• Open Loops - What's next, blockers, pending reviews

When to Use This Skill

Use when you need to:

• Continue development work in a fresh Claude Code session
• Hand off work to another developer (with AI context preserved)
• Resume after context window fills (180K+ tokens)
• Switch between different Claude Code instances
• Document current state before major refactoring
• Prepare for peer review (Codex/Gemini integration)

DO NOT use for:

• General conversation summaries (use base context-continuity skill)
• Non-development contexts (writing, research, analysis)
• Simple task handoffs without code changes

Workflow: Single Mode (Development-Optimized)

This skill uses a single optimized mode for development contexts (~400-600 words):

═══════════════════════════════════════════════════════════════════
DEV CONTEXT TRANSFER
═══════════════════════════════════════════════════════════════════
Generated: [ISO timestamp] | Session: [ID if available]

**MISSION**: [What we're building/fixing + why it matters]

**STATUS**: [✓ complete | ⧗ in-progress | ⚠ blocked | ↻ iterating]

**PROGRESS**: [High-level summary of work completed this session]

───────────────────────────────────────────────────────────────────
§ CODE CONTEXT
───────────────────────────────────────────────────────────────────

**Active Files**:
- [file:line] - [What changed or what you're working on]
- [file:line] - [Status: implemented | in-progress | pending]

**Key Changes**:
- [Function/class]: [What changed + why]
- [Module/component]: [Refactoring/addition/fix]

**Code State**:
- Modified: [List files with uncommitted changes]
- Created: [New files added]
- Deleted: [Files removed]

───────────────────────────────────────────────────────────────────
§ GIT STATE
───────────────────────────────────────────────────────────────────

**Branch**: [current-branch-name]
**Base**: [main/master/develop]
**Commits**: [X commits ahead of base]

**Recent Commits**:
- [hash] [message]
- [hash] [message]

**Staged**: [Files in staging area | None]
**Unstaged**: [Modified files not staged | None]
**Untracked**: [New files not in git | None]

**Merge Status**: [Clean | Conflicts in X files | Pending PR #XXX]

───────────────────────────────────────────────────────────────────
§ ENVIRONMENT STATE
───────────────────────────────────────────────────────────────────

**Running Services**:
- [Service]: [localhost:PORT] - [Status: healthy | issue]
- [Database]: [postgres:5432] - [State: connected, X records]

**Dependencies**:
- Recently installed: [package@version, ...]
- Pending: [Packages needed but not installed]

**Environment Variables**:
- Critical vars set: [APP_ENV=dev, DATABASE_URL=localhost, ...]
- Missing/needed: [API_KEY (required for testing), ...]

**Terminal State**:
- Active shells: [X terminals open in /path/to/project]
- Background processes: [npm run dev, docker compose up, ...]

───────────────────────────────────────────────────────────────────
§ TECHNICAL DECISIONS
───────────────────────────────────────────────────────────────────

**Decisions Made**:
| Decision | Rationale | Alternatives Rejected | Tradeoff |
|----------|-----------|----------------------|----------|
| [Choice] | [Why] | [What we didn't do] | [Cost we're paying] |

**Architecture Notes**:
- [Pattern/approach chosen]: [Why it fits this context]
- [Constraint observed]: [Technical/business reason]

**Peer Review Integration**:
- Codex consulted: [Yes/No] - [If yes: key recommendations]
- Gemini consulted: [Yes/No] - [If yes: key recommendations]
- Agreements: [Where both AIs aligned]
- Disagreements: [Where perspectives differed + our choice]

───────────────────────────────────────────────────────────────────
§ OPEN LOOPS
───────────────────────────────────────────────────────────────────

**Next Actions**:
- [ ] [Immediate next step - be specific]
- [ ] [Following step]

**Blockers**:
- [What's blocking + why]: [Waiting for X | Need to solve Y]

**Pending**:
- Code review: [PR #XXX awaiting review]
- Testing: [Need to test X scenario]
- Documentation: [Need to update README/docs]

**Questions to Resolve**:
- [ ] [Technical question needing answer]
- [ ] [Design decision pending]

───────────────────────────────────────────────────────────────────
§ TESTING & VALIDATION
───────────────────────────────────────────────────────────────────

**Test Status**:
- Passing: [X/Y tests pass]
- Failing: [Test names that fail + why]
- Coverage: [X% coverage | Not measured]

**Manual Testing Done**:
- [Scenario tested]: [Result]
- [Edge case checked]: [Outcome]

**Still Need to Test**:
- [ ] [Test case pending]
- [ ] [Integration scenario]

───────────────────────────────────────────────────────────────────
§ CONTEXT NOTES
───────────────────────────────────────────────────────────────────

**Key Insights**:
- [Important discovery from this session]
- [Gotcha/caveat to remember]

**Developer Notes**:
- Communication style: [Preferences for next session]
- Assumed knowledge: [What doesn't need re-explaining]
- Sensitive areas: [Code that's fragile, requires care]

**Links/References**:
- Documentation: [URLs to relevant docs]
- Related PRs/Issues: [GitHub links]
- Design docs: [Figma, diagrams, etc.]

═══════════════════════════════════════════════════════════════════
§ TRANSFER READY
═══════════════════════════════════════════════════════════════════
Review for accuracy before sharing. Check git state and file paths.

After generating, ask: "Before you transfer—are there any sections that need further detail or refinement?"

Generating the Artifact

Step 1: Gather Context

File Context:

# Get modified files
git status --short

# Get recent commits
git log --oneline -5

# Check current branch and tracking
git branch -vv

# Show uncommitted changes summary
git diff --stat
git diff --cached --stat

Environment Context:

# Check running processes
lsof -i -P -n | grep LISTEN

# Check environment
env | grep -E '(PATH|NODE_ENV|DATABASE|API|APP_)'

# Recent package changes (if applicable)
git log --oneline -10 package.json

Code Context:

• Note which files have been actively edited
• Identify key functions/classes modified
• Track new files created vs existing files changed

Step 2: Generate Artifact

Fill out sections systematically:

1. Mission/Status/Progress - What and why
2. Code Context - What files/functions changed
3. Git State - Branch, commits, staging area
4. Environment State - Services, dependencies, env vars
5. Technical Decisions - Choices made (include peer review input)
6. Open Loops - Next actions, blockers
7. Testing - What's validated, what's pending
8. Context Notes - Insights, gotchas, references

Step 3: Present & Refine

1. Present artifact in full
2. Add: "§ TRANSFER READY—Review for accuracy before sharing."
3. Ask: "Before you transfer, are there any sections that need further detail or refinement?"
4. Human reviews, requests expansions if needed

Step 4: Transfer to New Session

Receiving agent prompt (optional prepend):

[DEV CONTEXT TRANSFER]

The following is a development context transfer from a previous Claude Code session.

After reading, provide a handshake confirmation:

"I've reviewed the dev context. Quick confirmation:
- Mission: [Echo back what we're building]
- Code State: [Active files and key changes]
- Git: [Branch + commit status]
- Next: [Immediate next action]
- Environment: [Critical services/dependencies]

Ready to [next action]. What's your priority?"

Integration with Peer Review Skills

When using Codex or Gemini for peer review during the development session:

Before Peer Review

1. Generate a lightweight context artifact (just Code + Git + Technical Decisions sections)
2. Use as input to peer review request
3. Get Codex/Gemini perspective

After Peer Review

1. Update § Technical Decisions with peer review findings:

   • What Codex/Gemini recommended
   • Where they agreed
   • Where they disagreed
   • Which advice you followed (and why)

2. Include in transfer artifact so receiving agent knows:

   • What external validation was done
   • What technical debates were resolved
   • What alternatives were already considered

Example Integration

§ TECHNICAL DECISIONS

**Decisions Made**:
| Decision | Rationale | Alternatives Rejected | Tradeoff |
|----------|-----------|----------------------|----------|
| Use Redis for session storage | Sub-ms latency required, peer reviews validated | PostgreSQL (too slow), In-memory (no persistence) | Added infrastructure complexity |

**Peer Review Integration**:
- **Codex consulted**: Yes - Recommended Redis over Postgres for session store, flagged potential memory limits
- **Gemini consulted**: Yes - Agreed with Redis choice, suggested Redis Cluster for scaling
- **Agreements**: Both AIs validated Redis for performance needs
- **Disagreements**: Codex suggested 1GB limit, Gemini suggested 2GB - we chose 1.5GB as middle ground
- **Implementation notes**: Added eviction policy (allkeys-lru) based on Codex warning about memory pressure

Best Practices

Do:

• Run git status and git diff --stat before generating
• Include specific file paths with line numbers (file.py:123)
• Note running services and their ports
• Capture peer review insights in § Technical Decisions
• Include error messages or test failures verbatim
• Mark files as "in-progress" vs "completed"

Don't:

• Include secrets, API keys, credentials (redact them)
• Paste entire file contents (link to files with line ranges)
• Assume receiving agent has access to same environment
• Skip git state (critical for resuming work)
• Forget to note running services (easy to miss)

Examples

See references/examples.md for:

• Full-stack feature development handoff
• Bug fix mid-investigation transfer
• Refactoring session continuation
• Code review preparation
• Post-peer-review implementation
• Emergency context capture

Validation

Use the Python validator to check artifact quality:

python context-continuity-code/scripts/validate_dev_transfer.py artifact.md

Checks for:

• Required sections present
• Git state completeness
• File paths formatted correctly
• No secrets leaked
• Peer review integration (if applicable)

Design Principles

Development-First: Optimized for code handoffs, not general conversation Git-Aware: Git state is mandatory, not optional Tool State Required: Environment and services are core context Peer Review Integration: First-class support for Codex/Gemini consultation Single Mode: One format optimized for dev workflows (no Minimal/Full choice) Antifragile: Critical info first (Mission → Code → Git → Environment)

Differences from Base Context Continuity

Use this skill when resuming development work. Use base context-continuity for general conversations.