ouroboros-loops:context-handoff

Ouroboros: Context Handoff

Save a compressed context summary so the next step's agent can start fresh without losing critical information.

When to Use

The ouroboros-agent invokes this skill automatically after every step skill completes (analyze, fix, enhance, report, evaluate). Do not call directly.

Procedure

1. Read state.json

Read .ouroboros/state.json and collect:

• goal
• iteration
• currentStep — the step that just completed

2. Read config.json (if exists)

Read .ouroboros/config.json to include user preferences in the handoff for the next agent.

3. Determine next_step

Map completed step to the next step:

completed_step	next_step
research	analyze
analyze	fix
fix	branch
branch	enhance
enhance	report
report	evaluate
evaluate	determine
determine	(end of iteration)

4. Identify Modified Files

Review what was changed during this step. Check:

• Git status (git diff --name-only HEAD or git status --short) for uncommitted changes
• Any files explicitly mentioned in the step skill's output

List the modified files concisely.

5. Write handoff.md

Write .ouroboros/handoff.md (overwrite if exists):

# Ouroboros Handoff

- iteration: <N>
- completed_step: <step_name>
- next_step: <next_step_name or "end_of_iteration">
- timestamp: <YYYY-MM-DD>

## Goal
<goal from state.json>

## 사용자 설정
- intensity: <intensity from config.json, or "balanced" if not set>
- focusArea: <focusArea from config.json, or "전체" if not set>
- userNotes: <userNotes from config.json, or "(없음)">

## 이전 스텝 요약
<Brief description of what was done in this step — 3–5 sentences max. Focus on what changed, what was found, and key decisions made.>

## 수정된 파일
- <file1>
- <file2>
(empty list if no files were modified)

## 다음 스텝 참고사항
<Key information the next step agent needs to know. For example: which bugs were found and prioritized, which fixes were applied so enhance doesn't duplicate them, or which issues remain unresolved. Keep it actionable and brief.>

5b. Save Versioned Handoff (History Preservation)

After writing handoff.md, also write a versioned copy for history:

.ouroboros/handoff-history/handoff-<step>-iter<N>.md

Where <step> is completed_step and <N> is the iteration number (padded to 2 digits, e.g., 01).

Example: .ouroboros/handoff-history/handoff-fix-iter01.md

Create the .ouroboros/handoff-history/ directory if it does not exist. The versioned file has identical content to handoff.md. This allows post-hoc debugging of the full decision flow across all steps and iterations without affecting the main handoff.md used by agents.

6. Update state.json (evaluate / determine only)

If completed_step is evaluate and determine is NOT in the active step sequence (i.e., loop-config.json does not include "determine"), update currentStep in state.json to "done".

If completed_step is determine, update currentStep in state.json to "done".

For all other steps, leave currentStep unchanged — the start/resume skill writes it before each agent call.

Read the current state.json, update only the currentStep field, and write back. Preserve all other fields.

7. Output Completion

Print a brief completion message:

[context-handoff] Handoff saved: completed=<step>, next=<next_step>