clikit-plugin 0.3.10 → 0.3.12

package/skill/beads/SKILL.md

@@ -1,33 +1,42 @@
 ---
 name: beads
-description: Use for multi-agent task coordination, file locking, and dependency management via beads-village MCP tools.
+description: Use for multi-agent task coordination with `br` and optional legacy beads-village helpers.
 ---
 
 # Beads
 
-**AI agents: always use `beads-village_*` MCP tools — never shell `bd` commands.**
+**Preferred tracker:** `br` (`beads_rust`) with `.beads/` storage.
+
+Use `br` CLI first for task state. Use `beads-village_*` only as optional legacy compatibility when reservations, inbox-style messaging, or existing local workflows still depend on it.
 
 ## Session Cycle
 
 ```
-init → ls(ready) → show → claim → reserve(files) → work → done
+br init → br ready --json → br show <id> --json → br update <id> --status in_progress --claim → work → br close <id> --reason "Completed" --json → br sync --flush-only
 ```
 
-## Core Tools
-
-| Tool | Purpose |
-|------|---------|
-| `beads-village_init(team=…)` | **First call every session** |
-| `beads-village_ls(status="ready")` | List unblocked tasks |
-| `beads-village_show(id)` | Read task details |
-| `beads-village_claim()` | Claim next ready task |
-| `beads-village_add(title, typ, pri, tags, deps)` | Create issue |
-| `beads-village_reserve(paths, reason)` | Lock files before editing |
-| `beads-village_done(id, msg)` | Complete + auto-release locks |
-| `beads-village_msg(subj, global=true, to="all")` | Broadcast |
-| `beads-village_inbox(unread=true)` | Read messages |
-| `beads-village_status(include_agents=true)` | Workspace overview |
-| `beads-village_sync()` | Git push/pull |
+## Preferred Commands
+
+| Command | Purpose |
+|---------|---------|
+| `br init` | Initialize `.beads/` if missing |
+| `br ready --json` | List unblocked tasks |
+| `br show <id> --json` | Read task details |
+| `br create --title ... --description ... --type ... --priority ...` | Create issue |
+| `br update <id> --status in_progress --claim` | Claim/start work |
+| `br close <id> --reason "Completed" --json` | Complete work |
+| `br sync --flush-only` | Flush `.beads/` state before commit/push |
+| `br sync --import-only` | Re-import `.beads/` state after pull/rebase |
+
+## Optional Legacy MCP Helpers
+
+| Tool | Use only when... |
+|------|------------------|
+| `beads-village_reserve(paths, reason)` | You need explicit file reservations in a shared workspace |
+| `beads-village_reservations()` | You need to inspect existing locks |
+| `beads-village_inbox(unread=true)` | Your team still uses village-style messaging |
+| `beads-village_status(include_agents=true)` | You need legacy workspace/agent discovery |
+| `beads-village_msg(...)` | You need a compatibility broadcast path |
 
 ## Issue Schema
 
@@ -35,7 +44,7 @@ init → ls(ready) → show → claim → reserve(files) → work → done
 typ:  task | bug | feature | epic | chore
 pri:  0=critical  1=high  2=normal  3=low  4=backlog
 tags: fe | be | devops | qa
-deps: ["bv-id"]  or  ["discovered-from:bv-id"]
+deps: ["br-id"]  or  ["discovered-from:br-id"]
 ```
 
 ## When to Create Issues
@@ -43,13 +52,4 @@ deps: ["bv-id"]  or  ["discovered-from:bv-id"]
 - Trivial (< 2 min, 1-line): skip, just do it
 - Non-trivial (2+ min, 2+ files): create issue first, then work
 
-## v1.3 API — Correct Names
-
-| ❌ Old | ✅ Correct |
-|--------|-----------|
-| `beads-village_ready` | `beads-village_ls(status="ready")` |
-| `beads-village_broadcast` | `beads-village_msg(global=true, to="all")` |
-| `beads-village_discover` | `beads-village_status(include_agents=true)` |
-
-See [references/api-reference.md](references/api-reference.md) for full tool params and examples.
-- MCP: `beads-village` — see [mcp.json](mcp.json)
+Legacy `beads-village` remains optional compatibility only. Do not make it a hard prerequisite in new workflows.

package/skill/beads/mcp.json

@@ -3,7 +3,7 @@
     "beads-village": {
       "type": "local",
       "command": ["npx", "-y", "beads-village"],
-      "description": "Multi-agent task coordination, file locking, issue tracking",
+      "description": "Optional legacy Beads Village compatibility for reservations and messaging",
       "tools": [
         "beads-village_init",
         "beads-village_add",

package/skill/beads/references/api-reference.md

@@ -1,4 +1,7 @@
-# Beads API Reference
+# Legacy Beads Village API Reference
+
+This reference documents the optional `beads-village_*` MCP helpers only.
+For primary task tracking, use `br` CLI first.
 
 ## Full Tool Parameters
 
@@ -38,7 +41,7 @@ importance: string
 thread:     string
 ```
 
