agent-contracts 0.5.1 → 0.6.0

package/README.md

@@ -1,6 +1,9 @@
 
 # agent-contracts
 
+[![npm version](https://img.shields.io/npm/v/agent-contracts.svg)](https://www.npmjs.com/package/agent-contracts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **Design multi-agent systems as contracts.**
 
 `agent-contracts` is a toolkit for declaratively defining multi-agent development workflows in **YAML DSL**, with **static validation, semantic linting, and prompt rendering**.
@@ -116,7 +119,7 @@ version: 1
 system:
   id: my-project
   name: My Agent Workflow
-  default_phase_order: [design, implement]
+  default_workflow_order: [design, implement]
 
 agents:
   architect:
@@ -133,7 +136,7 @@ tasks:
     description: "Delegate feature implementation"
     target_agent: implementer
     allowed_from_agents: [architect]
-    phase: implement
+    workflow: implement
     input_artifacts: [spec-md]
     invocation_handoff: task-delegation
     result_handoff: implementation-result
@@ -184,7 +187,7 @@ A **Task** defines a delegatable unit of work:
 
 * target agent
 * allowed callers
-* phase
+* workflow
 * input artifacts
 * invocation/result handoffs
 * task-specific execution expectations
@@ -242,6 +245,7 @@ Design regressions become testable.
 * **Artifact ownership and lifecycle modeling**
 * **Config-driven prompt rendering**
 * **Inheritance with merge operators via `extends`**
+* **Flexible file splitting** via `$ref` (replacement) and `$refs` (import + deep-merge)
 * **JSON Schema for editor support and external tooling**
 * **CI-friendly workflow checks**
 
@@ -258,7 +262,7 @@ extends: "./base/"
 system:
   id: my-project
   name: My Agent Workflow
-  default_phase_order:
+  default_workflow_order:
     - analyze
     - specify
     - plan
@@ -289,7 +293,7 @@ tasks: { ... }
 artifacts: { ... }
 ````
 
-### Multi-file format
+### Multi-file format (section-level `$ref`)
 
 ````yaml
 version: 1
@@ -297,7 +301,7 @@ extends: "./base/"
 system:
   id: my-project
   name: My Agent Workflow
-  default_phase_order: [analyze, specify, plan, implement, audit, release, reflect]
+  default_workflow_order: [analyze, specify, plan, implement, audit, release, reflect]
 
 agents: { $ref: "./agents.yaml" }
 tasks: { $ref: "./tasks.yaml" }
@@ -309,6 +313,91 @@ workflow: { $ref: "./workflow.yaml" }
 policies: { $ref: "./policies.yaml" }
 ````
 
+### Per-entry `$ref`
+
+`$ref` can be used at any object position. This allows splitting individual entries into separate files:
+
+````yaml
+agents:
+  architect: { $ref: "./agents/architect.yaml" }
+  implementer: { $ref: "./agents/implementer.yaml" }
+  test-writer: { $ref: "./agents/test-writer.yaml" }
+````
+
+Each referenced file contains the agent definition directly (without the key):
+
+````yaml
+# agents/architect.yaml
+role_name: "Architect"
+purpose: "Drive phases and delegate work"
+can_invoke_agents: [implementer]
+````
+
+### Directory `$ref`
+
+When `$ref` points to a directory, all `*.yaml` / `*.yml` files in the directory are loaded and merged:
+
+````yaml
+agents: { $ref: "./agents/" }
+````
+
+Each file in the directory contains one or more keyed entries:
+
+````yaml
+# agents/architect.yaml
+architect:
+  role_name: "Architect"
+  purpose: "Drive phases and delegate work"
+````
+
+Files are loaded in alphabetical order. Conflicting leaf values across files result in an error.
+
+### `$refs` (import and merge)
+
+`$refs` imports multiple files and **deep-merges** them into the containing map.
+Unlike `$ref` (which replaces an object entirely), `$refs` allows mixing inline definitions with external files.
+
+````yaml
+agents:
+  inline-agent:
+    role_name: "Inline Agent"
+    purpose: "Defined right here"
+  $refs:
+    - "./agents/architect.yaml"
+    - "./agents/implementer.yaml"
+    - "./more-agents/"           # directories are also supported
+````
+
+Each referenced file uses the same keyed format:
+
+````yaml
+# agents/architect.yaml
+architect:
+  role_name: "Architect"
+  purpose: "Drive phases and delegate work"
+````
+
+`$refs` can also be used at the root level to compose a DSL from multiple aspect-oriented files:
+
+````yaml
+version: 1
+system:
+  id: my-project
+  name: My Agent Workflow
+  default_workflow_order: [analyze, implement]
+$refs:
+  - "./agents-core.yaml"        # agents + artifacts definitions
+  - "./agents-constraints.yaml"  # constraints for the same agents
+  - "./tasks.yaml"
+````
+
+Overlapping map keys are deep-merged recursively. Conflicting leaf values (scalar or array) result in an error.
+
+| Directive | Type   | Behavior                                                 |
+| --------- | ------ | -------------------------------------------------------- |
+| `$ref`    | string | Replace the object at that position with file contents   |
+| `$refs`   | array  | Import files and deep-merge into the containing map      |
+
 ---
 
 ## Example: Agent definition
@@ -357,7 +446,7 @@ tasks:
     target_agent: implementer
     allowed_from_agents:
       - main-architect
-    phase: implement
+    workflow: implement
     input_artifacts:
       - spec-md
       - plan-md
@@ -368,15 +457,21 @@ tasks:
     execution_steps:
       - id: read-specs
         action: "Read spec-md and design-docs"
+        description: "Read all relevant specification and design documents"
       - id: implement
         action: "Implement changes in codebase"
       - id: run-db-lint
         action: "Run db-lint"
+        description: "Run database schema linter to check migrations"
         uses_tool: db-lint
+        x-timeout: 120
     completion_criteria:
       - "canonical artifacts updated"
 ````
 
+`x-` prefixed custom properties work at any nesting level — including inside
+`execution_steps`, `rules`, `workflow.steps`, and other nested objects.
+
 ---
 
 ## Example: Artifact definition
@@ -516,7 +611,9 @@ Checks:
 * types
 * enums
 * handoff payload shape
-* invalid custom properties without `x-` prefix
+* invalid custom properties without `x-` prefix (checked at all nesting levels)
+
+Custom properties with `x-` prefix are allowed on any object in the DSL — top-level entities (agents, tasks, artifacts, …), nested objects (rules, execution steps, workflow steps, …), and the root DSL itself.
 
 ### Reference integrity