⚓ context-anchor — Working Reference Snapshots & Workstream Parking
Drop a compact working reference in <project-root>/.agents/ to prevent cascading context drift, and park parallel client workstreams under named anchors so an agency can switch lanes mid-session and resume instantly.
v1.1.0 positions this skill as the intra-session focus layer: anchors capture working state within sessions and park parallel workstreams; cross-session continuity belongs to handoff (.agents/artifacts/HANDOFF.md). The layering contract between them is normative — see references/layering-protocol.md.
When to Use
- Before switching tasks or workstreams mid-session.
- Parking a client workstream to work another lane ("park this workstream", "park", "switch-task").
- Resuming a parked workstream ("switch to
<slug>", "list anchors").
- Before delegating a subtask to another agent.
- At the start of a session when previous context is cold or stale (after the
handoff entry probe).
- Whenever you catch yourself re-reading dozens of messages to recall system state.
Anti-Triggers
- Cross-session continuity: the always-current boundary file is
handoff's .agents/artifacts/HANDOFF.md — do not duplicate it here. Anchor → fold → flush happens at session close (Step 6).
- Long-term quarterly reviews: use
periodic-retreat.
Quick Reference
Anchor Anatomy (≤15 lines, every line load-bearing)
| Field / Section |
Content Requirement |
Constraint |
workstream: header |
Slug of the lane (main, or e.g. client-acme-redesign) |
Exactly 1 |
branch: header |
Git branch at write time |
Exactly 1 |
Client: header (optional) |
Project codename — never legal client names under NDA |
0–1 |
| What's True Right Now |
Active state, key decisions made, and ruled-out paths |
2–4 bullets |
| The Working Reference |
Single actionable sentence ending in resume by: <how> |
Exactly 1 sentence |
| Next Action |
Single atomic next step with file and line reference |
Exactly 1 task item |
The Layering Protocol
| Layer |
File |
Scope |
Lifetime |
| Micro-anchor (this skill) |
.agents/anchor.md (default focus) or .agents/anchors/<slug>.md (parked workstreams) |
Current focus within a session |
Disposable; folded forward |
Boundary state (handoff v2.1.0) |
.agents/artifacts/HANDOFF.md |
Cross-session continuity |
Always-current, overwritten |
Precedence on conflict: HANDOFF.md wins for cross-session truth; the active anchor wins for intra-session focus. On workspace entry, read HANDOFF.md (handoff ladder rung 1) — never resurrect state from a stale anchor alone.
Token Budgets
| Phase |
Budget |
| Anchor write |
≤15 lines |
| Re-entry block on resume |
≤3 lines (state / reference / next action) |
| Detail loading |
On demand — named anchors are read only when their workstream is switched to |
Procedure
Step 1: Scan Active Session
Identify:
- What was being built / fixed / investigated.
- What decisions were finalized and why.
- What was tried and ruled out.
- The exact next concrete step.
Step 2: Write the Anchor
Default focus anchor → .agents/anchor.md; parked workstream → .agents/anchors/<slug>.md:
# Context Anchor — <ISO timestamp>
workstream: <slug> | branch: <branch>
Client: <codename or "internal">
## What's True Right Now
- [1-sentence state of active work]
- [Key decision made: what and why]
- [What was tried and ruled out]
## The Working Reference
> [One actionable sentence.] resume by: [exact re-entry move]
## Next Action
- [ ] `path/to/file.ts:line` — [Exact atomic action]
Step 3: Echo the Anchor
Display the anchor to the user for instant alignment.
Step 4: Consume Protocol (on resume)
- Re-entry block, ≤3 lines: state / working reference / next action. Nothing else before the first productive action.
- Freshness check: header
branch: must match the current branch and the timestamp must postdate the last commits on it. Mismatched or stale → treat as a hint, re-derive from HANDOFF.md or git, and overwrite the anchor with corrected state.
- Resume work; refresh the anchor at the next focus shift.
Step 5: Park / Switch / List (Workstream Operations)
- Park the current lane: write
.agents/anchors/<slug>.md with a resume by: clause. If the parked workstream is blocked, also emit a dead-letter packet.
- Switch to
<slug>: anchor the current focus first (never lose it), then read .agents/anchors/<slug>.md and run the Step 4 consume protocol.
- List: one line per anchor file — slug, timestamp, next-action summary. No file dumps.
- A workstream parked across sessions gets promoted into
HANDOFF.md In-Flight at close (Step 6), so it survives even if the anchor file is never reopened.
Step 6: Close-Out Fold
On session close, the active anchor's surviving content folds into handoff's HANDOFF.md (Next Step / In-Flight / Decisions) — handoff owns the flush; the anchor is scratch. At project close, archive or wipe client workstream anchors per the confidentiality guard below.
Client-Confidentiality Guard
Anchors capture raw working context and may be committed, synced, or read by contractors:
- Codename rule: when an NDA applies,
Client: carries a codename — never legal names, never contract terms, never pricing.
- No secrets: tokens, credentials, and
.env values never enter an anchor (same rule as every suite artifact).
- Close-out hygiene: archive client anchors to
.agents/archive/ or delete them at project end; stale client anchors left behind are knowledge-hygiene defects the audit skill will flag as orphans.
Pitfalls
- Verbosity & Noise: Every line must be load-bearing. Delete filler.
- Vague Next Actions: Never write "continue coding"; specify the exact file, line number, and function.
- Missing Decisions Rationale: Always include the "why" for architectural decisions so future agents don't revert them.
- Stale Anchor Trust: Never resume from an anchor that fails the freshness check without re-derivation.
- Confidentiality Leak: An anchor is an artifact; write it as if the client will read it — because they might.
- Parallel File Drift: Two files claiming current state (
anchor.md and HANDOFF.md) is a bug, not a backup — resolve via the layering protocol, never by maintaining both as truth.
Verification
- Confirm the anchor file exists, is ≤15 lines, and is formatted cleanly.
- Confirm Next Action points to an exact concrete file and line number.
- Confirm the header carries
workstream: and branch: for freshness checking.
- Confirm re-entry used the ≤3-line budget and the freshness check ran.
- Confirm no client-identifying or secret material under NDA scope.
1---2name: context-anchor-23description: Drop a working reference anchor at any point in a session to prevent cascading context drift, and park parallel client workstreams under named anchors for instant switching. The intra-session focus layer that folds into handoff's HANDOFF.md for cross-session continuity. Use when switching tasks, parking a client workstream, or refocusing mid-session.4license: MIT5---67# ⚓ context-anchor — Working Reference Snapshots & Workstream Parking89Drop a compact working reference in `<project-root>/.agents/` to prevent cascading context drift, and park parallel client workstreams under named anchors so an agency can switch lanes mid-session and resume instantly.1011v1.1.0 positions this skill as the **intra-session focus layer**: anchors capture working state *within* sessions and park *parallel workstreams*; cross-session continuity belongs to `handoff` (`.agents/artifacts/HANDOFF.md`). The layering contract between them is normative — see [references/layering-protocol.md](references/layering-protocol.md).1213---1415## When to Use1617- Before switching tasks or workstreams mid-session.18- **Parking a client workstream** to work another lane ("park this workstream", *"park"*, *"switch-task"*).19- **Resuming a parked workstream** ("switch to `<slug>`", *"list anchors"*).20- Before delegating a subtask to another agent.21- At the start of a session when previous context is cold or stale (after the `handoff` entry probe).22- Whenever you catch yourself re-reading dozens of messages to recall system state.2324### Anti-Triggers2526- **Cross-session continuity**: the always-current boundary file is `handoff`'s `.agents/artifacts/HANDOFF.md` — do not duplicate it here. Anchor → fold → flush happens at session close (Step 6).27- Long-term quarterly reviews: use [`periodic-retreat`](../periodic-retreat/SKILL.md).2829---3031## Quick Reference3233### Anchor Anatomy (≤15 lines, every line load-bearing)3435| Field / Section | Content Requirement | Constraint |36|:---|:---|:---|37| `workstream:` header | Slug of the lane (`main`, or e.g. `client-acme-redesign`) | Exactly 1 |38| `branch:` header | Git branch at write time | Exactly 1 |39| `Client:` header (optional) | Project codename — **never legal client names under NDA** | 0–1 |40| **What's True Right Now** | Active state, key decisions made, and ruled-out paths | 2–4 bullets |41| **The Working Reference** | Single actionable sentence ending in `resume by: <how>` | Exactly 1 sentence |42| **Next Action** | Single atomic next step with file and line reference | Exactly 1 task item |4344### The Layering Protocol4546| Layer | File | Scope | Lifetime |47|:---|:---|:---|:---|48| **Micro-anchor** (this skill) | `.agents/anchor.md` (default focus) or `.agents/anchors/<slug>.md` (parked workstreams) | Current focus within a session | Disposable; folded forward |49| **Boundary state** (`handoff` v2.1.0) | `.agents/artifacts/HANDOFF.md` | Cross-session continuity | Always-current, overwritten |5051Precedence on conflict: `HANDOFF.md` wins for cross-session truth; the active anchor wins for intra-session focus. On **workspace entry**, read `HANDOFF.md` (handoff ladder rung 1) — never resurrect state from a stale anchor alone.5253### Token Budgets5455| Phase | Budget |56|:---|:---|57| Anchor write | ≤15 lines |58| Re-entry block on resume | ≤3 lines (state / reference / next action) |59| Detail loading | On demand — named anchors are read only when their workstream is switched to |6061---6263## Procedure6465### Step 1: Scan Active Session66Identify:671. What was being built / fixed / investigated.682. What decisions were finalized and why.693. What was tried and ruled out.704. The exact next concrete step.7172### Step 2: Write the Anchor73Default focus anchor → `.agents/anchor.md`; parked workstream → `.agents/anchors/<slug>.md`:7475```markdown76# Context Anchor — <ISO timestamp>77workstream: <slug> | branch: <branch>78Client: <codename or "internal">7980## What's True Right Now81- [1-sentence state of active work]82- [Key decision made: what and why]83- [What was tried and ruled out]8485## The Working Reference86> [One actionable sentence.] resume by: [exact re-entry move]8788## Next Action89- [ ] `path/to/file.ts:line` — [Exact atomic action]90```9192### Step 3: Echo the Anchor93Display the anchor to the user for instant alignment.9495### Step 4: Consume Protocol (on resume)961. Re-entry block, ≤3 lines: state / working reference / next action. Nothing else before the first productive action.972. **Freshness check**: header `branch:` must match the current branch and the timestamp must postdate the last commits on it. Mismatched or stale → treat as a hint, re-derive from `HANDOFF.md` or git, and overwrite the anchor with corrected state.983. Resume work; refresh the anchor at the next focus shift.99100### Step 5: Park / Switch / List (Workstream Operations)101- **Park** the current lane: write `.agents/anchors/<slug>.md` with a `resume by:` clause. If the parked workstream is blocked, also emit a `dead-letter` packet.102- **Switch** to `<slug>`: anchor the current focus first (never lose it), then read `.agents/anchors/<slug>.md` and run the Step 4 consume protocol.103- **List**: one line per anchor file — slug, timestamp, next-action summary. No file dumps.104- A workstream parked **across sessions** gets promoted into `HANDOFF.md` In-Flight at close (Step 6), so it survives even if the anchor file is never reopened.105106### Step 6: Close-Out Fold107On session close, the active anchor's surviving content folds into `handoff`'s `HANDOFF.md` (Next Step / In-Flight / Decisions) — handoff owns the flush; the anchor is scratch. At **project close**, archive or wipe client workstream anchors per the confidentiality guard below.108109---110111## Client-Confidentiality Guard112113Anchors capture raw working context and may be committed, synced, or read by contractors:1141151. **Codename rule**: when an NDA applies, `Client:` carries a codename — never legal names, never contract terms, never pricing.1162. **No secrets**: tokens, credentials, and `.env` values never enter an anchor (same rule as every suite artifact).1173. **Close-out hygiene**: archive client anchors to `.agents/archive/` or delete them at project end; stale client anchors left behind are knowledge-hygiene defects the [`audit`](../audit/SKILL.md) skill will flag as orphans.118119---120121## Pitfalls122123- **Verbosity & Noise**: Every line must be load-bearing. Delete filler.124- **Vague Next Actions**: Never write *"continue coding"*; specify the exact file, line number, and function.125- **Missing Decisions Rationale**: Always include the *"why"* for architectural decisions so future agents don't revert them.126- **Stale Anchor Trust**: Never resume from an anchor that fails the freshness check without re-derivation.127- **Confidentiality Leak**: An anchor is an artifact; write it as if the client will read it — because they might.128- **Parallel File Drift**: Two files claiming current state (`anchor.md` and `HANDOFF.md`) is a bug, not a backup — resolve via the layering protocol, never by maintaining both as truth.129130---131132## Verification133134- Confirm the anchor file exists, is ≤15 lines, and is formatted cleanly.135- Confirm Next Action points to an exact concrete file and line number.136- Confirm the header carries `workstream:` and `branch:` for freshness checking.137- Confirm re-entry used the ≤3-line budget and the freshness check ran.138- Confirm no client-identifying or secret material under NDA scope.