agent-contracts 0.14.1 → 0.16.0

package/README.md

@@ -166,6 +166,8 @@ A working example is available in [`sample/`](./sample), including:
 * [`sample/templates`](./sample/templates)
 * [`sample/output`](./sample/output)
 
+A multi-team example is available in [`sample/multi-team/`](./sample/multi-team), demonstrating cross-team interface declaration and consumption.
+
 ---
 
 ## Core concepts
@@ -222,7 +224,7 @@ A **Workflow** defines a phase-level execution sequence:
 * `entry_conditions`
 * `trigger`
 * `external_participants` — actors/participants outside the agent system (e.g., User, external advisory)
-* ordered steps (delegate, gate, validation, decision)
+* ordered steps (`delegate`, `gate`, `team_task`, `decision`; legacy: `handoff`, `validation`)
 
 Workflow steps support additional properties:
 
@@ -332,7 +334,9 @@ Design regressions become testable.
 * **Guardrail policies** with configurable enforcement (block/warn/shadow/info)
 * **Software bindings** (DI) for tool-specific guardrail implementation (Cursor, Git, GitHub)
 * **Guardrail generation** from DSL + policy + bindings via `generate guardrails`
+* **Interface generation** from DSL via `generate interface` for cross-team contracts
 * **Flexible file splitting** via `$ref` (replacement), `$refs` (import + deep-merge), and JSON Pointer `$ref` (in-document)
+* **Multi-team collaboration** via `team_interface` (public boundary), `imports` (team consumption), and `team_task` (cross-team delegation)
 * **YAML safety linting** for reserved word collision detection across YAML 1.1/1.2
 * **`extensions` declarations** with scope, schema validation, and strict enforcement for custom `x-*` fields
 * **`resolve --expand-defaults`** to materialize all Zod schema defaults in output
@@ -368,6 +372,13 @@ artifacts: {}
 tools: {}
 validations: {}
 handoff_types: {}
+team_interface:             # optional — multi-team public boundary
+  version: 1
+  accepts:
+    workflows: {}
+  exposes:
+    artifacts: []
+imports: {}                 # optional — consumed team interfaces
 workflow: {}
 policies: {}
 guardrails: {}
@@ -830,6 +841,107 @@ Supported merge operators:
 
 ---
 