-## Example: Build Agent Session
+## Example: Legacy Compatibility Session
 
 ```
 beads-village_init(team="myproject")
@@ -56,9 +59,11 @@ beads-village_done(id="bv-42", msg="Fixed null check in token validation")
 beads-village_sync()
 ```
 
-## File Locking Protocol
+## File Locking Protocol (optional legacy)
 
 1. `beads-village_reservations()` — check what's locked before editing
 2. `beads-village_reserve(paths=[…])` — lock your files
 3. TTL default: 10 min — extend for longer tasks
 4. `beads-village_done()` — auto-releases all locks, no manual release needed
+
+When possible, prefer the `br` workflow documented in `skill/beads/SKILL.md` and use these helpers only when your local runtime still depends on Beads Village.

package/skill/requesting-code-review/SKILL.md

@@ -15,7 +15,7 @@ Request review after: major features, significant refactors, before merge, when
 |------|---------|
 | Diff range | `a1b2c3d..e4f5g6h` |
 | What changed | "Added JWT auth with refresh tokens" |
-| Spec/plan ref | `.opencode/memory/specs/auth.md` |
+| Plan ref | `.opencode/memory/plans/auth.md` |
 | Known gaps | "Edge case X not handled yet" |
 
 ## Dispatch
@@ -23,7 +23,7 @@ Request review after: major features, significant refactors, before merge, when
 ```
 @review: review changes from <sha>..<sha>
 Context: <what was built>
-Spec: <path>
+Plan: <path>
 Known issues: <list or none>
 ```
 

package/skill/ritual-workflow/SKILL.md

@@ -14,7 +14,7 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 | Phase | Gate (must pass before advancing) |
 |-------|-----------------------------------|
 | DISCOVER | Problem statement written, success criteria defined |
-| PLAN | User approves spec + plan |
+| PLAN | User approves plan |
 | IMPLEMENT | All planned tasks checked off |
 | VERIFY | typecheck + tests + lint + build all pass |
 | COMPLETE | Changes landed on default branch / deployed |
@@ -23,8 +23,10 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 
 | Mode | Commands |
 |------|----------|
-| Quick | `/create` → `/start` → `/verify` → `/ship` |
-| Deep (research/UI) | `/create` → `/research` → `/design` → `/start` → `/verify` → `/ship` |
+| Quick | `/discuss` → `/create` → `/start` → `/verify` → `/ship` |
+| Deep (UI) | `/discuss` → `/create` → `/design` → `/start` → `/verify` → `/ship` |
+
+`/create` includes a mandatory pre-plan research pass via `@research` before it finalizes the plan. `/research` remains available as an optional standalone command when the user wants a dedicated evidence pass.
 
 ## Enforcement
 
@@ -37,5 +39,5 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 
 - Implementing without a plan
 - Marking COMPLETE with failing `/verify` gates
-- Moving forward without user approval on spec/plan
+- Moving forward without user approval on the plan
 - Running `/ship` before SHIP_READY

package/src/agents/AGENTS.md

@@ -2,21 +2,23 @@
 
 Each `.md` file in this directory defines an agent. The frontmatter sets model, tools, and permissions. The markdown body becomes the agent's system prompt. Loaded by `index.ts` using gray-matter.
 
