docs(rules): strengthen context, audit, and review guidance

- Add context engineering rule and handoff bundle template
- Anchor audit report paths to GIT_REPO_ROOT and update self-review docs
- Enforce Cloudflare naming/Zone terminology guidance
- Require concrete performance rewrites during code review
- Add Go DI guidance (manual wiring first; when fx/dig/wire is justified)

Author: d-padmanabhan

README.md

@@ -13,6 +13,7 @@ Comprehensive, battle-tested Cursor IDE rules for professional software engineer
 ### Core Standards
 
 - **[100-core.mdc](rules/100-core.mdc)** - Core coding standards and review guidelines
+- **[015-context-engineering.mdc](rules/015-context-engineering.mdc)** - Context engineering (prompt packing, retrieval, compaction)
 - **[010-workflow.mdc](rules/010-workflow.mdc)** - Development workflow patterns
 - **[020-agent-audit.mdc](rules/020-agent-audit.mdc)** - Agent audit requirements
 - **[130-git.mdc](rules/130-git.mdc)** - Git conventions and commit standards

commands/self-review.md

@@ -160,7 +160,7 @@ Generate a structured review report:
 
 **Generate Audit Report (per `060-agent-audit.mdc`):**
 
-- Write report to `extras/agent_reports/agent_report_<repo>_<branch>_<yyyymmdd_HHMMSS>.md` (if `extras/` exists and is gitignored) or `/tmp/agent_report_<repo>_<branch>_<yyyymmdd_HHMMSS>.md`
+- Ensure `CURSOR_AGENT_CHAT_ID` and `GIT_REPO_ROOT` are set (generate/export if missing), then write report to `<GIT_REPO_ROOT>/extras/agent_reports/agent_report_<repo>_<branch>_<CURSOR_AGENT_CHAT_ID>.md` (if `<GIT_REPO_ROOT>/extras/` exists and is gitignored) or `/tmp/agent_report_<repo>_<branch>_<CURSOR_AGENT_CHAT_ID>.md`
 - Include:
   - Start/end timestamps (local and UTC)
   - Repo name, branch name, `HEAD` SHA

rules/010-workflow.mdc

