opencastle 0.10.7 → 0.12.0

package/src/orchestrator/agents/session-guard.agent.md

@@ -30,27 +30,21 @@ Run ALL checks. Report each as ✅ or ❌.
 
 ### 1. Delegation Records
 
-For each delegation in the session summary, verify a matching record exists in `.github/customizations/logs/delegations.ndjson`.
+For each delegation in the session summary, verify a matching record exists in `.github/customizations/logs/events.ndjson` (type=delegation).
 
-**How:** `tail -20 .github/customizations/logs/delegations.ndjson` and match agent + task against the summary.
+**How:** `grep '"type":"delegation"' .github/customizations/logs/events.ndjson | tail -20` and match agent + task against the summary.
 
-**Fix command template:**
-```bash
-(Fill in values from the session summary — see the Team Lead agent file for the canonical JSON schema)
-```
+**Fix:** Load the **observability-logging** skill and run the delegation record command (includes a verify step).
 
 Also verify each delegation record includes `session_id` (branch name). Records missing `session_id` should be flagged.
 
 ### 2. Session Record
 
-Verify a session record exists in `.github/customizations/logs/sessions.ndjson` for the current task.
+Verify a session record exists in `.github/customizations/logs/events.ndjson` (type=session) for the current task.
 
-**How:** `tail -5 .github/customizations/logs/sessions.ndjson` and match task description.
+**How:** `grep '"type":"session"' .github/customizations/logs/events.ndjson | tail -5` and match task description.
 
-**Fix command template:**
-```bash
-echo '{"timestamp":"<ISO>","agent":"Team Lead","model":"<model>","task":"<description>","outcome":"success","duration_min":<N>,"files_changed":<N>,"retries":0,"lessons_added":[],"discoveries":[]}' >> .github/customizations/logs/sessions.ndjson
-```
+**Fix:** Load the **observability-logging** skill and run the session record command (includes a verify step).
 
 ### 3. Lessons Captured
 
@@ -66,17 +60,11 @@ If the session summary lists discovered issues, verify they appear in:
 
 ### 5. Review & Panel Records
 
-If the session summary mentions fast reviews or panel reviews, verify matching records exist in `.github/customizations/logs/reviews.ndjson` and/or `.github/customizations/logs/panels.ndjson`.
+If the session summary mentions fast reviews or panel reviews, verify matching records exist in `.github/customizations/logs/events.ndjson` (type=review and/or type=panel).
 
-**How:** `tail -10 .github/customizations/logs/reviews.ndjson` and/or `tail -5 .github/customizations/logs/panels.ndjson`.
+**How:** `grep '"type":"review"' .github/customizations/logs/events.ndjson | tail -10` and/or `grep '"type":"panel"' .github/customizations/logs/events.ndjson | tail -5`.
 
-**Fix command templates:**
-```bash
-# Fast review
-echo '{"timestamp":"<ISO>","agent":"<reviewed-agent>","reviewer_model":"<model>","verdict":"<pass|fail>","attempt":1,"issues_critical":0,"issues_major":0,"issues_minor":0,"confidence":"high","escalated":false,"duration_sec":N}' >> .github/customizations/logs/reviews.ndjson
-# Panel review
-echo '{"timestamp":"<ISO>","panel_key":"<key>","verdict":"<pass|block>","pass_count":N,"block_count":N,"must_fix":0,"should_fix":0,"reviewer_model":"<model>","weighted":false,"attempt":1,"artifacts_count":N}' >> .github/customizations/logs/panels.ndjson
-```
+**Fix:** Load the **observability-logging** skill and run the review/panel record command as applicable (includes a verify step).
 
 ### 6. Uncommitted Changes
 

package/src/orchestrator/agents/team-lead.agent.md

