Hydra Manifest Specification (HMS) v1.0

The official JSON-based standard for defining Hydra workflows.

Overview

The Hydra Manifest Specification (HMS) provides a declarative, schema-based format for defining AI-assisted development workflows. HMS manifests are:

Declarative – Define what should happen, not how
Portable – Work across different AI IDEs
Type-safe – Validated against JSON Schema
Composable – Steps can depend on other steps

JSON Schema

https://hydra.opiusai.com/schemas/workflow/v1.0.json

Use this schema for IDE autocomplete and validation.

Root Fields

`$schema` (required)

Type: string
Value: https://hydra.opiusai.com/schemas/workflow/v1.0.json

Schema identifier declaring HMS v1.0 conformance.

{
  "$schema": "https://hydra.opiusai.com/schemas/workflow/v1.0.json"
}

`manifest_version` (required)

Type: string
Format: "major.minor" (e.g., "1.0")

Version of the HMS format being used.

{
  "manifest_version": "1.0"
}

`name` (required)

Type: string
Length: 1-200 characters

Human-readable name for the workflow.

{
  "name": "Bug Fix Workflow"
}

`intent` (optional)

Type: string
Length: Up to 500 characters

High-level description of what the workflow accomplishes.

{
  "intent": "Identify, fix, and validate a reported bug with comprehensive tests"
}

`context` (optional)

Type: object

Contextual information about the project or environment.

{
  "context": {
    "repo": "my-project",
    "entrypoint": "src/index.ts",
    "language": "typescript",
    "framework": "React",
    "connectors": ["GitHub", "Slack"]
  }
}

Standard Context Fields

Field	Type	Description
`repo`	string	Repository name or identifier
`entrypoint`	string	Main file or directory path
`language`	string	Programming language
`framework`	string	Framework name
`connectors`	string[]	MCP connectors to use

Additional custom fields are allowed.

`steps` (required)

Type: array
Min items: 1

Ordered list of workflow steps. See Steps section.

`outputs` (optional)

Type: object

Expected outputs from the workflow. See Outputs section.

`adapters` (optional)

Type: object

IDE-specific execution configurations. See Adapters section.

`inputs` (optional)

Type: object

Runtime input parameters that users provide when invoking the workflow. See Inputs section.

{
  "inputs": {
    "bug_description": {
      "type": "string",
      "description": "Description of the bug to fix",
      "required": true
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium"
    }
  }
}

Steps Array

Each step in the steps array defines a discrete action.

Step Fields

`id` (required)

Type: string
Format: snake_case

Unique identifier for the step within this workflow.

{
  "id": "analyze_code"
}

`name` (required)

Type: string

Human-readable name for the step.

{
  "name": "Analyze code for bugs"
}

`action` (required)

Type: string
Enum: See Actions Reference

The type of action this step performs.

{
  "action": "analyze_code"
}

`agent` (optional)

Type: string

Agent specialization for this step. Used to spawn specialized sub-agents.

{
  "agent": "security_expert"
}

`depends_on` (optional)

Type: array of string

Step IDs that must complete before this step executes.

{
  "depends_on": ["analyze_code", "identify_issues"]
}

`parameters` (optional)

Type: object

Step-specific parameters and configuration.

{
  "parameters": {
    "files": ["src/auth/login.ts"],
    "focus": "security vulnerabilities",
    "coverage_target": 80
  }
}

Common Parameters

Parameter	Type	Description
`files`	string[]	File paths to operate on
`focus`	string	What to focus on
`command`	string	Shell command to execute
`test_framework`	string	Testing framework name
`coverage_target`	number	Coverage percentage target
`connectors`	string[]	Connectors for this step

Outputs

Define expected workflow outputs.

`type` (required)

Type: string
Enum: "code", "documentation", "analysis", "mixed"

Primary type of output produced.

`schema` (optional)

Type: object (JSON Schema)

Structured schema defining the output format.

{
  "outputs": {
    "type": "code",
    "schema": {
      "type": "object",
      "properties": {
        "fixed_files": {
          "type": "array",
          "items": { "type": "string" }
        },
        "test_coverage": { "type": "number" }
      },
      "required": ["fixed_files"]
    }
  }
}

`expected_files` (optional)

Type: array of string

File paths expected to be created or modified.

{
  "outputs": {
    "type": "code",
    "expected_files": ["src/bugfix.ts", "tests/bugfix.test.ts"]
  }
}

Adapters

Configure IDE-specific behavior. See Adapters Reference for details.

Structure

{
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": { ... }
    },
    "cursor": {
      "mode": "direct",
      "config": { ... }
    },
    "codex": {
      "mode": "direct",
      "config": { ... }
    }
  }
}

`mode` (required)

Type: string
Enum: "sub_agent", "direct", "sequential", "parallel"

Execution mode for the adapter.

Mode	Description
`sub_agent`	Spawn sub-agent per step
`direct`	Execute in main agent
`sequential`	Force sequential execution
`parallel`	Allow parallel execution

`config` (optional)

Adapter-specific configuration options. See Adapters Reference.

Inputs

Define runtime input parameters that users provide when invoking the workflow. Inputs allow workflows to be parameterized and reusable.

Structure

{
  "inputs": {
    "bug_description": {
      "type": "string",
      "description": "Description of the bug to fix",
      "required": true
    },
    "target_files": {
      "type": "array",
      "description": "Files to analyze",
      "items": { "type": "string" }
    },
    "coverage_target": {
      "type": "number",
      "description": "Minimum test coverage percentage",
      "default": 80,
      "minimum": 0,
      "maximum": 100
    }
  }
}

Input Field Properties