+## Multi-team collaboration
+
+`agent-contracts` supports multi-team workflows where teams declare public interfaces and consume each other's capabilities.
+
+### Team Interface
+
+A `team_interface` declares what a team exposes to the outside:
+
+````yaml
+team_interface:
+  version: 1
+  description: "Backend team public interface"
+  accepts:
+    workflows:
+      implement:
+        internal_workflow: feature-implement
+        input_handoff: feature-request
+        output_handoff: implementation-result
+        description: "Request a feature implementation"
+  exposes:
+    artifacts:
+      - api-contract
+      - build-report
+  constraints:
+    - "feature-request must include acceptance_criteria"
+````
+
+Key design decisions:
+
+* **Workflow-level accepts** — external callers invoke a workflow, not individual tasks
+* **Explicit mapping** — `internal_workflow` separates the stable public name from the internal workflow ID
+* **Listing-based exposure** — an entity is external only if listed in `team_interface`
+
+### Imports
+
+A team consumes another team's generated interface via `imports`:
+
+````yaml
+imports:
+  backend:
+    interface: ./teams/backend/team-interface.yaml
+    version: ">=1"
+````
+
+Imported entities are referenced as `{team_id}.{public_name}` in cross-team workflow steps.
+
+### `team_task` workflow step
+
+Cross-team delegation uses the `team_task` step type:
+
+````yaml
+workflow:
+  execute-tests:
+    steps:
+      - type: team_task
+        to_team: backend
+        workflow: implement
+        handoff: feature-request
+        expects: implementation-result
+        description: "Delegate implementation to backend team"
+````
+
+| Field | Description |
+|-------|-------------|
+| `to_team` | Team ID from `imports` |
+| `workflow` | Public workflow name from the imported interface |
+| `handoff` | Handoff type for the request |
+| `expects` | Handoff type for the response |
+
+### Generating a team interface
+
+The `generate interface` command produces a self-contained `team-interface.yaml`:
+
+````bash
+agent-contracts generate interface -c agent-contracts.config.yaml
+agent-contracts generate interface -c agent-contracts.config.yaml --team backend
+agent-contracts generate interface -c agent-contracts.config.yaml -o custom-output.yaml
+agent-contracts generate interface -c agent-contracts.config.yaml --dry-run
+````
+
+The output includes:
+
+* Workflow entries with handoff key references
+* A `handoff_types` section containing only schemas referenced by external workflows
+* An `exposes.artifacts` section with type, description, and states
+* Metadata (`team_id`, `team_name`, `version`, `generated_at`)
+
+### Interface drift detection
+
+The `check` command detects drift between the declared `team_interface` and the generated `team-interface.yaml`:
+
+````bash
+agent-contracts check -c agent-contracts.config.yaml
+````
+
+If a `team-interface.yaml` exists and differs from what would be regenerated, the check reports drift.
+
+For managing multiple teams from a single configuration file (shared bindings, vars, and `--team` filtering), see [Multi-team configuration](#multi-team-configuration).
+
+---
+
 ## Variable substitution
 
 When using `extends` to share a base DSL across projects, base definitions often contain values that differ per project (project name, language, repository URL, etc.).
@@ -911,11 +1023,14 @@ npx agent-contracts
 | `agent-contracts render`          | Render outputs from config                             |
 | `agent-contracts score [path]`    | Calculate DSL completeness score                       |
 | `agent-contracts generate guardrails` | Generate guardrail artifacts from bindings       |
+| `agent-contracts generate interface` | Generate team interface YAML from DSL |
 | `agent-contracts check`           | Run resolve → validate → lint → render --check         |
 
 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.
 
+All commands also accept `--team <id>` to limit execution to a single team when using a [multi-team configuration](#multi-team-configuration).
+
 #### `resolve` options
 
 | Option | Description |
@@ -923,6 +1038,7 @@ If `-c` / `--config` is specified, the DSL path from the config file is used.
 | `--format <text\|json>` | Output format (default: `text`) |
 | `--expand-defaults` | Expand all Zod default values in output. Fields like `required_validations: []`, `tags: []`, and `can_read_artifacts: []` are written explicitly instead of being silently applied by schema defaults. |
 | `-c, --config <path>` | Path to `agent-contracts.config.yaml` |
+| `--team <id>` | Limit to one team (multi-team config only) |
 
 #### `score` options
 
@@ -931,6 +1047,7 @@ If `-c` / `--config` is specified, the DSL path from the config file is used.
 | `--format <text\|json>` | Output format (default: `text`) |
 | `--threshold <number>` | Minimum score; exit 1 if below (for CI gates) |
 | `-c, --config <path>` | Path to `agent-contracts.config.yaml` |
+| `--team <id>` | Limit to one team (multi-team config only) |
 
 The score command evaluates 7 dimensions:
 
@@ -957,6 +1074,9 @@ agent-contracts score --format json
 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
+agent-contracts generate interface -c agent-contracts.config.yaml
+agent-contracts generate interface -c agent-contracts.config.yaml --dry-run
+agent-contracts generate interface -c agent-contracts.config.yaml --format json
 ````
 
 ---
@@ -994,6 +1114,62 @@ This lets you generate static outputs for:
 
 all from the same resolved DSL.
 
+### Multi-team configuration
+
+When several teams (for example backend, QA, infra) are managed from one workspace, you can list every team in a single config file instead of maintaining separate configs.
+
+This complements the DSL-level [multi-team collaboration](#multi-team-collaboration) features (`team_interface`, `imports`, `team_task`).
+
+````yaml
+teams:
+  _defaults:
+    bindings:
+      - ./bindings/cursor.yaml
+    vars:
+      language: TypeScript
+    paths:
+      cursor_root: .cursor
+    active_guardrail_policy: default-enforcement
+
+  backend:
+    dsl: ./teams/backend/agent-contracts.yaml
+    interface_output: ./teams/backend/team-interface.yaml
+    bindings:
+      - ./teams/backend/bindings/observability.yaml
+    vars:
+      team_name: backend
+
+  qa:
+    dsl: ./teams/qa/agent-contracts.yaml
+    vars:
+      team_name: qa
+````
+
+**`_defaults`:** Reserved meta-entry in the `teams` map. It uses the same schema as team entries except `dsl` is not required. Values are inherited by all teams. The underscore prefix avoids colliding with real team IDs.
+
+**Merge with `_defaults`:**
+
+* `bindings` — `_defaults` bindings are prepended before team-specific bindings
+* `vars` — shallow merge; team values win
+* `paths` — shallow merge; team values win
+* `active_guardrail_policy` — team wins when present
+
+All commands accept `--team <id>` to run against a single team:
+
+````bash
+agent-contracts validate -c config.yaml              # all teams
+agent-contracts validate -c config.yaml --team backend  # one team
+agent-contracts check -c config.yaml --team qa          # one team
+````
+
+The `check` command also validates that imported interface files exist on disk (cross-team references).
+
+**Design constraints:**
+
+* `dsl` and `teams` are mutually exclusive at the config root
+* Every team except `_defaults` must specify `dsl`
+* Existing single-team configs (top-level `dsl` only) remain valid unchanged
+
 ### Render target options
 
 Each entry in `renders` supports these fields:
@@ -1414,6 +1590,8 @@ Checks:
 * owner / producer / editor / consumer validity
 * handoff schema consistency (`required` vs. `properties` alignment)
 * permission alignment between agents and artifacts
+* `team_interface` internal consistency (workflows, handoffs, and exposed artifacts exist in the DSL)
+* cross-team reference validity (`team_task` targets exist in `imports`)
 
 ### Semantic lint