@@ -99,11 +99,7 @@ Synchronous — blocks until result. Use when:
 
 When calling `runSubagent`, always specify which custom agent to use by name: *"Use the **[Agent Name]** agent to [task]."* This routes the sub-agent to the named agent's model and tools instead of inheriting the Team Lead's Premium model. Include objective, file paths, acceptance criteria, and what to return in the result.
 
-**After each sub-agent returns**, log the delegation record before doing anything else (before review, before verification):
-```bash
-echo '{"timestamp":"<ISO-NOW>","session_id":"<branch>","agent":"<name>","model":"<model>","tier":"<tier>","mechanism":"sub-agent","tracker_issue":"<issue-or-N/A>","outcome":"<success|partial|failed>","retries":0,"phase":<N>,"file_partition":["<paths>"]}' >> .github/customizations/logs/delegations.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/delegations.ndjson`
+**After each sub-agent returns**, log the delegation record before doing anything else (before review, before verification). This is a **⛔ hard gate** — do NOT proceed to review or any other action until the delegation is logged. Use the **observability-logging** skill's delegation record command (`--mechanism sub-agent`).
 
 > **`model` and `tier` must come from the agent registry** — not the Team Lead's own model. Look up the agent in [agent-registry.md](../customizations/agents/agent-registry.md) and use their assigned model and tier. For example, delegating to Developer → `"model":"claude-sonnet-4-6","tier":"quality"`, not the Team Lead's `claude-opus-4-6`.
 
@@ -117,11 +113,7 @@ Async in isolated Git worktree. Use when:
 
 Spawn via: Delegate Session → Background → Select agent → Enter prompt with full self-contained context (they cannot ask follow-ups).
 
-**After spawning**, log the delegation record before spawning another agent or doing any other work:
-```bash
-echo '{"timestamp":"<ISO-NOW>","session_id":"<branch>","agent":"<name>","model":"<model>","tier":"<tier>","mechanism":"background","tracker_issue":"<issue-or-N/A>","outcome":"pending","retries":0,"phase":<N>,"file_partition":["<paths>"]}' >> .github/customizations/logs/delegations.ndjson
-```
-Verify: `tail -1 .github/customizations/logs/delegations.ndjson`
+**After spawning**, log the delegation record before spawning another agent or doing any other work. This is a **⛔ hard gate** — do NOT spawn another agent or proceed until the delegation is logged. Use the **observability-logging** skill's delegation record command (`--mechanism background`, `--outcome pending`).
 
 > **`model` and `tier` must come from the agent registry** — see note in Sub-Agents section above.
 
@@ -133,20 +125,11 @@ Parallel agents must never touch the same files. Map file/directory ownership be
 
 ### Budget
 
-| Tier | Model | Est. Tokens | Est. Duration |
-|------|-------|-------------|---------------|
-| **Economy** | GPT-5 mini | ~5K–15K | 2–5 min |
-| **Fast** | GPT-5.3-Codex | ~10K–40K | 5–15 min |
-| **Standard** | Gemini 3.1 Pro | ~15K–50K | 8–20 min |
-| **Quality** | Claude Sonnet 4.6 | ~30K–80K | 10–25 min |
-| **Premium** | Claude Opus 4.6 | ~50K–150K | 15–30 min |
-
-**Quick reference:** Premium for orchestration, Quality for coding/UI/security/architecture, Standard for analysis/schemas/cost-sensitive, Fast for tests/data/terminal, Economy for docs.
+See the **team-lead-reference** skill for model tiers, token estimates, duration estimates, and budget rules.
 
 - Target 5–7 delegations per session. At 8 → warn. At 9 → checkpoint. At 10+ → STOP and save state.
 - Max 3 delegation attempts per task. After 3 failures → Dead Letter Queue + Architect.
 - Max 3 panel attempts. After 3 BLOCKs → dispute record.
-- Full model routing details in **team-lead-reference** skill.
 
 ### Pre-Delegation Checks
 
