agent-contracts 0.7.0 → 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.
@@ -458,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:
@@ -493,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`.
@@ -686,8 +723,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 +761,7 @@ 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}}}` | Generate Mermaid sequence diagram from workflow context (requires `workflow` context) |
 
 ---
 

package/dist/cli.js

@@ -59155,6 +59155,7 @@ var ExecutionStepSchema = z7.object({
   abort_on_failure: z7.boolean().optional(),
   uses_tool: z7.string().optional(),
   produces_artifact: z7.string().optional(),
+  reads_artifact: z7.string().optional(),
   depends_on: z7.array(z7.string()).optional(),
   skip_condition: z7.string().optional(),
   wait_for_approval: z7.boolean().optional()
@@ -59225,6 +59226,7 @@ var WorkflowStepSchema = z10.discriminatedUnion("type", [
   WorkflowDecisionStepSchema
 ]);
 var WorkflowSchema = z10.object({
+  description: z10.string().optional(),
   entry_conditions: z10.array(z10.string()).default([]),
   trigger: z10.string().optional(),
   steps: z10.array(WorkflowStepSchema)
@@ -59805,6 +59807,16 @@ var taskAgentBindingRule = {
             });
           }
         }
+        if (step.reads_artifact) {
+          if (!targetAgent.can_read_artifacts.includes(step.reads_artifact)) {
+            diagnostics.push({
+              ruleId: "task-agent-binding",
+              severity: "error",
+              path: `tasks.${taskId}.execution_steps`,
+              message: `Task "${taskId}" step reads_artifact "${step.reads_artifact}" not in target agent "${task.target_agent}" can_read_artifacts`
+            });
+          }
+        }
       }
     }
     return diagnostics;
@@ -60602,6 +60614,11 @@ function buildWorkflowContext(dsl, workflowId) {
       }
     }
   }
