---
name: enhance-cross-file
description: "Use when checking cross-file consistency: tools vs frontmatter, agent references, duplicate rules, contradictions."
version: 5.1.0
argument-hint: "[path]"
---

# enhance-cross-file

Analyze cross-file semantic consistency across agents, skills, and workflows.

## Parse Arguments

```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
```

## Purpose

Detects issues that span multiple files - things single-file analysis misses:
- Tools used in prompt body but not declared in frontmatter
- Agent references that don't exist
- Duplicate instructions across files (maintenance burden)
- Contradictory rules (ALWAYS vs NEVER conflicts)
- Orphaned agents not referenced by any workflow
- Skill tool mismatches (allowed-tools vs actual usage)

## Workflow

1. **Run Analyzer** - Execute the JavaScript analyzer to get findings:
   ```bash
   node -e "const a = require('./lib/enhance/cross-file-analyzer.js'); console.log(JSON.stringify(a.analyze('.'), null, 2));"
   ```
   For a specific path: `a.analyze('./plugins/enhance')`

2. **Parse Results** - The analyzer returns JSON with `summary` and `findings`
3. **Report** - Return findings grouped by category

The JavaScript analyzer (`lib/enhance/cross-file-analyzer.js`) implements all cross-file detection. The patterns below are reference documentation.

## Detection Patterns

### 1. Tool Consistency (MEDIUM Certainty)

**tool_not_in_allowed_list**: Tool used in prompt body but not in frontmatter `tools:` list

```yaml
# Frontmatter declares:
tools: Read, Grep

# But body uses:
Use Write({ file_path: "/out" })  # <- Not declared!
```

**skill_tool_mismatch**: Skill's `allowed-tools` doesn't match actual tool usage in skill body

### 2. Workflow Consistency (MEDIUM Certainty)

**missing_workflow_agent**: `subagent_type: "plugin:agent-name"` references non-existent agent

**orphaned_prompt**: Agent file exists but no workflow references it (may be entry point - check manually)

**incomplete_phase_transition**: Workflow phase mentions "Phase N" but no corresponding section

### 3. Instruction Consistency (MEDIUM Certainty)

**duplicate_instructions**: Same MUST/NEVER instruction in 3+ files (extract to shared location)

**contradictory_rules**: One file says "ALWAYS X" while another says "NEVER X"

## Output Format

```markdown
## Cross-File Analysis

**Files Analyzed**: {agents} agents, {skills} skills, {commands} commands

### Tool Consistency ({n})
| Agent | Issue | Fix |
|-------|-------|-----|
| exploration-agent | Uses Write but not in tools list | Add Write to frontmatter |

### Workflow Issues ({n})
| Source | Issue | Fix |
|--------|-------|-----|
| workflow.md | References nonexistent agent | Check spelling or create agent |

### Instruction Consistency ({n})
| Instruction | Files | Fix |
|-------------|-------|-----|
| "NEVER push --force" | 4 files | Extract to CLAUDE.md |
```

## Constraints

- All patterns are MEDIUM certainty (require context)
- No auto-fix (cross-file changes need human review)
- Skip content inside `<bad-example>`, `<bad_example>`, `<badexample>` tags
- Skip content inside code blocks with "bad" in info string
- Entry point agents (orchestrator, validator, discoverer) are not orphaned

## Pattern Statistics

| Category | Patterns | Auto-Fixable |
|----------|----------|--------------|
| Tool Consistency | 2 | 0 |
| Workflow | 3 | 0 |
| Consistency | 3 | 0 |
| **Total** | **8** | **0** |