@@ -250,6 +250,9 @@ Treat recurring mistakes as a signal to improve the system, not just the code:
 
 **IMPORTANT**: Context files are **workspace-specific** and should be in the **extras/** directory in the project root, NOT in the rules directory. This allows each workspace to have its own context while sharing rules via symlinks.
 
+> [!NOTE]
+> For prompt packing, retrieval, and “frequent intentional compaction” patterns, see `015-context-engineering.mdc`.
+
 **Templates:** Copy/paste-ready templates live alongside these rules under `templates/` (e.g., `.cursor/rules/templates/` when installed). In this repo, that path is `rules/templates/`. Copy them into `extras/` when you start a new workspace.
 
 For complex projects, maintain context files in the `extras/` directory:

rules/015-context-engineering.mdc

@@ -0,0 +1,115 @@
+---
+title: Context Engineering for Coding Agents
+description: Prompt packing, retrieval, and compaction patterns for reliable agent work.
+alwaysApply: true
+priority: 15
+---
+
+# Context Engineering for Coding Agents
+
+This rule strengthens agent performance by making context **intentional**, **minimal**, and **reproducible**.
+
+> [!NOTE]
+> This rule complements `010-workflow.mdc` (phases + context files) and `100-core.mdc` (anti-slop guardrails).
+
+---
+
+## Goals
+
+- Keep the agent’s working context small and high-signal
+- Make work resumable across sessions without “reloading the world”
+- Prefer retrieval over memory: fetch exactly what you need, when you need it
+
+---
+
+## Mental Model: Three Layers of Context
+
+- **Working context (volatile)**: what the model sees right now
+- **Repo context (retrievable)**: files, diffs, logs, docs that can be re-read on demand
+- **Durable context (portable)**: short summaries + decisions captured in `extras/` context files
+
+> [!IMPORTANT]
+> If it’s important and will matter later, it must be captured in **durable context**.
+
+---
+
+## Prompt Packing (What to Carry vs. What to Fetch)
+
+### Always carry (paste/recap)
+
+- **Goal**: one sentence
+- **Non-goals**: 1–3 bullets
+- **Constraints**: security, tooling, performance, “don’t refactor”, etc.
+- **Current plan**: 3–7 steps max
+- **Current state**: what’s done / what’s blocked
+- **Critical artifacts**: exact file paths, key identifiers, and error messages (verbatim)
+
+### Never carry (fetch instead)
+
+- Entire files or long logs “just in case”
+- Repeated restatements of requirements
+- Unbounded command output without a reason
+
+---
+
+## Retrieval Strategy (Search → Read Narrow → Cite)
+
+Use a tight loop:
+
+1. **Search** for the smallest set of candidate files (prefer repo-local sources first)
+2. **Read** only the minimal sections needed to decide or implement
+3. **Cite** exact file paths / relevant snippets in your reasoning and updates
+
+> [!TIP]
+> Prefer “retrieve just-in-time” over “load everything up-front”. It is faster and more accurate.
+
+---
+
+## Compaction Strategy (Frequent Intentional Compaction)
+
+After any meaningful milestone (plan approved, a module completed, a bug fixed), compact:
+
+- Update `extras/active-context.md` with:
+  - **Current focus**
+  - **Key decisions** (what and why)
+  - **Blockers** (and next action)
+  - **Context from previous sessions** (only what must persist)
+- Update `extras/progress.md` (if used) with “done/next”
+- Add a **Handoff Bundle** (copy/pasteable) for resuming work
+
+### Handoff Bundle (copy/paste)
+
+```text
+Goal:
+Non-goals:
+Constraints:
+Current state:
+Next 3 actions:
+Key files/paths:
+Key commands + outputs (verbatim, minimal):
+```
+
+---
+
+## Context Reset Triggers (Start Fresh on Purpose)
+
+Prefer a fresh chat/session when:
+
+- Plan is approved and you’re moving into implementation (see `010-workflow.mdc`)
+- The conversation has accumulated long tool output or multiple competing threads
+- You are switching to a new, independent task
+
+When restarting, bring only:
+
+- The approved plan (or the updated `extras/tasks.md`)
+- The Handoff Bundle
+- The minimal file/line references needed to continue
+
+---
+
+## Guardrails (Quality + Security)
+
+- Follow `100-core.mdc` anti-slop rules: be minimal, anchored, specific
+- Never paste secrets into context; redact tokens/keys/passwords
+- Prefer deterministic artifacts: file paths, commands, exit codes, and diffs
+

rules/020-agent-audit.mdc

@@ -87,11 +87,25 @@ Examples (not exhaustive):
 
 For every non-trivial task, write **one** report file at a deterministic path.
 
+### Chat/session identifier (required)
+
+Agents MUST ensure a stable identifier is available for the current chat/session:
+
+- If `CURSOR_AGENT_CHAT_ID` is already set: reuse it
+- Otherwise, generate one and export it once for the session:
+  - `export CURSOR_AGENT_CHAT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"`
+
+### Repo root identifier (required)
+
+Agents MUST resolve the absolute repository root path:
+
+- `export GIT_REPO_ROOT="$(git rev-parse --show-toplevel)"`
+
 ### Path rules
-- If the repo has an `extras/` folder **and** it is gitignored, write to:
-  - `extras/agent_reports/agent_report_<repo>_<branch>_<yyyymmdd_HHMMSS>.md`
+- If `<GIT_REPO_ROOT>/extras/` exists **and** it is gitignored, write to:
+  - `<GIT_REPO_ROOT>/extras/agent_reports/agent_report_<repo>_<branch>_<CURSOR_AGENT_CHAT_ID>.md`
 - Otherwise write to:
-  - `/tmp/agent_report_<repo>_<branch>_<yyyymmdd_HHMMSS>.md`
+  - `/tmp/agent_report_<repo>_<branch>_<CURSOR_AGENT_CHAT_ID>.md`
 
 ### Required contents
 The report MUST include:
@@ -117,13 +131,13 @@ For complex debugging sessions or demos, agents MAY create terminal recordings u
 - When user explicitly requests a recording
 
 **Recording path:**
-- Save to: `extras/agent_reports/recordings/<repo>_<branch>_<yyyymmdd_HHMMSS>.cast`
+- Save to: `<GIT_REPO_ROOT>/extras/agent_reports/recordings/<repo>_<branch>_<CURSOR_AGENT_CHAT_ID>.cast`
 - Reference the recording path in the markdown audit report
 
 **How to record:**
 ```bash
 # Start recording
-asciinema rec -q extras/agent_reports/recordings/session.cast
+asciinema rec -q "<GIT_REPO_ROOT>/extras/agent_reports/recordings/session.cast"
 
 # ... perform commands ...
 

rules/100-core.mdc

@@ -122,10 +122,19 @@ When providing feedback, organize by impact:
 
 1.  **Identify main issues first** before diving into details.
 2.  **Provide specific, actionable suggestions** with working code examples.
+3.  **Look for inefficient logic** and propose a more efficient rewrite when it is safe and justified.
 3.  **Explain the "why"** - what benefit does the change provide?
 4.  **Suggest incremental refactoring** over big-bang rewrites.
 5.  **Preserve existing code** - no placeholders like `// ... (existing code)` or incomplete sections.
 
+> [!IMPORTANT]
+> **Performance rewrite requirement (when reviewing existing code):**
+>
+> If you find clearly inefficient logic (e.g., \(O(n^2)\) loops, N+1 queries, repeated expensive work, unnecessary allocations/parsing), you MUST:
+> - Provide a **concrete improved implementation** (minimal diff) that preserves behavior
+> - State the **expected impact** (time/space/calls) and a **measurement plan** (benchmark/metric)
+> - Prefer the **smallest safe change**; do not “optimize everything” without evidence
+
 ### Anti-slop guardrails (write less, say more)
 
 **Default behavior:** Prefer the smallest change that solves the stated problem. If a change, paragraph, or abstraction doesn’t clearly earn its keep, don’t add it.

rules/210-go.mdc

@@ -384,6 +384,20 @@ import "github.com/lib/timeutils"  // When time package works fine
 //  - It's a well-maintained, stable library
 ```
 
+### Dependency Injection (DI) & Application Wiring
+
+**Default (Go-idiomatic):** Prefer **manual wiring** at the composition root (`cmd/<app>/main.go`). Pass interfaces/structs explicitly via constructors.
+
+Use a DI framework **only when** it clearly reduces risk/complexity, typically:
+- You have a **large dependency graph** changing frequently across teams
+- You need consistent **lifecycle orchestration** (start/stop ordering, cleanup) across modules
+- You run multiple servers/workers in one binary and need coordinated shutdown
+
+If you adopt a DI framework (e.g., `uber/fx`/`dig`, or compile-time `google/wire`):
+- Keep framework usage **at the edges** (composition root); constructors remain plain Go
+- Avoid “service locator” patterns (hidden dependencies); make deps visible in constructors
+- Prefer the **smallest safe change** when refactoring wiring; don’t churn the graph without need
+
 ### Make the Zero Value Useful
 
 **Proverb**: "Make the zero value useful"

rules/400-cloudflare.mdc

@@ -20,6 +20,8 @@ files:
 
 **Guiding Principles:**
 
+- **Naming Consistency**: Never use `CloudFlare` anywhere (code/documentation). If any existing docs contain it, flag and fix to `Cloudflare`
+- **Terminology Consistency**: Do not use the word `Domain` for Cloudflare. Always use `Zone`. If any existing docs mention “Cloudflare Domain”, flag and fix to “Cloudflare Zone”
 - **Performance First**: Order conditions from fast to slow (IP/host/method → path/headers → body/regex)
 - **Security by Default**: Assume hostile intent; validate and sanitize all inputs
 - **Fail Securely**: Block by default, allow explicitly; log everything

rules/templates/active-context.md.template

@@ -20,3 +20,13 @@ Not Started
 
 ## Context from Previous Sessions
 [Any important context that needs to be remembered]
+
+## Handoff Bundle (copy/paste)
+
+Goal:
+Non-goals:
+Constraints:
+Current state:
+Next 3 actions:
+Key files/paths:
+Key commands + outputs (verbatim, minimal):