agent-contracts 0.0.1 → 0.5.0

package/README.md

@@ -1,48 +1,259 @@
+
 # agent-contracts
 
-A toolkit for declaratively defining multi-agent development workflows in **YAML DSL**, with static validation, linting, and prompt rendering.
+**Design multi-agent systems as contracts.**
 
-## Features
+`agent-contracts` is a toolkit for declaratively defining multi-agent development workflows in **YAML DSL**, with **static validation, semantic linting, and prompt rendering**.
+
+It is designed for teams that need more than “agents that happen to work”.
+It helps you define, validate, and evolve:
+
+- who each agent is
+- what tasks can be delegated
+- which artifacts exist and who owns them
+- what validations are required
+- how handoffs are structured
+- how prompts are rendered from the design itself
+
+Instead of letting workflow rules live only in prompts and code, `agent-contracts` makes the system **explicit, reviewable, and CI-checkable**.
+
+---
+
+## Why agent-contracts?
+
+Most agent frameworks focus on **runtime execution**.
+
+`agent-contracts` focuses on **design-time guarantees**.
+
+As multi-agent systems grow, teams usually run into the same problems:
+
+- agent responsibilities become ambiguous
+- handoff rules drift across prompts
+- artifact ownership is unclear
+- validation logic is inconsistent
+- prompts diverge from the intended workflow
+- shared team conventions stop being enforceable
+
+`agent-contracts` addresses this by treating your agent workflow as a **contract**, not just a set of prompts.
+
+You can think of it as:
+
+- **OpenAPI for multi-agent workflows**
+- **a contract layer above runtime orchestration**
+- **a source of truth for agent roles, handoffs, and artifact flows**
+
+---
+
+## Who this is for
 
-- **Define agent responsibilities, permissions, and handoff relationships** in structured YAML
-- **Track artifact ownership, editors, consumers, and validation requirements**
-- **Detect design flaws statically** via Schema Validation + Semantic Lint
-- **Define and validate handoff payloads** with structured schemas
-- **Generate static agent prompts (md)** from Handlebars templates via Prompt Renderer
-- **Separate common and project-specific definitions** using the `extends` inheritance mechanism
+`agent-contracts` is a strong fit for teams that build or operate:
 
-## Design Philosophy
+- multi-agent coding workflows
+- spec → implement → audit → release style pipelines
+- internal agent platforms
+- review-heavy or gate-heavy delivery processes
+- agent systems where artifact ownership matters
+- reusable team definitions shared across projects
 
-Just as OpenAPI represents "API contracts," agent-contracts expresses **the entire operational design — including agent organization, artifacts, validation, and handoffs** — in YAML.
+Typical users include:
 
-### 3-Layer Model
+- platform teams standardizing agent workflows
+- engineering teams building internal coding/review agents
+- products that require explicit validation and handoff policies
+- teams that want CI enforcement for agent design consistency
 
-| Layer | Role | Defined in |
-|---|---|---|
-| **Agent** | Capability declaration and general behavioral spec of the execution entity | `agents` |
-| **Task** | Work type that can be delegated to an agent, with task-specific behavioral spec | `tasks` |
-| **Handoff** | A concrete delegation instance | Generated at runtime |
+---
+
+## Who this is not for
+
+`agent-contracts` is probably **not** the right starting point if you want:
+
+- a single-agent chatbot
+- a quick prompt prototype
+- an all-in-one hosted agent runtime
+- built-in scheduling, memory, tracing, or hosting
+- a purely code-first orchestration style with no declarative spec
+- maximum flexibility with minimal process constraints
+
+In short:
+
+- if you want to **run agents quickly**, start with a runtime framework
+- if you want to **design multi-agent systems that stay coherent over time**, use `agent-contracts`
+
+---
+
+## What makes it different?
 
-### Definition Inheritance and Override
+`agent-contracts` does not try to replace every agent framework.
 
-```text
-base definition (shared team definition)
-  ↓ project definition references base via extends
-    ↓ id-based deep merge + merge operators apply diffs
-      → resolved YAML (final result)
-```
+It occupies a different layer.
 
