agent-contracts 0.6.1 → 0.7.1

package/README.md

@@ -204,6 +204,15 @@ An **Artifact** defines the objects that move through the workflow:
 * required validations
 * visibility
 
+### Workflow
+
+A **Workflow** defines a phase-level execution sequence:
+
+* description
+* entry conditions
+* trigger
+* ordered steps (handoff, validation, decision)
+
 ### Handoff
 
 A **Handoff** is a runtime delegation instance.
@@ -244,6 +253,7 @@ Design regressions become testable.
 * **Structured handoff definitions**
 * **Artifact ownership and lifecycle modeling**
 * **Config-driven prompt rendering**
+* **Variable substitution** via `${vars.xxx}` in DSL values
 * **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**
@@ -457,12 +467,13 @@ tasks:
     execution_steps:
       - id: read-specs
         action: "Read spec-md and design-docs"
-        description: "Read all relevant specification and design documents"
+        reads_artifact: spec-md
       - id: implement
         action: "Implement changes in codebase"
+        produces_artifact: codebase
+        depends_on: [read-specs]
       - 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:
@@ -492,6 +503,33 @@ artifacts:
 
 ---
 
+## Example: Workflow definition
+
+````yaml
+workflow:
+  specify:
+    description: "Externalize requirements — create spec.md from user stories"
+    entry_conditions:
+      - User story or feature request received
+    trigger: "User invokes /speckit.specify or asks to create a feature spec."
+    steps:
+      - type: handoff
+        handoff_kind: delegation
+        task: specify-feature
+        from_agent: main-architect
+      - type: validation
+        validation_id: spec-semantic-review
+      - type: decision
+        agent: main-architect
+        options:
+          - label: approve
+            next_workflow: plan
+          - label: revise
+            retry_from_step: 0
+````
+
+---
+
 ## Inheritance and merge operators
 
 `agent-contracts` supports shared base definitions with project-level overrides through `extends`.
@@ -533,6 +571,67 @@ Supported merge operators:
 
 ---
 
+## 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.).
+
+`vars` in `agent-contracts.config.yaml` lets you define project-specific values that are substituted into DSL string values using `${vars.xxx}` syntax.
+
+### Defining vars
+
+Add a `vars` section to your config file. Values must be flat string key-value pairs.
+
+````yaml
+# agent-contracts.config.yaml
+vars:
+  project_name: "my-service"
+  language: "TypeScript"
+  repo_url: "https://github.com/org/my-service"
+````
+
+### Using placeholders in DSL
+
+Use `${vars.<key>}` in any string value within the DSL YAML (base or project).
+
+````yaml
+# base/agent-contracts.yaml
+agents:
+  implementer:
+    purpose: "Implements features for ${vars.project_name}"
+    constraints:
+      - "Use ${vars.language} for all implementations"
+      - "Repository: ${vars.repo_url}"
+````
+
+### Processing order
+
+Variable substitution happens **after** DSL resolution (`extends` merge) and **before** schema validation:
+
+1. Load config (including `vars`)
+2. Resolve DSL (load + merge `extends`)
+3. Substitute `${vars.xxx}` in all string values
+4. Validate schema
+5. Render / lint / check
+
+This ensures that merged strings from both base and project are substituted, and the resulting values pass schema validation.
+
+### Error handling
+
+If a placeholder references an undefined variable, the command exits with an error:
+
+````
+VarsSubstitutionError: Undefined variable "repo_url" in value "Repository: ${vars.repo_url}"
+  Defined vars: project_name, language
+````
+
+### Notes
+
+- Only string values are substituted; object keys are not affected.
+- `vars` is optional. If omitted, no substitution occurs.
+- Patterns that do not match `${vars.<key>}` (e.g. `${env.HOME}`, `$vars.xxx`, `{{vars.xxx}}`) are left unchanged.
+
+---
+
 ## CLI
 
 ### Installation
@@ -576,6 +675,11 @@ Rendering is configured via `agent-contracts.config.yaml`.
 ````yaml
 dsl: ./agent-contracts.yaml
 
+vars:
+  project_name: "my-service"
+  language: "TypeScript"
+  repo_url: "https://github.com/org/my-service"
+
 renders:
   - template: ./templates/agent-prompt.md.hbs
     context: agent
