Plugin-declared CLAUDE.md fragments for agent guidance

[albertgwo]

Problem

Plugins that modify agent behavior (hooks, validators, custom tools) have no mechanism to inject guidance into the user's CLAUDE.md that teaches agents how to work with them correctly.

Concrete example: The bash-validator plugin gates dangerous bash commands behind approval prompts. It has specific patterns agents should follow (use jq not python3 -c for JSON formatting, use the Write tool not cat > file << EOF, etc.). But agents never learn these rules because the guidance lives only in the plugin's skill files, which are loaded on-demand, not injected into every session.

Observed impact (from 11 days of rejection log analysis):

• 39% of all validator rejections are retry storms: agents retry blocked patterns because the rejection message gives no guidance on alternatives
• 5% are tool misuse (cat > instead of Write) that agents would avoid if they knew the rule
• 13% are inline analysis scripts (python3 -c) where a plugin skill exists to guide the agent toward approved patterns, but agents don't know the skill exists

The upstream cause is the same in each case: plugin knowledge doesn't reach agents unless a skill is explicitly invoked.

Proposed Solution

Allow plugins to declare CLAUDE.md fragments in their plugin.json manifest. These fragments would be assembled into the user's CLAUDE.md during claude-sync sync operations, alongside the existing fragment assembly from ~/.claude-sync/claude-md/.

Plugin manifest addition

{
  "name": "bash-validator",
  "claude_md": [
    {
      "key": "bash-validator-guidance",
      "section": "## Bash Commands",
      "content_file": "claude-md/guidance.md",
      "priority": 50
    }
  ]
}

Behavior

1. During sync, claude-sync reads claude_md entries from enabled plugins
2. Each entry's content_file (relative to plugin root) is read and assembled as a fragment
3. Fragments are keyed under the plugin's namespace (e.g., plugin:bash-validator::bash-validator-guidance)
4. Standard fragment ordering and conflict resolution applies
5. Users can override or disable specific plugin fragments via the existing fragment system

Design considerations

• Opt-in for users: Plugin fragments should be visible in claude-sync status and removable per-project if unwanted.
• Scoping: Some plugins are global; some are project-specific. Fragment injection should respect the same scoping.
• Staleness: When a plugin is uninstalled, its fragments should be cleaned up on next sync.
• Size budget: Plugin fragments should be concise (guidance, not documentation). Consider enforcing a size limit per plugin.

Alternatives Considered

1. Hookify rules that inject system messages on rejection. This addresses retry storms but not the upstream knowledge gap. Agents still don't know the rules until they break them.
2. Adding guidance to the Bash tool description. This is where the "prefer dedicated tools" instruction already lives. It's insufficient: subagents may receive condensed prompts, and the instruction competes with many other tool-description paragraphs.
3. Plugin-specific CLAUDE.md files in the plugin directory. These exist (the bash-validator has one), but they're only loaded if the agent happens to be working in the plugin directory. They don't propagate to project-level sessions.

Related Issues

• claude-sync plugin not auto-installed — SessionStart/SessionEnd hooks never fire #26 (claude-sync plugin not auto-installed): If the sync plugin isn't running, no fragment assembly happens at all. This feature depends on claude-sync plugin not auto-installed — SessionStart/SessionEnd hooks never fire #26 being resolved.