<!-- BEGIN AGENTSCAFFOLD MANAGED SECTION -->
<!-- Managed by AgentScaffold. The content between these markers is regenerated by `scaffold agents ...`; edits inside the block are overwritten. Everything OUTSIDE the markers is always preserved. Delete both markers to take full ownership of this file (AgentScaffold will then append a fresh block instead of replacing). -->

---
alwaysApply: false
---

# AgentScaffold MCP Rule Routing

This project uses AgentScaffold MCP tools for code intelligence.
Apply MCP-first routing, then fallback to direct reads/search when needed.

## AgentScaffold Tool Selection Policy (MCP-First with Practical Fallback)

You MUST attempt AgentScaffold MCP tools first when the request matches a known intent.
If MCP output is insufficient, direct file reads/search are allowed.

## Required Procedure

1. Classify the request into an AgentScaffold intent.
2. If matched, call the mapped MCP tool first.
3. If the tool fails or is insufficient, fall back to direct reads/search.
4. Before fallback, state one short reason.
5. If intent is unclear, ask one concise clarification question.

## Fallback Is Allowed When

- MCP tool errors or times out.
- Graph/index is unavailable or stale.
- MCP output does not contain the specific detail needed.

## High-Value MCP-First Routes

- Plan review/gap/challenge -> `scaffold_prepare_review` first
- Project status/blockers/next steps -> `scaffold_orient` first
  (use embedded `recommended_actions` / `plan_progress`; do not also
  call `scaffold_next_action` unless those fields are absent)
- Mid-implementation progress / what's left on a plan ->
  `scaffold_diff_plan_vs_code` first
- Decision lineage (ADR/spike/study) -> `scaffold_decision_context` first
- Symbol context/impact -> `scaffold_context` or `scaffold_impact` first
- Empty search/impact/context -> consume inline `why_empty` +
  `grep_fallback` on that same response before extra tool hops

## Call Compression Discipline

Prefer fewer, richer MCP calls. Do not undo fused responses with
redundant follow-ups:

- After `scaffold_orient`, act on `recommended_actions` /
  `plan_progress` / `next_action_focus` instead of calling
  `scaffold_next_action` again.
- After empty `scaffold_search`, `scaffold_impact`, or missing-symbol
  `scaffold_context`, use inline `why_empty` and `grep_fallback`
  instead of immediately calling `scaffold_why_empty` or
  `scaffold_grep_graph`.
- Use standalone `scaffold_why_empty`, `scaffold_grep_graph`, and
  `scaffold_next_action` only when fused fields are missing or
  insufficient.
- Prefer `scaffold_diff_plan_vs_code` over dumping or re-reading the
  full plan file just to check progress.

## Graph Trust Discipline (Avoid Context Blindness)

AgentScaffold's graph is a fast first-pass, not ground truth. Treat its
structural results as evidence to narrow your search, not as proof.

- An empty result (`0 callers`, `0 importers`, no impact) means
  `unconfirmed`, NOT `unused`. Do not conclude code is safe to change
  from an empty graph result alone.
- When search/impact/context returns empty, read `why_empty` and
  `grep_fallback` on that same response before a follow-up tool or
  treating the target as unused.
- Call/import edges exist ONLY for parsed languages (python, javascript,
  typescript, go, rust, java, c, cpp). Markdown, YAML, shell, SQL, JSON,
  and config files are invisible to structural queries. Check the
  `coverage` field on tool output; heed any `caveat`.
- Static analysis cannot see dynamic dispatch, reflection (`getattr`),
  dependency-injection registries, or config/string-driven wiring.
- Before changing safety-critical, cross-language, or dynamically-wired
  code, confirm usage with a text search (grep) in addition to the graph
  (inline `grep_fallback` counts when present).
- If `scaffold_orient` reports low parsed coverage, lean more on grep.

## Multi-Project Workspace Discipline

