agent-contracts 0.20.0 → 0.22.0

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions.
 
-**Version:** 0.19.4
+**Version:** 0.22.0
 
 ## Table of Contents
 
@@ -78,20 +78,6 @@ agent-contracts resolve -c agent-contracts.config.yaml
 
 - **stderr:** format=`text`
 
-#### Extensions
-
-```yaml
-x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
-  idempotent: true
-  sideEffects: 
-
-  expectedDurationMs: 3000
-  retryableExitCodes: 
-
-```
-
 ---
 
 ### validate
@@ -144,20 +130,6 @@ agent-contracts validate --quiet
 
 - **stderr:** format=`text`
 
-#### Extensions
-
-```yaml
-x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
-  idempotent: true
-  sideEffects: 
-
-  expectedDurationMs: 3000
-  retryableExitCodes: 
-
-```
-
 ---
 
 ### lint
@@ -207,27 +179,16 @@ agent-contracts lint --format json
 
 - **stderr:** format=`text`
 
-#### Extensions
-
-```yaml
-x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
-  idempotent: true
-  sideEffects: 
-
-  expectedDurationMs: 3000
-  retryableExitCodes: 
-
-```
-
 ---
 
 ### render
 
-Render resolved DSL with Handlebars templates.
+(deprecated) Alias for 'generate templates'.
 
-Renders output files from the resolved DSL using Handlebars templates configured in agent-contracts.config.yaml. Supports drift detection via --check mode. Requires a config file.
+Deprecated alias for 'agent-contracts generate templates'. Renders output files from the resolved DSL using Handlebars templates and emits a deprecation warning. Supports --check for drift detection. Requires a config file.
+
+> **Deprecated**: Use 'agent-contracts generate templates' instead.
+> Use `generate templates` instead.
 
 **Usage:**
 
@@ -247,16 +208,16 @@ agent-contracts render --quiet
 |---|---|---|---|---|
 | `--config` | -c | No |  | Path to agent-contracts.config.yaml. |
 | `--team` |  | No |  | Limit to one team (multi-team config only). |
-| `--check` |  | No | `false` | Check for drift without writing files. |
+| `--check` |  | No | `false` | Check for template drift without writing files. |
 | `--quiet` |  | No | `false` | Suppress output on success. |
 
 #### Exit Codes
 
-**Exit 0:** Render succeeded (or no drift detected in --check mode).
+**Exit 0:** Generation succeeded (or no drift detected in --check mode).
 
 - **stdout:** format=`text`
 
-**Exit 1:** Render failed, config not found, schema validation failed, or drift detected in --check mode.
+**Exit 1:** Generation failed, config not found, schema validation failed, or drift detected in --check mode.
 
 - **stderr:** format=`text`
 
@@ -264,20 +225,9 @@ agent-contracts render --quiet
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
-  idempotent: true
-  idempotentNote: Output is deterministic from DSL input and templates. Repeated runs produce identical files. Confirmation is not required because the command is idempotent and --check provides a side-effect-free preview mode.
-  sideEffects: 
-    - file_write
-  sideEffectNote: Writes rendered files to configured output paths. No file writes occur when --check is specified.
-  safeDryRunOption: check
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists with render targets.
     - Run validate first to confirm DSL is valid.
-  expectedDurationMs: 5000
-  retryableExitCodes: 
-
 ```
 
 ---
@@ -324,16 +274,8 @@ agent-contracts check --format json --quiet
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
-  idempotent: true
-  sideEffects: 
-
   recommendedBeforeUse: 
     - Ensure agent-contracts.config.yaml exists.
-  expectedDurationMs: 10000
-  retryableExitCodes: 
-
 ```
 
 ---
@@ -384,20 +326,6 @@ agent-contracts score -c agent-contracts.config.yaml
 
 - **stderr:** format=`text`
 
-#### Extensions
-
-```yaml
-x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
-  idempotent: true
-  sideEffects: 
-
-  expectedDurationMs: 5000
-  retryableExitCodes: 
-
-```
-
 ---
 
 ### audit
@@ -479,15 +407,6 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
-  idempotent: false
-  idempotentNote: Safe to repeat (no persistent side effects beyond network calls), but LLM inference is non-deterministic — identical inputs may produce different findings, severity assignments, and recommendation text across runs.
-  sideEffects: 
-    - network
-  sideEffectNote: Makes LLM API calls to the configured adapter (e.g. OpenAI, Gemini, Cursor) unless --dry-run is specified. Incurs token cost and sends DSL content to the LLM provider.
-  safeDryRunOption: dry-run
-  expectedDurationMs: 120000
   retryableExitCodes: 
     - 12
   recommendedBeforeUse: 
