From 4ed473af734991f3325d92394c86afb7620a5227 Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Mon, 2 Feb 2026 04:28:49 +0000 Subject: [PATCH] Add AI Helpers Enabled workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This workflow provides a development environment with the odh-ai-helpers marketplace pre-configured and automatically enabled in every session. Features: - Zero-configuration marketplace integration - Automatic plugin enablement (odh-ai-helpers@odh-ai-helpers) - 5-phase structured methodology (Understand → Plan → Execute → Verify → Document) - Specialized marketplace agent (Helper - Marketplace Specialist) - Three utility commands: - /helpers.list - List available marketplace plugins - /helpers.validate - Validate marketplace configuration - /helpers.scan-fips - Run FIPS compliance scan - Comprehensive documentation and field reference - Production-ready configuration (no comments in JSON) The workflow is designed for developers who want immediate access to AI automation tools and productivity plugins without manual setup. Co-Authored-By: Claude Sonnet 4.5 --- .../ai-helpers-enabled/.ambient/ambient.json | 12 + .../agents/helper-marketplace-specialist.md | 102 +++++ .../.claude/claude-settings.json | 13 + .../.claude/commands/helpers.list.md | 88 +++++ .../.claude/commands/helpers.scan-fips.md | 133 +++++++ .../.claude/commands/helpers.validate.md | 127 ++++++ .../ai-helpers-enabled/FIELD_REFERENCE.md | 367 ++++++++++++++++++ workflows/ai-helpers-enabled/README.md | 266 +++++++++++++ 8 files changed, 1108 insertions(+) create mode 100644 workflows/ai-helpers-enabled/.ambient/ambient.json create mode 100644 workflows/ai-helpers-enabled/.claude/agents/helper-marketplace-specialist.md create mode 100644 workflows/ai-helpers-enabled/.claude/claude-settings.json create mode 100644 workflows/ai-helpers-enabled/.claude/commands/helpers.list.md create mode 100644 workflows/ai-helpers-enabled/.claude/commands/helpers.scan-fips.md create mode 100644 workflows/ai-helpers-enabled/.claude/commands/helpers.validate.md create mode 100644 workflows/ai-helpers-enabled/FIELD_REFERENCE.md create mode 100644 workflows/ai-helpers-enabled/README.md diff --git a/workflows/ai-helpers-enabled/.ambient/ambient.json b/workflows/ai-helpers-enabled/.ambient/ambient.json new file mode 100644 index 0000000..77c2761 --- /dev/null +++ b/workflows/ai-helpers-enabled/.ambient/ambient.json @@ -0,0 +1,12 @@ +{ + "name": "AI Helpers Enabled", + "description": "A workflow with the odh-ai-helpers marketplace automatically enabled, providing AI automation tools, plugins, and assistants for enhanced productivity.", + "systemPrompt": "You are an AI development assistant with the odh-ai-helpers marketplace enabled. Your role is to help users with development tasks while leveraging specialized AI automation tools and productivity plugins from the marketplace.\n\nKEY RESPONSIBILITIES:\n- Guide users through development tasks using enhanced AI tools\n- Leverage odh-ai-helpers marketplace plugins when applicable\n- Maintain clear documentation of work performed\n- Follow established coding standards and best practices\n- Execute slash commands to perform specific workflow tasks\n\nWORKFLOW METHODOLOGY:\n\n1. UNDERSTAND - Analyze the user's request and requirements\n - Ask clarifying questions to fully understand the goal\n - Identify which marketplace tools might be helpful\n - Assess the scope and complexity of the task\n\n2. PLAN - Create a structured approach\n - Break down complex tasks into manageable steps\n - Determine which AI helpers and plugins to use\n - Identify potential challenges and dependencies\n\n3. EXECUTE - Implement the solution\n - Leverage marketplace capabilities for enhanced productivity\n - Write clean, well-documented code\n - Use automation tools to streamline repetitive tasks\n\n4. VERIFY - Validate results and ensure quality\n - Test implementations thoroughly\n - Review code for best practices and standards\n - Ensure all requirements are met\n\n5. DOCUMENT - Provide clear documentation\n - Document what was accomplished\n - Explain key decisions and approaches\n - Provide usage instructions and examples\n\nAVAILABLE COMMANDS:\n- /helpers.list - List available marketplace plugins and tools\n- /helpers.validate - Validate marketplace configuration\n- /helpers.scan-fips - Run FIPS compliance scan (if available)\n\nOUTPUT LOCATIONS:\n- Create all artifacts in: artifacts/ai-helpers/\n- Create documentation in: artifacts/ai-helpers/docs/\n- Create code in: artifacts/ai-helpers/code/\n- Create reports in: artifacts/ai-helpers/reports/\n\nWORKSPACE NAVIGATION:\nCRITICAL: Follow these rules to avoid fumbling when looking for files.\n\nStandard file locations (from workflow root):\n- Config: .ambient/ambient.json (ALWAYS at this path)\n- Claude Settings: .claude/claude-settings.json\n- Agents: .claude/agents/*.md\n- Commands: .claude/commands/*.md\n- Outputs: artifacts/\n\nTool selection rules:\n- Use Read for: Known paths, standard files (ambient.json, README.md), files you just created\n- Use Glob for: Discovery (finding multiple files by pattern), unknown locations\n- Use Grep for: Content search, finding files containing specific text\n\nNever glob for standard files:\n✅ DO: Read .ambient/ambient.json\n❌ DON'T: Glob **/ambient.json\n\nFiles you create: Remember the path you wrote to and use Read (not Glob) to read them back.\n\nMARKETPLACE CAPABILITIES:\nThe odh-ai-helpers marketplace provides specialized plugins including:\n- fips-compliance-checker: Scan for FIPS compliance\n- odh-ai-helpers: AI automation tools and productivity assistants\n\nExplore and leverage these tools to enhance your capabilities for specific tasks.\n\nBEST PRACTICES:\n- Leverage marketplace tools when they add value to the task\n- Maintain clear documentation of your work\n- Follow established coding standards and conventions\n- Test your implementations thoroughly\n- Communicate clearly with the user throughout the process\n- Ask for clarification when requirements are ambiguous", + "startupPrompt": "Welcome! I'm your AI Assistant with the odh-ai-helpers marketplace enabled.\n\n🚀 ENHANCED CAPABILITIES:\nThis workflow comes pre-configured with the odh-ai-helpers marketplace, giving you access to specialized AI automation tools and productivity plugins.\n\n📋 WORKFLOW PHASES:\n1. Understand - Analyze requirements and identify helpful tools\n2. Plan - Create structured approach leveraging marketplace capabilities\n3. Execute - Implement solution using enhanced AI tools\n4. Verify - Validate results and ensure quality\n5. Document - Provide clear documentation\n\n🛠️ AVAILABLE COMMANDS:\n- /helpers.list - List available marketplace plugins\n- /helpers.validate - Validate marketplace configuration\n- /helpers.scan-fips - Run FIPS compliance scan\n\n💡 GETTING STARTED:\nI can help you with:\n- Development tasks with enhanced AI tools\n- Automated workflows and productivity enhancements\n- Specialized assistance from marketplace plugins\n\nSimply tell me what you'd like to work on, and I'll leverage the available tools and helpers to assist you efficiently.\n\nWhat can I help you with today?", + "results": { + "All Artifacts": "artifacts/ai-helpers/**/*", + "Documentation": "artifacts/ai-helpers/docs/**/*.md", + "Code": "artifacts/ai-helpers/code/**/*", + "Reports": "artifacts/ai-helpers/reports/**/*.md" + } +} diff --git a/workflows/ai-helpers-enabled/.claude/agents/helper-marketplace-specialist.md b/workflows/ai-helpers-enabled/.claude/agents/helper-marketplace-specialist.md new file mode 100644 index 0000000..37aabd7 --- /dev/null +++ b/workflows/ai-helpers-enabled/.claude/agents/helper-marketplace-specialist.md @@ -0,0 +1,102 @@ +# Helper - Marketplace Specialist + +## Role +An expert in leveraging the odh-ai-helpers marketplace to enhance development workflows with specialized AI tools, plugins, and automation capabilities. + +## Expertise +- odh-ai-helpers marketplace architecture and capabilities +- Plugin integration and configuration +- FIPS compliance scanning and security validation +- AI-powered automation and productivity tools +- Troubleshooting marketplace connectivity and plugin issues + +## Responsibilities + +### Marketplace Integration +- Validate marketplace configuration and connectivity +- Identify appropriate plugins for specific tasks +- Configure and enable marketplace plugins +- Troubleshoot plugin activation issues + +### Tool Selection +- Recommend marketplace tools based on task requirements +- Explain capabilities and limitations of available plugins +- Guide users in choosing the right tools for their needs +- Stay current with new marketplace offerings + +### Automation Enhancement +- Leverage marketplace plugins to automate repetitive tasks +- Integrate AI helpers into development workflows +- Optimize tool usage for maximum productivity +- Identify opportunities for workflow improvement + +## Communication Style + +### Approach +- Practical and solution-oriented +- Clear explanations of marketplace capabilities +- Proactive in suggesting helpful tools +- Patient when troubleshooting issues + +### Typical Responses +Helper provides actionable guidance on marketplace usage, explains plugin capabilities clearly, and offers concrete examples of how tools can enhance workflows. Responses focus on practical application rather than theoretical concepts. + +### Example Interaction +``` +User: "How can I check if this code is FIPS compliant?" + +Helper: "I can help you with that using the FIPS compliance checker from the odh-ai-helpers marketplace. This plugin scans your codebase for FIPS compliance issues. + +Let me run /helpers.scan-fips to perform the scan. The tool will: +1. Analyze your code for cryptographic library usage +2. Check for FIPS 140-2/140-3 approved algorithms +3. Identify any non-compliant implementations +4. Generate a detailed report with findings + +After the scan completes, I'll provide a summary of any compliance issues found and recommendations for remediation." +``` + +## When to Invoke + +Invoke Helper when you need assistance with: +- Validating marketplace configuration +- Discovering available marketplace plugins +- Running FIPS compliance scans +- Troubleshooting plugin issues +- Optimizing workflow with marketplace tools +- Understanding marketplace capabilities +- Integrating AI helpers into development tasks + +## Tools and Techniques + +### Marketplace Commands +- /helpers.list - Enumerate available plugins +- /helpers.validate - Check marketplace configuration +- /helpers.scan-fips - Run FIPS compliance scanning + +### Diagnostic Approaches +- Verify marketplace directory accessibility +- Check plugin registration and enablement +- Validate configuration files +- Test plugin connectivity + +### Integration Patterns +- Identify task-appropriate tools +- Configure plugins for specific workflows +- Combine multiple marketplace tools effectively +- Monitor tool performance and results + +## Key Principles + +1. **Right Tool for the Job**: Match marketplace tools to specific task requirements rather than force-fitting tools +2. **Validation First**: Always verify marketplace configuration before attempting to use plugins +3. **Clear Communication**: Explain what each tool does and why it's appropriate for the task +4. **Graceful Degradation**: Provide alternatives when marketplace tools aren't available or fail + +## Example Artifacts + +When Helper contributes to a workflow, they typically produce: +- Marketplace validation reports in `artifacts/ai-helpers/reports/marketplace-validation.md` +- FIPS compliance scan results in `artifacts/ai-helpers/reports/fips-compliance.md` +- Tool recommendation documents in `artifacts/ai-helpers/docs/tool-recommendations.md` +- Plugin configuration guides in `artifacts/ai-helpers/docs/plugin-setup.md` diff --git a/workflows/ai-helpers-enabled/.claude/claude-settings.json b/workflows/ai-helpers-enabled/.claude/claude-settings.json new file mode 100644 index 0000000..71f5264 --- /dev/null +++ b/workflows/ai-helpers-enabled/.claude/claude-settings.json @@ -0,0 +1,13 @@ +{ + "extraKnownMarketplaces": { + "odh-ai-helpers": { + "source": { + "source": "directory", + "path": "/opt/ai-helpers" + } + } + }, + "enabledPlugins": { + "odh-ai-helpers@odh-ai-helpers": true + } +} diff --git a/workflows/ai-helpers-enabled/.claude/commands/helpers.list.md b/workflows/ai-helpers-enabled/.claude/commands/helpers.list.md new file mode 100644 index 0000000..53d43a2 --- /dev/null +++ b/workflows/ai-helpers-enabled/.claude/commands/helpers.list.md @@ -0,0 +1,88 @@ +# /helpers.list - List Available Marketplace Plugins + +## Purpose +Enumerates all available plugins and tools from the odh-ai-helpers marketplace, displaying their capabilities, descriptions, and current status. This command helps users discover what marketplace tools are available for their tasks. + +## Prerequisites +- Marketplace must be configured in `.claude/claude-settings.json` +- The `/opt/ai-helpers` directory must be accessible +- Marketplace metadata file must exist at `/opt/ai-helpers/.claude-plugin/marketplace.json` + +## Process + +1. **Verify Marketplace Configuration** + - Check that `.claude/claude-settings.json` exists + - Confirm `odh-ai-helpers` is registered in `extraKnownMarketplaces` + - Verify plugin is enabled in `enabledPlugins` + +2. **Access Marketplace Directory** + - Navigate to `/opt/ai-helpers` + - Read marketplace metadata from `.claude-plugin/marketplace.json` + - Parse plugin definitions + +3. **Enumerate Plugins** + - List each plugin by name + - Display plugin description + - Show source information (URL or local path) + - Indicate current activation status + +4. **Generate Plugin Report** + - Create formatted output showing all available tools + - Group plugins by category if applicable + - Provide usage guidance for each plugin + +## Output +- **Console Display**: Formatted list of plugins with descriptions + - Shows plugin names, descriptions, and sources + - Indicates which plugins are currently enabled + +- **Plugin Inventory**: `artifacts/ai-helpers/reports/plugin-inventory.md` + - Complete catalog of available marketplace tools + - Detailed description of each plugin's capabilities + - Usage examples and recommendations + +## Usage Examples + +Basic usage: +``` +/helpers.list +``` + +Expected output: +``` +odh-ai-helpers Marketplace Plugins +=================================== + +✓ fips-compliance-checker + Description: Plugin to scan for FIPS compliance + Source: https://github.com/opendatahub-io/fips-compliance-checker-claude-code-plugin.git + Status: Available + +✓ odh-ai-helpers + Description: AI automation tools, plugins, and assistants for enhanced productivity + Source: ./helpers + Status: Enabled + +Total plugins available: 2 +``` + +## Success Criteria + +After running this command, you should have: +- [ ] Complete list of available marketplace plugins displayed +- [ ] Plugin descriptions and capabilities clearly explained +- [ ] Current activation status shown for each plugin +- [ ] Plugin inventory report generated in artifacts directory + +## Next Steps + +After reviewing available plugins: +1. Run `/helpers.validate` to ensure marketplace is properly configured +2. Use specific plugin commands as needed for your tasks +3. Refer to the generated inventory for plugin capabilities + +## Notes +- Plugin availability depends on marketplace installation and configuration +- Some plugins may require additional setup or authentication +- Plugin list reflects the current marketplace version installed at `/opt/ai-helpers` +- New plugins may be added to the marketplace through updates diff --git a/workflows/ai-helpers-enabled/.claude/commands/helpers.scan-fips.md b/workflows/ai-helpers-enabled/.claude/commands/helpers.scan-fips.md new file mode 100644 index 0000000..8af3c38 --- /dev/null +++ b/workflows/ai-helpers-enabled/.claude/commands/helpers.scan-fips.md @@ -0,0 +1,133 @@ +# /helpers.scan-fips - Run FIPS Compliance Scan + +## Purpose +Executes a FIPS (Federal Information Processing Standards) compliance scan on the codebase using the fips-compliance-checker plugin from the odh-ai-helpers marketplace. This command identifies cryptographic implementations that may not comply with FIPS 140-2/140-3 standards. + +## Prerequisites +- odh-ai-helpers marketplace must be configured and enabled +- fips-compliance-checker plugin must be available +- Target codebase must be accessible in the workspace +- Run `/helpers.validate` first to ensure marketplace is operational + +## Process + +1. **Verify Plugin Availability** + - Confirm fips-compliance-checker plugin is accessible + - Check marketplace configuration + - Validate plugin dependencies are met + +2. **Prepare Scan Environment** + - Identify target directory for scanning (default: current workspace) + - Create output directory for scan results + - Initialize scan configuration + +3. **Execute FIPS Scan** + - Invoke fips-compliance-checker plugin + - Scan codebase for cryptographic library usage + - Check for FIPS-approved algorithms + - Identify non-compliant implementations + - Detect deprecated or weak cryptographic functions + +4. **Analyze Results** + - Parse scan output + - Categorize findings by severity + - Identify file locations of non-compliant code + - Generate recommendations for remediation + +5. **Generate Compliance Report** + - Create detailed report of findings + - Include code snippets showing issues + - Provide remediation guidance + - Summarize compliance status + +## Output +- **FIPS Compliance Report**: `artifacts/ai-helpers/reports/fips-compliance.md` + - Executive summary of compliance status + - Detailed findings with file locations and line numbers + - Severity classification (Critical, High, Medium, Low) + - Remediation recommendations + - List of FIPS-approved alternatives + +- **Scan Log**: `artifacts/ai-helpers/reports/fips-scan-log.txt` + - Raw output from fips-compliance-checker plugin + - Timestamp and scan configuration + - Complete list of files scanned + +## Usage Examples + +Scan current workspace: +``` +/helpers.scan-fips +``` + +Scan specific directory: +``` +/helpers.scan-fips path/to/code +``` + +Expected output: +``` +FIPS Compliance Scan Report +============================ + +Scan Summary: +- Files scanned: 47 +- Issues found: 3 +- Critical: 1 +- High: 1 +- Medium: 1 +- Low: 0 + +Critical Issues: +---------------- +1. Non-FIPS approved algorithm detected + File: src/crypto/encryption.py:23 + Issue: Using MD5 hashing (not FIPS 140-2 approved) + Recommendation: Replace with SHA-256 or SHA-3 + +High Issues: +----------- +1. Weak key length detected + File: src/auth/keys.py:45 + Issue: RSA key length < 2048 bits + Recommendation: Use minimum 2048-bit RSA keys + +Medium Issues: +------------- +1. Deprecated cryptographic function + File: src/utils/crypto.py:67 + Issue: Using DES encryption + Recommendation: Migrate to AES-256 + +Compliance Status: ✗ NON-COMPLIANT + +Review the detailed report at: +artifacts/ai-helpers/reports/fips-compliance.md +``` + +## Success Criteria + +After running this command, you should have: +- [ ] FIPS compliance scan completed successfully +- [ ] All cryptographic implementations analyzed +- [ ] Non-compliant code identified with file locations +- [ ] Remediation recommendations provided +- [ ] Compliance report generated + +## Next Steps + +After reviewing the scan results: +1. Prioritize fixes based on severity (Critical → High → Medium → Low) +2. Review remediation recommendations for each issue +3. Implement approved cryptographic alternatives +4. Re-run `/helpers.scan-fips` to verify fixes +5. Document compliance status in project documentation + +## Notes +- Scan may take several minutes for large codebases +- Plugin scans for common non-compliant patterns but may not catch all issues +- Manual security review is recommended in addition to automated scanning +- FIPS compliance requirements vary by use case and jurisdiction +- Consult security team for compliance interpretation +- Some findings may be false positives - review carefully +- Plugin requires access to codebase files (read permissions) diff --git a/workflows/ai-helpers-enabled/.claude/commands/helpers.validate.md b/workflows/ai-helpers-enabled/.claude/commands/helpers.validate.md new file mode 100644 index 0000000..62c2148 --- /dev/null +++ b/workflows/ai-helpers-enabled/.claude/commands/helpers.validate.md @@ -0,0 +1,127 @@ +# /helpers.validate - Validate Marketplace Configuration + +## Purpose +Performs comprehensive validation of the odh-ai-helpers marketplace configuration to ensure it is properly set up and accessible. This command diagnoses configuration issues and verifies that marketplace plugins are ready to use. + +## Prerequisites +- Workflow must be loaded in an ACP session +- `.claude/claude-settings.json` should exist in the workflow directory + +## Process + +1. **Check Configuration Files** + - Verify `.claude/claude-settings.json` exists + - Validate JSON syntax is correct + - Confirm `extraKnownMarketplaces` section is present + - Check that `odh-ai-helpers` marketplace is registered + - Verify plugin enablement in `enabledPlugins` section + +2. **Validate Marketplace Directory** + - Check if `/opt/ai-helpers` directory exists and is accessible + - Count files in marketplace directory + - Verify directory permissions allow read access + +3. **Check Marketplace Metadata** + - Locate marketplace definition at `/opt/ai-helpers/.claude-plugin/marketplace.json` + - Validate metadata file syntax + - Extract marketplace name and owner information + - Enumerate registered plugins + +4. **Test Plugin Availability** + - Attempt to access each registered plugin + - Verify plugin source paths are valid + - Check for any plugin loading errors + +5. **Generate Validation Report** + - Document configuration status + - List any issues found + - Provide remediation recommendations + - Summary of marketplace health + +## Output +- **Validation Report**: `artifacts/ai-helpers/reports/marketplace-validation.md` + - Configuration status (PASS/FAIL) + - Marketplace directory accessibility + - List of detected plugins + - Issues found and recommendations + - Overall marketplace health status + +## Usage Examples + +Basic usage: +``` +/helpers.validate +``` + +Expected successful output: +``` +Marketplace Validation Report +============================== + +Configuration Check: ✓ PASS +- Claude settings file: EXISTS +- Marketplace registered: YES (odh-ai-helpers) +- Plugin enabled: YES + +Marketplace Availability: ✓ PASS +- Directory /opt/ai-helpers: ACCESSIBLE +- Files found: 101 +- Metadata file: PRESENT + +Plugins Detected: 2 +- fips-compliance-checker +- odh-ai-helpers + +Overall Status: ✓ HEALTHY + +The marketplace is properly configured and ready to use. +``` + +Expected failure output: +``` +Marketplace Validation Report +============================== + +Configuration Check: ✗ FAIL +- Claude settings file: MISSING +- Marketplace registered: NO +- Plugin enabled: N/A + +Marketplace Availability: ✗ FAIL +- Directory /opt/ai-helpers: NOT FOUND + +Recommendations: +1. Ensure workflow is loaded in an ACP session with marketplace support +2. Verify /opt/ai-helpers is mounted in the session environment +3. Check .claude/claude-settings.json configuration + +Overall Status: ✗ UNAVAILABLE +``` + +## Success Criteria + +After running this command, you should have: +- [ ] Configuration validation completed +- [ ] Marketplace accessibility confirmed +- [ ] Plugin availability verified +- [ ] Validation report generated with clear status +- [ ] Remediation steps provided if issues found + +## Next Steps + +If validation passes: +1. Run `/helpers.list` to see available plugins +2. Proceed with using marketplace tools in your workflow + +If validation fails: +1. Review the validation report for specific issues +2. Follow remediation recommendations +3. Contact support if issues persist +4. Check ACP session configuration + +## Notes +- This command is safe to run multiple times +- Validation checks are non-invasive (read-only) +- Run this command if marketplace plugins aren't working as expected +- Validation report includes timestamps for troubleshooting +- Directory checks may fail outside of ACP sessions (expected behavior) diff --git a/workflows/ai-helpers-enabled/FIELD_REFERENCE.md b/workflows/ai-helpers-enabled/FIELD_REFERENCE.md new file mode 100644 index 0000000..3f09c07 --- /dev/null +++ b/workflows/ai-helpers-enabled/FIELD_REFERENCE.md @@ -0,0 +1,367 @@ +# AI Helpers Enabled - Field Reference + +This document provides detailed information about the configuration fields in `.ambient/ambient.json` and explains how to customize the workflow. + +## Required Fields + +### name +- **Type:** string +- **Purpose:** Display name shown in ACP UI +- **Current Value:** "AI Helpers Enabled" +- **Guidelines:** Keep concise (2-5 words), use title case + +### description +- **Type:** string +- **Purpose:** Explains workflow purpose in UI +- **Current Value:** "A workflow with the odh-ai-helpers marketplace automatically enabled, providing AI automation tools, plugins, and assistants for enhanced productivity." +- **Guidelines:** 1-3 sentences, clear and specific about marketplace integration + +### systemPrompt +- **Type:** string +- **Purpose:** Defines AI agent's role and behavior +- **Current Value:** See `.ambient/ambient.json` +- **Guidelines:** + - Start with clear role definition emphasizing marketplace capabilities + - List key responsibilities for guiding users + - Reference available slash commands (/helpers.*) + - Specify output locations (artifacts/ai-helpers/) + - Include workspace navigation rules + - Explain marketplace capabilities and best practices + +**Key Sections in System Prompt:** +1. **KEY RESPONSIBILITIES** - What the AI assistant does +2. **WORKFLOW METHODOLOGY** - 5-phase approach (Understand → Plan → Execute → Verify → Document) +3. **AVAILABLE COMMANDS** - List of /helpers.* commands +4. **OUTPUT LOCATIONS** - Where artifacts are created +5. **WORKSPACE NAVIGATION** - File finding rules +6. **MARKETPLACE CAPABILITIES** - Available plugins and tools +7. **BEST PRACTICES** - Guidance for effective workflow usage + +### startupPrompt +- **Type:** string +- **Purpose:** Initial message when workflow activates +- **Current Value:** See `.ambient/ambient.json` +- **Guidelines:** + - Greet user warmly + - Highlight marketplace integration as key differentiator + - List workflow phases + - Show available commands + - Provide clear next steps for getting started + +## Optional Fields + +### results +- **Type:** object with string values (glob patterns) +- **Purpose:** Maps artifact types to file paths for ACP UI +- **Current Value:** + ```json + { + "All Artifacts": "artifacts/ai-helpers/**/*", + "Documentation": "artifacts/ai-helpers/docs/**/*.md", + "Code": "artifacts/ai-helpers/code/**/*", + "Reports": "artifacts/ai-helpers/reports/**/*.md" + } + ``` +- **Guidelines:** Use glob patterns to match multiple files, organize by artifact type + +### version +- **Type:** string +- **Example:** "1.0.0" +- **Purpose:** Track workflow configuration version +- **Not currently used but recommended for future releases** + +### author +- **Type:** string or object +- **Example:** {"name": "Your Name", "email": "you@example.com"} +- **Purpose:** Identify workflow creator +- **Useful for multi-team environments** + +### tags +- **Type:** array of strings +- **Example:** ["marketplace", "ai-helpers", "automation", "fips-compliance"] +- **Purpose:** Categorize workflow for discovery in ACP +- **Helpful for organizations with many workflows** + +### icon +- **Type:** string (emoji) +- **Example:** "🔧" or "🤖" +- **Purpose:** Visual identifier in ACP UI +- **Makes workflow easier to recognize** + +## Claude Settings Configuration + +The marketplace is enabled via `.claude/claude-settings.json`: + +### extraKnownMarketplaces +- **Type:** object +- **Purpose:** Registers additional marketplaces beyond defaults +- **Structure:** + ```json + { + "marketplace-id": { + "source": { + "source": "directory", + "path": "/path/to/marketplace" + } + } + } + ``` +- **Current Value:** + ```json + { + "odh-ai-helpers": { + "source": { + "source": "directory", + "path": "/opt/ai-helpers" + } + } + } + ``` + +### enabledPlugins +- **Type:** object with boolean values +- **Purpose:** Controls which plugins are automatically enabled +- **Structure:** + ```json + { + "marketplace-id@plugin-name": true + } + ``` +- **Current Value:** + ```json + { + "odh-ai-helpers@odh-ai-helpers": true + } + ``` + +## Customization Examples + +### Adding a New Command + +Create a new file in `.claude/commands/`: + +```markdown +# /helpers.mycmd - My Custom Command + +## Purpose +What this command does... + +## Prerequisites +- What must exist first + +## Process +1. Step one +2. Step two + +## Output +- Where files are created + +## Usage Examples +\`\`\` +/helpers.mycmd +\`\`\` +``` + +Then update `systemPrompt` in `.ambient/ambient.json`: + +``` +AVAILABLE COMMANDS: +- /helpers.list - List available marketplace plugins +- /helpers.validate - Validate marketplace configuration +- /helpers.scan-fips - Run FIPS compliance scan +- /helpers.mycmd - My custom command +``` + +### Changing Artifact Location + +To change where outputs are saved: + +1. Update `systemPrompt` OUTPUT LOCATIONS section: + ``` + OUTPUT LOCATIONS: + - Create all artifacts in: artifacts/my-new-path/ + ``` + +2. Update `results` section: + ```json + "results": { + "All Artifacts": "artifacts/my-new-path/**/*", + "Documentation": "artifacts/my-new-path/docs/**/*.md" + } + ``` + +3. Update all command files in `.claude/commands/` to reference new path + +### Adding Environment-Specific Configuration + +Add to `.ambient/ambient.json`: + +```json +{ + "name": "AI Helpers Enabled", + "environment": { + "MARKETPLACE_PATH": "/opt/ai-helpers", + "ARTIFACTS_ROOT": "artifacts/ai-helpers", + "LOG_LEVEL": "info" + } +} +``` + +### Customizing Marketplace Path + +If your marketplace is at a different location: + +1. Update `.claude/claude-settings.json`: + ```json + { + "extraKnownMarketplaces": { + "odh-ai-helpers": { + "source": { + "source": "directory", + "path": "/custom/path/to/ai-helpers" + } + } + } + } + ``` + +2. Update validation scripts to check new path + +3. Update command documentation references + +## Agent Files + +Agent persona files are located in `.claude/agents/` and follow this structure: + +```markdown +# Name - Role +## Role +## Expertise +## Responsibilities +## Communication Style +## When to Invoke +## Tools and Techniques +## Key Principles +## Example Artifacts +``` + +**Current Agents:** +- `helper-marketplace-specialist.md` - Expert in marketplace integration and plugin usage + +**Adding New Agents:** + +Create a new file `.claude/agents/myagent-myrole.md` following the template above. The agent will be automatically available for invocation when the workflow loads. + +## Command Files + +Slash command files are located in `.claude/commands/` and follow this structure: + +```markdown +# /command.name - Description +## Purpose +## Prerequisites +## Process +## Output +## Usage Examples +## Success Criteria +## Next Steps +## Notes +``` + +**Current Commands:** +- `helpers.list.md` - List marketplace plugins +- `helpers.validate.md` - Validate marketplace configuration +- `helpers.scan-fips.md` - Run FIPS compliance scan + +**Adding New Commands:** + +Create files using the format `{prefix}.{action}.md`. Commands should align with the workflow's purpose (marketplace integration and AI-assisted development). + +## File Naming Conventions + +- **Workflow directory:** `workflows/ai-helpers-enabled/` +- **Agent files:** `{name}-{role}.md` (e.g., `helper-marketplace-specialist.md`) +- **Command files:** `{prefix}.{action}.md` (e.g., `helpers.validate.md`) +- **Artifacts:** `artifacts/ai-helpers/{category}/{files}` + +**Guidelines:** +- Use lowercase for all file names +- Use hyphens for agent files +- Use dots for command files +- Be descriptive but concise + +## Validation Checklist + +Before deploying this workflow, verify: + +- [ ] `.ambient/ambient.json` is valid JSON (no comments in production file) +- [ ] All required fields are present (name, description, systemPrompt, startupPrompt) +- [ ] `.claude/claude-settings.json` properly configures marketplace +- [ ] All agent files follow the template structure +- [ ] All command files have unique names and proper format +- [ ] Output paths in config match those in command files +- [ ] README.md accurately describes the workflow +- [ ] All file references use correct paths +- [ ] Marketplace path (`/opt/ai-helpers`) is appropriate for target environment + +## Testing Checklist + +After loading the workflow in an ACP session: + +- [ ] Run `/helpers.validate` to verify marketplace configuration +- [ ] Run `/helpers.list` to confirm plugins are accessible +- [ ] Test `/helpers.scan-fips` on a sample codebase +- [ ] Verify artifacts are created in correct locations +- [ ] Check that agent can be invoked properly +- [ ] Confirm marketplace tools are accessible +- [ ] Review generated documentation and reports + +## Marketplace Integration Details + +### Plugin Discovery + +The workflow discovers plugins by: +1. Reading `/opt/ai-helpers/.claude-plugin/marketplace.json` +2. Parsing plugin definitions from the metadata file +3. Checking plugin source paths (URL or local directory) +4. Verifying plugin accessibility + +### Plugin Activation + +Plugins are activated through: +1. Registration in `.claude/claude-settings.json` under `extraKnownMarketplaces` +2. Enablement in `enabledPlugins` section +3. Automatic loading when workflow starts +4. Availability for invocation via commands + +### Common Marketplace Paths + +- **Production ACP:** `/opt/ai-helpers` +- **Development:** `/workspace/repos/ai-helpers` +- **Custom Install:** Specify in `.claude/claude-settings.json` + +## References + +- [ACP Documentation](https://ambient-code.github.io/vteam) +- [Template Workflow](https://github.com/ambient-code/workflows/tree/main/workflows/template-workflow) +- [ai-helpers Repository](https://github.com/opendatahub-io/ai-helpers) +- [Workflow Best Practices](https://ambient-code.github.io/vteam/guides/workflows) +- [Claude Settings Schema](https://docs.anthropic.com/claude/docs/claude-settings) + +## Troubleshooting Common Issues + +**Issue:** JSON parse error in ambient.json +**Solution:** Ensure no trailing commas, comments, or syntax errors. Validate with `jq . .ambient/ambient.json` + +**Issue:** Commands not appearing +**Solution:** Check file names follow `{prefix}.{action}.md` pattern, verify files are in `.claude/commands/` + +**Issue:** Marketplace not loading +**Solution:** Verify path in `.claude/claude-settings.json` matches actual marketplace location + +**Issue:** Plugins not found +**Solution:** Run `/helpers.validate` to diagnose, check `/opt/ai-helpers` exists and contains `.claude-plugin/marketplace.json` + +--- + +For additional help, refer to the main README.md or ACP documentation. diff --git a/workflows/ai-helpers-enabled/README.md b/workflows/ai-helpers-enabled/README.md new file mode 100644 index 0000000..76058f9 --- /dev/null +++ b/workflows/ai-helpers-enabled/README.md @@ -0,0 +1,266 @@ +# AI Helpers Enabled + +A workflow with the odh-ai-helpers marketplace automatically enabled, providing AI automation tools, plugins, and assistants for enhanced productivity. + +## Overview + +This workflow provides a development environment with the odh-ai-helpers marketplace pre-configured and enabled. The marketplace gives you immediate access to specialized AI automation tools, plugins, and productivity assistants without any additional setup. + +The workflow guides you through a structured 5-phase approach for any development task: + +### 1. Understand +Analyze the user's request and requirements. Ask clarifying questions, identify which marketplace tools might be helpful, and assess the scope and complexity of the task. + +### 2. Plan +Create a structured approach to the task. Break down complex work into manageable steps, determine which AI helpers and plugins to use, and identify potential challenges and dependencies. + +### 3. Execute +Implement the solution while leveraging marketplace capabilities. Write clean, well-documented code and use automation tools to streamline repetitive tasks. + +### 4. Verify +Validate results and ensure quality. Test implementations thoroughly, review code for best practices and standards, and ensure all requirements are met. + +### 5. Document +Provide clear documentation of what was accomplished, explain key decisions and approaches, and provide usage instructions and examples. + +## Getting Started + +### Prerequisites +- Ambient Code Platform session with workflow support +- Access to the odh-ai-helpers marketplace at `/opt/ai-helpers` +- Claude Code runner with marketplace support + +### Installation +1. Load this workflow in your ACP session +2. The marketplace is automatically enabled - no setup required +3. Run `/helpers.validate` to confirm marketplace is operational + +## Workflow Phases + +### Phase 1: Understand +**No specific command - interactive discussion** + +Begin by describing what you'd like to work on. The AI assistant will ask clarifying questions to understand your requirements and identify which marketplace tools might be helpful. + +**Output:** +- Clear understanding of task requirements and goals + +### Phase 2: Plan +**No specific command - interactive planning** + +The assistant will create a structured approach to your task, breaking down complex work and determining which AI helpers and plugins to use. + +**Output:** +- `artifacts/ai-helpers/docs/task-plan.md` - Structured plan for the task + +### Phase 3: Execute +**Command:** `/helpers.scan-fips` (if applicable) or standard development workflow + +Implement the solution while leveraging marketplace capabilities and automation tools. + +**Output:** +- `artifacts/ai-helpers/code/` - Generated or modified code +- `artifacts/ai-helpers/reports/` - Analysis and scan results + +### Phase 4: Verify +**Command:** `/helpers.validate` (for marketplace verification) + +Validate that implementations meet requirements, test thoroughly, and review for best practices. + +**Output:** +- `artifacts/ai-helpers/reports/validation-results.md` - Test and validation results + +### Phase 5: Document +**No specific command - documentation generation** + +Generate documentation explaining what was accomplished, key decisions, and usage instructions. + +**Output:** +- `artifacts/ai-helpers/docs/` - Documentation and guides + +## Available Agents + +This workflow includes specialized expert agents: + +### Helper - Marketplace Specialist +Expert in leveraging the odh-ai-helpers marketplace for enhanced development workflows. +**Expertise:** Marketplace integration, Plugin configuration, FIPS compliance, Automation tools, Troubleshooting + +## Available Commands + +### /helpers.list - List Available Plugins +Enumerates all available plugins and tools from the odh-ai-helpers marketplace, displaying their capabilities and current status. + +**Usage:** +``` +/helpers.list +``` + +### /helpers.validate - Validate Marketplace Configuration +Performs comprehensive validation of marketplace setup to ensure it is properly configured and accessible. + +**Usage:** +``` +/helpers.validate +``` + +### /helpers.scan-fips - Run FIPS Compliance Scan +Executes a FIPS compliance scan on the codebase using the fips-compliance-checker plugin. + +**Usage:** +``` +/helpers.scan-fips +``` + +Or scan a specific directory: +``` +/helpers.scan-fips path/to/code +``` + +## Output Artifacts + +All workflow outputs are saved in the `artifacts/ai-helpers/` directory: + +``` +artifacts/ai-helpers/ +├── code/ # Generated or modified code +├── docs/ # Documentation and guides +│ ├── task-plan.md +│ ├── tool-recommendations.md +│ └── plugin-setup.md +└── reports/ # Analysis and validation results + ├── marketplace-validation.md + ├── plugin-inventory.md + ├── fips-compliance.md + └── validation-results.md +``` + +## Example Usage + +```bash +# Step 1: Validate marketplace is configured +/helpers.validate + +# Step 2: See what plugins are available +/helpers.list + +# Step 3: Work on your task +# Simply describe what you want to accomplish, and the assistant +# will leverage marketplace tools as appropriate + +# Step 4: Run compliance scans if needed +/helpers.scan-fips + +# Review outputs in artifacts/ai-helpers/ +``` + +## Configuration + +This workflow is configured via `.ambient/ambient.json`. Key settings: + +- **Name:** AI Helpers Enabled +- **Description:** Marketplace-enabled workflow with AI automation tools +- **Artifact Path:** `artifacts/ai-helpers/` +- **Marketplace:** odh-ai-helpers at `/opt/ai-helpers` + +### Claude Settings + +The marketplace is enabled via `.claude/claude-settings.json`: + +```json +{ + "extraKnownMarketplaces": { + "odh-ai-helpers": { + "source": { + "source": "directory", + "path": "/opt/ai-helpers" + } + } + }, + "enabledPlugins": { + "odh-ai-helpers@odh-ai-helpers": true + } +} +``` + +## Marketplace Plugins + +The odh-ai-helpers marketplace includes: + +### fips-compliance-checker +Scans codebase for FIPS 140-2/140-3 compliance issues. +- Detects non-approved cryptographic algorithms +- Identifies weak key lengths +- Finds deprecated cryptographic functions +- Provides remediation recommendations + +### odh-ai-helpers +AI automation tools and productivity assistants. +- Enhanced development capabilities +- Automated workflow tools +- Productivity plugins + +## Customization + +You can extend this workflow by: + +1. **Adding Custom Agents**: Create new agent personas in `.claude/agents/` +2. **Creating Commands**: Add workflow-specific commands in `.claude/commands/` +3. **Modifying System Prompt**: Edit `.ambient/ambient.json` to customize AI behavior +4. **Adding Templates**: Create template files for common tasks in a `templates/` directory + +## Best Practices + +1. **Validate First**: Always run `/helpers.validate` when starting a session to ensure marketplace is available +2. **Explore Plugins**: Use `/helpers.list` to discover what tools are available before starting work +3. **Leverage Automation**: Take advantage of marketplace plugins to automate repetitive tasks +4. **Document Results**: Maintain clear documentation of work performed and tools used +5. **Review Scan Results**: Carefully review automated scan results - some findings may be false positives + +## Troubleshooting + +**Problem:** Marketplace not available / validation fails +**Solution:** +- Verify you're in an ACP session with marketplace support +- Check that `/opt/ai-helpers` directory exists and is accessible +- Review `.claude/claude-settings.json` configuration +- Contact support if issues persist + +**Problem:** fips-compliance-checker plugin not found +**Solution:** +- Run `/helpers.list` to see available plugins +- Verify marketplace is properly configured +- Check that plugin is installed in `/opt/ai-helpers` + +**Problem:** Scan results seem incorrect +**Solution:** +- Review scan configuration and target directory +- Some findings may be false positives - investigate each +- Consult security team for compliance interpretation +- Re-run scan after making changes to verify fixes + +## Contributing + +To improve this workflow: +1. Fork the repository +2. Make your changes +3. Test thoroughly in an ACP session +4. Submit a pull request with description + +## License + +MIT License + +## Support + +For issues or questions: +- Run `/helpers.validate` to diagnose configuration issues +- Review generated reports in `artifacts/ai-helpers/reports/` +- Refer to the [ACP documentation](https://ambient-code.github.io/vteam) +- Check the [ai-helpers repository](https://github.com/opendatahub-io/ai-helpers) + +--- + +**Created with:** ACP Workflow Creator +**Workflow Type:** Custom (Marketplace Integration) +**Version:** 1.0.0