@agents-at-scale/ark 0.1.37 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-at-scale/ark",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "Ark CLI - Interactive terminal interface for ARK agents",
   "main": "dist/index.js",
   "type": "module",
@@ -8,10 +8,12 @@
     "ark": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
+    "build": "npm run copy-templates && tsc && chmod +x dist/index.js",
+    "copy-templates": "rm -rf templates && cp -r ../../templates .",
     "dev": "tsc --watch",
     "start": "NODE_NO_WARNINGS=1 node dist/index.js",
     "clean": "rm -rf dist",

package/templates/agent/agent.template.yaml

@@ -0,0 +1,27 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: {{ .Values.agentName }}-agent
+  labels:
+    project: {{ .Values.projectName }}
+    role: assistant
+    tier: basic
+spec:
+  description: {{ .Values.agentName }} agent for {{ .Values.projectName }} project
+  prompt: |
+    You are a helpful AI assistant for the {{ .Values.projectName }} project. You provide clear, concise, and accurate responses to user questions.
+
+    Key guidelines:
+    - Be direct and to the point
+    - Use simple language when possible
+    - If you don't know something, say so
+    - Always be polite and professional
+
+  # Reference to model (will be created by Helm chart)
+  modelRef:
+    name: default
+
+  # Optional: Add built-in tools
+  tools:
+    - type: built-in
+      name: terminate

package/templates/marketplace/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.py]
+indent_size = 4
+
+[*.go]
+indent_style = tab

package/templates/marketplace/.github/.keep

@@ -0,0 +1,11 @@
+# GitHub Configuration Directory
+
+GitHub-specific configuration files for the marketplace repository.
+
+Expected contents:
+- workflows/ - GitHub Actions workflows
+- ISSUE_TEMPLATE/ - Issue templates
+- PULL_REQUEST_TEMPLATE.md - PR template
+- CODEOWNERS - Code ownership rules
+
+These files help maintain quality and consistency in contributions.

package/templates/marketplace/.github/workflows/.keep

@@ -0,0 +1,16 @@
+# GitHub Workflows Directory
+
+GitHub Actions workflows for automating marketplace operations.
+
+Common workflows:
+- component-validation.yml - Validate contributed components
+- security-scan.yml - Security scanning of components
+- documentation-build.yml - Build and deploy documentation
+- release.yml - Automated releases
+- pr-checks.yml - Pull request validation
+
+Workflows should:
+- Be efficient and reliable
+- Provide clear feedback
+- Follow security best practices
+- Be well-documented

package/templates/marketplace/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

package/templates/marketplace/.prettierrc.json

@@ -0,0 +1,20 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "overrides": [
+    {
+      "files": "*.yaml",
+      "options": {
+        "singleQuote": false
+      }
+    }
+  ]
+}

package/templates/marketplace/.yamllint.yml

@@ -0,0 +1,53 @@
+# Default rules for yamllint
+extends: default
+
+rules:
+  # 120 chars should be enough, but don't fail if a line is longer
+  line-length:
+    max: 120
+    level: warning
+
+  # accept both       key:value and key: value
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: -1
+
+  # don't bother me with tabs vs spaces issues
+  indentation:
+    spaces: consistent
+    indent-sequences: whatever
+
+  # allow empty values like 'key:'
+  empty-values:
+    forbid-in-block-mappings: false
+    forbid-in-flow-mappings: false
+
+  # sometimes you have to use quotes
+  quoted-strings:
+    quote-type: any
+    required: false
+
+  # allow trailing spaces in comments
+  trailing-spaces:
+    level: warning
+
+  # allow truthy values
+  truthy:
+    allowed-values: ['true', 'false', 'on', 'off', 'yes', 'no']
+    check-keys: false
+
+  # allow ! in yaml
+  comments:
+    require-starting-space: false
+    ignore-shebangs: true
+    min-spaces-from-content: 1
+
+  # brackets
+  brackets:
+    max-spaces-inside: 1
+    max-spaces-inside-empty: 0
+
+  # braces
+  braces:
+    max-spaces-inside: 1
+    max-spaces-inside-empty: 0

package/templates/marketplace/README.md