-2-layer model. Priority: **project > base**
+### Positioning
+
+| Product / approach | Primary focus | Best fit | How `agent-contracts` differs |
+|---|---|---|---|
+| **OpenAI Agents SDK** | runtime execution with instructions, tools, and handoffs | apps built around agent runtime behavior | `agent-contracts` focuses on design contracts, static guarantees, and artifact relationships |
+| **CrewAI** | agent/task workflow orchestration | teams that want runtime task execution in YAML | `agent-contracts` goes deeper on validation, ownership, inheritance, and renderable design specs |
+| **AutoGen** | code-first multi-agent programming | research or custom orchestration flows | `agent-contracts` is more declarative, reviewable, and CI-oriented |
+| **Google ADK style patterns** | choosing runtime interaction patterns | production systems built around runtime composition | `agent-contracts` is framework-agnostic and centered on workflow design as a contract |
+
+The key distinction is simple:
+
+> Other frameworks mainly answer: **How do I run these agents?**  
+> `agent-contracts` answers: **What is the allowed structure of this agent system, and how do we keep it correct as it evolves?**
+
+This positioning is consistent with common industry patterns: some frameworks center the agent runtime, others separate agent definition and task invocation, but `agent-contracts` is strongest as a **design-time contract layer** across those execution models.
 
 ---
 
-## DSL Structure
+## Quick Start
 
-### Top Level
+Define your system in a single YAML file:
 
 ```yaml
+# agent-contracts.yaml
 version: 1
-extends: "@agent-contracts/base-team"  # Inheritance source (optional; standalone if omitted)
+system:
+  id: my-project
+  name: My Agent Workflow
+  default_phase_order: [design, implement]
+
+agents:
+  architect:
+    role_name: "Architect"
+    purpose: "Drive phases and delegate work"
+    can_invoke_agents: [implementer]
+
+  implementer:
+    role_name: "Implementer"
+    purpose: "Implement features based on specs"
+
+tasks:
+  implement-feature:
+    description: "Delegate feature implementation"
+    target_agent: implementer
+    allowed_from_agents: [architect]
+    phase: implement
+    input_artifacts: [spec-md]
+    invocation_handoff: task-delegation
+    result_handoff: implementation-result
+
+artifacts:
+  spec-md:
+    type: document
+    owner: architect
+    producers: [architect]
+    editors: [architect]
+    consumers: [implementer]
+    states: [draft, reviewed, approved]
+````
+
+Validate and render:
+
+````bash
+agent-contracts validate
+agent-contracts render -c agent-contracts.config.yaml
+````
+
+
+A working example is available in [`sample/`](./sample), including:
+
+* [`sample/agent-contracts.yaml`](./sample/agent-contracts.yaml)
+* [`sample/agent-contracts.config.yaml`](./sample/agent-contracts.config.yaml)
+* [`sample/templates`](./sample/templates)
+* [`sample/output`](./sample/output)
+
+---
+
+## Core concepts
+
+### Agent
+
+An **Agent** defines who an execution entity is:
+
+* role name
+* purpose
+* capabilities
+* permissions
+* constraints
+* behavioral rules
+
+### Task
+
+A **Task** defines a delegatable unit of work:
+
+* target agent
+* allowed callers
+* phase
+* input artifacts
+* invocation/result handoffs
+* task-specific execution expectations
+
+### Artifact
+
+An **Artifact** defines the objects that move through the workflow:
+
+* owner
+* producers
+* editors
+* consumers
+* states
+* required validations
+* visibility
+
+### Handoff
+
+A **Handoff** is a runtime delegation instance.
+The YAML defines the allowed handoff types and constraints; concrete handoffs are created at runtime.
+
+---
+
+## Why teams adopt it
+
+### 1. Explicit workflow design
+
+Your architecture stops living only in prompts, code, and tribal knowledge.
+
+### 2. Static guarantees before runtime
+
+You can catch broken references, invalid ownership, missing validations, and workflow inconsistencies before execution.
+
+### 3. Prompt generation from source of truth
+
+Rendered prompts come from the same DSL that defines roles, tasks, artifacts, and policies.
+
+### 4. Reuse across teams and projects
+
+Shared base definitions can be extended safely with `extends`.
+
+### 5. Better CI discipline
+
+Design regressions become testable.
+
+---
+
+## Features
+
+* **Declarative YAML DSL** for multi-agent development workflows
+* **Static schema validation**
+* **Reference integrity checks**
+* **Semantic linting**
+* **Structured handoff definitions**
+* **Artifact ownership and lifecycle modeling**
+* **Config-driven prompt rendering**
+* **Inheritance with merge operators via `extends`**
+* **JSON Schema for editor support and external tooling**
+* **CI-friendly workflow checks**
+
+---
+
+## DSL structure
+
+Entities are defined as **maps keyed by ID**.
+
+````yaml
+version: 1
+extends: "./base/"
 
 system:
   id: my-project
@@ -56,35 +267,33 @@ system:
     - release
     - reflect
 
-agents: []
-tasks: []
-artifacts: []
-tools: []
-validations: []
-handoff_types: []
-workflow: []
-policies: []
-```
+agents: {}
+tasks: {}
+artifacts: {}
+tools: {}
+validations: {}
+handoff_types: {}
+workflow: {}
+policies: {}
+````
 
