@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/plugin-dev/commands/create-plugin.md

@@ -0,0 +1,498 @@
+---
+description: Create plugins with guided 8-phase workflow
+argument-hint: [plugin-description]
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(mkdir:*), Bash(git init:*), TaskCreate, TaskGet, TaskUpdate, TaskList, AskUserQuestion, Skill, Task
+model: sonnet
+---
+
+# Plugin Creation Workflow
+
+Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
+
+## Core Principles
+
+- **Ask clarifying questions**: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
+- **Load relevant skills**: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
+- **Use specialized agents**: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
+- **Follow best practices**: Apply patterns from plugin-dev's own implementation
+- **Progressive disclosure**: Create lean skills with references/examples
+- **Use Task tools**: Track all progress throughout all phases using TaskCreate, TaskUpdate, and TaskList
+
+**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 [docs/workflow-security.md](../../../docs/workflow-security.md) for details.
+
+---
+
+## Phase 1: Discovery
+
+**Goal**: Understand what plugin needs to be built and what problem it solves
+
+**Actions**:
+
+1. Create task list with all 8 phases
+2. If plugin purpose is clear from arguments:
+   - Summarize understanding
+   - Identify plugin type (integration, workflow, analysis, toolkit, etc.)
+3. If plugin purpose is unclear, ask user:
+   - What problem does this plugin solve?
+   - Who will use it and when?
+   - What should it do?
+   - Any similar plugins to reference?
+4. Summarize understanding and confirm with user before proceeding
+
+**Output**: Clear statement of plugin purpose and target users
+
+---
+
+## Phase 2: Component Planning
+
+**Goal**: Determine what plugin components are needed
+
+**MUST load plugin-structure skill** using Skill tool before this phase.
+
+**Actions**:
+
+1. Load plugin-structure skill to understand component types
+2. Analyze plugin requirements and determine needed components:
+   - **Skills**: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
+   - **Commands**: User-initiated actions? (deploy, configure, analyze)
+   - **Agents**: Autonomous tasks? (validation, generation, analysis)
+   - **Hooks**: Event-driven automation? (validation, notifications)
+   - **MCP**: External service integration? (databases, APIs)
+   - **LSP**: Code intelligence? (go-to-definition, find references)
+   - **Settings**: User configuration? (.local.md files)
+3. For each component type needed, identify:
+   - How many of each type
+   - What each one does
+   - Rough triggering/usage patterns
+4. Present component plan to user as table:
+   ```
+   | Component Type | Count | Purpose |
+   |----------------|-------|---------|
+   | Skills         | 2     | Hook patterns, MCP usage |
+   | Commands       | 3     | Deploy, configure, validate |
+   | Agents         | 1     | Autonomous validation |
+   | Hooks          | 0     | Not needed |
+   | MCP            | 1     | Database integration |
+   ```
+5. Get user confirmation or adjustments
+
+**Output**: Confirmed list of components to create
+
+---
+
+## Phase 3: Detailed Design & Clarifying Questions
+
+**Goal**: Specify each component in detail and resolve all ambiguities
+
+**CRITICAL**: This is one of the most important phases. DO NOT SKIP.
+
+**Actions**:
+
+1. For each component in the plan, identify underspecified aspects:
+   - **Skills**: What triggers them? What knowledge do they provide? How detailed?
+   - **Commands**: What arguments? What tools? Interactive or automated?
+   - **Agents**: When to trigger (proactive/reactive)? What tools? Output format?
+   - **Hooks**: Which events? Prompt or command based? Validation criteria?
+   - **MCP**: What server type? Authentication? Which tools?
+   - **Settings**: What fields? Required vs optional? Defaults?
+
+2. **Present all questions to user in organized sections** (one section per component type)
+
+3. **Wait for answers before proceeding to implementation**
+
+4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
+
+**Example questions for a skill**:
+
+- What specific user queries should trigger this skill?
+- Should it include utility scripts? What functionality?
+- How detailed should the core SKILL.md be vs references/?
+- Any real-world examples to include?
+
+**Example questions for an agent**:
+
+- Should this agent trigger proactively after certain actions, or only when explicitly requested?
+- What tools does it need (Read, Write, Bash, etc.)?
+- What should the output format be?
+- Any specific quality standards to enforce?
+
+**Output**: Detailed specification for each component
+
+---
+
+## Phase 4: Plugin Structure Creation
+
+**Goal**: Create plugin directory structure and manifest
+
+**Actions**:
+
+1. Determine plugin name (kebab-case, descriptive)
+2. Choose plugin location:
+   - Ask user: "Where should I create the plugin?"
+   - Offer options: current directory, ../new-plugin-name, custom path
+3. Create directory structure using bash:
+   ```bash
+   mkdir -p plugin-name/.agents
+   mkdir -p plugin-name/skills     # if needed
+   mkdir -p plugin-name/commands   # if needed
+   mkdir -p plugin-name/agents     # if needed
+   mkdir -p plugin-name/hooks      # if needed
+   ```
+4. Create **canonical** `.agents/plugin.json` (see `plugin-structure` skill and `spec/enact.json`):
+   ```json
+   {
+     "name": "plugin-name",
+     "version": "0.1.0",
+     "description": "[brief description]",
+     "targets": ["claude", "codex", "cursor"],
+     "skills": "./skills/",
+     "commands": "./commands/",
+     "hooks": "./hooks/hooks.json",
+     "mcpServers": "./.mcp.json",
+     "author": { "name": "[author]" }
+   }
+   ```
+5. Sync and validate host manifests:
+   ```bash
+   cd /path/to/plugin-name
+   enact-extensions sync
+   enact-extensions validate
+   ```
+6. Create README.md template
+7. Create .gitignore if needed
+8. Initialize git repo if creating new directory (only `git init` is available; additional git operations are left to the user)
+
+**Output**: Plugin directory structure created and ready for components
+
+**Post-workflow git operations** (user can run after completion):
+
+```bash
+git add .
+git commit -m "feat: initial plugin structure"
+```
+
+---
+
+## Phase 5: Component Implementation
+
+**Goal**: Create each component following best practices
+
+**LOAD RELEVANT SKILLS** before implementing each component type:
+
+- Skills: Load skill-development skill
+- Commands: Load command-development skill
+- Agents: Load agent-development skill
+- Hooks: Load hook-development skill
+- MCP: Load mcp-integration skill
+- LSP: Load lsp-integration skill
+- Settings: Load plugin-settings skill
+
+**Actions for each component**:
+
+### For Skills
+
+1. Load skill-development skill using Skill tool
+2. For each skill:
+   - Ask user for concrete usage examples (or use from Phase 3)
+   - Plan resources (scripts/, references/, examples/)
+   - Create skill directory structure
+   - Write SKILL.md with:
+     - Third-person description with specific trigger phrases
+     - Lean body (1,500-2,000 words) in imperative form
+     - References to supporting files
+   - Create reference files for detailed content
+   - Create example files for working code
+   - Create utility scripts if needed
+3. Use skill-reviewer agent to validate each skill
+
+### For Commands
+
+1. Load command-development skill using Skill tool
+2. For each command:
+   - Write command markdown with frontmatter
+   - Include clear description and argument-hint
+   - Specify allowed-tools (minimal necessary)
+   - Write instructions FOR Claude (not TO user)
+   - Provide usage examples and tips
+   - Reference relevant skills if applicable
+
+### For Agents
+
+1. Load agent-development skill using Skill tool
+2. For each agent, use agent-creator agent:
+   - Provide description of what agent should do
+   - Agent-creator generates: identifier, whenToUse with examples, systemPrompt
+   - Create agent markdown file with frontmatter and system prompt
+   - Add appropriate model, color, and tools
+   - Validate using plugin-validator agent
+
+### For Hooks
+
+1. Load hook-development skill using Skill tool
+2. For each hook:
+   - Create hooks/hooks.json with hook configuration
+   - Prefer prompt-based hooks for complex logic
+   - Use ${CLAUDE_PLUGIN_ROOT} for portability
+   - Create hook scripts if needed (in examples/ not scripts/)
+   - Validate using plugin-validator agent (handles hook schema validation)
+
+### For MCP
+
+1. Load mcp-integration skill using Skill tool
+2. Create .mcp.json configuration with:
+   - Server type (stdio for local, SSE for hosted)
+   - Command and args (with ${CLAUDE_PLUGIN_ROOT})
+   - extensionToLanguage mapping if LSP
+   - Environment variables as needed
+3. Document required env vars in README
+4. Provide setup instructions
+
+### For LSP
+
+1. Load lsp-integration skill using Skill tool
+2. Add lspServers configuration to plugin.json:
+   - Server command and args
+   - extensionToLanguage mapping
+   - Environment variables if needed
+3. Bundle LSP server binary if self-contained
+4. Or document external server installation in README
+5. Test with language files matching configured extensions
+
+### For Settings
+
+1. Load plugin-settings skill using Skill tool
+2. Create settings template in README
+3. Create example .claude/plugin-name.local.md file (as documentation)
+4. Implement settings reading in hooks/commands as needed
+5. Add to .gitignore: `.claude/*.local.md`
+
+**Progress tracking**: Update tasks as each component is completed
+
+**Output**: All plugin components implemented
+
+---
+
+## Phase 6: Validation & Quality Check
+
+**Goal**: Ensure plugin meets quality standards and works correctly
+
+**Actions**:
+
+1. **Run plugin-validator agent**:
+   - Use plugin-validator agent to comprehensively validate plugin
+   - Check: manifest, structure, naming, components, security
+   - Review validation report
+
+2. **Fix critical issues**:
+   - Address any critical errors from validation
+   - Fix any warnings that indicate real problems
+
+3. **Review with skill-reviewer** (if plugin has skills):
+   - For each skill, use skill-reviewer agent
+   - Check description quality, progressive disclosure, writing style
+   - Apply recommendations
+
+4. **Test agent triggering** (if plugin has agents):
+   - For each agent, verify <example> blocks are clear
+   - Check triggering conditions are specific
+   - Verify via plugin-validator agent
+
+5. **Test hook configuration** (if plugin has hooks):
+   - Validate via plugin-validator agent (checks hook schema and scripts)
+   - Verify ${CLAUDE_PLUGIN_ROOT} usage
+
+6. **Present findings**:
+   - Summary of validation results
+   - Any remaining issues
+   - Overall quality assessment
+
+7. **Ask user**: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
+
+**Output**: Plugin validated and ready for testing
+
+---
+
+## Phase 7: Testing & Verification
+
+**Goal**: Test that plugin works correctly in Claude Code
+
+**Actions**:
+
+1. **Installation instructions**:
+   - Show user how to test locally:
+     ```bash
+     claude --plugin-dir /path/to/plugin-name
+     ```
+   - Or copy to `.claude-plugin/` for project testing
+
+2. **Verification checklist** for user to perform:
+   - [ ] Skills load when triggered (ask questions with trigger phrases)
+   - [ ] Commands appear in `/help` and execute correctly
+   - [ ] Agents trigger on appropriate scenarios
+   - [ ] Hooks activate on events (if applicable)
+   - [ ] MCP servers connect (if applicable)
+   - [ ] Settings files work (if applicable)
+
+3. **Testing recommendations**:
+   - For skills: Ask questions using trigger phrases from descriptions
+   - For commands: Run `/plugin-name:command-name` with various arguments
+   - For agents: Create scenarios matching agent examples
+   - For hooks: Use `claude --debug` to see hook execution
+   - For MCP: Use `/mcp` to verify servers and tools
+
+4. **Ask user**: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"
+
+5. **If user wants guidance**, walk through testing each component with specific test cases
+
+**Output**: Plugin tested and verified working
+
+---
+
+## Phase 8: Documentation & Next Steps
+
+**Goal**: Ensure plugin is well-documented and ready for distribution
+
+**Actions**:
+
+1. **Verify README completeness**:
+   - Check README has: overview, features, installation, prerequisites, usage
+   - For MCP plugins: Document required environment variables
+   - For hook plugins: Explain hook activation
+   - For settings: Provide configuration templates
+
+2. **Ask about marketplace publishing**:
+   - Ask user: "Would you like to publish this plugin to a marketplace?"
+   - If yes, proceed with marketplace integration
+   - If no, skip to step 4
+
+3. **Marketplace integration** (if publishing):
+   - Load marketplace-structure skill using Skill tool
+   - Determine target marketplace:
+     - Ask: "Which marketplace? (existing marketplace path, create new, or skip)"
+   - If existing marketplace:
+     - Read marketplace.json
+     - Draft plugin entry:
+
+       ```json
+       {
+         "name": "[plugin-name]",
+         "source": "[relative-path-or-github]",
+         "description": "[from plugin.json]",
+         "version": "[from plugin.json]",
+         "category": "[suggest based on plugin type]"
+       }
+       ```
+
+     - Show diff of marketplace.json before/after addition
+     - Ask user to confirm entry
+     - Update marketplace.json with new plugin entry
+     - Update marketplace metadata.version (bump patch version)
+
+   - If create new marketplace:
+     - Suggest using `/plugin-dev:create-marketplace` command
+     - Or create minimal marketplace.json with this plugin as first entry
+   - Validate marketplace after update using plugin-validator agent
+
+4. **Create summary**:
+   - Mark all tasks complete
+   - List what was created:
+     - Plugin name and purpose
+     - Components created (X skills, Y commands, Z agents, etc.)
+     - Key files and their purposes
+     - Total file count and structure
+   - If added to marketplace:
+     - Marketplace name and location
+     - Plugin entry details
+   - Next steps:
+     - Testing recommendations
+     - Publishing to marketplace (if not done)
+     - Iteration based on usage
+
+5. **Suggest improvements** (optional):
+   - Additional components that could enhance plugin
+   - Integration opportunities
+   - Testing strategies
+
+**Output**: Complete, documented plugin ready for use or publication
+
+---
+
+## Important Notes
+
+### Throughout All Phases
+
+- **Use Task tools** to track progress at every phase (TaskCreate, TaskUpdate, TaskList)
+- **Load skills with Skill tool** when working on specific component types
+- **Use specialized agents** (agent-creator, plugin-validator, skill-reviewer)
+- **Ask for user confirmation** at key decision points
+- **Follow plugin-dev's own patterns** as reference examples
+- **Apply best practices**:
+  - Third-person descriptions for skills
+  - Imperative form in skill bodies
+  - Commands written FOR Claude
+  - Strong trigger phrases
+  - ${CLAUDE_PLUGIN_ROOT} for portability
+  - Progressive disclosure
+  - Security-first (HTTPS, no hardcoded credentials)
+
+### Key Decision Points (Wait for User)
+
+1. After Phase 1: Confirm plugin purpose
+2. After Phase 2: Approve component plan
+3. After Phase 3: Proceed to implementation
+4. After Phase 6: Fix issues or proceed
+5. After Phase 7: Continue to documentation
+
+### Skills to Load by Phase
+
+- **Phase 2**: plugin-structure
+- **Phase 5**: skill-development, command-development, agent-development, hook-development, mcp-integration, lsp-integration, plugin-settings (as needed)
+- **Phase 6**: (agents will use skills automatically)
+- **Phase 8**: marketplace-structure (if publishing to marketplace)
+
+### Quality Standards
+
+Every component must meet these standards:
+
+- ✅ Follows plugin-dev's proven patterns
+- ✅ Uses correct naming conventions
+- ✅ Has strong trigger conditions (skills/agents)
+- ✅ Includes working examples
+- ✅ Properly documented
+- ✅ Validated with utilities
+- ✅ Tested in Claude Code
+
+---
+
+## Example Workflow
+
+### User Request
+
+"Create a plugin for managing database migrations"
+
+### Phase 1: Discovery
+
+- Understand: Migration management, database schema versioning
+- Confirm: User wants to create, run, rollback migrations
+
+### Phase 2: Component Planning
+
+- Skills: 1 (migration best practices)
+- Commands: 3 (create-migration, run-migrations, rollback)
+- Agents: 1 (migration-validator)
+- MCP: 1 (database connection)
+
+### Phase 3: Clarifying Questions
+
+- Which databases? (PostgreSQL, MySQL, etc.)
+- Migration file format? (SQL, code-based?)
+- Should agent validate before applying?
+- What MCP tools needed? (query, execute, schema)
+
+### Phase 4-8: Implementation, Validation, Testing, Documentation
+
+---
+
+Begin with Phase 1: Discovery.