@@ -0,0 +1,197 @@
+# ARK Marketplace
+
+Welcome to the ARK Marketplace - a central repository for sharing reusable ARK components across projects and teams.
+
+## Overview
+
+The marketplace serves as a community-driven collection of:
+
+- **Agents** - Pre-configured AI agents for specific tasks
+- **Teams** - Multi-agent workflows and orchestration patterns
+- **Models** - Model configurations for different providers and use cases
+- **Tools** - Extensions that add capabilities to agents
+- **MCP Servers** - Model Context Protocol server implementations
+- **Queries** - Reusable query templates and patterns
+- **Projects** - Complete, end-to-end Ark project templates and solutions
+
+## Repository Structure
+
+```
+marketplace/
+├── agents/           # Reusable agent definitions
+├── teams/            # Multi-agent workflow configurations
+├── models/           # Model configurations by provider
+├── queries/          # Query templates and patterns
+├── tools/            # Tool definitions and implementations
+├── mcp-servers/      # MCP server configurations
+├── projects/         # Complete Ark project templates and solutions
+├── tests/            # Test configurations and utilities
+├── scripts/          # Automation and validation scripts
+├── docs/             # Documentation and guides
+├── templates/        # Component creation templates
+└── .github/          # GitHub workflows and templates
+```
+
+## Contributing Components
+
+### Getting Started
+
+1. **Fork** this repository
+2. **Choose** the appropriate directory for your component type
+3. **Copy** the relevant template from `templates/` directory
+4. **Implement** your component following the guidelines
+5. **Test** your component thoroughly
+6. **Submit** a pull request
+
+### Component Guidelines
+
+#### Agents (`agents/`)
+
+- One agent per subdirectory
+- Include `agent.yaml` with complete agent definition
+- Provide comprehensive `README.md` with usage examples
+- Test with multiple model providers when possible
+
+#### Teams (`teams/`)
+
+- Document the workflow strategy and use cases
+- Include example inputs and expected outputs
+- Explain when to use this team configuration
+- Test the complete workflow end-to-end
+
+#### Models (`models/`)
+
+- Organize by provider (openai/, anthropic/, etc.)
+- Include provider-specific configurations
+- Document capabilities, limitations, and costs
+- Specify recommended use cases
+
+#### Tools (`tools/`)
+
+- Follow Ark tool specification
+- Include source code and build instructions
+- Provide security considerations
+- Include comprehensive error handling
+
+#### MCP Servers (`mcp-servers/`)
+
+- Follow MCP protocol specifications
+- Document all available tools and resources
+- Include security and monitoring configurations
+- Provide integration examples
+
+#### Queries (`queries/`)
+
+- Make queries parameterizable where possible
+- Document expected inputs and outputs
+- Specify compatible agents and teams
+- Include usage examples
+
+#### Projects (`projects/`)
+
+- Provide complete, self-contained Ark project structures
+- Include comprehensive documentation with architecture overview
+- Specify all required dependencies (models, tools, external services)
+- Provide clear setup and deployment instructions
+- Include working examples and sample data where applicable
+- Document the use case and target scenarios
+- Follow Ark best practices for resource organization
+- Include multiple components working together (agents, teams, tools, etc.)
+
+### Quality Standards
+
+All contributions must meet these standards:
+
+- ✅ **Documentation** - Clear README with setup and usage instructions
+- ✅ **Security** - Follow security best practices
+- ✅ **Compatibility** - Work with latest Ark version
+- ✅ **Examples** - Provide working usage examples
+- ✅ **Validation** - Pass all automated validation checks
+
+### Submission Process
+
+1. **Create** your component following the guidelines above
+2. **Run** validation scripts: `scripts/validate-component.sh <component-path>`
+3. **Test** your component in a real environment
+4. **Submit** pull request with:
+   - Clear description of the component's purpose
+   - Usage examples and test results
+   - Documentation of any dependencies
+   - Screenshots or demos if applicable
+
+### Review Process
+
+1. **Automated Checks** - CI pipeline validates component structure and security
+2. **Community Review** - Other contributors provide feedback
+3. **Maintainer Review** - Core team performs final review
+4. **Approval** - Component is merged and becomes available
+
+## Using Marketplace Components
+
+### Finding Components
+
+- Browse directories by component type
+- Check `README.md` files for detailed descriptions
+- Look for tags and categories in component metadata
+- Use GitHub search to find specific functionality
+
+### Installing Components
+
+1. **Copy** the component files to your project
+2. **Customize** configuration as needed
+3. **Install** any dependencies listed in component README
+4. **Test** the component in your environment
+5. **Deploy** following your project's deployment process
+
+### Component Versioning
+
+Components follow semantic versioning:
+
+- **Major** - Breaking changes requiring migration
+- **Minor** - New features, backward compatible
+- **Patch** - Bug fixes and minor improvements
+
+## Support and Community
+
+### Getting Help
+
+- 📖 **Documentation** - Check `docs/` directory for guides
+- 💬 **Discussions** - Use GitHub Discussions for questions
+- 🐛 **Issues** - Report bugs or request features via GitHub Issues
+- 📧 **Contact** - Reach out to maintainers for urgent matters
+
+### Contributing Beyond Components
+
+We welcome contributions in many forms:
+
+- 📝 **Documentation** improvements
+- 🧪 **Testing** and validation improvements
+- 🔧 **Tooling** and automation enhancements
+- 🎨 **Templates** and examples
+- 🔍 **Reviews** and feedback on submissions
+
+## Governance
+
+### Maintainers
+
+The marketplace is maintained by the core team and trusted community contributors.
+
+### Licensing
+
+All contributions must be compatible with the project license. By contributing, you agree to license your contributions under the same terms.
+
+### Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). Please read and follow these guidelines in all interactions.
+
+## Quick Start
+
+Ready to contribute? Start here:
+
+1. **Explore** existing components for inspiration
+2. **Choose** a template from `templates/` directory
+3. **Read** the component-specific guidelines in `docs/`
+4. **Create** your component following the standards
+5. **Submit** your pull request
+
+Thank you for contributing to the {{ .Values.projectName }} Marketplace! 🚀