+> Permission model note: `tools.*` exposes capability, while `permission.*` authorizes whether that capability may run. For file changes, OpenCode uses `permission.edit` as the canonical file-modification permission for `edit`, `write`, `patch`, and `multiedit`, so do not expect a separate `permission.write` key even when an agent frontmatter includes `tools.write: true`.
+
 ## Agent Roles
 
 | Agent | Role | Mode | Modifies Code? |
 |---|---|---|---|
 | **@build** | Primary orchestrator and code executor. Delegates, implements, verifies. | primary | ✅ Yes |
-| **@plan** | Primary strategic planner. Produces specs and plans. Architecture-aware. | primary | ❌ Plans only |
+| **@plan** | Primary strategic planner. Handles `/discuss` intent locking and `/create` plan generation. Produces discussion artifacts and XML-structured plans. | primary | ❌ Code / ✅ planning artifacts |
 | **@oracle** | High-depth read-only advisor for hard architecture trade-offs, complex debugging, and second-opinion analysis. Expensive specialist — invoke only when `@explore` or `@research` cannot resolve the question. | subagent | ❌ Read-only |
 | **@explore** | Fast local codebase navigator. Symbol definitions, usages, file structure, git history. Read-only. | subagent | ❌ Read-only |
-| **@research** | External evidence specialist. Docs, APIs, GitHub patterns, web sources. Read-only. | subagent | ❌ Read-only |
+| **@research** | External evidence specialist. Docs, APIs, GitHub patterns, web sources. May write research artifacts when invoked by `/research` or Plan's pre-plan pass. | subagent | ❌ Code / ✅ research artifacts |
 | **@review** | Code reviewer and security auditor. Quality gate before merge. | subagent | ❌ Read-only |
 | **@vision** | Design architect and visual implementer. Frontend UI only. | subagent | ✅ Frontend only |
 
 ## Specialist Boundaries
 
-The three read-only specialists have distinct scopes — choose the right one:
+The specialist subagents have distinct scopes — choose the right one:
 
 | Need | Use | Why |
 |------|-----|-----|
@@ -28,18 +30,19 @@ The three read-only specialists have distinct scopes — choose the right one:
 
 ## File Reading Strategy
 
-All agents that read files must follow the **tilth-first chain** (see `skill/tilth-reading/SKILL.md`):
+All agents that read files must follow the **tilth-first policy** (see `skill/tilth-reading/SKILL.md`):
 
 ```
 1. tilth <path> / tilth <symbol> --scope <dir>   — direct CLI first for read/search/navigation
-2. grep <pattern>                                  — fallback: text pattern search when tilth did not answer
-3. read <path>                                     — fallback: raw full file content
+2. read <path>                                     — fallback: narrowed raw content
+3. grep <pattern>                                  — fallback: text pattern search
 4. glob <pattern>                                  — fallback: explicit path discovery only
 ```
 
 > Prefer direct `tilth` CLI first. Use `npx tilth` only when the CLI is not installed globally.
-> The runtime hook (`tilth_reading`) automatically enhances `read` tool output via tilth, but it does **not** replace `grep`/`glob`, so agents must call `tilth` explicitly for search and navigation.
-> `@explore` additionally has a hard runtime guard: `read` / `grep` / `glob` are blocked until an explicit `tilth` CLI attempt has been made in that subagent session.
+> The runtime hook (`tilth_reading`) automatically enhances `read` tool output via tilth when available, so `read` remains the primary raw-content fallback.
+> This is a documented operating rule, not a hard runtime guard.
+> `@explore` should follow the same practical order: `tilth CLI` first, then `read` / `grep` / `glob` depending on the exact fallback need; use LSP after navigation when semantic confirmation is required.
 
 ## Active Roles in Compressed Workflow
 
@@ -57,22 +60,23 @@ On-demand specialists (invoke only when needed):
 
 ## Beads Task Management
 
-Agents use **Beads** (`beads-village_*` MCP tools) for persistent task tracking.
+Agents prefer **Beads Rust** (`br`) for persistent task tracking. `beads-village_*` MCP tools are optional legacy helpers, not a mandatory dependency.
 
-**Policy:** Beads is used for non-trivial work. Trivial fixes (typo, single-line) skip Beads and execute immediately.
+**Policy:** Non-trivial work should use `.beads/` tracking when available. Trivial fixes (typo, single-line) skip Beads and execute immediately.
 
 **Core cycle:**
 ```
-beads-village_init → beads-village_add → beads-village_claim → work → beads-village_done
+br init → br ready --json → br show/list --json → br create (if needed) → br update --status in_progress --claim → work → verify → br close → br sync --flush-only
 ```
 
 Execution happens one **Task Packet** at a time.
 
