/vocab-init

name: vocab-init
description: "Create a vocabulary skill for the target project — detect layout, extract literary warrant from the corpus, seed canonical noun/verb tables, write the opt-in stub. Use to start adopting R51 vocabulary discipline in any Claude Code plugin or NL-artifact-heavy repo."
argument-hint: "[path]"
allowed-tools: Read, Write, Glob, Grep, Bash

User Input

$ARGUMENTS

Workflow

Step 1: Resolve target path

Parse `$ARGUMENTS`:

| Input | Behavior | |-------|----------| | (empty) | Target = current working directory | | absolute path | Target = that path | | relative path | Target = `<cwd>/<path>` |

If the target does not exist or is not a directory → "Target path not found: {path}". Stop.

Step 2: Detect plugin name

Read `<target>/.claude-plugin/plugin.json` if it exists. Use the `name` field.

If no manifest exists, use the basename of the target directory (e.g., `/home/dev/my-project/` → `my-project`). Lowercase, replace spaces/underscores with hyphens.

Store as `plugin_name` for the rest of the workflow.

Step 3: Detect layout

Use `Glob` against the target path to check which of these patterns exist; build the scope config from what is present:

| Pattern | Scope | Role | Notes | |---------|-------|------|-------| | `commands/*.md` | internal | verb-filename | Claude Code plugin commands | | `agents/*.md` | internal | noun-filename | Claude Code plugin agents | | `skills/*/*/SKILL.md` | internal | skill-dirname | Plugin-namespaced skills | | `skills/*/SKILL.md` | internal | skill-dirname | Flat skill layout (no plugin namespace) | | `.github/workflows/*.yml` | auditor | verb-filename | Auditor-style workflows; only emit this scope if at least 3 workflow files match `auditor-*` or similar pipeline naming | | `hooks/hooks.json` | internal | (no extraction; presence-only) | Skip in scope config; just note in the skeleton | | `docs/*.md` | internal | headings | Author/user docs | | `analysis/*.md` | internal | headings | Design notes |

Only include scopes where at least one matching file exists. If only `docs/` matches and nothing else, the project has too little NL surface for vocabulary discipline — stop with: "Target has minimal NL surface (only {N} files matched). Vocabulary discipline is premature here. Re-run /nlpm:vocab-init after the artifact set grows."

Step 4: Write the scope config

Create `<target>/analysis/vocab-init-scopes.json` with the detected scopes. Format:

{
  "scopes": {
    "commands": { "scope": "internal", "glob": "commands/*.md", "role": "verb-filename" },
    "agents":   { "scope": "internal", "glob": "agents/*.md",   "role": "noun-filename" }
  }
}

Include only the scopes detected in Step 3.

Step 5: Run the extractor

Find NLPM's plugin root. Two paths to try in order:

1. `${CLAUDE_PLUGIN_ROOT}/analysis/scripts/extract-vocabulary.py` — set when the command runs from within NLPM 2. Fall back to running the script via Bash with the literal path the user has NLPM installed at (probe `~/.claude/plugins/cache/xiaolai/nlpm/*/analysis/scripts/extract-vocabulary.py` with Glob)

Invoke via Bash:

python3 <nlpm-root>/analysis/scripts/extract-vocabulary.py \
  --root <target> \
  --scopes <target>/analysis/vocab-init-scopes.json \
  --out <target>/analysis/vocabulary-extract/

If the script exits non-zero, stop and report the stderr. Otherwise, the extraction wrote three files into `<target>/analysis/vocabulary-extract/`: `summary.md`, `verbs.json`, `nouns.json`.

Step 6: Read the extraction output

Read `<target>/analysis/vocabulary-extract/verbs.json` and `nouns.json`. Extract:

• **Top verbs by total frequency**, partitioned by scope (`internal` / `auditor`). Cut off at frequency ≥ 2, max 15 per scope.
• **Top role-nouns** (from `agents:filename` source) — these become the implementation-role section.
• **Top concept-nouns** (from `skills:dirname` source) — these become artifact-class or domain nouns; adopter decides.
• **Top heading nouns** filtered to single-word repeated proper-cased terms with frequency ≥ 3.

Step 7: Write `skills/<plugin>/vocabulary/SKILL.md` skeleton

Write to `<target>/skills/<plugin_name>/vocabulary/SKILL.md`. If the file already exists, stop with: "Vocabulary skill already exists at {path}. Refusing to overwrite. Re-run after backing up if you want to regenerate."

Use this template (substitute `{plugin_name}` and the extracted term tables):

---
name: vocabulary
description: "Use when writing, reviewing, or naming any {plugin_name} artifact — pick the canonical noun or verb from this registry rather than coining a synonym. Loaded by NLPM's scorer and checker when R51 is enabled in .claude/nlpm.local.md."
version: 0.1.0
---

# {plugin_name} Domain Vocabulary

> The canonical noun-and-verb set for {plugin_name}. Every artifact name, prose description, and rule wording should draw from this registry. Synonyms are flagged by `/nlpm:check` and penalized by `/nlpm:score` when R51 is enabled.
>
> **Status:** seeded by `/nlpm:vocab-init` on {ISO date}. Adopter must prune, define deprecation pairs, and confirm scopes before enforcement. Re-run `analysis/scripts/extract-vocabulary.py` after artifact changes to refresh.

---

## Scopes (P1 of vocabulary-design-principles.md)

{For each detected scope, emit a row with its name, path-prefix, and a one-line description the adopter fills in.}

| Scope | Paths | Description |
|-------|-------|-------------|
| internal | commands/, agents/, skills/, ... | (fill in: what {plugin_name} does to its own artifacts) |
| auditor  | .github/workflows/, auditor/    | (only if detected) |

## Verbs (literary warrant from corpus)

{For each scope, emit a table of extracted verbs. Mark every `deprecated:` column as TODO — adopter fills in.}

### internal scope

| Canonical verb | Frequency | Deprecated synonyms (fill in) |
|----------------|-----------|------------------------------|
| `<verb1>` | <N> | (