If the repo is part of a multi-project workspace (a `workspace.yaml` at the
workspace root lists more than one project), several projects share one
graph. Otherwise (a lone repo) this section is a no-op -- there is exactly
one project and nothing is scoped.

- Reads default to the CURRENT project (resolved from the working
  directory): search and governance queries (plans, findings, learnings,
  studies, ADRs) return only this project's knowledge. Plan numbers and
  file paths are NOT unique across projects, so do not assume a result
  belongs to a sibling.
- VIA MCP TOOLS the server runs from one fixed directory and cannot infer
  which project you are editing. On every project-scoped tool call, pass
  `working_path` = the file or dir you are working on; the server resolves
  the owning project from it and scopes the read accordingly. Omitting it
  falls back to the server's default project.
- To look at another project, pass `project=<name>` (tools) / `--project
  <name>` (CLI); to search across all of them, pass `all_projects=true` /
  `--all-projects` (federated results carry a `project` provenance field --
  always report which project a cross-project hit came from).
- `scaffold graph duplicates` surfaces cross-project near-duplicate
  definitions (shared-library reuse candidates); treat hits as advisory.
- Scoping is a relevance boundary within a single trust domain, not a
  security isolation boundary. When unsure which project you are in, run
  `scaffold workspace list`.

## Governance Guardrails (Always Apply)

- Read and follow `AGENTS.md` before every task.
- Do NOT execute plans with incomplete review checklists.
- Do NOT skip dependency verification.
- Do NOT create interfaces without contracts.
- Do NOT modify `docs/ai/system_architecture.md` without human approval.
- Every feature or bug fix MUST include corresponding tests.
- Emojis are forbidden in repository content.
- Follow core standards: `errors`, `logging`, `config`, `testing`.

## Intent Map

### scaffold_prepare_review

Trigger phrases:
- review plan X
- critique plan X
- devil's advocate on plan X
- prepare plan X for review
- let's review plan X
- following the collab protocol for plan X
- pre-reviews for plan X
- all three reviews for plan X
- pressure-test plan X
- stress test plan X
- challenge this plan before coding

### scaffold_prepare_implementation

Trigger phrases:
- implement plan X
- start plan X
- execute plan X
- begin implementation of plan X
- what do I need to implement plan X
- prep for implementing plan X
- approved to go on plan X
- begin implementation per collab protocol
- start building plan X
- begin building plan X
- ready to build plan X

### scaffold_compare_plans

Trigger phrases:
- does plan X conflict with plan Y
- overlap between plans
- check plan X vs plan Y
- compare plans X and Y
- any overlapping concerns between plan X and Y
- do plans X and Y overlap
- check for conflicts between X and Y
- do these plans step on each other
- are these plans stepping on each other

### scaffold_staleness_check

Trigger phrases:
- is plan X stale
- is this plan still valid
- is plan X still valid
- staleness review on plan X
- has anything changed since plan X
- does plan X need updating
- check if plan X needs refactoring
- has this plan gone out of date
- is this plan out of date

### scaffold_prepare_rewrite

Trigger phrases:
- rewrite plan X
- update plan X
- expand plan X
- refresh plan X with current state
- revise plan X
- update plan X to use Y

### scaffold_prepare_retro

Trigger phrases:
- retro on plan X
- retrospective for plan X
- post-implementation review
- quant architect review on plan X
- post implementation review and retro for plan X
- share the review and retro
- post implementation retrospective
- let's do the post-implementation retrospective

### scaffold_orient

Note: Primary session router. Prefer its `recommended_actions`, `plan_progress`, and `next_action_focus` over a follow-up `scaffold_next_action` call.

Trigger phrases:
- where did we leave off
- what's the current state
- what's blocked
- what are the next steps
- session start
- where are we
- what should I work on now
- what are the next priorities
- latest blockers and what's next
- current blockers and next steps

### scaffold_find_studies

Trigger phrases:
- any studies on X
- experiments related to X
- what did we test for X
- show me studies about X
- prior experiments about X
- any prior experiments about X

### scaffold_prior_experiments

