agent-contracts 0.7.0 → 0.8.0

package/README.md

@@ -204,6 +204,30 @@ An **Artifact** defines the objects that move through the workflow:
 * required validations
 * visibility
 
+### Tool
+
+A **Tool** defines an invokable CLI/MCP tool:
+
+* kind (cli, mcp, etc.)
+* input/output artifacts
+* invokable_by (which agents can use it)
+* `commands` — structured list of sub-commands with `category`, `reads`, `writes`, and `purpose`
+
+### Workflow
+
+A **Workflow** defines a phase-level execution sequence:
+
+* `description` — human-readable summary
+* `entry_conditions`
+* `trigger`
+* `external_participants` — actors/participants outside the agent system (e.g., User, external advisory)
+* ordered steps (handoff, validation, decision)
+
+Workflow steps support additional properties:
+
+* `group` — consecutive steps with the same group are rendered as `par` (parallel) blocks in sequence diagrams
+* `retry` (handoff steps only) — defines a conditional retry loop with `condition`, `fix_task`, and optional `revalidate_task`
+
 ### Handoff
 
 A **Handoff** is a runtime delegation instance.
@@ -458,12 +482,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:
@@ -493,6 +518,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`.
@@ -686,8 +738,8 @@ Each `context` type provides a different rendering scope:
 
 * `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
-* `relatedArtifacts` — artifacts from `can_read_artifacts`, `can_write_artifacts`, and `input_artifacts`
+* `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:
@@ -724,6 +776,8 @@ Templates can use these built-in helpers:
 | `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}}}` or `{{{sequenceDiagram @key ../dsl}}}` | Generate Mermaid sequence diagram. Supports `external_participants`, `group` (par blocks), `retry` (opt blocks), and read-only agent separation into Audit box |
+| `overviewFlowchart` | `{{{overviewFlowchart dsl}}}` | Generate Mermaid graph showing phases → agents/tools/artifacts relationships (system context) |
 
 ---
 
@@ -762,6 +816,8 @@ Checks:
 * merge integrity
 * read-only write violations
 * prerequisite readability
+* artifact ownership — `produces_artifact`/`reads_artifact` in execution steps vs. artifact producers/editors/consumers
+* tool commands — `commands[].reads`/`commands[].writes` reference valid artifacts and align with `output_artifacts`
 * naming/style issues through Spectral rules
 
 ---