docs: document security scope and trust model for workflow commands (#165)

## Summary

Documents the security model and trust requirements for workflow
commands (`/plugin-dev:create-plugin` and
`/plugin-dev:create-marketplace`), providing transparency about their
file system access.

## Problem

Fixes #162

The workflow commands have broad file system access (Write, Edit,
Bash(mkdir:*), etc.) which is correct and necessary for their
scaffolding function. However, security-conscious users had no
documentation explaining what access they're granting or why it's
needed.

## Solution

Implemented Option 3 from the issue (both command files + CLAUDE.md):

### CLAUDE.md - Comprehensive "Workflow Command Security" section

- Explains why broad tool access is needed (creating directories,
generating templates, initializing git)
- Documents security considerations (permission scope, confirmation
prompts, directory verification)
- Contrasts with `/plugin-dev:start` which uses minimal permissions
- Provides guidance for security-sensitive environments

### Command files - Brief security notes

- Added one-sentence security notes to both workflow commands
- Cross-references the detailed documentation in CLAUDE.md
- Doesn't slow down users but provides visibility

### Alternatives Considered

1. **Command files only** - Would duplicate content and increase
maintenance burden
2. **CLAUDE.md only** - Less discoverable for users reading command
files
3. **Both (chosen)** - Best discoverability with single source of truth
for details

## Changes

| File | Change |
|------|--------|
| `CLAUDE.md` | Added "Workflow Command Security" subsection under
Workflow |
| `commands/create-plugin.md` | Added brief security note after Core
Principles |
| `commands/create-marketplace.md` | Added brief security note after
Core Principles |

## Testing

- [x] markdownlint passes on all modified files
- [x] Documentation is accurate (verified against actual frontmatter)
- [x] Cross-references are correct

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjnims

CLAUDE.md

@@ -225,6 +225,36 @@ An 8-phase guided workflow for marketplace creation:
 7. Validation - Run marketplace validators
 8. Testing & Finalization - Test installation and finalize
 
+### Workflow Command Security
+
+The workflow commands (`/plugin-dev:create-plugin` and `/plugin-dev:create-marketplace`) require broad file system access to perform their scaffolding functions:
+
+```yaml
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), ...
+```
+
+**Why this access is needed:**
+
+- Creating plugin directory structures requires `Write` and `Bash(mkdir:*)`
+- Generating manifest files and component templates requires `Write` and `Edit`
+- Initializing git repositories requires `Bash(git init:*)`
+- Exploring existing code for patterns requires `Read`, `Grep`, `Glob`
+
+**Security considerations:**
+
+- These commands can write to any location within the user's permission scope
+- The commands prompt for confirmation before creating structures
+- Review the target directory before starting a workflow
+- In multi-user environments, verify the working directory is appropriate
+
+**Design contrast with `/plugin-dev:start`:**
+
+The entry point command uses `disable-model-invocation: true` and restricts tools to `AskUserQuestion, SlashCommand, TodoWrite` since it only routes to other commands. The workflow commands need broader access because they perform the actual file creation work.
+
+**For security-sensitive environments:**
+
+Review the `allowed-tools` frontmatter in each command file to understand exactly what access is granted. Future Claude Code versions may support path-scoped tool restrictions (e.g., `Write(./plugins/*)`), which would allow tighter scoping.
+
 ## Validation Agents
 
 Use these agents proactively after creating components:

plugins/plugin-dev/commands/create-marketplace.md

@@ -19,6 +19,8 @@ Guide the user through creating a complete plugin marketplace from initial conce
 
 **Initial request:** $ARGUMENTS
 
+**Security note:** This workflow has broad file system access to create marketplace structures. It can write files and create directories within your permission scope. Review the target directory before starting, and see CLAUDE.md "Workflow Command Security" for details.
+
 ---
 
 ## Phase 1: Discovery

plugins/plugin-dev/commands/create-plugin.md

@@ -20,6 +20,8 @@ Guide the user through creating a complete, high-quality Claude Code plugin from
 
 **Initial request:** $ARGUMENTS
 
+**Security note:** This workflow has broad file system access to create plugin structures. It can write files and create directories within your permission scope. Review the target directory before starting, and see CLAUDE.md "Workflow Command Security" for details.
+
 ---
 
 ## Phase 1: Discovery