Trigger phrases:
- has this been tested
- prior experiments for plan X
- any evidence for this approach
- what experiments relate to plan X

### scaffold_find_adrs

Trigger phrases:
- any ADRs about X
- what architectural decisions cover X
- show me ADRs related to storage
- which ADR governs X
- what ADR blocks plan X
- the ADR blocking them
- which architecture decision governs X
- what architecture decision governs X

### scaffold_decision_context

Trigger phrases:
- what's the decision history for plan X
- was there a spike for plan X
- what ADR governs plan X
- show me the full decision chain for plan X
- what was the original intent for plan X
- trace the decisions for plan X
- trace the rationale chain for plan X
- why was this plan decided this way

### scaffold_search

Note: On empty results, read inline `why_empty` and `grep_fallback` before calling `scaffold_why_empty` or `scaffold_grep_graph`.

Trigger phrases:
- search the workspace for X
- search across all projects for X
- find code related to X
- find duplicates across projects
- look for duplicate code in the workspace
- search all projects for similar implementations
- look across every project for similar implementations

### scaffold_record_finding

Trigger phrases:
- record finding
- log finding
- note a finding
- discovered issue in plan
- review found an issue
- I found an issue in plan X
- log this review finding
- capture this finding

### scaffold_resolve_finding

Trigger phrases:
- mark finding resolved
- close finding
- fix has been addressed
- resolved finding
- finding has been closed
- mark this issue as resolved
- resolve this finding
- finding is resolved

### scaffold_record_findings_batch

Trigger phrases:
- record all findings
- log all findings
- record findings batch
- record multiple findings
- save all review findings
- batch record findings
- record findings in the plan appendix
- log these findings
- capture all findings
- write all findings to graph

### scaffold_record_backlog_item

Trigger phrases:
- add backlog item
- record backlog item
- log backlog item
- add to backlog
- create backlog item
- note backlog item
- track backlog item

### scaffold_resolve_backlog_item

Trigger phrases:
- resolve backlog item
- close backlog item
- mark backlog item done
- complete backlog item
- archive backlog item
- mark backlog item complete
- backlog item is done

### scaffold_begin_plan

Trigger phrases:
- begin plan X
- start plan X
- kick off plan X
- let's start implementation of plan X
- run the pre-reviews for plan X
- follow the collab protocol to begin plan X
- pre-review chain for plan X
- run begin plan for plan X

### scaffold_complete_plan

Trigger phrases:
- wrap up plan X
- complete plan X
- post-implementation for plan X
- close out plan X
- run the retro for plan X
- follow the collab protocol to close plan X
- run complete plan for plan X
- finish plan X

### scaffold_diff_plan_vs_code

Note: Preferred mid-implementation progress check (next unchecked step, disk/graph presence, symbol spot-checks). Prefer over re-reading the full plan body for status.

Trigger phrases:
- diff plan X vs code
- what's left on plan X
- plan vs implementation for plan X
- which planned files are missing
- mid-implementation progress on plan X

### scaffold_grep_graph

Note: Fallback only. Prefer inline `grep_fallback` on empty search/impact when present; otherwise use for low coverage / non-parsed languages.

Trigger phrases:
- grep the workspace for X
- ripgrep for X in the project
- text search the repo for X
- scaffold grep for X

### scaffold_why_empty

Note: Fallback only. Prefer inline `why_empty` on empty search/impact/context responses when present.

Trigger phrases:
- why is search empty
- why no callers
- why empty impact
- explain empty scaffold result

### scaffold_next_action

Note: Fallback only. Prefer `recommended_actions` from `scaffold_orient` when present.

Trigger phrases:
- what should I do next
- next action
- what tool should I call next
- route me to the next step

<!-- END AGENTSCAFFOLD MANAGED SECTION -->

## Enforcement Rules

- **PostToolUse** (Edit/Write): run `scaffold index --incremental` to keep the knowledge graph fresh.
- **SessionStart**: run `scaffold orient` to load current context.