@@ -597,6 +701,68 @@ This lets you generate static outputs for:
 
 all from the same resolved DSL.
 
+### Available context types
+
+Each `context` type provides a different rendering scope:
+
+| Context | Scope | Output | Key variables |
+|---------|-------|--------|---------------|
+| `system` | Single file | `output` as-is | `system`, `dsl` |
+| `agent` | Per agent | `{agent.id}` in output path | `agent`, `receivableTasks`, `delegatableTasks`, `relatedArtifacts`, `relatedTools`, `relatedHandoffTypes`, `mergedBehavior`, `dsl` |
+| `task` | Per task | `{task.id}` in output path | `task`, `targetAgent`, `dsl` |
+| `artifact` | Per artifact | `{artifact.id}` in output path | `artifact`, `relatedTools`, `relatedValidations`, `producerAgents`, `consumerAgents`, `editorAgents`, `createdInWorkflows`, `dsl` |
+| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `dsl` |
+| `validation` | Per validation | `{validation.id}` in output path | `validation`, `dsl` |
+| `handoff_type` | Per handoff type | `{handoff_type.id}` in output path | `handoff_type`, `relatedTasks`, `dsl` |
+| `workflow` | Per workflow phase | `{workflow.id}` in output path | `workflow`, `relatedAgents`, `relatedTasks`, `relatedTools`, `relatedArtifacts`, `relatedValidations`, `dsl` |
+| `policy` | Per policy | `{policy.id}` in output path | `policy`, `dsl` |
+
+#### Enriched context details
+
+**`workflow` context** collects all entities involved in a phase:
+
+* `relatedTasks` — tasks where `task.workflow` matches this phase
+* `relatedAgents` — agents from task `target_agent`, `allowed_from_agents`, step `from_agent`, and validation executors
+* `relatedTools` — tools from `can_execute_tools` of all related agents, plus `uses_tool` in execution steps
+* `relatedArtifacts` — artifacts from `can_read_artifacts`, `can_write_artifacts`, `input_artifacts`, plus `produces_artifact` and `reads_artifact` in execution steps
+* `relatedValidations` — validations referenced in workflow steps
+
+**`artifact` context** provides ownership and cross-reference data:
+
+* `relatedTools` — tools with this artifact in `input_artifacts` or `output_artifacts`
+* `relatedValidations` — validations targeting this artifact
+* `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
+* `createdInWorkflows` — workflow phases where this artifact is written
+
+**`tool` context** resolves agent and artifact references:
+
+* `invokableAgents` — agents listed in `invokable_by`
+* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
+
+### Handlebars helpers
+
+Templates can use these built-in helpers:
+
+| Helper | Usage | Description |
+|--------|-------|-------------|
+| `eq` | `{{#if (eq a b)}}` | Strict equality |
+| `notEmpty` | `{{#if (notEmpty obj)}}` | True when object has at least one key |
+| `inc` | `{{inc @index}}` | Increment number by 1 (for 1-based indexing) |
+| `yamlBlock` | `{{{yamlBlock obj}}}` | Render value as YAML-formatted text |
+| `lookupPayloadFields` | `{{#each (lookupPayloadFields payload)}}` | Extract payload field info (name, type, required, enum) |
+| `join` | `{{join arr ", "}}` | Join array elements with separator |
+| `contains` | `{{#if (contains arr "x")}}` | True when array includes value |
+| `groupBy` | `{{#with (groupBy arr "key")}}` | Group array elements by field value |
+| `filterByField` | `{{#each (filterByField arr "field" "val")}}` | Filter array by field match |
+| `keys` | `{{#each (keys obj)}}` | Object keys as array |
+| `values` | `{{#each (values obj)}}` | Object values as array |
+| `size` | `{{size obj}}` | Array length or object key count |
+| `not` | `{{#if (not x)}}` | Boolean negation |
+| `or` | `{{#if (or a b)}}` | Boolean OR (variadic) |
+| `and` | `{{#if (and a b)}}` | Boolean AND (variadic) |
+| `gt` / `gte` / `lt` | `{{#if (gt a b)}}` | Numeric comparisons |
+| `sequenceDiagram` | `{{{sequenceDiagram}}}` | Generate Mermaid sequence diagram from workflow context (requires `workflow` context) |
+
 ---
 
 ## Validation model