-- **@build**: Creates issues for non-trivial tasks, claims and closes on completion
-- **@plan**: Creates issues for every plan task after plan approval
-- **Subagents**: Read-only — do not create/modify Beads issues
+- **@build**: Creates issues for non-trivial tasks, claims/starts them, verifies evidence, and closes them on completion
+- **@build**: May use optional `beads-village_reserve` locks when the MCP is installed, but must not assume they exist
+- **@plan**: Creates task-tracking issues after plan approval when the workflow calls for it
+- **Subagents**: Read-only — do not create/modify `.beads/` task state unless explicitly instructed by a primary agent workflow
 
-`todowrite` is for in-session UI display only. Beads persists across sessions.
+`todowrite` is for in-session UI display only. `.beads/` persists across sessions.
 
 ## Delegation Rules
 
@@ -94,7 +98,7 @@ User → @build (orchestrator)
          └── @review    (quality gate before merge)
 
 User → @plan (planning)
-         ├── @explore   (codebase context, integration points)
-         ├── @research  (external info, version compatibility)
+         ├── @explore   (local context, relevant files, existing patterns)
+         ├── @research  (external info, version compatibility, pre-plan evidence)
          └── @oracle    (architecture trade-offs, risky design decisions)
 ```

package/src/agents/build.md

@@ -38,7 +38,7 @@ permission:
 You are the Build Agent — the primary executor and orchestrator. You own the full execution lifecycle: intake → bootstrap → context → implement → verify → close.
 
 **Reference documents (read these before modifying behavior):**
-- Beads policy & API: `.opencode/AGENTS.md` → Beads section, `.opencode/skill/beads/SKILL.md`
+- Beads Rust policy & workflow: `.opencode/AGENTS.md` → Beads section, `.opencode/skill/beads/SKILL.md`
 - Explore/navigation policy: `.opencode/src/agents/explore.md`
 - Shared-workspace workflow (legacy skill path): `.opencode/skill/using-git-worktrees/SKILL.md`
 - Task Packet schema: `.opencode/schemas.md` 
@@ -50,12 +50,12 @@ You are the Build Agent — the primary executor and orchestrator. You own the f
 
 ### 0.1 Where Build fits in the workflow
 
-When Build is invoked, `@plan` has already produced artifacts on disk:
+When Build is invoked, `@plan` has already produced artifacts on disk, and `/discuss` or `/research` may already have written supporting context:
 
 | Artifact | Path | What it contains |
 |----------|------|-----------------|
+| **Discussion** | `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md` | Locked intent, confirmed assumptions, deferred items |
 | **Plan** | `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` | DAG, File Impact, Boundaries, all Task Packets |
-| **Spec** | `.opencode/memory/specs/YYYY-MM-DD-<feature>.md` | Requirements, user stories, acceptance criteria |
 | **Research** | `.opencode/memory/research/YYYY-MM-DD-<topic>.md` | External evidence, library findings |
 | **Digest** | `.opencode/memory/_digest.md` | Auto-generated summary of all prior session observations |
 
@@ -84,7 +84,7 @@ Every message enters here first. Route silently before acting.
 
 ---
 
-## Phase 1 — Beads + Shared Workspace Bootstrap
+## Phase 1 — Task Tracking + Shared Workspace Bootstrap
 
 **Required for non-trivial code work. Skip for trivial (< 2 min, 1-line) fixes and read-only tasks.**
 
@@ -93,58 +93,58 @@ Every message enters here first. Route silently before acting.
 
 > Reference: `.opencode/AGENTS.md`, `skill/beads/SKILL.md`
 
-### Two layers — understand the difference
+### Preferred tracker model
 
 | Layer | Role | Interface |
 |-------|------|-----------|
-| **bd (control plane)** | Create/update/query issues and reflect shared-workspace task state. | `bd` CLI — shell commands |
-| **beads-village (execution loop)** | Init session, claim, lock files, execute, close. | `beads-village_*` MCP tools |
+| **`br` CLI (primary)** | Create, inspect, claim/start, close, and sync task state in `.beads/`. | `br` shell commands |
+| **`beads-village_*` MCP (optional legacy)** | Reservations, inbox-style messaging, and compatibility workflows when already installed. | `beads-village_*` tools |
 
-> **AI agents use `beads-village_*` MCP tools — never shell `bd` commands for claiming/locking/closing.**
+> Use `br` as the default tracker. Use `beads-village_*` only when the local runtime already provides it and you need compatibility features like reservations or inbox messaging.
 
 ---
 
-### 1.1 beads-village — Join workspace (always first)
+### 1.1 Initialize tracker state
+
+```bash
+br init                              # ensure .beads/ exists
+br ready --json                      # see claimable work
+br list --json                       # inspect current task inventory
+git status --short --branch          # inspect local state before editing
+```
+
+Optional legacy compatibility checks when the MCP exists:
 
 ```