-### File Organization
+This makes definitions easy to merge, extend, and reference by stable identifiers.
 
-**Single-file format** — All sections in one YAML file:
+### Single-file format
 
-```yaml
-# agentdef.yaml
+````yaml
 version: 1
 system: { ... }
-agents: [...]
-tasks: [...]
-artifacts: [...]
-```
+agents: { ... }
+tasks: { ... }
+artifacts: { ... }
+````
 
-**Multi-file format** — Entry point references split files via `$ref`:
+### Multi-file format
 
-```yaml
-# agentdef.yaml
+````yaml
 version: 1
-extends: "@agent-contracts/base-team"
+extends: "./base/"
 system:
   id: my-project
   name: My Agent Workflow
@@ -98,19 +307,19 @@ validations: { $ref: "./validations.yaml" }
 handoff_types: { $ref: "./handoff-types.yaml" }
 workflow: { $ref: "./workflow.yaml" }
 policies: { $ref: "./policies.yaml" }
-```
+````
 
 ---
 
-## DSL Definition Examples
+## Example: Agent definition
 
-### Agent Definition
-
-```yaml
+````yaml
 agents:
-  - id: main-architect
+  main-architect:
     role_name: "Architect"
     purpose: "Drive phases, delegate, make gate decisions, integrate audits"
+    dispatch_only: true
+    mode: read-only
     can_read_artifacts:
       - spec-md
       - codebase
@@ -127,32 +336,23 @@ agents:
     can_return_handoffs:
       - evidence-gate-verdict
 
-    # General behavioral spec (common across all tasks)
     responsibilities:
       - "Manage phase progression and gate decisions"
     constraints:
       - "Never write code directly"
-    rules:
-      - id: R-ARCH-001
-        description: "Evidence Gates must use structured evaluation criteria"
-        severity: mandatory
 
-    # Extension properties (freely added with x- prefix)
     x-identity: |
       You act as the Architect. You NEVER implement or test directly.
       Instead you delegate to specialist sub-agents.
-    x-role-selection-guide:
-      - agent: implementer
-        condition: "Backend code, infrastructure, database migrations"
-      - agent: test-writer
-        condition: "Test code creation and coverage improvement"
-```
+````
 
-### Task Definition
+---
 
-```yaml
+## Example: Task definition
+
+````yaml
 tasks:
-  - id: implement-feature
+  implement-feature:
     description: "Delegate feature implementation"
     target_agent: implementer
     allowed_from_agents:
@@ -163,8 +363,6 @@ tasks:
       - plan-md
     invocation_handoff: task-delegation
     result_handoff: dependency-evidence
-
-    # Task-specific behavioral spec
     responsibilities:
       - "Implement all requirements from spec-md"
     execution_steps:
@@ -177,13 +375,15 @@ tasks:
         uses_tool: db-lint
     completion_criteria:
       - "canonical artifacts updated"
-```
+````
 
-### Artifact Definition
+---
 
-```yaml
+## Example: Artifact definition
+
+````yaml
 artifacts:
-  - id: spec-md
+  spec-md:
     type: document
     description: "Specification document"
     owner: main-architect
@@ -193,30 +393,29 @@ artifacts:
     states: [draft, reviewed, approved]
     required_validations: [spec-semantic-review]
     visibility: internal
-```
+````
 
