hone

# Hone: Plugin Quality Auditor

You are the Hone orchestrator. When the user runs `/hone <plugin-name>`, execute this 5-phase audit workflow. Follow each phase in order. Do not skip phases.

## Phase 0: Discovery

### Step 1: Parse Plugin Name

Extract the plugin name from `$ARGUMENTS`. If empty or missing, list available plugins by globbing `plugins/*/` and use AskUserQuestion to ask which to audit.

### Step 2: Validate Plugin Exists

Glob for `plugins/$ARGUMENTS/.claude-plugin/plugin.json`. If not found, tell the user the plugin doesn't exist and abort.

### Step 3: Build Plugin Manifest

Run parallel Glob calls to discover all files under `plugins/<name>/`:

| Category | Glob Pattern |
|----------|-------------|
| Metadata | `plugins/<name>/.claude-plugin/*.json` |
| Skills | `plugins/<name>/skills/*/SKILL.md` |
| Skill references | `plugins/<name>/skills/*/references/*.md` |
| Agents | `plugins/<name>/agents/*.md` |
| Hooks | `plugins/<name>/hooks/*.json` |
| MCP | `plugins/<name>/.mcp.json` |
| Docs | `plugins/<name>/README.md` |
| Legacy | `plugins/<name>/commands/*.md` |
| All files | `plugins/<name>/**/*` |

Get line counts for all discovered files via a single Bash call: `wc -l <file1> <file2> ...`

### Step 4: Present Plugin Map

```
=== PLUGIN MAP ===
Plugin: <name> v<version>

Skills (N):
  skills/<skill>/SKILL.md              XX lines
  skills/<skill>/references/foo.md     XX lines
Agents (N):
  agents/<agent>.md                    XX lines
Hooks:
  hooks/hooks.json                     XX lines
Metadata:
  .claude-plugin/plugin.json           XX lines
  README.md                            XX lines
Legacy:
  [commands/ if found]

Total: N files, ~N lines
=== END MAP ===
```

Tell the user:
```
Phase 1: Building expert context from official plugin documentation...
```

---

## Phase 1: Build Expert Context

### Step 1: Load Expert Context

Invoke `/claudit:knowledge ecosystem` to retrieve ecosystem knowledge.

**If the skill runs successfully** (outputs `=== CLAUDIT KNOWLEDGE: ecosystem ===` block):
- Use its output as the ecosystem portion of Expert Context
- Also read `.claude/skills/smith/references/plugin-spec.md` for plugin-authoring-specific detail (plugin.json schema, directory conventions) that the ecosystem cache may not cover at full depth
- Combine both as **Expert Context**
- **Skip to Phase 2**

**If the skill is not available** (claudit not installed — the invocation produces an error, is not recognized as a command, or produces no knowledge output):
- Proceed to Step 2

### Step 2: Dispatch Research Agents (Fallback)

Dispatch **2 research subagents in parallel** using the Task tool. Both must be foreground.

In a single message, dispatch both Task tool calls:

**Research Plugin Spec:**
- `description`: "Research plugin spec docs"
- `subagent_type`: "research-plugin-spec"
- `prompt`: "Build expert knowledge on Claude Code plugin, skill, and sub-agent authoring. Read the baseline from .claude/skills/smith/references/plugin-spec.md first, then fetch official Anthropic documentation. Return structured expert knowledge."

**Research Hooks & MCP:**
- `description`: "Research hooks/MCP docs"
- `subagent_type`: "research-hooks-mcp"
- `prompt`: "Build expert knowledge on Claude Code hooks and MCP server configuration. Fetch official Anthropic documentation. Return structured expert knowledge."

### Assemble Expert Context

Once both return, combine results:

```
=== EXPERT CONTEXT ===

## Plugin System Knowledge
[Results from research-plugin-spec]

## Hooks & MCP Knowledge
[Results from research-hooks-mcp]

=== END EXPERT CONTEXT ===
```

Tell the user:
```
Expert context assembled. Dispatching audit agents...

Phase 2: Analyzing plugin against expert knowledge...
```

---

## Phase 2: Audit

### Step 1: Build Agent Prompts

Read all plugin files before dispatching. Each agent needs:
1. The full Expert Context from Phase 1
2. Its specific file contents (read and include them in the prompt)

### Step 2: Dispatch Audit Agents

Dispatch 5 agents in parallel — the four content audits plus `audit-boundary`. Send all five Task tool calls in a single message.

**audit-structure:**
- `description`: "Audit plugin structure"
- `subagent_type`: "audit-structure"
- `prompt`: Include Expert Context + the full plugin manifest with paths and line counts. The agent checks directory layout, required files, naming conventions.

**audit-skills-agents:**
- `description`: "Audit skills and agents"
- `subagent_type`: "audit-skills-agents"
- `prompt`: Include Expert Context + full contents of all SKILL.md and agent .md files. The agent validates frontmatter, instruction quality, and cross-references.

**audit-metadata-docs:**
- `description`: "Audit metadata and docs"
- `subagent_type`: "audit-metadata-docs"
- `prompt`: Include Expert Context + contents of plugin.json, marketplace.json entry, plugin README.md, and root README.md entry. Also include the plugin directory path for the security scan. The agent checks version consistency, docs quality, and secrets.

**audit-design:**
- `description`: "Audit design quality"
- `subagent_type`: "audit-design"
- `prompt`: Include Expert Context + contents of all plugin files (skills, agents, hooks). The agent assesses over-engineering, hook quality, and design patterns.

**audit-boundary:**
- `description`: "Audit plugin boundary compliance"
- `subagent_type`: "audit-boundary"
- `prompt`: Include Expert Context + plugin name and root path (`plugins/<name>/`). The agent audits surface declaration, silent consumer-artefact mutation, hook invariants, and manifest/script drift.

---

## Phase 3: Scoring

Once all audit agents return, read the scoring rubric:
- Read `${SKILL_ROOT}/references/scoring-rubric.md`

### Score Each Category

Apply the rubric to audit findings. For each applicable category:

1. Start at base score of **100**
2. Apply matching **deductions** from the rubric
3. Apply matching **bonuses** from the rubric
4. Clamp to 0-100 range