Property	Type	Description
`type`	string	Data type: `"string"`, `"number"`, `"boolean"`, `"object"`, `"array"`
`description`	string	Human-readable description
`required`	boolean	Whether input must be provided (default: false)
`default`	any	Default value if not provided
`enum`	string[]	Allowed values for string inputs
`minimum`	number	Minimum value for numbers
`maximum`	number	Maximum value for numbers
`minLength`	number	Minimum length for strings/arrays
`maxLength`	number	Maximum length for strings/arrays
`items`	object	JSON Schema for array item types
`properties`	object	JSON Schema for object properties

Using Inputs in Steps

Reference input values in step parameters using the {{input.inputName}} syntax:

{
  "steps": [
    {
      "id": "analyze_bug",
      "name": "Analyze the bug",
      "action": "analyze_code",
      "parameters": {
        "focus": "{{input.bug_description}}",
        "files": "{{input.target_files}}"
      }
    },
    {
      "id": "write_tests",
      "name": "Write tests",
      "action": "generate_tests",
      "parameters": {
        "coverage_target": "{{input.coverage_target}}"
      }
    }
  ]
}

Input Validation

Inputs are validated at runtime when a workflow is invoked:

Required inputs must be provided
Type checking ensures values match declared types
Enum validation restricts string values to allowed options
Range validation enforces min/max constraints

Validation Rules

Step IDs must be unique within a workflow
Dependencies must reference valid step IDs
Circular dependencies are not allowed
Action types must be from the allowed enum
$schema URL must be exact
Step IDs must use snake_case
At least one step is required

Complete Example

{
  "$schema": "https://hydra.opiusai.com/schemas/workflow/v1.0.json",
  "manifest_version": "1.0",
  "name": "Full Stack Feature Workflow",
  "intent": "Implement a complete feature with frontend, backend, and tests",
  "context": {
    "repo": "my-fullstack-app",
    "language": "typescript",
    "framework": "Next.js",
    "connectors": ["GitHub", "Figma"]
  },
  "inputs": {
    "feature_name": {
      "type": "string",
      "description": "Name of the feature to implement",
      "required": true
    },
    "coverage_target": {
      "type": "number",
      "description": "Minimum test coverage percentage",
      "default": 80,
      "minimum": 50,
      "maximum": 100
    }
  },
  "steps": [
    {
      "id": "analyze_requirements",
      "name": "Analyze requirements",
      "action": "analyze_code",
      "agent": "architect",
      "parameters": {
        "focus": "existing patterns, API structure for {{input.feature_name}}"
      }
    },
    {
      "id": "design_api",
      "name": "Design API endpoints",
      "action": "design_architecture",
      "depends_on": ["analyze_requirements"]
    },
    {
      "id": "implement_backend",
      "name": "Implement backend",
      "action": "generate_code",
      "depends_on": ["design_api"],
      "parameters": {
        "files": ["src/api/**/*.ts"]
      }
    },
    {
      "id": "implement_frontend",
      "name": "Implement frontend",
      "action": "generate_code",
      "depends_on": ["design_api"],
      "parameters": {
        "files": ["src/components/**/*.tsx"]
      }
    },
    {
      "id": "write_tests",
      "name": "Write tests",
      "action": "generate_tests",
      "depends_on": ["implement_backend", "implement_frontend"],
      "parameters": {
        "test_framework": "Jest",
        "coverage_target": "{{input.coverage_target}}"
      }
    },
    {
      "id": "run_tests",
      "name": "Run tests",
      "action": "execute_command",
      "depends_on": ["write_tests"],
      "parameters": {
        "command": "npm test"
      }
    },
    {
      "id": "commit",
      "name": "Review and commit",
      "action": "review_and_commit",
      "depends_on": ["run_tests"]
    }
  ],
  "outputs": {
    "type": "code",
    "expected_files": [
      "src/api/**/*.ts",
      "src/components/**/*.tsx",
      "tests/**/*.test.ts"
    ]
  },
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": {
        "spawn_agents_per_step": true,
        "max_parallel_agents": 2
      }
    },
    "cursor": {
      "mode": "parallel",
      "config": {
        "use_composer": true,
        "show_diff": true
      }
    }
  }
}

TypeScript Types

HMS types are available in the @hydra/shared package:

import type {
  HydraManifest,
  ManifestStep,
  ManifestAction,
  ManifestContext,
  ManifestOutputs,
  ManifestAdapters,
  AdapterConfig,
  AdapterMode,
  WorkflowInputs,
  WorkflowInput,
  WorkflowInputType
} from '@hydra/shared';

Version History

Version	Date	Changes
1.0.1	2024-11	Added `inputs` field for runtime workflow parameters
1.0	2024-01	Initial release

Troubleshooting & FAQ HMS Schema (Generated)

Hydra Manifest Specification (HMS) v1.0

Overview

JSON Schema

Root Fields

$schema (required)

manifest_version (required)

name (required)

intent (optional)

context (optional)

Standard Context Fields

steps (required)

outputs (optional)

adapters (optional)

inputs (optional)

Steps Array

Step Fields

id (required)

name (required)

action (required)

agent (optional)

depends_on (optional)

parameters (optional)

Common Parameters

Outputs

type (required)

schema (optional)

expected_files (optional)

Adapters

Structure

mode (required)

config (optional)

Inputs

Structure

Input Field Properties

Using Inputs in Steps

Input Validation

Validation Rules

Complete Example

TypeScript Types

Version History

Related

`$schema` (required)

`manifest_version` (required)

`name` (required)

`intent` (optional)

`context` (optional)

`steps` (required)

`outputs` (optional)

`adapters` (optional)

`inputs` (optional)

`id` (required)

`name` (required)

`action` (required)

`agent` (optional)

`depends_on` (optional)

`parameters` (optional)

`type` (required)

`schema` (optional)

`expected_files` (optional)

`mode` (required)

`config` (optional)