-### Merge Operators (for diffs in `extends` inheritance)
+---
 
-When inheriting a base definition via `extends`, entities are matched by `id` within each section, and diffs are described using merge operators.
+## Inheritance and merge operators
 
-```yaml
-# Project definition (inherits base via extends)
-extends: "@agent-contracts/base-team"
+`agent-contracts` supports shared base definitions with project-level overrides through `extends`.
+
+````yaml
+extends: "./base/"
 
 agents:
-  # Same id exists in base → deep merge
-  - id: implementer
+  implementer:
     constraints:
       $append:
-        - "Import litedbmodel only via package path"
+        - "Use only approved external libraries"
 
-  # id not in base → added as new
-  - id: designer
+  designer:
     role_name: "Designer"
     purpose: "UI design"
 
 tasks:
-  - id: implement-feature
+  implement-feature:
     execution_steps:
       $insert_after:
         target: run-db-lint
@@ -224,46 +423,18 @@ tasks:
           - id: run-contract-pipeline
             action: "Run contract pipeline"
             uses_tool: api-pipeline
-```
-
-Merge operators:
+````
 
-| Operator | Behavior |
-|---|---|
-| `$append` | Append to end of array |
-| `$prepend` | Prepend to beginning of array |
-| `$insert_after` | Insert after element with specified id |
-| `$replace` | Replace entire array/value |
-| `$remove` | Remove element by id |
-| (direct value) | Override scalar field |
+Supported merge operators:
 
-### Extension Properties (`x-` prefix)
-
-Information that cannot be expressed with the standard schema can be written as properties with the `x-` prefix (following OpenAPI conventions).
-
-```yaml
-agents:
-  - id: main-architect
-    # ... standard properties ...
-
-    # Scalar (multiline text)
-    x-identity: |
-      You act as the Architect.
-
-    # Array
-    x-role-selection-guide:
-      - agent: implementer
-        condition: "Backend code, infrastructure"
-
-    # Object
-    x-cursor-config:
-      subagent_type: null
-      globs: ["**/*"]
-```
-
-- `x-` properties pass through the schema validator (no type errors)
-- Same merge rules and operators as standard properties apply during `extends` inheritance
-- Included in the Prompt Renderer template context
+| Operator        | Behavior                                   |
+| --------------- | ------------------------------------------ |
+| `$append`       | Append entries to end of map/array         |
+| `$prepend`      | Prepend entries to beginning of map/array  |
+| `$insert_after` | Insert after element with specified key/id |
+| `$replace`      | Replace entire value                       |
+| `$remove`       | Remove entries by key/id                   |
+| direct value    | Override scalar field                      |
 
 ---
 
@@ -271,222 +442,135 @@ agents:
 
 ### Installation
 