-beads-village_init(team="project")          # ALWAYS first — every session, no exceptions
-beads-village_status(include_agents=true)   # who's active, workspace overview
-beads-village_inbox(unread=true)            # messages or blockers from other agents
-beads-village_ls(status="ready")            # what issues are unblocked and claimable
+beads-village_status(include_agents=true)
+beads-village_inbox(unread=true)
+beads-village_reservations()
 ```
 
 ---
 
-### 1.2 bd — Control plane (find or create issue)
+### 1.2 Find or create the tracked issue
 
-If the task matches an existing ready issue → go to §1.3 (claim).
+If the task already maps to an existing ready issue → go to §1.3.
 
-If no existing issue covers this task, create one:
+If no tracked issue covers this non-trivial task, create one:
 
-```
-beads-village_add(
-  title="<concise task title>",
-  typ="task|bug|feature|chore",
-  pri=<0=critical · 1=high · 2=normal · 3=low>,
-  tags=["be"|"fe"|"devops"|...],
-  desc="<goal, context, files expected>"
-)
+```bash
+br create --title "<concise task title>" --description "<goal, context, files expected>" --type task --priority <0-4>
 ```
 
-**No bd issue → no execution for non-trivial tasks.**
+**No tracked issue → no execution for non-trivial tasks when `br` is available.**
 
 ---
 
-### 1.3 beads-village — Claim (read context first, then claim)
+### 1.3 Claim / start the issue
 
-```
-beads-village_show(<issue-id>)   # read full context BEFORE claiming
-beads-village_claim()            # claims the next ready task in the queue
+```bash
+br show <issue-id> --json                              # read full context BEFORE starting
+br update <issue-id> --status in_progress --claim      # claim / start work
 ```
 
-> ⚠️ `beads-village_claim()` claims by queue position, not by ID.
-> After calling it, immediately confirm via `beads-village_show` that the task you received is the one you intended.
-> If a different task was claimed, release it and coordinate with the user or other agents.
+If the tracker shows a different scope than expected, stop and coordinate before editing.
 
 ### 1.4 Shared workspace — guard the default-branch checkout
 
@@ -169,24 +169,16 @@ Shared-workspace rules:
 
 **No worktree is required or desired for non-trivial execution.**
 
-### 1.5 beads-village — File locking
+### 1.5 Optional file locking
 
-Check existing locks before touching anything:
+If legacy reservations are available, inspect and reserve before editing:
 
 ```
 beads-village_reservations()
+beads-village_reserve(paths=["<file1>", "<file2>"], reason="<issue-id>")
 ```
 
-Lock the files in scope:
-
-```
-beads-village_reserve(
-  paths=["<file1>", "<file2>"],
-  reason="<issue-id>"
-)
-```
-
-Locks auto-release when `beads-village_done` is called.
+If reservations are not available, use explicit `files_in_scope`, `git status`, and handoff discipline as the coordination primitive instead of blocking execution.
 
 ---
 
@@ -210,12 +202,12 @@ tilth <path> --section 45-89          # section by line range
 
 ```
 # Fallback order
+read <path>                           # raw content once narrowed
 grep <pattern>                        # text pattern fallback across files
