[FEATURE] Allow rules for specific agent types / modes

Preflight Checklist

• [x] I have searched existing issues to verify this is not a duplicate
• [x] This is a single feature request (not multiple combined)

Problem Statement

Rules in .claude/rules/ are always loaded into context regardless of the current execution context. This wastes tokens and can confuse agents that don't need certain rules.

Concrete example: A working-principles.md rule file containing architectural guidelines (KISS, YAGNI, BDD, security-by-design) is essential during planning and QA verification, where decisions are made against these principles. However, during implementation, the coder agent follows a concrete plan and doesn't need 200+ lines of high-level principles in context — they add noise and consume tokens without value.

Today there is no way to express: "Load this rule during planning but not during coding."

Related issues (distinct):

• #27861 — scoped rules by read/write file operations (different axis)
• #8395 — rule propagation to subagents (hierarchy, not conditional activation)
• #25005 / #16352 — on-demand/lazy rule loading (mechanism, not context scoping)

Proposed Solution

Add optional frontmatter fields to .claude/rules/ files for context-based activation:

---
agents: [main, plan, coder]     # activate only for these agent types
modes: [plan, code]              # activate only in these operational modes
---
# Rule content here

Examples:

---
modes: [plan]
---
# Architectural principles — only needed when making design decisions

---
agents: [coder]
---
# Implementation-specific coding standards

Rules without these fields continue to load globally (backward compatible).

Alternative Solutions

1. claudeMdExcludes in settings — static, requires manual toggling per phase, not context-aware
2. Skills as rule carriers — skills can Read rule files on demand, but content is lost on context compaction (not persistent like rules)
3. Embedding principles into Task descriptions — works but forces every planning skill to manually distill and duplicate rule content into tasks
4. Hooks-based injection — could conditionally inject rules, but hooks API lacks the conditional/chainable capabilities needed (#4446)

All workarounds are either manual, fragile, or violate DRY.

Priority

Medium

Feature Category

Configuration and settings

Use Case Example

Step-by-step scenario:

1. User has .claude/rules/general/working-principles.md with modes: [plan] frontmatter
2. User enters plan mode → rule is loaded into context, architect agent uses principles for design decisions
3. User approves plan, exits plan mode → implementation begins
4. Coder agent runs in code mode → working-principles.md is NOT loaded, saving ~800 tokens
5. User invokes /qa → QA skill runs, rule file with modes: [plan, qa] would load for verification

Token impact: In a project with 10+ rule files, 30-40% may be phase-specific. Not loading them during irrelevant phases could save 2,000-4,000 tokens per agent invocation.

Additional Context

• This would complement the existing paths: frontmatter (file-based scoping) with context-based scoping
• The agents: field would be especially valuable for projects using custom subagents (.claude/agents/) where different agents have different responsibilities
• Backward compatible: rules without new frontmatter fields behave exactly as today
• Platform: macOS, Claude Code latest