@@ -191,7 +174,7 @@ Every delegation prompt must include:
 - **File paths** — exact files to read/modify (the agent's partition)
 - **Acceptance criteria** — from the tracker issue
 - **Patterns** — link to existing code examples
-- **Reminder:** *"Read `LESSONS-LEARNED.md` before starting. Add lessons for any retries. Follow the Discovered Issues Policy."*
+- **Reminder:** *"Read `LESSONS-LEARNED.md` before starting. Use the **self-improvement** skill for any lessons. Follow the Discovered Issues Policy."*
 
 For complex tasks (score 5+), load the **decomposition** skill for the Delegation Spec Template.
 
@@ -205,7 +188,7 @@ For complex tasks (score 5+), load the **decomposition** skill for the Delegatio
 For each task:
   1. Move issue → In Progress
   2. Delegate to specialist agent by name (e.g., "Use the Developer agent to...")
-  3. Log delegation to delegations.ndjson (immediately — verify with `tail -1`)
+  3. Log delegation (⛔ hard gate — do NOT proceed until logged. See the **observability-logging** skill for the command and verify step.)
   4. Monitor for drift (load orchestration-protocols skill)
   5. Verify output:
      - Changed files within partition
@@ -216,7 +199,7 @@ For each task:
      - High-stakes: panel review (load panel-majority-vote skill)
      - Discovered issues tracked (not silently ignored)
      - Lessons captured (if agent retried anything)
-  6. PASS → log review, move issue → Done
+  6. PASS → log review (⛔ hard gate — do NOT proceed until logged), move issue → Done
      FAIL → re-delegate with failure details (max 3 attempts)
 ```
 
@@ -248,16 +231,7 @@ See [shared-delivery-phase.md](../agent-workflows/shared-delivery-phase.md) for
 
 ## Observability
 
-> **⛔ HARD GATE — ALL observability logging is mandatory.** No record type is optional.
-> The Session Guard will flag missing records, but do not rely on it — log inline as you go.
-
-| Record | File | When to log | Timing |
-|--------|------|-------------|--------|
-| **Session** | `sessions.ndjson` | Every session — always | Before yielding to user |
-| **Delegation** | `delegations.ndjson` | After each `runSubagent` / background spawn | **Inline** — immediately after each delegation, before review |
-| **Fast review** | `reviews.ndjson` | After each fast review | After review completes |
-| **Panel** | `panels.ndjson` | After each panel majority vote | After panel completes |
-| **Dispute** | `disputes.ndjson` | After each dispute is created | When dispute is filed |
+> **⛔ HARD GATE — ALL observability logging is mandatory.** Load the **observability-logging** skill for record schemas, logging commands, and the pre-response quality gate.
 
 **Self-check before calling Session Guard:** Count delegations, reviews, and panels performed → count records written → numbers must match for each type. If any count is off, fix it before calling the guard.
 
@@ -273,7 +247,7 @@ See [shared-delivery-phase.md](../agent-workflows/shared-delivery-phase.md) for
 8. Never proceed to dependent task until prerequisite is verified
 9. Sub-agents must not spawn other sub-agents (no recursive delegation)
 10. Never push to `main` — feature branch → PR → human merges
-11. Log every delegation inline — immediately after each `runSubagent` or background spawn, not at session end
+11. Log every delegation and review inline — immediately after each `runSubagent` or background spawn, and after each fast review/panel. This is a hard gate — never proceed without logging first
 12. Steer early — don't wait until an agent finishes to redirect when you spot drift
 13. Never exceed session budget without checkpointing — context degrades after 8+ delegations
 14. Read `LESSONS-LEARNED.md` before delegating — include relevant lessons in prompts

package/src/orchestrator/agents/testing-expert.agent.md

@@ -76,4 +76,4 @@ When completing a task, return a structured summary:
 4. **Edge Cases Tested** — List edge cases covered and any known gaps
 5. **Regressions Checked** — Adjacent features/pages verified to still work
 
-See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).
+See **Base Output Contract** in the **observability-logging** skill for the standard closing items (Discovered Issues + Lessons Applied).

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -56,4 +56,4 @@ When completing a task, return a structured summary:
 3. **Responsive** — Breakpoints tested (per project testing config)
 4. **Visual Evidence** — Screenshots at each breakpoint
 
-See **Base Output Contract** in `general.instructions.md` for the standard closing items (Discovered Issues + Lessons Applied).
+See **Base Output Contract** in the **observability-logging** skill for the standard closing items (Discovered Issues + Lessons Applied).

package/src/orchestrator/customizations/AGENT-PERFORMANCE.md

@@ -6,45 +6,44 @@ Tracks agent success rates across panel reviews and delegated tasks to inform mo
 ## Data Sources
 
 Performance data is collected automatically via NDJSON session logs:
-- **Session data:** `.github/customizations/logs/sessions.ndjson` — appended by every agent after each session
-- **Delegation data:** `.github/customizations/logs/delegations.ndjson` — appended by the Team Lead after each delegation
+- **All events:** `.github/customizations/logs/events.ndjson` — unified log for all event types (sessions, delegations, reviews, panels, disputes), appended via `opencastle log`
 - **Dashboard:** Run `npx opencastle dashboard` to visualize agent performance
 
 ## Quick Queries
 
 ```bash
 # Sessions per agent
-jq -r '.agent' .github/customizations/logs/sessions.ndjson | sort | uniq -c | sort -rn
+jq -r 'select(.type == "session") | .agent' .github/customizations/logs/events.ndjson | sort | uniq -c | sort -rn
 
 # Success rate by agent
-jq -r '[.agent, .outcome] | @tsv' .github/customizations/logs/sessions.ndjson | sort | uniq -c
+jq -r 'select(.type == "session") | [.agent, .outcome] | @tsv' .github/customizations/logs/events.ndjson | sort | uniq -c
 
 # Delegation tier distribution
-jq -r '.tier' .github/customizations/logs/delegations.ndjson | sort | uniq -c
+jq -r 'select(.type == "delegation") | .tier' .github/customizations/logs/events.ndjson | sort | uniq -c
 
 # Failed delegations
-jq 'select(.outcome == "failed")' .github/customizations/logs/delegations.ndjson
+jq 'select(.type == "delegation" and .outcome == "failed")' .github/customizations/logs/events.ndjson
 ```
 
 ## Panel Review Performance
 
-Panel review data is collected automatically via `.github/customizations/logs/panels.ndjson` (appended by the panel runner after each review — see step 7 in the panel majority vote skill).
+Panel review data is collected automatically in `.github/customizations/logs/events.ndjson` with `type: "panel"` (appended by the panel runner after each review — see step 7 in the panel majority vote skill).
 
 ```bash
 # Total panel reviews
-wc -l .github/customizations/logs/panels.ndjson
+jq 'select(.type == "panel")' .github/customizations/logs/events.ndjson | wc -l
 
 # Pass vs block rate
-jq -r '.verdict' .github/customizations/logs/panels.ndjson | sort | uniq -c
+jq -r 'select(.type == "panel") | .verdict' .github/customizations/logs/events.ndjson | sort | uniq -c
 
 # Reviews by panel key
-jq -r '.panel_key' .github/customizations/logs/panels.ndjson | sort | uniq -c | sort -rn
+jq -r 'select(.type == "panel") | .panel_key' .github/customizations/logs/events.ndjson | sort | uniq -c | sort -rn
 
 # Reviews that required retries (attempt > 1)
-jq 'select(.attempt > 1)' .github/customizations/logs/panels.ndjson
+jq 'select(.type == "panel" and .attempt > 1)' .github/customizations/logs/events.ndjson
 
 # Average SHOULD-FIX items per review
-jq -s 'if length > 0 then (map(.should_fix) | add) / length else 0 end' .github/customizations/logs/panels.ndjson
+jq -s '[.[] | select(.type == "panel")] | if length > 0 then (map(.should_fix) | add) / length else 0 end' .github/customizations/logs/events.ndjson
 ```
 
 ## Usage

package/src/orchestrator/customizations/DISPUTES.md

@@ -86,7 +86,7 @@ Which option the Team Lead recommends and why. Include specific next steps:
 
 Links to evidence for human review:
 - Panel report: `.github/customizations/logs/panel/[panel-key].md`
-- Review log entries: `.github/customizations/logs/reviews.ndjson` (filter by issue)
+- Review log entries: `.github/customizations/logs/events.ndjson` (filter by `type: "review"` and issue)
 - Changed files: [list of files in the last attempt]
 - DLQ entry (if any): `DLQ-XXX`
 ```
@@ -112,7 +112,7 @@ Links to evidence for human review:
 ┌──────────────────────────────────────┐
 │  Team Lead creates dispute record     │
 │  Status: pending                      │
-│  Logs to disputes.ndjson              │
+│  Logs to events.ndjson                │
 │  Links to tracker issue               │
 └──────────────┬───────────────────────┘
                │

package/src/orchestrator/customizations/README.md

@@ -50,9 +50,7 @@ Structured machine-readable logs appended automatically by agents during session
 | File | Purpose |
 |------|---------|
 | `README.md` | Schema documentation for the NDJSON log files |
-| `sessions.ndjson` | Structured session log entries |
-| `delegations.ndjson` | Structured delegation log entries |
-| `panels.ndjson` | Structured panel review log entries |
+| `events.ndjson` | All structured event log entries (sessions, delegations, reviews, panels, disputes) |
 
 ## When to update
 

package/src/orchestrator/customizations/logs/README.md

@@ -1,21 +1,64 @@
 # Agent Session Logs
 
-Append-only NDJSON logs for agent activity tracking. Each file stores one JSON object per line.
+Append-only NDJSON log for agent activity tracking. All events are stored in a single file with a `type` discriminator — one JSON object per line.
 
-## Files
+## File
 
-| File | Appended by | Schema |
-|------|------------|--------|
-| `sessions.ndjson` | All agents (via self-improvement protocol) | Session record |
-| `delegations.ndjson` | Team Lead agent | Delegation record |
-| `reviews.ndjson` | Team Lead (via fast-review skill) | Fast review record |
-| `panels.ndjson` | Panel runner (via panel majority vote skill) | Panel record |
-| `disputes.ndjson` | Team Lead (via dispute protocol) | Dispute record |
+| File | Description |
+|------|-------------|
+| `events.ndjson` | All agent events, sorted by timestamp |
 
-## Session Record Schema
+## Type Discriminator
+
+Each record includes a `type` field that identifies the event kind:
+
+| `type` value | Appended by | Description |
+|-------------|-------------|-------------|
+| `session` | All agents (via self-improvement protocol) | Session record |
+| `delegation` | Team Lead agent | Delegation record |
+| `review` | Team Lead (via fast-review skill) | Fast review record |
+| `panel` | Panel runner (via panel majority vote skill) | Panel record |
+| `dispute` | Team Lead (via dispute protocol) | Dispute record |
+
+## CLI Usage
+
+Use `opencastle log` to append events. Agents should call this instead of raw `echo` commands.
+
+```sh
+# Session
+opencastle log --type session --agent Developer --model claude-sonnet-4-6 \
+  --task "PRJ-57: Fix header component" --outcome success --duration_min 12 \
+  --files_changed 5 --retries 0
+
+# Delegation
+opencastle log --type delegation --session_id feat/prj-57 --agent Developer \
+  --model claude-opus-4-6 --tier fast --mechanism sub-agent \
+  --outcome success --phase 2 --file_partition "src/components/,src/pages/"
+
+# Review
+opencastle log --type review --tracker_issue PRJ-42 --agent Developer \
+  --reviewer_model gpt-5-mini --verdict pass --attempt 1 \
+  --issues_critical 0 --issues_major 0 --issues_minor 2 \
+  --confidence high --escalated false
+
+# Panel
+opencastle log --type panel --panel_key auth-review --verdict pass \
+  --pass_count 3 --block_count 0 --must_fix 0 --should_fix 5 \
+  --reviewer_model claude-opus-4-6 --weighted false --attempt 1
+
+# Dispute
+opencastle log --type dispute --dispute_id DSP-001 --tracker_issue PRJ-42 \
+  --priority high --trigger panel-3x-block --implementing_agent Developer \
+  --reviewing_agents "Reviewer,Panel (3x)" --total_attempts 6 --status pending
+```
+
+Run `opencastle log --help` for full options.
+
+## Session Record (`type: "session"`)
 
 ```json
 {
+  "type": "session",
   "timestamp": "2026-02-25T14:30:00Z",
   "agent": "Developer",
   "model": "gpt-5.3-codex",
@@ -32,6 +75,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"session"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `agent` | `string` | Yes | Agent name from the registry |
 | `model` | `string` | Yes | Model used (e.g., `claude-opus-4-6`, `gpt-5.3-codex`) |
@@ -44,10 +88,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `lessons_added` | `string[]` | No | Lesson IDs added (e.g., `["LES-015"]`) |
 | `discoveries` | `string[]` | No | Issues discovered (issue IDs or KNOWN-ISSUES IDs) |
 
-## Delegation Record Schema
+## Delegation Record (`type: "delegation"`)
 
 ```json
 {
+  "type": "delegation",
   "timestamp": "2026-02-25T14:30:00Z",
   "session_id": "feat/prj-57",
   "agent": "Developer",
@@ -64,6 +109,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"delegation"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `session_id` | `string` | Yes | Branch name or feature identifier |
 | `agent` | `string` | Yes | Agent name delegated to |
@@ -76,10 +122,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `phase` | `number` | No | Execution phase number |
 | `file_partition` | `string[]` | No | Directories/files assigned |
 
-## Fast Review Record Schema
+## Fast Review Record (`type: "review"`)
 
 ```json
 {
+  "type": "review",
   "timestamp": "2026-02-28T14:30:00Z",
   "tracker_issue": "PRJ-42",
   "agent": "Developer",
@@ -97,6 +144,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"review"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `tracker_issue` | `string` | No | Issue ID if applicable |
 | `agent` | `string` | Yes | Agent whose output was reviewed |
@@ -110,10 +158,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `escalated` | `boolean` | Yes | Whether this review triggered escalation to panel |
 | `duration_sec` | `number` | No | Review duration in seconds |
 
-## Panel Record Schema
+## Panel Record (`type: "panel"`)
 
 ```json
 {
+  "type": "panel",
   "timestamp": "2026-02-25T14:30:00Z",
   "panel_key": "instruction-refactoring",
   "verdict": "pass",
@@ -132,6 +181,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"panel"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) |
 | `panel_key` | `string` | Yes | Filesystem-safe panel identifier |
 | `verdict` | `string` | Yes | `pass` or `block` |
@@ -146,10 +196,11 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 | `artifacts_count` | `number` | No | Number of artifacts reviewed |
 | `report_path` | `string` | No | Path to the full panel report |
 
-## Dispute Record Schema
+## Dispute Record (`type: "dispute"`)
 
 ```json
 {
+  "type": "dispute",
   "timestamp": "2026-02-28T16:00:00Z",
   "dispute_id": "DSP-001",
   "tracker_issue": "PRJ-42",
@@ -167,6 +218,7 @@ Append-only NDJSON logs for agent activity tracking. Each file stores one JSON o
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `type` | `string` | Yes | Always `"dispute"` |
 | `timestamp` | `string` | Yes | ISO 8601 datetime when dispute was created |
 | `dispute_id` | `string` | Yes | Dispute ID (e.g., `DSP-001`) |
 | `tracker_issue` | `string` | No | Issue ID if applicable |

package/src/orchestrator/instructions/ai-optimization.instructions.md

@@ -1,145 +1,34 @@
 ---
-description: 'AI assistant optimization techniques for efficient context usage and faster responses'
+description: 'AI assistant optimization patterns for efficient context usage and tool calls'
 applyTo: '**'
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
-# AI Assistant Optimization Instructions
+# AI Optimization
 
-## Batch Processing
+Batch independent operations, gather context before acting, and avoid redundant tool calls.
 
-### DO: Batch Independent Operations
+## Key Rules
 
-When gathering context, batch all read operations together in a single parallel call:
+- **Batch independent reads** — parallelize file reads, searches, and error checks in a single call instead of sequentially
+- **Don't batch dependent ops** — if step B needs step A's output, run them sequentially
+- **Gather context first** — read and search before editing; don't act on assumptions
+- **Read strategically** — prefer large ranges (500–2000 lines) over many micro-reads; use `grep_search` to locate, then read targeted ranges
+- **Combine searches** — use regex alternation (`word1|word2|word3`) instead of separate searches
+- **Don't re-read** — if a file or sub-agent result is already in context, use it directly
+- **Verify once per phase** — run tests/lint/errors after a batch of edits, not after each individual change
+- **Scale planning to complexity** — trivial (1–2 files) → act directly; large (10+ files) → full decomposition
+- **Trust sub-agent results** — don't re-search or re-read what a sub-agent already returned
+- **Include file paths in delegation prompts** — saves the sub-agent from wasting context on discovery
 
-```
-Good: Read 3 files + search in parallel → 1 cache-friendly turn
-Bad: Read file 1 → Read file 2 → Read file 3 → 3 separate turns
-```
+## Anti-Patterns
 
-When modifying multiple independent files, batch the edits:
-
-```
-Good: Update 5 config files in parallel
-Bad: Update config 1 → wait → Update config 2 → wait...
-```
-
-### DON'T: Batch Dependent Operations
-
-Don't batch operations where one depends on the output of another:
-
-```
-Bad: Read file + Edit file (need to read first)
-Good: Read file → Analyze → Edit file
-```
-
-## Context Gathering Workflow
-
-Gather all necessary context upfront before analysis/implementation:
-
-```
-Phase 1 (parallel): Read files + search for patterns + check errors
-Phase 2: Analyze and plan
-Phase 3 (parallel if independent): Create/modify files
-Phase 4: Verify (tests, errors, lint)
-```
-
-## Token Reduction Techniques
-
-### Strategic Tool Selection
-
-- Use `grep_search` with `includePattern` to scope searches to specific directories
-- Use `file_search` to find files by pattern before reading
-- Use `semantic_search` for exploring unfamiliar code instead of multiple grep searches
-- Read targeted line ranges when you know approximately where code is
-
-### Avoid Redundant Operations
-
-- Don't re-read files already in context from the same conversation turn
-- Check errors once per phase, not after every single change
-- Don't search for what's already mentioned in context
-- Use regex with alternation (e.g., `word1|word2|word3`) to combine searches
-
-### Read Strategically
-
-- Read larger sections (500-2000 lines) instead of many small reads
-- Use `grep_search` to locate code, then read targeted ranges around it
-- Deduplicate file paths before batching read operations
-
-## Multi-Agent Optimization
-
-### Sub-Agent Context Isolation
-
-Sub-agents run in isolated context windows. Use this to your advantage:
-
-- **Offload exploration** — fire a sub-agent to research a broad question; only the concise result comes back, keeping your primary context clean
-- **Parallel research** — launch multiple sub-agents simultaneously for independent research tasks (e.g., "find all CMS queries" + "list all components using X" at the same time)
-- **Detailed prompts save tokens** — a specific sub-agent prompt avoids the sub-agent doing its own exploratory searches, which would waste its context budget
-
-### Trust Sub-Agent Results
-
-- Don't re-read files a sub-agent just analyzed — trust the returned summary
-- Don't re-search for patterns a sub-agent already identified
-- If a sub-agent returns file paths or code snippets, use them directly
-
-### Background Agents for Long Work
-
-- Delegate tasks expected to take >5 minutes to background agents — they run in parallel without blocking
-- Include **all necessary context** in the delegation prompt (background agents can't ask follow-up questions)
-- Batch independent background delegations together (e.g., launch DB migration + UI components + docs simultaneously)
-
-### Delegation Prompt Efficiency
-
-- Include exact file paths so the delegated agent doesn't waste time searching
-- Reference existing patterns ("follow the structure in `libs/ui-kit/src/lib/Button/`") instead of describing patterns from scratch
-- Set clear scope boundaries ("only modify files under `libs/queries/`") to prevent unnecessary exploration
-
-## Response Optimization
-
-- Provide brief progress updates after batched operations
-- Describe changes concisely instead of repeating large code blocks
-- Plan what context is needed before making tool calls
-- Combine multiple related edits in planning before executing
-
-## Planning Thresholds
-
-Scale planning effort to task complexity — don't over-plan simple work:
-
-| Complexity | Planning | Approach |
-|-----------|----------|----------|
-| Trivial (1-2 files, clear fix) | None | Act directly |
-| Small (3-5 files, single concern) | Mental plan | Brief reasoning, then act |
-| Medium (5-10 files, multiple concerns) | Todo list | Track steps, batch reads |
-| Large (10+ files, cross-cutting) | Full decomposition | Dependency graph, phased execution |
-
-**Stop-and-re-plan trigger:** See the Task Decomposition Protocol in `general.instructions.md` (step 5).
-
-## Test & Build Output Efficiency
-
-- Capture full test/build output **once** per verification phase, not after each micro-change
-- Pipe verbose output through `tail -n 30` or `grep -E 'FAIL|ERROR|PASS'` to reduce noise
-- When tests fail, read the **relevant failure block** — don't re-run the entire suite repeatedly
-
-## README Cascade Reading
-
-When entering an unfamiliar directory, check for a `README.md` before exploring files. READMEs provide architecture context that prevents wasted searches. Priority order:
-1. Project root `README.md` (already covered by instruction files)
-2. Library/app-level `README.md` (e.g., `libs/queries/README.md`)
-3. Feature-level `README.md` (e.g., `libs/data-pipeline/src/lib/scrapers/README.md`)
-
-## Anti-Patterns to Avoid
-
-1. **Micro-reads** — Reading tiny file sections repeatedly
-2. **Sequential searches** — Running searches one at a time when they're independent
-3. **Premature actions** — Acting before gathering sufficient context
-4. **Silent processing** — Batching without progress updates
-5. **Exploratory tool calls** — Making tool calls without a clear plan
-6. **Over-checking** — Validating after every tiny change instead of batching
-7. **Re-gathering delegated context** — Re-reading files or re-searching after a sub-agent already returned the information
-8. **Vague delegation prompts** — Forcing sub-agents to waste their context budget on discovery you already completed
-9. **Sequential delegation** — Running independent sub-agents one-by-one when they could run in parallel
-10. **Leaking secrets** — Printing tokens, keys, or passwords in terminal output or logs (violates Constitution #1)
-11. **Over-planning** — Writing a full decomposition for a 2-file fix (see Planning Thresholds)
+1. **Micro-reads** — reading tiny file sections repeatedly
+2. **Sequential searches** — running independent searches one at a time
+3. **Premature actions** — editing before gathering sufficient context
+4. **Over-checking** — validating after every tiny change instead of batching
+5. **Re-gathering delegated context** — re-reading files a sub-agent already analyzed
+6. **Over-planning** — full decomposition for a 2-file fix
 
 <!-- End of AI Optimization Instructions -->