+  for (const task of relatedTasks) {
+    for (const step of task.execution_steps ?? []) {
+      if (step.uses_tool) toolIds.add(step.uses_tool);
+    }
+  }
   const relatedTools = {};
   for (const id of toolIds) {
     if (dsl.tools[id]) relatedTools[id] = dsl.tools[id];
@@ -60609,6 +60626,10 @@ function buildWorkflowContext(dsl, workflowId) {
   const artifactIds = /* @__PURE__ */ new Set();
   for (const task of relatedTasks) {
     for (const artId of task.input_artifacts) artifactIds.add(artId);
+    for (const step of task.execution_steps ?? []) {
+      if (step.produces_artifact) artifactIds.add(step.produces_artifact);
+      if (step.reads_artifact) artifactIds.add(step.reads_artifact);
+    }
   }
   for (const id of agentIds) {
     const agent = dsl.agents[id];
@@ -60752,6 +60773,248 @@ function buildPerAgentContext(dsl, agent) {
   };
 }
 
+// src/renderer/sequence-diagram.ts
+function hashToColor(s2, saturation, lightness) {
+  let hash = 0;
+  for (const ch of s2) hash = (hash << 5) - hash + ch.charCodeAt(0) | 0;
+  const h2 = (hash % 360 + 360) % 360;
+  const c2 = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const x3 = c2 * (1 - Math.abs(h2 / 60 % 2 - 1));
+  const m2 = lightness - c2 / 2;
+  let r3 = 0, g2 = 0, b3 = 0;
+  if (h2 < 60) {
+    r3 = c2;
+    g2 = x3;
+  } else if (h2 < 120) {
+    r3 = x3;
+    g2 = c2;
+  } else if (h2 < 180) {
+    g2 = c2;
+    b3 = x3;
+  } else if (h2 < 240) {
+    g2 = x3;
+    b3 = c2;
+  } else if (h2 < 300) {
+    r3 = x3;
+    b3 = c2;
+  } else {
+    r3 = c2;
+    b3 = x3;
+  }
+  return `rgb(${Math.round((r3 + m2) * 255)},${Math.round((g2 + m2) * 255)},${Math.round((b3 + m2) * 255)})`;
+}
+function sanitizeAlias(id) {
+  return id.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function agentAlias(id, agent) {
+  const words = agent.role_name.split(/\s+/);
+  if (words.length === 1) return sanitizeAlias(words[0].slice(0, 4));
+  return sanitizeAlias(words.map((w2) => w2[0]).join(""));
+}
+function collectReferencedIds(workflow, dsl, relatedTasks) {
+  const agents = /* @__PURE__ */ new Set();
+  const tools = /* @__PURE__ */ new Set();
+  const artifacts = /* @__PURE__ */ new Set();
+  const taskMap = /* @__PURE__ */ new Map();
+  for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  for (const step of workflow.steps) {
+    if (step.type === "handoff") {
+      if (step.from_agent) agents.add(step.from_agent);
+      if (step.task) {
+        const task = taskMap.get(step.task);
+        if (task) {
+          agents.add(task.target_agent);
+          for (const es of task.execution_steps ?? []) {
+            collectExecutionStepIds(es, tools, artifacts);
+          }
+        }
+      }
+    } else if (step.type === "validation") {
+      const val = dsl.validations[step.validation];
+      if (val) {
+        if (val.executor_type === "agent") agents.add(val.executor);
+        else tools.add(val.executor);
+        artifacts.add(val.target_artifact);
+      }
+    } else if (step.type === "decision") {
+    }
+  }
+  return { agents, tools, artifacts };
+}
+function collectExecutionStepIds(es, tools, artifacts) {
+  if (es.uses_tool) tools.add(es.uses_tool);
+  if (es.produces_artifact) artifacts.add(es.produces_artifact);
+  if (es.reads_artifact) artifacts.add(es.reads_artifact);
+}
+function buildParticipants(ids, dsl) {
+  const participants = [];
+  const usedAliases = /* @__PURE__ */ new Set();
+  function uniqueAlias(preferred) {
+    let alias = preferred;
+    let i3 = 2;
+    while (usedAliases.has(alias)) {
+      alias = `${preferred}${i3}`;
+      i3++;
+    }
+    usedAliases.add(alias);
+    return alias;
+  }
+  for (const id of ids.agents) {
+    const agent = dsl.agents[id];
+    if (!agent) continue;
+    const alias = uniqueAlias(agentAlias(id, agent));
+    participants.push({ id, alias, label: agent.role_name, group: "agents" });
+  }
+  for (const id of ids.tools) {
+    const tool = dsl.tools[id];
+    if (!tool) continue;
+    const alias = uniqueAlias(sanitizeAlias(id));
+    participants.push({ id, alias, label: id, group: "toolchain" });
+  }
+  for (const id of ids.artifacts) {
+    const art = dsl.artifacts[id];
+    if (!art) continue;
+    const alias = uniqueAlias(sanitizeAlias(id));
+    participants.push({ id, alias, label: id, group: "artifacts" });
+  }
+  return participants;
+}
+function participantAlias(participants, id) {
+  const p2 = participants.find((pp) => pp.id === id);
+  return p2 ? p2.alias : sanitizeAlias(id);
+}
+function emitParticipants(participants, lines, indent) {
+  const groups = {
+    agents: [],
+    toolchain: [],
+    artifacts: []
+  };
+  for (const p2 of participants) groups[p2.group].push(p2);
+  const groupConfig = [
+    { key: "agents", label: "Agents", color: "rgb(200,220,255)" },
+    { key: "toolchain", label: "Toolchain", color: "rgb(220,255,220)" },
+    { key: "artifacts", label: "Artifacts", color: "rgb(255,230,210)" }
+  ];
+  for (const { key, label, color } of groupConfig) {
+    const members = groups[key];
+    if (members.length === 0) continue;
+    lines.push(`${indent}box ${color} ${label}`);
+    for (const p2 of members) {
+      if (p2.alias === p2.label) {
+        lines.push(`${indent}participant ${p2.alias}`);
+      } else {
+        lines.push(`${indent}participant ${p2.alias} as ${p2.label}`);
+      }
+    }
+    lines.push(`${indent}end`);
+  }
+}
+function emitHandoffStep(step, participants, dsl, relatedTasks, lines, indent) {
+  const taskMap = /* @__PURE__ */ new Map();
+  for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  if (!step.task) {
+    if (step.from_agent) {
+      const fromAlias2 = participantAlias(participants, step.from_agent);
+      lines.push(`${indent}${fromAlias2}->>${fromAlias2}: ${step.handoff_kind}`);
+    }
+    return;
+  }
+  const task = taskMap.get(step.task);
+  if (!task) return;
+  const fromAlias = step.from_agent ? participantAlias(participants, step.from_agent) : null;
+  const targetAlias = participantAlias(participants, task.target_agent);
+  if (fromAlias) {
+    lines.push(`${indent}${fromAlias}->>${targetAlias}: delegate ${step.task}`);
+  }
+  for (const es of task.execution_steps ?? []) {
+    emitExecutionStep(es, targetAlias, participants, lines, indent);
+  }
+  if (fromAlias) {
+    lines.push(`${indent}${targetAlias}-->>${fromAlias}: ${task.result_handoff}`);
+  }
+}
+function emitExecutionStep(es, agentAlias2, participants, lines, indent) {
+  if (es.reads_artifact) {
+    const artAlias = participantAlias(participants, es.reads_artifact);
+    lines.push(`${indent}${agentAlias2}->>${artAlias}: [R] ${es.action}`);
+  }
+  if (es.produces_artifact) {
+    const artAlias = participantAlias(participants, es.produces_artifact);
+    lines.push(`${indent}${agentAlias2}->>${artAlias}: [W] ${es.action}`);
+  }
+  if (es.uses_tool) {
+    const toolAlias = participantAlias(participants, es.uses_tool);
+    lines.push(`${indent}${agentAlias2}->>${toolAlias}: ${es.action}`);
+  }
+  if (!es.reads_artifact && !es.produces_artifact && !es.uses_tool) {
+    lines.push(`${indent}${agentAlias2}->>${agentAlias2}: ${es.action}`);
+  }
+}
+function emitValidationStep(step, participants, dsl, lastFromAgent, lines, indent) {
+  const val = dsl.validations[step.validation];
+  if (!val) return;
+  const executorAlias = participantAlias(participants, val.executor);
+  const artifactAlias = participantAlias(participants, val.target_artifact);
+  const fromAlias = lastFromAgent ? participantAlias(participants, lastFromAgent) : null;
+  if (fromAlias && fromAlias !== executorAlias) {
+    lines.push(`${indent}${fromAlias}->>${executorAlias}: ${step.validation}`);
+  }
+  lines.push(`${indent}${executorAlias}->>${artifactAlias}: [R] ${val.target_artifact}`);
+  if (fromAlias && fromAlias !== executorAlias) {
+    lines.push(`${indent}${executorAlias}-->>${fromAlias}: results`);
+  }
+}
+function emitDecisionStep(step, participants, lastFromAgent, lines, indent) {
+  const branches = Object.entries(step.branches);
+  if (branches.length === 0) return;
+  const agentAlias2 = lastFromAgent ? participantAlias(participants, lastFromAgent) : null;
+  for (let i3 = 0; i3 < branches.length; i3++) {
+    const [key, values] = branches[i3];
+    if (i3 === 0) {
+      lines.push(`${indent}alt ${key}`);
+    } else {
+      lines.push(`${indent}else ${key}`);
+    }
+    if (agentAlias2) {
+      lines.push(`${indent}    Note over ${agentAlias2}: ${values.join(", ")}`);
+    } else {
+      lines.push(`${indent}    Note right of ${participantAlias(participants, [.../* @__PURE__ */ new Set()].join(""))}: ${values.join(", ")}`);
+    }
+  }
+  lines.push(`${indent}end`);
+}
+function generateSequenceDiagram(workflow, relatedTasks, dsl) {
+  const ids = collectReferencedIds(workflow, dsl, relatedTasks);
+  const participants = buildParticipants(ids, dsl);
+  const lines = [];
+  const indent = "    ";
+  lines.push("sequenceDiagram");
+  emitParticipants(participants, lines, indent);
+  lines.push("");
+  lines.push(`${indent}rect ${hashToColor(workflow.id, 0.15, 0.95)}`);
+  const firstP = participants[0];
+  const lastP = participants[participants.length - 1];
+  if (firstP && lastP) {
+    const noteLabel = workflow.description ? `${workflow.id} \u2014 ${workflow.description}` : workflow.id;
+    lines.push(`${indent}Note over ${firstP.alias},${lastP.alias}: ${noteLabel}`);
+  }
+  let lastFromAgent;
+  for (const step of workflow.steps) {
+    lines.push("");
+    if (step.type === "handoff") {
+      if (step.from_agent) lastFromAgent = step.from_agent;
+      emitHandoffStep(step, participants, dsl, relatedTasks, lines, indent);
+    } else if (step.type === "validation") {
+      emitValidationStep(step, participants, dsl, lastFromAgent, lines, indent);
+    } else if (step.type === "decision") {
+      emitDecisionStep(step, participants, lastFromAgent, lines, indent);
+    }
+  }
+  lines.push("");
+  lines.push(`${indent}end`);
+  return lines.join("\n");
+}
+
 // src/renderer/renderer.ts
 Handlebars.registerHelper("eq", (a3, b3) => a3 === b3);
 Handlebars.registerHelper("notEmpty", (obj) => {
@@ -60913,6 +61176,16 @@ Handlebars.registerHelper("size", (obj) => {
   if (obj && typeof obj === "object") return Object.keys(obj).length;
   return 0;
 });
+Handlebars.registerHelper(
+  "sequenceDiagram",
+  function() {
+    const workflow = this["workflow"];
+    const relatedTasks = this["relatedTasks"];
+    const dsl = this["dsl"];
+    if (!workflow || !dsl) return "";
+    return generateSequenceDiagram(workflow, relatedTasks ?? [], dsl);
+  }
+);
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,