-```bash
-npm install -g agent-contracts    # Global
-npm install -D agent-contracts    # Project-local
-npx agent-contracts               # Direct execution
-```
-
-### Commands
-
-| Command | Description |
-|---|---|
-| `agent-contracts resolve [dir]` | Resolve `extends` inheritance and output resolved YAML |
-| `agent-contracts validate [dir]` | Schema validation + reference integrity check. Exit 1 on errors |
-| `agent-contracts lint [dir]` | Run semantic lint. Display diagnostics and control exit code by severity |
-| `agent-contracts render [dir]` | Generate prompt md from resolved YAML + Handlebars templates |
-| `agent-contracts render [dir] --check` | Drift check. Detect diffs without writing files; exit 1 if diffs found |
-
-### Render Command Options
-
-| Option | Description |
-|---|---|
-| `--template-dir <path>` | Handlebars template directory (required) |
-| `--output-dir <path>` | Output directory (required) |
-| `agent-contracts check [dir]` | Run resolve → validate → lint → render --check in sequence (for CI) |
-
-### Common Options
-
-| Option | Description |
-|---|---|
-| `--format json\|text` | Specify output format |
-| `--quiet` | Show errors only |
-| `--strict` | Treat warnings as exit 1 |
-
-### Usage Examples
-
-```bash
-# Output resolved YAML to stdout
-agent-contracts resolve ./my-project
-
-# Output resolved YAML to file
-agent-contracts resolve ./my-project -o resolved.yaml
-
-# Schema validation
-agent-contracts validate ./my-project
-
-# Semantic lint (JSON output)
-agent-contracts lint ./my-project --format json
+````bash
+npm install -g agent-contracts
+npm install -D agent-contracts
+npx agent-contracts
+````
 
-# Generate prompt md
-agent-contracts render ./my-project --template-dir ./templates --output-dir ./rendered
+### Main commands
 
-# Drift check in CI
-agent-contracts render ./my-project --template-dir ./templates --output-dir ./rendered --check
+| Command                           | Description                                            |
+| --------------------------------- | ------------------------------------------------------ |
+| `agent-contracts resolve [path]`  | Resolve `extends` inheritance and output resolved YAML |
+| `agent-contracts validate [path]` | Validate schema and references                         |
+| `agent-contracts lint [path]`     | Run semantic lint                                      |
+| `agent-contracts render`          | Render outputs from config                             |
+| `agent-contracts check`           | Run resolve → validate → lint → render --check         |
 
-# Run all checks in CI
-agent-contracts check ./my-project --template-dir ./templates --output-dir ./rendered --strict
-```
+The `[path]` argument defaults to `agent-contracts.yaml` in the current directory.
+If `-c` / `--config` is specified, the DSL path from the config file is used.
 
-### Multi-level Inheritance (base → team → project)
+### Common usage
 
-```bash
-# 1. Resolve base
-agent-contracts resolve ./base/ -o ./team/base-resolved.yaml
-
-# 2. Resolve team definition (references base-resolved.yaml via extends)
-agent-contracts resolve ./team/ -o ./project/team-resolved.yaml
-
-# 3. Resolve project definition
-agent-contracts resolve ./project/ -o ./resolved.yaml
-```
+````bash
+agent-contracts resolve
+agent-contracts validate
+agent-contracts lint --strict
+agent-contracts render -c agent-contracts.config.yaml
+agent-contracts render -c agent-contracts.config.yaml --check
+agent-contracts check -c agent-contracts.config.yaml --strict
+````
 
 ---
 
-## Workflow
-
-```text
-1. Define DSL in YAML
-   ├── agentdef.yaml (entry point; references base via extends)
-   └── agents.yaml, tasks.yaml, ... (for multi-file format)
+## Config-driven rendering
 
-2. agent-contracts resolve
-   Resolve extends inheritance → id-based deep merge → generate resolved YAML
+Rendering is configured via `agent-contracts.config.yaml`.
 
-3. agent-contracts validate
-   Zod schema shape validation + reference integrity check
+````yaml
+dsl: ./agent-contracts.yaml
 
-4. agent-contracts lint
-   Bidirectional consistency, coverage analysis, workflow graph completeness
+renders:
+  - template: ./templates/agent-prompt.md.hbs
+    context: agent
+    output: ./output/{agent.id}.md
 
-5. agent-contracts render
-   resolved YAML + Handlebars templates → generate agent prompts (md)
+  - template: ./templates/overview.md.hbs
+    context: system
+    output: ./output/overview.md
+````
 
-6. agent-contracts check in CI
-   Run steps 2–5 in sequence to ensure design consistency and up-to-date rendered output
-```
-
----
+This lets you generate static outputs for:
 
-## Prompt Rendering
+* agent prompts
+* task specs
+* overviews
+* artifact docs
+* validation docs
+* workflow docs
 
-Generates static md files from resolved YAML and Handlebars templates.
+all from the same resolved DSL.
 
-### Template Context
-
-| Context | Contents |
-|---|---|
-| **global context** | Entire resolved YAML (system, agents, tasks, artifacts, etc. + extension properties) |
-| **per-agent context** | Each agent + related tasks + related handoff_types + related artifacts/tools |
+---
 
-### Template Example
+## Validation model
 