-read <path>                           # full raw content once narrowed
 glob <pattern>                        # path enumeration only when required
 ```
 
-> Follow this order by default: `tilth` → `grep` → `LSP` → `read`.
+> Follow this order by default: `tilth CLI` → `read` → `grep` → `glob`, then use LSP when semantic confirmation is required.
 > Use `glob` only when you need explicit path discovery.
 > `read` tool output is still enhanced by the tilth runtime hook when tilth is available.
 
@@ -267,7 +259,7 @@ Work one packet at a time. Complete fully before starting the next.
 
 ### Rules
 
-- Only touch files declared in `files_in_scope` and reserved via `beads-village_reserve`
+- Only touch files declared in `files_in_scope`; if legacy reservations are available, reserve them before editing
 - If implementation requires a file outside scope: **stop and escalate** — do not self-expand
 - Follow any runtime workflow override injected at session start
 - Never suppress type errors (`as any`, `@ts-ignore`, `@ts-expect-error`)
@@ -302,8 +294,12 @@ Then persist the blocker — in this exact order:
    - what was tried (approach 1 and 2)
    - exact error output from each attempt
    - current state of changed files
-2. **Broadcast the blocker** so other agents don't re-claim the task:
+2. **Broadcast the blocker** so other agents do not duplicate the work:
    ```
