Workflow Protocols

End with:

• What failed and why (one paragraph).
• What changed (files + intent).
• What ran (commands + pass/fail).
• If you changed versions, include the before/after.
• If CI-only, include the most likely cause and the exact signal you used.

2. Minidiff Refactor

Use for refactors/migrations/multi-file changes. Enforce incremental steps, tiny diffs, and continuous compilation/tests.

Rules of Engagement

• Split work into mechanical steps that keep the project running between each step.
• Prefer "introduce new path, then switch callers, then delete old path" over a big-bang rewrite.
• Keep diffs reviewable: small patches, isolated concerns.
• Avoid mixed concerns; one refactor axis per step.

Checklist

• Compile/build after each step (or run the closest equivalent).
• Run unit tests for touched areas.
• Use /diff and /review before considering the work "done."
• If there is no test coverage, add a minimal smoke test or runnable check.

Output

Summarize: steps performed, key diffs, tests run, any follow-ups you intentionally deferred.

3. Research Freshness

Use when implementing or debugging anything that depends on external APIs/SDKs/tools and must be current.

Treat this as the "you don't get to guess" workflow.

When to Invoke

Any time you are about to:

• write code that calls an external API or SDK,
• change build tooling, CLIs, or deployment scripts,
• migrate versions,
• rely on a flag, config key, or command you are not 100% certain is current.

Tool Stack (in order)

1. First-party web search — Use first for "what changed recently" and broad recall.
2. Context7 — Use for exact API signatures and versioned docs pages. Prefer official vendor docs and release notes.
3. Exa — Use as a quality override when first-party results are noisy or incomplete.
4. Firecrawl — Use only when you must extract content from JS-heavy sites or long pages. Extract the smallest relevant section.

Anti-Hallucination Rules

• If you cannot verify a symbol/flag/endpoint from docs or real examples, do not use it.
• Prefer "show me the exact snippet / version line" over paraphrase.
• Confirm versions explicitly (package.json, lockfile, --version output, release note date).

Output ("Freshness Receipts")

At the end of the task report, include:

Freshness receipts:
- Source: <doc URL or release note>  Version/date: <...>  Notes: <1 line>
- Source: <...>

4. Context Control

Use when the session is long or tool output is huge. Keep context lean.

Tools to Use Selectively

• Use /compact only when context feels too heavy; do not auto-compact.
• /fork to explore alternatives without polluting the main thread.
• /status to confirm token usage, model, and writable roots.
• Tune tool_output_token_limit if you keep hitting "missing logs" vs "too much noise".

Output Discipline

• Prefer targeted outputs: grep, tail, file+line references.
• If a log is large, summarize and point to the exact command/file/line that matters.
• Keep a short "state of play" paragraph in the transcript when the task spans multiple turns.

Hand-off

When stopping mid-task, leave: current status, what's already verified, the next single command to run.