feat: add context handoff compaction

[pertrai1-bot]

Summary

• Add directives/context-handoff.md for compacting task state at directive, phase, PR, or session boundaries.
• Define .agents/handoff.md as the active rewritten handoff and .agents/handoff-log.md as optional historical audit trail.
• Integrate handoff selection into adaptive routing and the AGENTS/CLAUDE/Copilot templates.
• Update README to document the new directive and handoff usage.

Verification

• git diff --check
• Local directive frontmatter validation
• Local routing/reference validation
• Template checks for directives/context-handoff.md references and removal of stale Light Path file-count heuristics

Notes

• This is a stacked PR based on feat/adaptive-workflow-routing because context handoff depends on the adaptive router introduced there.
• The directive is intentionally non-programmatic: it cannot erase model context, but it defines a portable handoff discipline and file/response/PR-comment storage fallback.

Summary by CodeRabbit

• New Features

  • Introduced context-handoff directive for compacting and persisting task state across workflow phase and session boundaries.
  • Added new HANDOFF workflow phase for state management at directive transitions.

• Updates

  • Routing guidance refined to distinguish low-risk changes from behavioral/structural changes.
  • Adaptive routing now determines context handoff requirements for workflows.
  • Systematic debugging skill extended to recognize build and integration failure triggers.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The changes introduce a new context-handoff directive that specifies how task state should be compacted and persisted across workflow boundaries. Documentation across templates, directives, and the README is updated to incorporate context handoff routing decisions and introduce an explicit "HANDOFF" phase. A skill's routing triggers are expanded to include build and integration failure categories.

Changes

Cohort / File(s)	Summary
New Directive Documentation directives/context-handoff.md, README.md	New context-handoff.md directive defines handoff capsule structure, storage selection, rewrite-at-boundaries semantics, and phase boundary rules. README updated to include context handoff in directive set count and workflow overview, with Quick Start extended to use handoff for long tasks.
Directive Updates directives/adaptive-routing.md, directives/codebase-navigation.md	Adaptive routing extended to output Handoff required field and reference context handoff at phase/session transitions across all paths (Light, Review, Exploration, Debugging, Boundary, Full, Policy). Codebase navigation trigger broadened to include "review" alongside "implementation" and conditional loading refined.
Workflow Templates templates/AGENTS.md, templates/CLAUDE.md, templates/copilot-instructions.md	Templates updated to incorporate context handoff into adaptive routing decisions and introduce explicit "HANDOFF" phase (5.5) for compacting task state at boundaries. Light Path criteria tightened to exclude bug/behavior/API/dependency changes; Full Path expanded to enumerate those categories. Test-Driven Development scoped to behavior changes.
Skill Routing Configuration skills/systematic-debugging/SKILL.md	build-failure and integration-failure added to routing triggers, enabling skill selection for those failure categories.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add adaptive workflow routing #5: Directly builds on this same PR series by extending adaptive-routing workflow with the context-handoff directive and updating multiple templates and directives to reference handoff at phase transitions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'feat: add context handoff compaction' accurately describes the main change—introducing a new context handoff directive and documentation for compacting task state at boundaries.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/context-handoff-compaction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds a new “Context Handoff” directive and wires it into the repo’s adaptive workflow routing and agent instruction templates, so long-running or multi-phase work can be compacted into an explicit handoff capsule instead of relying on accumulating chat history.

Changes:

• Introduces directives/context-handoff.md defining handoff capsule semantics and storage conventions.
• Updates directives/adaptive-routing.md to include handoff requirements in routing output and path rules.
• Updates templates and README to reference and document the new directive and workflow step.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
templates/copilot-instructions.md	Adds context-handoff awareness to routing guidance and Full Path workflow steps.
templates/CLAUDE.md	Updates Light/Full Path guidance and adds a HANDOFF step + directive reference.
templates/AGENTS.md	Same as CLAUDE template: clarified path selection + HANDOFF step + directive table entry.
directives/context-handoff.md	New directive defining when/how to compact task state and where to store it.
directives/adaptive-routing.md	Extends routing output and rules to include handoff requirement selection and usage.
README.md	Documents the new directive and updates included workflow directive count and quick start.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.