@@ -500,16 +419,25 @@ x-agent:
 
 ### generate
 
-Generate guardrail or interface artifacts from DSL.
+Generate artifacts from DSL — templates, guardrails, and/or interface.
 
-Generates runtime artifacts from the DSL. When type is "guardrails" (default), produces guardrail binding files from DSL, policies, and software bindings. When type is "interface", generates a team interface YAML/JSON file from the DSL's team_interface section.
+Unified generation command. When type is omitted, runs all generation targets (templates, guardrails, interface). When type is "templates", renders output files from the DSL using Handlebars templates. When type is "guardrails", produces guardrail binding files from DSL, policies, and software bindings. When type is "interface", generates a team interface YAML/JSON file from the DSL's team_interface section.
 
 **Usage:**
 
+```
+agent-contracts generate
+```
 ```
 agent-contracts generate -c agent-contracts.config.yaml
 ```
 ```
+agent-contracts generate templates
+```
+```
+agent-contracts generate templates --check
+```
+```
 agent-contracts generate guardrails -c agent-contracts.config.yaml
 ```
 ```
@@ -532,7 +460,7 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 | Name | Required | Description |
 |---|---|---|
-| `type` | No | Type of artifacts to generate. |
+| `type` | No | Type of artifacts to generate. Omit to run all targets. |
 
 #### Options
 
@@ -540,6 +468,7 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 |---|---|---|---|---|
 | `--config` | -c | No |  | Path to agent-contracts.config.yaml. |
 | `--team` |  | No |  | Limit to one team (multi-team config only). |
+| `--check` |  | No | `false` | Check for template drift without writing files. Only applies to the templates target. |
 | `--binding` |  | No |  | Filter to specific software binding(s). Guardrails type only. |
 | `--output` | -o | No |  | Output path for generated team interface. Interface type only. |
 | `--format` |  | No | `"yaml"` | Output format for team interface (yaml or json). Interface type only. |
@@ -548,11 +477,11 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 #### Exit Codes
 
-**Exit 0:** Generation succeeded.
+**Exit 0:** Generation succeeded (or no drift detected in --check mode).
 
 - **stdout:** format=`text`
 
-**Exit 1:** Generation failed — unknown type, schema validation failed, config not found, or error-level diagnostics.
+**Exit 1:** Generation failed — unknown type, schema validation failed, config not found, drift detected, or error-level diagnostics.
 
 - **stderr:** format=`text`
 
@@ -560,20 +489,9 @@ agent-contracts generate interface -o team-interface.yaml --dry-run
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
-  idempotent: true
-  idempotentNote: Output is deterministic from DSL input, policies, and bindings. Repeated runs produce identical files. Confirmation is not required because the command is idempotent and --dry-run provides a side-effect-free preview mode.
-  sideEffects: 
-    - file_write
-  sideEffectNote: Writes guardrail binding files or team interface files to configured output paths. No file writes occur when --dry-run is specified.
-  safeDryRunOption: dry-run
   recommendedBeforeUse: 
-    - Ensure agent-contracts.config.yaml exists with binding definitions.
+    - Ensure agent-contracts.config.yaml exists with render targets and/or binding definitions.
     - Run validate first to confirm DSL is valid.
-  expectedDurationMs: 5000
-  retryableExitCodes: 
-
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-contracts",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -31,6 +31,7 @@
     "lint": "eslint src/ test/",
     "typecheck": "tsc --noEmit",
     "generate:schema": "tsx scripts/generate-json-schema.ts",
+    "generate:cli": "cli-contracts generate typescript",
     "generate:docs": "cli-contracts docs",
     "version": "node -e \"const fs=require('fs');const f='cli-contract.yaml';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace(/^  version: .*/m,'  version: '+process.env.npm_package_version))\" && git add cli-contract.yaml",
     "prepublishOnly": "npm run clean && npm run build"
@@ -67,7 +68,8 @@
     "handlebars": "^4.7.9",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "zod-to-json-schema": "^3.25.2"
+    "zod-to-json-schema": "^3.25.2",
+    "cli-contracts": "^0.7.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.138",
@@ -76,8 +78,7 @@
     "@google/genai": "^2.0.1",
     "@openai/agents": "^0.11.1",
     "@types/node": "^25.6.0",
-    "agent-contracts-runtime": "^0.12.0",
-    "cli-contracts": "^0.5.2",
+    "agent-contracts-runtime": "^0.13.0",
     "eslint": "^10.2.0",
     "globals": "^17.5.0",
     "prettier": "^3.8.2",