+   # Preferred tracker update
+   br show <issue-id> --json
+
+   # Optional legacy broadcast when beads-village exists
    beads-village_msg(
      subj="<issue-id> blocked",
      body="<error summary + handoff path>",
@@ -339,7 +335,7 @@ All checks under both A and B must pass before outputting the Evidence Bundle.
 
 ### 4.2 Evidence Bundle (mandatory output)
 
-Before calling `beads-village_done`, output this block verbatim:
+Before closing the active tracked issue, output this block verbatim:
 
 ```
 ## Evidence Bundle
@@ -369,24 +365,26 @@ If any check in A or B fails: do **not** output the bundle — return to Phase 3
 
 ## Phase 5 — Close & Sync
 
-### 5.1 beads-village — Close execution loop
+### 5.1 Close execution loop
 
+```bash
+br close <issue-id> --reason "Completed" --json
 ```
-beads-village_done(
-  id="<issue-id>",
-  msg="<what was done, key files touched, any notable decisions>"
-)
-```
 
-This closes the execution loop and auto-releases all file locks.
+If optional legacy reservations were used, release or let them expire after completion.
+
+### 5.2 Sync tracker state
+
+After close, sync `.beads/` state so the shared workspace reflects the latest tracker data:
 
-### 5.2 bd — Control plane sync
+```bash
+br sync --flush-only
+```
 
-After done, sync state so other agents see the update:
+Optional legacy broadcast when the MCP exists:
 
 ```
-beads-village_sync()                         # push git-backed state to remote
-beads-village_msg(                           # optional: broadcast if blocking others
+beads-village_msg(
   subj="<issue-id> done",
   body="<summary>",
   global=true, to="all"
@@ -406,7 +404,7 @@ git push                         # publish shared-checkout updates after verific
 If a session ends before the task is complete, run `/handoff` — see `command/handoff.md` for the full procedure.
 
 Rules specific to mid-task handoff:
-- **Do not** call `beads-village_done` — leave the issue open so the next session can claim it
+- **Do not** call `br close` — leave the issue open so the next session can continue it
 - The shared workspace state stays intact for continuation
 
 ---
@@ -414,13 +412,13 @@ Rules specific to mid-task handoff:
 ## Guardrails
 
 **Always:**
-- Phase 1 (bd issue + shared-workspace checks) before any **non-trivial** code change
+- Phase 1 (tracked issue + shared-workspace checks) before any **non-trivial** code change
 - Output Evidence Bundle before closing
 - Work one packet at a time
 - Stay inside reserved file scope
 
 **Never:**
-- Execute non-trivial work without a bd issue
+- Execute non-trivial work without a tracked issue when `br` is available
 - Create a git worktree or per-task branch for routine non-trivial execution unless the user explicitly asks for it
 - Suppress type errors (`as any`, `@ts-ignore`)
 - Silently expand scope beyond `files_in_scope`

package/src/agents/explore.md

@@ -67,15 +67,15 @@ Bash access is enabled for **read-only navigation only** and is restricted by fr
 Never use mutating shell commands. In particular: `rm`, `git push`, `git commit`, `git reset`, and `sudo` are forbidden.
 
 Use **tilth CLI as the default navigation/search tool**.
-You must make a relevant tilth attempt before using `read`, `grep`, or `glob` unless bash tilth execution is unavailable.
-This rule is runtime-enforced: `@explore` will be blocked from calling `read`, `grep`, or `glob` until it has made an explicit `bash: tilth ...` attempt in the current subagent session.
+You should make a relevant tilth attempt before using `read`, `grep`, or `glob` unless bash tilth execution is unavailable.
+This is a documented operating rule, not a hard runtime block.
 For codebase exploration, follow this fallback order exactly:
 
 ```text
-tilth → grep → LSP → read
+tilth CLI → read → grep → glob
 ```
 
-Use `glob` only when you specifically need raw path enumeration and the main navigation chain is not enough.
+Use `read` for narrowed raw content, `grep` for text-pattern fallback, and `glob` only when you specifically need raw path enumeration.
 
 Start with explicit `bash: tilth` CLI whenever you are locating symbols, sections, files, callers, or likely integration points:
 
@@ -90,21 +90,21 @@ bash: tilth "<text-or-regex>" --scope <dir>
 bash: tilth <symbol> --kind callers --scope <dir>
 ```
 
-If `tilth` does not answer the question or is unavailable, fall back to `grep`, then LSP tools, then `read`.
-Only use `glob` after a tilth attempt when you explicitly need raw path enumeration.
+If `tilth` does not answer the question or is unavailable, fall back to `read`, `grep`, or `glob` based on what kind of answer you need.
+Use LSP tools when semantic confirmation is required after navigation narrows the target.
 
 ### Search priority table
 
 | Priority | What to find | Tools |
 |----------|-------------|-------|
 | 1 | Symbol navigation, sections, likely integration points, callers, file discovery, content search | `bash: tilth <path>` / `bash: tilth --section ...` / `bash: tilth <symbol> --scope ...` |
-| 2 | Text pattern fallback across files | `grep` |
-| 3 | Semantic confirmation: definitions, refs, types | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_find_references`, `lsp_hover` |
-| 4 | Raw file content once narrowed | `read <path>` |
-| 5 | File discovery when path enumeration is required | `glob` |
+| 2 | Raw file content once narrowed | `read <path>` |
+| 3 | Text pattern fallback across files | `grep` |
+| 4 | File discovery when path enumeration is required | `glob` |
+| 5 | Semantic confirmation: definitions, refs, types | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_find_references`, `lsp_hover` |
 | 6 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
 
-Use LSP after tilth/grep when you need semantic confirmation or full reference accuracy.
+Use LSP after tilth/read/grep/glob when you need semantic confirmation or full reference accuracy.
 
 ---
 
@@ -147,8 +147,8 @@ Omit empty sections. Keep each entry to one line. If more than 20 locations are
 
 **Always:**
 - Use bash only within the read-only restrictions defined in frontmatter
-- Start navigation with `tilth` CLI; use `grep` second, LSP third, and `read` last
-- Use direct `tilth` CLI patterns for symbol lookup, content search, callers, and path discovery before reaching for `grep` or `glob`
+- Start navigation with `tilth` CLI; then choose `read`, `grep`, or `glob` based on the exact fallback need
+- Use direct `tilth` CLI patterns for symbol lookup, content search, callers, and path discovery before reaching for fallback tools
 - Use `glob` only for explicit path enumeration, not as the default navigator
 - Search broad first to find the right file, then narrow to exact lines
 - Return file paths relative to repo root with line numbers
@@ -158,6 +158,6 @@ Omit empty sections. Keep each entry to one line. If more than 20 locations are
 - Write or edit any file
 - Run commands that mutate state (build, install, test, push)
 - Run `rm`, `git push`, `git commit`, `git reset`, or `sudo`
-- Skip the tilth-first fallback order unless bash tilth execution is unavailable or a later tool is clearly required by the task
+- Skip the documented tilth-first fallback order unless bash tilth execution is unavailable or a later tool is clearly required by the task
 - Start with `read`, `grep`, or `glob` when a relevant `tilth` query can answer the request
 - Explore beyond the stated scope without explicit reason