package/templates/marketplace/agents/.keep

@@ -0,0 +1,29 @@
+# Agents Directory
+
+This directory contains reusable agent definitions that can be shared across projects.
+
+## Structure
+
+Each agent should be in its own file or subdirectory (complex agents) with:
+
+- agent.yaml (the main agent definition)
+- README.md (documentation)
+- examples/ (optional usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the agent's purpose:
+
+- data-analyst/
+- code-reviewer/
+- security-scanner/
+- documentation-writer/
+
+## Contributing
+
+When contributing an agent:
+
+1. Ensure it follows the Ark agent specification
+2. Include comprehensive documentation
+3. Provide usage examples
+4. Test with multiple models when possible

package/templates/marketplace/docs/.keep

@@ -0,0 +1,19 @@
+# Documentation Directory
+
+Documentation for the marketplace and its components.
+
+## Structure
+
+- contributing.md - Guidelines for contributors
+- component-specs/ - Specifications for different component types
+- best-practices/ - Development and usage best practices
+- tutorials/ - Step-by-step guides
+- api/ - API documentation
+
+## Documentation Standards
+
+1. Use clear, concise language
+2. Include code examples
+3. Keep documentation up-to-date
+4. Follow markdown conventions
+5. Include diagrams where helpful

package/templates/marketplace/mcp-servers/.keep

@@ -0,0 +1,32 @@
+# MCP Servers Directory
+
+This directory contains Model Context Protocol (MCP) server configurations and implementations.
+
+## Structure
+
+Each MCP server should be in its own subdirectory with:
+
+- mcp-server.yaml (server configuration)
+- src/ (source code if custom implementation)
+- Dockerfile (if containerized)
+- README.md (documentation)
+- examples/ (usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the server's purpose:
+
+- file-system-server/
+- database-server/
+- api-gateway-server/
+- knowledge-base-server/
+
+## Contributing
+
+When contributing an MCP server:
+
+1. Follow MCP protocol specifications
+2. Include security configurations
+3. Document all available tools/resources
+4. Provide integration examples
+5. Include monitoring and logging setup

package/templates/marketplace/models/.keep

@@ -0,0 +1,23 @@
+# Models Directory
+
+This directory contains model configurations for different AI providers and use cases.
+
+## Structure
+Each model configuration should be:
+- provider-specific directories (openai/, anthropic/, etc.)
+- model-specific YAML files within each directory
+- README.md documenting capabilities and limitations
+
+## Naming Convention
+Use provider and model names:
+- openai/gpt-4.yaml
+- anthropic/claude-3-sonnet.yaml
+- azure/gpt-4-32k.yaml
+- local/llama2-7b.yaml
+
+## Contributing
+When contributing a model configuration:
+1. Include provider-specific settings
+2. Document token limits and capabilities
+3. Specify recommended use cases
+4. Include cost considerations if applicable

package/templates/marketplace/projects/.keep

@@ -0,0 +1,43 @@
+# Projects Directory
+
+This directory contains complete, reusable Ark projects that demonstrate comprehensive use cases and multi-component solutions.
+
+## Purpose
+
+- **Full Project Templates**: Complete Ark project structures with multiple agents, teams, models, and tools working together
+- **End-to-End Solutions**: Real-world scenarios that showcase complex workflows and integrations
+- **Reference Implementations**: Best practices for structuring large-scale Ark deployments
+
+## Structure Guidelines
+
+Each project should include:
+
+- **Complete project structure**: All necessary YAML configurations
+- **README.md**: Detailed setup instructions, use case description, and architecture overview
+- **Documentation**: Architecture diagrams, workflow explanations, and deployment guides
+- **Examples**: Sample queries and expected outputs
+- **Dependencies**: Clear list of required models, tools, and external services
+
+## Naming Convention
+
+Use descriptive names that indicate the use case:
+
+- `customer-support-workflow/` - Multi-agent customer service system
+- `research-assistant-pipeline/` - Academic research and analysis workflow
+- `content-generation-studio/` - Creative content production system
+
+## Project Requirements
+
+- Each project must be self-contained and deployable
+- Include comprehensive documentation
+- Provide clear setup and configuration instructions
+- Include sample data or test cases where applicable
+- Follow Ark best practices for resource organization
+
+## Examples
+
+- Multi-agent workflows with specialized roles
+- Integration with external APIs and services
+- Complex data processing pipelines
+- Cross-functional team collaboration scenarios
+- Industry-specific solution templates

package/templates/marketplace/queries/.keep

@@ -0,0 +1,25 @@
+# Queries Directory
+
+This directory contains reusable query templates for common use cases.
+
+## Structure
+Each query should be in its own file or subdirectory:
+- query-name.yaml (simple queries)
+- complex-query/ (for queries with multiple files)
+  - query.yaml
+  - README.md
+  - examples/
+
+## Naming Convention
+Use descriptive names that indicate the query's purpose:
+- code-analysis.yaml
+- data-transformation.yaml
+- security-audit.yaml
+- document-summarization.yaml
+
+## Contributing
+When contributing a query:
+1. Make it parameterizable where possible
+2. Include clear documentation of expected inputs
+3. Provide example outputs
+4. Specify compatible agents/teams

package/templates/marketplace/teams/.keep

@@ -0,0 +1,29 @@
+# Teams Directory
+
+This directory contains reusable team configurations for multi-agent workflows.
+
+## Structure
+
+Each team should be in its own file (simple) or subdirectory (complex) with:
+
+- team.yaml (the main team definition)
+- README.md (documentation describing the workflow)
+- examples/ (optional usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the team's workflow:
+
+- code-review-team/
+- data-pipeline-team/
+- content-creation-team/
+- security-audit-team/
+
+## Contributing
+
+When contributing a team:
+
+1. Document the team's workflow and strategy
+2. Explain when to use this team configuration
+3. Include examples of typical inputs and outputs
+4. Test the team configuration thoroughly

package/templates/marketplace/tools/.keep

@@ -0,0 +1,32 @@
+# Tools Directory
+
+This directory contains reusable tool definitions for extending agent capabilities.
+
+## Structure
+
+Each tool should be in its own subdirectory with:
+
+- tool.yaml (the main tool definition)
+- src/ (source code if applicable)
+- Dockerfile (if containerized)
+- README.md (documentation)
+- examples/ (usage examples)
+
+## Naming Convention
+
+Use descriptive names that indicate the tool's function:
+
+- file-processor/
+- database-connector/
+- api-client/
+- data-validator/
+
+## Contributing
+
+When contributing a tool:
+
+1. Follow the Ark tool specification
+2. Include comprehensive documentation
+3. Provide usage examples
+4. Ensure proper error handling
+5. Include security considerations

package/templates/marketplace/tools/examples/.keep

@@ -0,0 +1,17 @@
+# Tool Examples Directory
+
+This directory contains example tool implementations that can serve as templates.
+
+Examples should demonstrate:
+
+- Best practices for tool development
+- Common patterns and use cases
+- Integration with different agent types
+- Error handling and logging
+
+Each example should include:
+
+- Complete source code
+- Documentation
+- Build instructions
+- Testing guidelines