package/extensions/plugin-dev/commands/start.md

@@ -0,0 +1,81 @@
+---
+description: Start plugin development - choose your path
+argument-hint: [description]
+allowed-tools: AskUserQuestion, Skill, TaskCreate, TaskGet, TaskUpdate, TaskList
+model: sonnet
+disable-model-invocation: true
+---
+
+# Plugin Development Entry Point
+
+Welcome the user and help them choose the right path for their plugin development journey.
+
+## Your Task
+
+Present the user with a clear choice between two development paths, explain when each is appropriate, then route them to the correct workflow.
+
+## Step 1: Handle Arguments
+
+If the user provided arguments ($ARGUMENTS is not empty):
+
+- Analyze the arguments to see if intent is already clear
+- If arguments clearly indicate a plugin (e.g., "database migration tool"), suggest plugin path
+- If arguments clearly indicate a marketplace (e.g., "team collection", "distribute our plugins"), suggest marketplace path
+- Still ask for confirmation before routing
+
+**Initial request:** $ARGUMENTS
+
+## Step 2: Provide Context
+
+Before presenting the question, briefly explain:
+
+```text
+Welcome to the Enact Plugin Manager!
+
+**Plugin** → One bundle for Claude, Codex, and Cursor
+- Canonical manifest: .agents/plugin.json
+- Shared components: skills/, commands/, hooks/, .mcp.json
+- Host copies: .claude-plugin/, .codex-plugin/, .cursor-plugin/
+- Example: ../enact-operator/extensions/ (sibling top-level submodule of enact-os)
+
+Load the plugin-structure skill, then run create-plugin for the full workflow.
+```
+
+## Step 3: Ask User Question
+
+Use the AskUserQuestion tool with these parameters:
+
+- **header**: "Create"
+- **question**: "Ready to create an Enact plugin?"
+- **multiSelect**: false
+- **options**: (defined below)
+
+**Options**:
+
+Option 1:
+
+- label: "Create a plugin (Recommended)"
+- description: "Scaffold a multi-platform plugin with .agents/plugin.json and synced host manifests."
+
+Option 2:
+
+- label: "Validate an existing plugin"
+- description: "Run plugin-validator on an existing bundle (e.g. ../enact-operator/extensions)."
+
+## Step 4: Route Based on Choice
+
+**Create a plugin** → invoke `create-plugin` with `$ARGUMENTS`.
+
+**Validate an existing plugin** → invoke `plugin-validator` agent on the path the user provides (default: `../enact-operator/extensions`).
+
+---
+
+## Important Notes
+
+- Load `plugin-structure` when the user is new to multi-platform layout.
+- After editing `.agents/plugin.json`, remind them to run `enact-extensions sync`.
+- Marketplace authoring is archived under `commands/_archive/` — only mention if explicitly requested.
+
+---
+
+Begin with the welcome message, then route to create or validate.

package/extensions/plugin-dev/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}