commit a6aed6b6ce2ee4f51c880849296b128f9abfb5f2 Author: Zhongwei Li Date: Sun Nov 30 08:42:15 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..5dee144 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "plugin-template", + "description": "Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create", + "version": "1.0.0", + "author": { + "name": "Nathan Vale", + "email": "hi@nathanvale.com" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..59fb950 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# plugin-template + +Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create diff --git a/commands/create.md b/commands/create.md new file mode 100644 index 0000000..dcc2ce3 --- /dev/null +++ b/commands/create.md @@ -0,0 +1,203 @@ +--- +description: Create a new plugin scaffold with configurable components +argument-hint: [plugin-name] +model: claude-sonnet-4-5-20250929 +allowed-tools: Bash, Write, Edit, Read, Glob, AskUserQuestion +--- + +# Create New Plugin + +Generate a new plugin scaffold with configurable components following the SideQuest marketplace patterns. + +## Instructions + +You are a plugin scaffolding specialist. Create well-structured Claude Code plugins using the established patterns. + +### Input + +The plugin name is provided as `$1` (or `$ARGUMENTS`). + +### Validation + +1. **Plugin name** must be in kebab-case format: + - Lowercase letters, numbers, and hyphens only + - Must start with a letter + - No consecutive hyphens + - Examples: `my-plugin`, `code-analyzer`, `git-helper` + +2. **Check for conflicts**: + - Verify `plugins/{name}` directory doesn't already exist + - Check marketplace.json for existing plugin with same name + +### Step 1: Component Selection + +Use `AskUserQuestion` to ask the user which components to include: + +**Question**: "Which components should this plugin include?" + +| Component | Description | +|-----------|-------------| +| commands | Slash commands (e.g., `/plugin:action`) | +| mcp-server | MCP server with tools for Claude to call | +| hooks | Event hooks (PostToolUse, PreToolUse, etc.) | +| skills | Autonomous capabilities Claude can invoke | + +Enable multi-select. Default to all components if user doesn't specify. + +### Step 2: Implementation Type Selection + +Use `AskUserQuestion` to ask about implementation type: + +**Question**: "What implementation type?" + +| Type | Description | +|------|-------------| +| Markdown only | Commands/skills are just prompts, no code (stub scripts) | +| TypeScript | Includes CLI tools, utilities, or testable logic (full scripts + src/) | + +**Auto-select TypeScript** if `mcp-server` component was chosen (MCP always needs code). + +### Directory Structure + +Based on selections, create: + +``` +MARKDOWN ONLY: TYPESCRIPT: + +plugins/{name}/ plugins/{name}/ +├── .claude-plugin/ ├── .claude-plugin/ +│ └── plugin.json │ └── plugin.json +├── package.json ←(stubs) ├── package.json ←(full) +├── commands/ ├── tsconfig.json +│ └── sample.md ├── src/ +└── skills/ │ ├── index.ts + └── {name}/ │ └── index.test.ts + └── SKILL.md ├── commands/ + │ └── sample.md + └── skills/ + └── {name}/ + └── SKILL.md +``` + +### Package.json Differences + +**Markdown only (stub scripts):** +```json +{ + "scripts": { + "test": "echo 'No tests'", + "typecheck": "echo 'No typecheck'" + } +} +``` + +**TypeScript (full scripts):** +```json +{ + "scripts": { + "test": "bun test --recursive", + "typecheck": "tsc --noEmit", + "format": "biome format --write .", + "lint": "biome lint .", + "check": "biome check --write ." + }, + "devDependencies": { + "@types/bun": "latest" + } +} +``` + +### Author Information + +Default to git config: +- Name: `git config user.name` +- Email: `git config user.email` + +### File Generation + +Use templates from `$PLUGIN_DIR/src/templates.ts`: + +1. **package.json**: Use `packageJsonForType()` based on implementation type +2. **plugin.json**: Metadata with name, description, version, author +3. **tsconfig.json**: Only for TypeScript type +4. **src/index.ts**: Only for TypeScript type +5. **src/index.test.ts**: Only for TypeScript type +6. **sample.md**: Command with frontmatter and usage example +7. **index.ts**: MCP server using `mcpez` library +8. **.mcp.json**: Server configuration with `${CLAUDE_PLUGIN_ROOT}` +9. **hooks.json**: Empty hooks structure with comments +10. **SKILL.md**: Skill with frontmatter and instructions + +### Marketplace Registration + +After generating files, update `.claude-plugin/marketplace.json`: + +1. Read current marketplace.json +2. Add new plugin entry to the `plugins` array: + ```json + { + "name": "{name}", + "source": "./plugins/{name}", + "description": "{description}", + "version": "1.0.0", + "author": { "name": "{author}" }, + "category": "development", + "keywords": ["{name}"] + } + ``` +3. Write updated marketplace.json + +### Post-Generation Steps + +After creating the plugin: + +1. **Run setup commands** (TypeScript only): + ```bash + cd plugins/{name} && bun install + ``` + +2. **Verify generation** (TypeScript only): + ```bash + bun test --recursive + ``` + +3. **Output summary**: + - List all created files + - Show implementation type chosen + - Show next steps for the user + - Mention `/plugin-template:strip` if they want to remove TypeScript later + - Mention `/plugin-template:upgrade` if they want to add TypeScript later + +### Example Usage + +``` +User: /plugin-template:create my-awesome-plugin +``` + +Expected flow: +1. Validate plugin name +2. Ask which components to include (multi-select) +3. Ask implementation type (unless mcp-server forces TypeScript) +4. Create directory structure +5. Generate all files +6. Register in marketplace +7. Run bun install (if TypeScript) +8. Show summary with next steps + +### Error Handling + +- If plugin name is invalid, explain the format requirements +- If directory already exists, ask user if they want to overwrite +- If marketplace.json update fails, show manual steps +- Always clean up partial generation on failure + +### Important Notes + +- Follow the @sidequest namespace convention +- Use Biome for formatting (configured in root biome.json) +- MCP servers use mcpez library +- All paths should use `${CLAUDE_PLUGIN_ROOT}` for portability +- Generated code should pass typecheck and lint +- If user chose mcp-server, TypeScript is auto-selected + +Now create the plugin scaffold based on the provided name and user preferences. diff --git a/commands/strip.md b/commands/strip.md new file mode 100644 index 0000000..937eea8 --- /dev/null +++ b/commands/strip.md @@ -0,0 +1,151 @@ +--- +description: Strip TypeScript from a plugin, converting it to markdown-only +argument-hint: [plugin-name] +model: claude-sonnet-4-5-20250929 +allowed-tools: Bash, Write, Edit, Read, Glob, AskUserQuestion +--- + +# Strip TypeScript from Plugin + +Remove TypeScript setup from a plugin, converting it to markdown-only mode with stub scripts. + +## Instructions + +You are a plugin maintenance specialist. Safely strip TypeScript from plugins while preserving markdown content. + +### Input + +The plugin name is provided as `$1` (or `$ARGUMENTS`). + +### Validation + +1. **Verify plugin exists**: + - Check `plugins/{name}` directory exists + - If not found, show error and list available plugins + +2. **Verify it's a TypeScript plugin**: + - Check for `tsconfig.json` presence + - If already markdown-only, inform user and exit + +3. **Check for MCP server**: + - If `mcp-servers/` exists, warn user that MCP requires TypeScript + - Ask if they want to proceed anyway (will break MCP functionality) + +### Confirmation Required + +**CRITICAL**: Before making any changes, use `AskUserQuestion`: + +**Question**: "Are you sure you want to strip TypeScript from '{name}'?" + +Show what will be deleted: +- `tsconfig.json` +- `src/` directory (all files) +- `devDependencies` from package.json + +Show what will be modified: +- `package.json` scripts will become stubs + +Options: +1. **Yes, strip TypeScript** - Proceed with removal +2. **No, cancel** - Abort operation + +### Files to Delete + +``` +plugins/{name}/ +├── tsconfig.json ❌ DELETE +└── src/ ❌ DELETE (entire directory) + ├── index.ts ❌ + ├── index.test.ts ❌ + └── ... ❌ +``` + +### Files to Modify + +**package.json** - Replace scripts with stubs: + +Before: +```json +{ + "scripts": { + "test": "bun test --recursive", + "typecheck": "tsc --noEmit", + "format": "biome format --write .", + "lint": "biome lint .", + "check": "biome check --write ." + }, + "devDependencies": { + "@types/bun": "latest" + } +} +``` + +After: +```json +{ + "scripts": { + "test": "echo 'No tests'", + "typecheck": "echo 'No typecheck'" + } +} +``` + +### Execution Steps + +1. **Confirm with user** (AskUserQuestion) +2. **Delete tsconfig.json**: + ```bash + rm plugins/{name}/tsconfig.json + ``` +3. **Delete src/ directory**: + ```bash + rm -rf plugins/{name}/src + ``` +4. **Update package.json**: + - Read current package.json + - Replace scripts with stub versions + - Remove devDependencies + - Write updated package.json + +### Files to Preserve + +Do NOT touch these: +- `.claude-plugin/plugin.json` +- `commands/` directory +- `skills/` directory +- `hooks/` directory +- `mcp-servers/` directory (warn but preserve) +- `.mcp.json` + +### Output Summary + +After stripping: + +``` +Stripped TypeScript from 'my-plugin' + +Deleted: + - tsconfig.json + - src/index.ts + - src/index.test.ts + +Modified: + - package.json (scripts now use stubs) + +Plugin is now markdown-only. + +To add TypeScript back later: + /plugin-template:upgrade my-plugin +``` + +### Error Handling + +- If plugin doesn't exist, list available plugins +- If already markdown-only, inform user (no action needed) +- If deletion fails, show error and rollback suggestions +- If package.json update fails, show manual fix steps + +### Example Usage + +``` +User: /plugin-template:strip my-plugin \ No newline at end of file diff --git a/commands/upgrade.md b/commands/upgrade.md new file mode 100644 index 0000000..9bb4f2b --- /dev/null +++ b/commands/upgrade.md @@ -0,0 +1,166 @@ +--- +description: Add TypeScript setup to a markdown-only plugin +argument-hint: [plugin-name] +model: claude-sonnet-4-5-20250929 +allowed-tools: Bash, Write, Edit, Read, Glob +--- + +# Upgrade Plugin to TypeScript + +Add TypeScript setup to a markdown-only plugin, enabling CLI tools, utilities, and testable logic. + +## Instructions + +You are a plugin maintenance specialist. Safely upgrade plugins to TypeScript while preserving existing content. + +### Input + +The plugin name is provided as `$1` (or `$ARGUMENTS`). + +### Validation + +1. **Verify plugin exists**: + - Check `plugins/{name}` directory exists + - If not found, show error and list available plugins + +2. **Verify it's a markdown-only plugin**: + - Check for absence of `tsconfig.json` + - If already TypeScript, inform user and exit + +### Files to Create + +``` +plugins/{name}/ +├── tsconfig.json ✨ CREATE +└── src/ ✨ CREATE + ├── index.ts ✨ CREATE + └── index.test.ts ✨ CREATE +``` + +### Files to Modify + +**package.json** - Replace stub scripts with full TypeScript scripts: + +Before: +```json +{ + "scripts": { + "test": "echo 'No tests'", + "typecheck": "echo 'No typecheck'" + } +} +``` + +After: +```json +{ + "scripts": { + "test": "bun test --recursive", + "typecheck": "tsc --noEmit", + "format": "biome format --write .", + "format:check": "biome format .", + "lint": "biome lint .", + "check": "biome check --write ." + }, + "devDependencies": { + "@types/bun": "latest" + } +} +``` + +### Template Content + +**tsconfig.json**: +```json +{ + "extends": "../../tsconfig.base.json", + "include": ["src/**/*.ts"], + "exclude": ["**/node_modules/**"] +} +``` + +**src/index.ts** - Use template from `$PLUGIN_DIR/src/templates.ts`: +- Export interface for plugin result type +- Export sample function with JSDoc +- Ready for user to add their logic + +**src/index.test.ts** - Use template from `$PLUGIN_DIR/src/templates.ts`: +- Import from bun:test +- Basic test for sample function +- Ready for user to add more tests + +### Execution Steps + +1. **Create tsconfig.json** +2. **Create src/ directory** +3. **Create src/index.ts** with template +4. **Create src/index.test.ts** with template +5. **Update package.json**: + - Read current package.json + - Add full scripts + - Add devDependencies + - Write updated package.json +6. **Run bun install** +7. **Run tests to verify** + +### Files to Preserve + +Do NOT touch these: +- `.claude-plugin/plugin.json` +- `commands/` directory +- `skills/` directory +- `hooks/` directory +- `mcp-servers/` directory +- `.mcp.json` + +### Post-Upgrade Steps + +```bash +cd plugins/{name} && bun install && bun test +``` + +### Output Summary + +After upgrading: + +``` +Upgraded 'my-plugin' to TypeScript + +Created: + - tsconfig.json + - src/index.ts + - src/index.test.ts + +Modified: + - package.json (full scripts + devDependencies) + +Next steps: + 1. Edit src/index.ts to add your logic + 2. Add tests to src/index.test.ts + 3. Run 'bun test' to verify + +To strip TypeScript later: + /plugin-template:strip my-plugin +``` + +### Error Handling + +- If plugin doesn't exist, list available plugins +- If already TypeScript, inform user (no action needed) +- If file creation fails, show error and cleanup steps +- If bun install fails, show manual steps + +### Example Usage + +``` +User: /plugin-template:upgrade my-plugin +``` + +Expected flow: +1. Validate plugin exists and is markdown-only +2. Create tsconfig.json +3. Create src/index.ts and src/index.test.ts +4. Update package.json with full scripts +5. Run bun install +6. Run bun test to verify +7. Show summary with next steps diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..3bc33fa --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:nathanvale/side-quest-marketplace:plugins/plugin-template", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "633e9c6d1c9b32fbf46dd888d2c76858c447692c", + "treeHash": "216a26a423515e2e0f10dd9404837e5d9b5740afa19eb759c5b53a30cc5e88b2", + "generatedAt": "2025-11-28T10:27:15.901966Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "plugin-template", + "description": "Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5f94094631cc2780027a969b1ce9057e49fb3a6d8fe54b15aca3b0df88e0a820" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "35d46d04fe66d693910cfa5732d6b2c3adee83047b424f55f673a8f7c68c37d1" + }, + { + "path": "commands/strip.md", + "sha256": "7c39453a33a3d5b74ba41d0554e689604ee7986cf8e7c15a84f4947c5350c383" + }, + { + "path": "commands/create.md", + "sha256": "146c1bfcac36d316a1d63ccdf2d1cae87598b57059226ddb41af7f8224996d34" + }, + { + "path": "commands/upgrade.md", + "sha256": "20367b5c9d55a111e6bf96d76c5fb35f674c236749bc3f89eba5e9effa471bc2" + }, + { + "path": "skills/plugin-creator/SKILL.md", + "sha256": "9bd0c4ab9801376f3fb0e505fcf14639be5245aded3e626cddd3bafa893353ff" + } + ], + "dirSha256": "216a26a423515e2e0f10dd9404837e5d9b5740afa19eb759c5b53a30cc5e88b2" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/plugin-creator/SKILL.md b/skills/plugin-creator/SKILL.md new file mode 100644 index 0000000..e334e11 --- /dev/null +++ b/skills/plugin-creator/SKILL.md @@ -0,0 +1,173 @@ +--- +name: plugin-creator +description: Generate new Claude Code plugin scaffolds with configurable components. Use when users want to create a new plugin, start a plugin project, or scaffold plugin components. +--- + +# Plugin Creator + +Generate well-structured Claude Code plugins following SideQuest marketplace patterns. + +## When to Use This Skill + +- User wants to create a new plugin +- User asks about plugin structure or scaffolding +- User mentions "new plugin", "create plugin", "plugin template" +- User wants to add components (commands, MCP server, hooks, skills) to a project + +## Plugin Components + +| Component | Purpose | Files Created | +|-----------|---------|---------------| +| commands | Slash commands users invoke | `commands/*.md` | +| mcp-server | Tools Claude can call | `mcp-servers/{name}/index.ts` | +| hooks | Event handlers | `hooks/hooks.json` | +| skills | Autonomous capabilities | `skills/{name}/SKILL.md` | + +## Implementation Types + +| Type | Use Case | Structure | +|------|----------|-----------| +| Markdown only | Commands/skills are just prompts | No src/, stub scripts | +| TypeScript | CLI tools, utilities, testable logic | src/, full scripts | + +**Note**: MCP server component auto-selects TypeScript (code required). + +## Quick Reference + +### Create Plugin +``` +/plugin-template:create my-plugin +``` +Then select: +1. Components (commands, mcp-server, hooks, skills) +2. Implementation type (markdown or typescript) + +### Strip TypeScript +``` +/plugin-template:strip my-plugin +``` +Converts TypeScript plugin to markdown-only. + +### Upgrade to TypeScript +``` +/plugin-template:upgrade my-plugin +``` +Adds TypeScript setup to markdown-only plugin. + +### Plugin Naming +- Use kebab-case: `my-awesome-plugin` +- Lowercase letters, numbers, hyphens +- Must start with a letter + +### Standard Structures + +**Markdown Only:** +``` +plugins/{name}/ +├── .claude-plugin/plugin.json +├── package.json ←(stub scripts) +├── commands/ +└── skills/{name}/ +``` + +**TypeScript:** +``` +plugins/{name}/ +├── .claude-plugin/plugin.json +├── package.json ←(full scripts) +├── tsconfig.json +├── src/ +│ ├── index.ts +│ └── index.test.ts +├── commands/ +├── mcp-servers/{name}/ +├── hooks/ +└── skills/{name}/ +``` + +## Generation Workflow + +1. **Validate** plugin name (kebab-case, no conflicts) +2. **Ask** which components to include +3. **Create** directory structure +4. **Generate** files from templates +5. **Register** in marketplace.json +6. **Install** dependencies with bun +7. **Verify** with tests + +## Template Patterns + +### package.json +- Namespace: `@sidequest/{name}` +- Scripts: test, typecheck, format, lint, check +- Uses Biome for formatting/linting + +### MCP Server +- Uses `mcpez` library +- Export types for testing +- Zod schemas for input validation + +### Commands +- YAML frontmatter with description +- argument-hint for usage hints +- allowed-tools for security + +### Skills +- YAML frontmatter with name, description +- When to use section +- Quick reference table + +## Post-Generation Steps + +After generating a plugin: + +1. **Navigate**: `cd plugins/{name}` +2. **Install**: `bun install` +3. **Test**: `bun test` +4. **Develop**: Add your logic to the generated files + +## Examples + +### Example 1: Create Simple Command Plugin +``` +User: I want to create a plugin for managing todo lists +Assistant: I'll create a todo-manager plugin for you. +[Uses /plugin-template:create todo-manager] +[Selects commands component] +[Generates scaffold] +``` + +### Example 2: Create Full Plugin with MCP +``` +User: Create a plugin that provides git statistics +Assistant: I'll scaffold a git-stats plugin with an MCP server. +[Uses /plugin-template:create git-stats] +[Selects commands, mcp-server, skills] +[Generates full structure] +``` + +### Example 3: Add Components to Existing Plugin +``` +User: My plugin needs an MCP server now +Assistant: I'll add an MCP server to your existing plugin. +[Creates mcp-servers/{name}/ directory] +[Generates index.ts and package.json] +[Updates .mcp.json] +``` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Name conflict | Choose different name or remove existing | +| Invalid name | Use kebab-case (lowercase, hyphens) | +| Bun install fails | Check network, run manually | +| Tests fail | Check generated code, fix issues | + +## Related Commands + +- `/plugin-template:create [name]` - Create new plugin +- `/plugin-template:strip [name]` - Remove TypeScript, convert to markdown-only +- `/plugin-template:upgrade [name]` - Add TypeScript to markdown-only plugin +- `/git:commit` - Commit your plugin changes +- `/para-brain:capture` - Document plugin ideas