chore: update opencode workflow and local config

.config/opencode/AGENTS.md

@@ -4,6 +4,37 @@ type: note
 permalink: opencode-config/agents
 ---
 
+## MCP Code-Indexing Tooling
+
+This repo configures two MCP servers for structural code analysis, registered in `opencode.jsonc`:
+
+| Server | Purpose | Runtime |
+|---|---|---|
+| `ast-grep` | Structural pattern search (AST-level grep) | `uvx` (Python/uv) |
+| `codebase-memory` | Relationship mapping, dependency graphs, blast-radius analysis | `codebase-memory-mcp` binary |
+
+### Prerequisites
+
+- `uvx` available on `PATH` (for `ast-grep`)
+- `codebase-memory-mcp` binary installed and on `PATH`
+
+### Intended usage layering
+
+When analyzing code, prefer tools in this order to minimize overhead:
+
+1. **`ast-grep` first** — structural pattern matching; fastest and most targeted
+2. **`codebase-memory` next** — relationship/blast-radius queries when structure alone is insufficient
+
+### Role allocation (summary)
+
+Per-agent tooling scopes are defined in each agent's guidance file under `agents/`. The high-level allocation:
+
+- **coder**: `ast-grep` only for targeted implementation discovery; avoid `codebase-memory` unless explicitly needed
+- **explorer / researcher / sme / reviewer / tester**: `ast-grep` + `codebase-memory`
+- **critic / designer / librarian**: no code-indexing tooling guidance (use standard tools)
+
+Detailed per-agent behavioral guidance lives in `agents/*.md` files and is not duplicated here.
+
 ## Memory System (Single: basic-memory)
 
 Memory uses one persistent system: **basic-memory**.
@@ -226,6 +257,12 @@ All agents except `lead`, `coder`, and `librarian` are code/source read-only. Ag
 - **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, and subagent delegations alike.
 - Before issuing a sequence of calls, ask: *"Does call B require the result of call A?"* If not, send them together.
 
+## Skill Loading Policy
+
+- Relevant skills are **not optional**. When a task matches a skill's trigger conditions, the lead must load that skill proactively before proceeding with ad hoc execution.
+- Keep skill usage operational: use skills to drive planning, decomposition, debugging, verification, and workflow enforcement instead of relying on generic reminders.
+- `AGENTS.md` defines this as policy; concrete skill trigger rules and enforcement behavior belong in `agents/lead.md`.
+
 ## Human Checkpoint Triggers
 
 When implementing features, the Lead must stop and request explicit user approval before dispatching coder work in these situations:
@@ -313,3 +350,69 @@ Before implementing a feature, the lead must verify its understanding of what th
 When in doubt, ask. A 30-second clarification prevents hours of rework on a fundamentally misunderstood feature.
 
 This complements the Clarification Rule above — that rule covers *ambiguous requirements*; this rule covers *requirements that seem clear but may be misunderstood*. The test: "If I'm wrong about what this means, would I build something completely different?" If yes, verify.
+
+## Proactive Bug Search
+
+Do not limit quality work to the requested diff. The Lead should actively search for likely related defects before and after implementation.
+
+### Minimum proactive bug-hunt pass
+
+For any non-trivial feature or bug fix, inspect nearby risk surfaces in addition to the primary edit point:
+
+- sibling components/handlers in the same feature area
+- duplicated or copy-pasted logic paths
+- recent churn hotspots and TODO/FIXME comments
+- adjacent validation, error handling, empty-state, and permission logic
+- parallel codepaths that should stay behaviorally consistent
+
+This pass is not open-ended archaeology; it is a focused search for bugs that are likely to be coupled to the requested work.
+
+### Discovery and review expectations
+
+- During DISCOVER, include a short "likely bug surfaces" list in the findings when the task is non-trivial.
+- During EXECUTE, require reviewer and tester prompts to check for **related regressions and likely adjacent bugs**, not just direct spec compliance.
+- If proactive bug hunting finds unrelated non-blocking issues, record them in project memory or a backlog note rather than silently folding them into the current task.
+- If a discovered bug is blocking correctness of the current task, treat it as in-scope and explicitly add it to the plan.
+
+### Bug-fix workflow
+
+- Prefer reproduction-first debugging: capture the failing scenario, failing test, or concrete bug path before fixing when feasible.
+- After the fix, re-run the same scenario as the primary verification step.
+- For bug fixes without an automated regression test, document the exact manual reproduction and re-verification path.
+
+## Planning Rigor
+
+Planning should be detailed enough to reduce rework, not just to describe intent.
+
+### Plan minimums
+
+Every non-trivial plan must include, per task or feature:
+
+- the exact user-visible outcome
+- explicit acceptance criteria
+- edge cases and error cases
+- non-goals / what is intentionally out of scope
+- verification method
+- impacted files, systems, or integration surfaces
+- likely breakage or regression surfaces
+
+### Required pre-mortem
+
+Before EXECUTE, add a short pre-mortem section to the plan for non-trivial work:
+
+- what is most likely to fail
+- which assumption is most fragile
+- what would force a redesign or user checkpoint
+- what regression is easiest to miss
+
+The goal is to surface rework risks early, before coder dispatch.
+
+### Retry learning loop
+
+When review or testing fails and a retry is needed, update the plan with a brief note covering:
+
+- what was misunderstood or missed
+- what new constraint was discovered
+- what changed in the execution approach
+
+Do not resend the same plan unchanged after a failed cycle unless the failure was purely mechanical.