Implement Phase 1.2: Schema Design & Validation System

.eslintrc.js

@@ -55,6 +55,15 @@ module.exports = {
       rules: {
         '@typescript-eslint/no-var-requires': 'off'
       }
+    },
+    {
+      files: ['scripts/**/*.ts'],
+      parserOptions: {
+        project: null
+      },
+      rules: {
+        'no-console': 'off'
+      }
     }
   ]
 };

.gitignore

@@ -10,6 +10,11 @@ build/
 lib/
 *.tsbuildinfo
 
+# Compiled scripts
+scripts/**/*.js
+scripts/**/*.d.ts
+scripts/**/*.map
+
 # Environment variables
 .env
 .env.local

docs/api/configuration-schema.md

@@ -0,0 +1,286 @@
+# Configuration Schema Reference
+
+This document provides a comprehensive reference for the Agents CLI configuration schema.
+
+## Overview
+
+Agents CLI uses a JSON or YAML configuration file to define agents, workflows, and their behavior.
+The configuration is validated using Zod schemas to ensure correctness before execution.
+
+## Configuration File Structure
+
+```typescript
+{
+  "metadata": {
+    "name": "string",
+    "description": "string",
+    "version": "string",
+    "author": "string"
+  },
+  "agents": {
+    "[agent_id]": {
+      // Agent configuration
+    }
+  },
+  "workflow": {
+    // Workflow configuration
+  }
+}
+```
+
+## Metadata (Optional)
+
+Configuration metadata for documentation and versioning.
+
+| Field         | Type   | Required | Description                            |
+| ------------- | ------ | -------- | -------------------------------------- |
+| `name`        | string | No       | Configuration name                     |
+| `description` | string | No       | Configuration description              |
+| `version`     | string | No       | Configuration version (default: "1.0") |
+| `author`      | string | No       | Configuration author                   |
+| `created`     | string | No       | Creation timestamp (ISO 8601)          |
+| `updated`     | string | No       | Last update timestamp (ISO 8601)       |
+
+## Agents Configuration
+
+The `agents` object contains one or more agent configurations, keyed by agent ID.
+
+### Agent Configuration
+
+| Field           | Type   | Required | Default  | Description                        |
+| --------------- | ------ | -------- | -------- | ---------------------------------- |
+| `name`          | string | Yes      | -        | Human-readable agent name          |
+| `instructions`  | string | Yes      | -        | Agent's system instructions/prompt |
+| `model`         | string | No       | "gpt-4o" | OpenAI model to use                |
+| `modelSettings` | object | No       | -        | Model fine-tuning parameters       |
+| `tools`         | array  | No       | []       | Tools available to the agent       |
+| `guardrails`    | array  | No       | []       | Safety guardrails                  |
+| `handoffs`      | array  | No       | []       | Other agents to hand off to        |
+| `memory`        | object | No       | -        | Memory configuration               |
+| `context`       | object | No       | -        | Context management settings        |
+| `metadata`      | object | No       | -        | Custom metadata                    |
+
+### Model Options
+
+Supported models:
+
+**High Performance:**
+
+- `gpt-4o` (default, flagship model)
+- `o1-preview`
+- `o1`
+
+**Low Cost:**
+
+- `gpt-4o-mini`
+- `gpt-3.5-turbo`
+- `o1-mini`
+
+### Model Settings
+
+| Field               | Type   | Range   | Description                |
+| ------------------- | ------ | ------- | -------------------------- |
+| `temperature`       | number | 0-1     | Sampling temperature       |
+| `top_p`             | number | 0-1     | Nucleus sampling parameter |
+| `max_tokens`        | number | >0      | Maximum tokens in response |
+| `presence_penalty`  | number | -2 to 2 | Presence penalty           |
+| `frequency_penalty` | number | -2 to 2 | Frequency penalty          |
+
+### Tools Configuration
+
+Tools can be specified as:
+
+1. **Built-in tool names** (strings):
+   - `file_operations`
+   - `git_tools`
+   - `web_search`
+   - `security_scanner`
+
+2. **MCP Server configuration** (object):
+
+   ```json
+   {
+     "type": "mcp_server",
+     "name": "server-name",
+     "command": "npx",
+     "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+     "env": { "PATH": "/usr/bin" }
+   }
+   ```
+
+3. **Custom function tool** (object):
+   ```json
+   {
+     "type": "custom_function",
+     "name": "my_tool",
+     "description": "Tool description",
+     "parameters": {},
+     "handler": "./path/to/handler.js"
+   }
+   ```
+
+### Guardrails
+
+Built-in guardrails:
+
+- `no_destructive_operations` - Prevent destructive file/git operations
+- `require_approval` - Require human approval for actions
+- `file_access_control` - Restrict file system access
+- `rate_limiting` - Limit API call rate
+- `content_filtering` - Filter sensitive content
+
+### Handoffs
+
+Handoffs enable agent-to-agent delegation. Specify as:
+
+- **Simple string**: Agent ID to hand off to
+- **Handoff rule object**:
+  ```json
+  {
+    "target_agent": "agent_id",
+    "condition": "when to hand off",
+    "priority": 1
+  }
+  ```
+
+### Memory Configuration
+
+| Field         | Type    | Default   | Description                                 |
+| ------------- | ------- | --------- | ------------------------------------------- |
+| `enabled`     | boolean | true      | Enable conversation memory                  |
+| `max_turns`   | number  | -         | Maximum turns to remember                   |
+| `max_tokens`  | number  | -         | Maximum tokens to store                     |
+| `persistence` | string  | "session" | Persistence level: none, session, permanent |
+
+### Context Configuration
+
+| Field                | Type    | Default | Description                    |
+| -------------------- | ------- | ------- | ------------------------------ |
+| `max_context_length` | number  | -       | Maximum context length         |
+| `context_window`     | number  | -       | Context window size            |
+| `summarization`      | boolean | false   | Enable automatic summarization |
+
+## Workflow Configuration
+
+The `workflow` object defines how agents are orchestrated.
+
+| Field         | Type   | Required | Default      | Description            |
+| ------------- | ------ | -------- | ------------ | ---------------------- |
+| `entry_point` | string | Yes      | -            | Agent ID to start with |
+| `pattern`     | string | No       | "sequential" | Execution pattern      |
+| `output`      | object | No       | -            | Output format settings |
+| `limits`      | object | No       | -            | Resource limits        |
+
+### Workflow Patterns
+
+- `sequential` - Execute agents in sequence
+- `handoff_chain` - Agents hand off to each other
+- `parallel` - Execute agents in parallel
+- `conditional` - Conditional agent execution
+
+### Output Format
+
+| Field              | Type    | Default | Description                                     |
+| ------------------ | ------- | ------- | ----------------------------------------------- |
+| `format`           | string  | "json"  | Output format: json, text, markdown, structured |
+| `stream`           | boolean | false   | Enable streaming output                         |
+| `include_metadata` | boolean | true    | Include metadata in output                      |
+| `include_trace`    | boolean | false   | Include execution trace                         |
+
+### Resource Limits
+
+| Field                   | Type   | Default | Description           |
+| ----------------------- | ------ | ------- | --------------------- |
+| `max_turns`             | number | 10      | Maximum agent turns   |
+| `timeout`               | number | 300     | Timeout in seconds    |
+| `max_tokens`            | number | -       | Maximum total tokens  |
+| `max_concurrent_agents` | number | -       | Max concurrent agents |
+
+## Environment Variables
+
+Configuration files support environment variable substitution using the syntax:
+
+- `${VAR_NAME}` - Use environment variable
+- `${VAR_NAME:-default}` - Use variable with default fallback
+
+Example:
+
+```json
+{
+  "agents": {
+    "assistant": {
+      "model": "${OPENAI_MODEL:-gpt-4o}",
+      "name": "Assistant"
+    }
+  }
+}
+```
+
+## Configuration File Discovery
+
+Agents CLI automatically discovers configuration files in this order:
+
+1. `agents-cli.json`
+2. `agents-cli.yaml`
+3. `agents-cli.yml`
+4. `agents.config.json`
+5. `agents.config.yaml`
+6. `agents.config.yml`
+7. `.agents-cli.json`
+8. `.agents-cli.yaml`
+
+## Examples
+
+See the [examples directory](../../examples/) for complete configuration examples:
+
+- [simple.json](../../examples/simple.json) - Minimal single-agent example
+- [code-review.json](../../examples/code-review.json) - Multi-agent code review
+- [architecture-review.json](../../examples/architecture-review.json) - Architecture analysis
+
+## JSON Schema
+
+The complete JSON Schema is available at
+[schemas/configuration.schema.json](schemas/configuration.schema.json) for IDE integration and
+validation.
+
+## Validation
+
+Validate your configuration using the CLI:
+
+```bash
+# Basic validation
+agents-cli validate config.json
+
+# Verbose output
+agents-cli validate config.json --verbose
+
+# JSON output
+agents-cli validate config.json --format json
+
+# Hide warnings
+agents-cli validate config.json --no-warnings
+```
+
+## IDE Integration
+
+For IDE autocomplete and validation, configure your editor to use the JSON schema:
+
+### VS Code
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["**/agents-cli.json", "**/agents.config.json"],
+      "url": "./docs/api/schemas/configuration.schema.json"
+    }
+  ]
+}
+```
+
+### JetBrains IDEs
+
+Go to Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings and add the schema
+mapping.