context-workflow

A context-management + auto-compact relay workflow for opencode, built for read-heavy, non-pure-code tasks - reports, multi-document analysis, architecture planning, skill refactors - where you read a lot of files, analyze and plan, then execute or produce a deliverable.

The problem it solves. These tasks are context-hungry: every turn pulls in new files, so the total context keeps growing - and you pay for the full window on every request. Once you pass ~100K tokens the cost climbs steeply and long jobs (5h+) become impractical. Interrupting is expensive too - resuming means re-reading big files back into context.

The insight. These tasks are step-plannable up front. Each step has a different focus and doesn't need the whole project in context. So instead of dragging everything along, you split the task into steps, keep only what each step needs, and relay state between steps via lightweight JSON files.

How it works. Breaks a task into independent steps persisted to workflow.json, drops notes summaries the moment key files are read, writes a handoff.json relay at step completion, validates the handoff before compact, and restores in one shot after compact - all enforced by script gates, not prompt soft-rules. This keeps the window between 100K–150K tokens across multi-hour runs, cutting cost dramatically, while the JSON relay makes long tasks resumable and less error-prone.

Pairs with the context-workflow-guard plugin for automatic token-water-level injection and a wf_compact tool that lets the agent trigger compact on its own.

Core Features

• Step-based workflow: tasks split into independent steps, relayed via JSON, no shared context between steps
• Notes persistence: summaries extracted the moment important files are read, surviving compact
• Handoff relay: a handoff file written at step completion drives the next step's recovery
• Compact gate: scripts validate the handoff is complete before allowing compact; compact forbidden mid-step
• Automatic water-level injection: the plugin injects token levels every turn — no manual probing needed
• One-shot post-compact recovery: wf_resume.ps1 reads handoff + notes and prints a recovery guide

Installation

1. Install the skill

Copy the skills/ directory into opencode's skill discovery location:

# Windows
Copy-Item -Recurse skill "$env:USERPROFILE\.agents\skills\context-workflow"

# or clone and symlink

2. Install the guard plugin

Copy the plugins/ directory into opencode's plugin directory:

Copy-Item -Recurse plugin "$env:USERPROFILE\.config\opencode\plugins\context-workflow-guard"

3. (Optional) Install the run-long-script tool

If your long tasks run heavy scripts (tqdm/akshare/PDF parsing, typically >30s), install the bundled run-long-script tool. It redirects stdout/stderr to disk so progress bars never pollute the agent context, and a PowerShell watchdog auto-kills stuck processes.

Copy-Item -Recurse tools "$env:USERPROFILE\.config\opencode\"

This is optional - context-workflow works without it. The tool is also available as a standalone repo for users who only need script execution without the workflow framework.

See tools/ for details.

4. Verify

Restart opencode, load the context-workflow skill, and run:

& "~/.agents/skills/context-workflow/scripts/wf_init.ps1" -TaskName "test-task"

If a workflow directory is created successfully, installation is done.

Default Working Directory

Without -WorkDir, task data lives under ~/context-workflow-projects/.

To point it elsewhere, set an environment variable:

setx CONTEXT_WORKFLOW_PROJECT_DIR "D:\my-projects"

Resolution order (three tiers): -WorkDir explicit parameter > CONTEXT_WORKFLOW_PROJECT_DIR env var > ~/context-workflow-projects/ fallback.

Quick Start

# 1. Initialize the workflow (first action after loading the skill)
& "<skill_dir>/scripts/wf_init.ps1" -TaskName "my-task" -PlanJson '[{"id":"S01","name":"Step 1","goal":"Goal","actions":["Action 1"],"depends_on":[],"est_budget_tokens":60000}]'

# 2. Start the first step
& "<skill_dir>/scripts/wf_step.ps1" -Action start -WorkDir "<wf_root>" -StepId "S01" -KeyFiles "C:\path\file.pdf"

# 3. After reading an important file, drop a summary
& "<skill_dir>/scripts/wf_note.ps1" -WorkDir "<wf_root>" -StepId "S01" -SourceFile "C:\path\file.pdf" -Content "key info extracted"

# 4. Complete the step (validates handoff + notes)
& "<skill_dir>/scripts/wf_step.ps1" -Action done -WorkDir "<wf_root>" -StepId "S01"

# 5. Compact sequence: guard check -> wf_compact tool -> wf_resume after compact
& "<skill_dir>/scripts/wf_guard.ps1" -WorkDir "<wf_root>"
# invoke the wf_compact tool (param workdir=<wf_root>)
& "<skill_dir>/scripts/wf_resume.ps1" -WorkDir "<wf_root>"

# 6. Archive when everything is done
& "<skill_dir>/scripts/wf_archive.ps1" -WorkDir "<wf_root>"

See skills/SKILL.md for full usage, and skills/references/details.md for schemas and detail-level requirements.

Water-Level Thresholds

Total tokens	Level	Action
< 100K	normal	proceed normally
100K ~ 120K	watch	monitoring starts
120K ~ 140K	compact_recommended	prepare to compact
140K ~ 150K	compact_now	compact immediately after completing handoff
>= 150K	compact_now	red line, compact now

Prerequisites

• opencode's built-in compact must not be disabled: the wf_compact tool calls opencode's native client.session.summarize() to compress context and depends on that feature working. If auto-compaction is disabled in the opencode config, this framework cannot auto-compact — you'll need to run /compact manually.
• opencode auto-approve permission required: for stable unattended long runs (5h+), enable opencode's auto-approve permission so the agent can proceed through steps and trigger wf_compact without per-action confirmation. With manual approval on, every tool call and compact waits for user input, which breaks the relay timing and defeats the point of an automated workflow.

License

MIT

Copyright (c) 2026 Thexinyi