-```handlebars
-# {{agent.role_name}}
+`agent-contracts` validates your system in multiple layers.
 
-## Purpose
+### Schema validation
 
-{{agent.purpose}}
+Checks:
 
-## Responsibilities
+* required fields
+* types
+* enums
+* handoff payload shape
+* invalid custom properties without `x-` prefix
 
-{{#each mergedResponsibilities}}
-- {{this}}
-{{/each}}
+### Reference integrity
 
-{{#if agent.x-identity}}
-## Identity
+Checks:
 
-{{{agent.x-identity}}}
-{{/if}}
+* cross-entity references
+* owner / producer / editor / consumer validity
+* handoff and payload consistency
+* permission alignment between agents and artifacts
 
-{{#if agent.x-role-selection-guide}}
-## Role Selection Guide
+### Semantic lint
 
-{{#each agent.x-role-selection-guide}}
-- **{{this.agent}}**: {{this.condition}}
-{{/each}}
-{{/if}}
-```
+Checks:
 
-Templates are responsible only for **defining section structure and rendering methods**. All project-specific content is sourced from YAML (standard properties + extension properties).
+* bidirectional consistency
+* validation coverage
+* workflow graph completeness
+* merge integrity
+* read-only write violations
+* prerequisite readability
+* naming/style issues through Spectral rules
 
 ---
 
-## Validation Layers
-
-agent-contracts separates validation into 3 layers.
-
-### A. Schema Validation (Zod + Spectral)
+## Best used with runtime frameworks
 
-- Type, required field, and enum validation
-- Detection of custom properties without `x-` prefix
-- Handoff payload shape validation
-- Naming conventions
+`agent-contracts` works well alongside runtime frameworks and internal agent infrastructure.
 
-### B. Reference Resolution
+A practical model is:
 
-- ID reference integrity across agents / tasks / artifacts / tools / validations
-- Existence check for owner, producers, editors, consumers references
+1. define the workflow in YAML
+2. validate and lint it in CI
+3. render prompts and derived docs
+4. execute the workflow in your runtime of choice
 
-### C. Semantic Lint (TypeScript custom rules)
-
-- **Bidirectional consistency** between `can_execute_tools` and `tools.invokable_by`
-- Bidirectional consistency between `allowed_from_agents` and `can_invoke_agents`
-- Validation coverage analysis (e.g., whether code artifacts have mechanical validation)
-- Workflow graph completeness (existence of release / audit roots)
-- Design rule validation on post-merge resolved definitions
-
----
-
-## Programmatic API
-
-In addition to the CLI, a programmatic API is available for use from TypeScript.
-
-```typescript
-import { resolve, validate, lint, render } from "agent-contracts";
-
-const resolved = await resolve("./my-project");
-const validationResult = await validate(resolved);
-const lintResult = await lint(resolved);
-await render(resolved, { templateDir: "./templates", outputDir: "./rendered" });
-```
+That separation keeps runtime concerns and architecture concerns from being mixed together.
 
 ---
 
-## Tech Stack
+## Tech stack
 
-| Category | Choice |
-|---|---|
-| Language | TypeScript 5.x (ESM, strict mode) |
-| Schema | Zod |
-| YAML parsing | yaml (npm) |
-| Lint | Spectral (Stoplight) |
-| Templates | Handlebars |
-| CLI | commander |
-| Testing | Vitest |
-| Build | tsup |
+| Category     | Choice                             |
+| ------------ | ---------------------------------- |
+| Language     | TypeScript (ESM, strict mode)      |
+| Schema       | Zod                                |
+| YAML parsing | yaml                               |
+| Lint         | TypeScript custom rules + Spectral |
+| Templates    | Handlebars                         |
+| CLI          | commander                          |
+| Testing      | Vitest                             |
+| Build        | tsup                               |
 
 ---
 
-## Project Structure
-
-```text
-agent-contracts/
-  src/
-    schema/         # Zod schema definitions
-    loader/         # YAML loading and integration
-    resolver/       # extends resolution + id-based deep merge
-    validator/      # Schema Validation + reference integrity
-    linter/         # Semantic Lint (TypeScript custom rules)
-    renderer/       # Prompt Renderer (Handlebars)
-    cli/            # CLI entry point + commands
-  spectral/         # Spectral rulesets
-  schemas/          # JSON Schema derived from Zod
-  test/
-    fixtures/       # Test YAML samples
-```
-
 ## License
 
 MIT