Context Zones

A compact VS Code context panel for telling coding agents exactly what matters without attaching whole files.

Context Zones keeps five small, workspace-specific sections:

• Objective — the user-owned outcome.
• Status — the agent's current state, focus, next step, and blocker.
• Work Area — selected ranges the agent may edit.
• References — selected ranges that provide read-only guidance.
• History — a bounded ledger of decisions, completed milestones, failed attempts, and scope changes.

The existing nested Steps checklist remains available below the context sections.

Run it locally

1. Open this folder in VS Code.
2. Press F5.
3. In the Extension Development Host, open a source file and select a range.
4. Right-click the selection and choose Context Zones: Add Selection to Work Area or Add Selection to References.
5. Run Context Zones: Open Beside Code to inspect the shared packet.

Use Ctrl+Alt+T (Cmd+Alt+T on macOS) to reveal the beside-code panel. The Activity Bar view can also be moved to the primary sidebar, secondary sidebar, or bottom panel.

Work Area ranges use a yellow editor marker. Reference ranges use blue. Clicking a range chip reopens and selects that code.

Tell an agent about the zones

Native VS Code chat tool

Compatible VS Code chat agents can enable or mention the Manage Context Zones tool:

#contextZones Read the active context packet, perform the objective inside the Work Area,
and keep Status and History current.

The tool returns the compact packet and its scope rules. It supports:

• get
• setObjective (only when the user explicitly requests it)
• setStatus
• appendHistory
• removeSelection
• clearHistory

VS Code asks for confirmation before an agent mutates shared context.

Any other coding extension

Run Context Zones: Copy Compact Agent Packet, then paste it into the coding extension. This sends file names and exact ranges without repeating source code.

If the target agent cannot read workspace files, use Context Zones: Copy Agent Packet with Source instead. That packet embeds only the selected source, never the whole file.

The generated protocol tells the agent:

• Work Area is the primary editable scope.
• References are read-only guidance.
• Objective is user-owned.
• Status and History must remain concise.
• Scope expansion must be explained before editing elsewhere.

Context packet

<context-packet version="1">
  <objective>Add validation without changing the public API.</objective>
  <status state="in-progress">
    <current>Implementing validation rules</current>
    <next>Run user-service tests</next>
  </status>
  <work-area editable="true">
    <range id="..." file="src/users/create.ts" range="24:1-61:2" />
  </work-area>
  <references editable="false">
    <range id="..." file="src/orders/create.ts" range="18:1-47:2" />
  </references>
  <history>
    <entry type="decision">Reuse the existing ValidationError format.</entry>
  </history>
</context-packet>

History retains at most 20 entries, and a normal packet sends only the eight most recent entries.

Commands

• Context Zones: Set Objective
• Context Zones: Add Selection to Work Area
• Context Zones: Add Selection to References
• Context Zones: Copy Compact Agent Packet
• Context Zones: Copy Agent Packet with Source
• Context Zones: Clear Code Selections
• Context Zones: Open Beside Code
• Context Zones: Show Docked View

Existing Floating Plan todo commands remain available for compatibility.

Extension API

const extension = vscode.extensions.getExtension('vikasavnish.floating-plan');
const api = await extension.activate();

await api.setObjective('Add validation without changing the public API');
await api.setStatus({ state: 'in-progress', current: 'Editing rules' });
await api.appendHistory({ type: 'decision', summary: 'Reuse ValidationError' });

const state = api.getContext();
const packet = api.serializeContext();

Context members:

• getContext()
• setObjective(objective)
• setStatus(status)
• appendHistory(entry)
• addContextSelection(zone, selection)
• removeContextSelection(id)
• serializeContext(options?)
• onDidChangeContext

The previous todo API is unchanged.

Test and package

npm run check
npm run package

The extension is plain JavaScript and has no runtime dependencies.