@probelabs/visor 0.1.113 → 0.1.122

package/defaults/workflow-builder.yaml

@@ -0,0 +1,720 @@
+version: "1.0"
+
+# Meta-workflow for building and editing Visor workflows through AI-powered generation
+# Uses an AI router to interpret user intent and determine create vs edit mode.
+#
+# Flow:
+# 1. User describes what they want (natural language)
+# 2. AI router interprets intent, finds existing files if editing
+# 3. Claude CLI generates/edits the workflow (with optional MCP tools)
+# 4. Validation → Lint → Test → Review loop with auto-fix
+#
+# Uses Claude CLI directly via command type (no SDK required).
+#
+# MCP Server Support:
+# Pass mcp_config input to enable MCP tools for Claude (e.g., Probe Agent for codebase exploration)
+# Example: --input mcp_config='{"mcpServers":{"probe":{"command":"npx","args":["@anthropic/probe-agent"]}}}'
+
+id: workflow-builder
+name: Workflow Builder
+description: AI-powered Visor workflow generator and editor with integrated validation
+
+workspace:
+  enabled: true
+  base_path: .visor-workspaces
+
+inputs:
+  - name: mcp_config
+    description: Optional MCP server configuration JSON for Claude CLI
+    required: false
+    schema:
+      type: string
+
+routing:
+  max_loops: 30
+
+outputs:
+  - name: workflow_path
+    description: Path to the generated/edited workflow file
+    value: "{{ outputs['interpret-request'].workflow_path }}"
+
+  - name: success
+    description: Whether the workflow was successfully generated/edited
+    value_js: |
+      const review = outputs['review-workflow'];
+      return review && !(review.issues?.some(i =>
+        i.severity === 'critical' || i.severity === 'error'
+      ));
+
+steps:
+  # 1. Get requirements from user
+  get-requirements:
+    type: human-input
+    group: input
+    prompt: |
+      What would you like to do?
+
+      Examples:
+      - "Create a workflow that validates PR titles follow conventional commits"
+      - "Edit defaults/code-review.yaml to add a security check step"
+      - "Add tests to my-workflow.yaml"
+      - "Fix the routing in defaults/task-refinement.yaml"
+
+      Describe your request:
+
+    multiline: true
+    allow_empty: false
+
+  # 2. AI interprets the request and determines mode
+  interpret-request:
+    type: ai
+    group: input
+    criticality: internal
+    depends_on: [get-requirements]
+
+    assume:
+      - "outputs['get-requirements']?.text != null"
+
+    guarantee: "output && output.mode && output.workflow_path && output.requirements"
+
+    timeout: 120000
+
+    prompt: |
+      Analyze this user request and determine if they want to CREATE a new workflow
+      or EDIT an existing one.
+
+      User request:
+      {{ outputs['get-requirements'].text }}
+
+      Instructions:
+      1. If the user mentions a specific file path, they want to EDIT that file
+      2. If they say "create", "new", "build" without a file path, they want to CREATE
+      3. If they reference an existing workflow by name (e.g., "code-review workflow"),
+         try to find it - check defaults/*.yaml and *.yaml in current directory
+      4. Extract the core requirements/changes they want
+
+      IMPORTANT PATH RULES:
+      - For CREATE mode: ALWAYS use "./generated-workflow.yaml" as workflow_path (MUST be this exact path)
+      - For EDIT mode: Use the actual path to the existing file
+      - Tests should ALWAYS be included inline in the same workflow file (not separate)
+
+    schema:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum: [create, edit]
+          description: Whether to create new or edit existing workflow
+        workflow_path:
+          type: string
+          description: Path to the workflow file (./generated-workflow.yaml for create)
+        requirements:
+          type: string
+          description: Cleaned up requirements string
+        existing_workflow_summary:
+          type: string
+          description: Summary of existing workflow (only for edit mode)
+      required: [mode, workflow_path, requirements]
+
+  # 3. Checkout Visor source for context (provides docs and examples)
+  checkout-visor:
+    type: git-checkout
+    group: setup
+    criticality: internal
+    depends_on: [interpret-request]
+
+    assume:
+      - "outputs['interpret-request']?.mode != null"
+
+    repository: probelabs/visor
+    ref: new-branch
+    fetch_depth: 1
+    working_directory: "{% if env.VISOR_WORKSPACE_MAIN_PROJECT %}{{ env.VISOR_WORKSPACE_MAIN_PROJECT }}/.visor-context{% else %}./.visor-context{% endif %}"
+
+  # 4. Generate/edit workflow using AI with file editing capabilities
+  generate-workflow:
+    type: ai
+    group: generation
+    criticality: internal
+    depends_on: [checkout-visor]
+
+    assume:
+      - "outputs['checkout-visor']?.success === true"
+      - "outputs['interpret-request']?.requirements != null"
+
+    guarantee: "output != null"
+    timeout: 600000
+
+    ai:
+      allowEdit: true
+      allowBash: true
+      bashConfig:
+        allow:
+          - "npx:*"
+          - "visor:*"
+          - "ls:*"
+          - "cat:*"
+          - "head:*"
+          - "tail:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+      {% assign visorPath = outputs['checkout-visor'].path | default: '/tmp/visor-context' %}
+
+      {% if r.mode == 'edit' %}
+      EDIT the existing Visor workflow based on these requirements:
+
+      {{ r.requirements }}
+
+      The workflow to edit is at: {{ workflowPath }}
+      {% if r.existing_workflow_summary %}
+      Current structure: {{ r.existing_workflow_summary }}
+      {% endif %}
+      {% else %}
+      CREATE a new Visor workflow based on these requirements:
+
+      {{ r.requirements }}
+
+      Create the workflow at this EXACT path: {{ workflowPath }}
+      The working directory is the workspace project folder; create/edit files there (relative paths resolve inside the workspace).
+
+      CRITICAL: The file MUST be named exactly "{{ workflowPath }}" - no variations!
+      - DO NOT use names like "generated-workflow-fixed.yaml" or "hello-world.yaml"
+      - DO NOT add suffixes like "-fixed", "-v2", "-new"
+      {% endif %}
+
+      AVAILABLE TOOLS - You can ONLY use these tools:
+      - `create` - Create a new file. Arguments: file_path (string), content (string)
+      - `edit` - Edit an existing file. Arguments: file_path (string), old_string (string), new_string (string)
+      - `search` - Search for files or content
+      - `bash` - Run shell commands (only npx, visor, ls, cat, head, tail are allowed)
+
+      IMPORTANT: Do NOT try to use tools like "implement", "write", or any other tool name.
+      To create a file, use the `create` tool with file_path and content arguments.
+
+      INSTRUCTIONS:
+      1. Read the guide: {{ visorPath }}/docs/workflow-creation-guide.md
+      2. Study examples: {{ visorPath }}/defaults/code-review.yaml, {{ visorPath }}/defaults/task-refinement.yaml
+
+      {% if r.mode == 'edit' %}
+      3. READ the existing workflow: {{ workflowPath }}
+      4. Make targeted changes using the `edit` tool - preserve existing functionality
+      5. Update inline tests if needed (tests: section in the same file)
+      {% else %}
+      3. Use the `create` tool to create the workflow file at EXACTLY: {{ workflowPath }}
+      4. Include tests INLINE in the same file using the tests: section
+      {% endif %}
+
+      IMPORTANT: Tests must be included INLINE in the workflow file using a "tests:" section.
+      Do NOT create separate test files. Add tests that cover ALL intended use-cases
+      (happy paths, error paths, and edge cases). Example structure:
+      ```yaml
+      version: "1.0"
+      steps:
+        my-step:
+          type: log
+          message: "Hello"
+      tests:
+        cases:
+          - name: test-case
+            mocks:
+              my-step: { success: true }
+            expect:
+              calls:
+                - step: my-step
+      ```
+
+      Follow style guide: one step/one responsibility, guards, contracts, proper key ordering.
+
+      VALIDATION COMMANDS - You may run ONLY these commands to verify your work:
+      - Validate: npx @probelabs/visor@latest validate --config {{ workflowPath }}
+      - Test: npx @probelabs/visor@latest test --config {{ workflowPath }}
+
+      IMPORTANT: You MUST use "npx @probelabs/visor@latest" - do NOT use just "visor".
+      Only "npx @probelabs/visor" commands are allowed in bash.
+      DO NOT run this agent/workflow directly from this step.
+      Do NOT run validate or lint manually; the workflow will handle validation.
+
+      After creating the file with the `create` tool, run the validate command first, then the test command if needed.
+      If there are errors, fix them using the `edit` tool before finishing.
+
+    on_success:
+      goto: validate-workflow
+
+  # 5. Validate against Visor conventions
+  validate-workflow:
+    type: command
+    group: validation
+    criticality: internal
+    depends_on: [generate-workflow]
+
+    assume:
+      - "outputs['generate-workflow'] != null"
+
+    exec: |
+      {% assign r = outputs['interpret-request'] %}
+      WORKFLOW_PATH={{ r.workflow_path | default: './generated-workflow.yaml' | shell_escape }}
+      echo "DEBUG: Current directory: $(pwd)"
+      echo "DEBUG: Looking for: $WORKFLOW_PATH"
+      echo "DEBUG: Files in current directory:"
+      ls -la . 2>&1 | head -20
+      if [ -f "$WORKFLOW_PATH" ]; then
+        npx @probelabs/visor@latest validate --config "$WORKFLOW_PATH" 2>&1
+      else
+        echo "Error: $WORKFLOW_PATH not found" >&2
+        exit 1
+      fi
+
+    guarantee: "output != null"
+    fail_if: "output.exit_code !== 0"
+
+    on_fail:
+      run: [fix-validation-errors]
+
+    on_success:
+      goto: lint-workflow
+
+  # 6. Fix validation errors using AI
+  fix-validation-errors:
+    type: ai
+    group: fixes
+    criticality: internal
+    depends_on: [validate-workflow]
+
+    assume:
+      - "outputs['interpret-request']?.workflow_path != null || true"
+
+    guarantee: "output != null"
+    timeout: 300000
+
+    ai:
+      allowEdit: true
+      allowBash: true
+      bashConfig:
+        allow:
+          - "npx:*"
+          - "visor:*"
+          - "cat:*"
+          - "ls:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      The workflow validation failed. Fix the issues.
+
+      CRITICAL: The workflow file MUST be at this EXACT path: {{ workflowPath }}
+      DO NOT create any other file. Only edit {{ workflowPath }}.
+
+      Validation output:
+      {{ outputs['validate-workflow'].stdout }}
+      {{ outputs['validate-workflow'].stderr }}
+
+      AVAILABLE TOOLS - You can ONLY use these tools:
+      - `create` - Create a new file. Arguments: file_path (string), content (string)
+      - `edit` - Edit an existing file. Arguments: file_path (string), old_string (string), new_string (string)
+      - `search` - Search for files or content
+      - `bash` - Run shell commands (only npx, visor, cat, ls are allowed)
+
+      Instructions:
+      1. If {{ workflowPath }} doesn't exist, use the `create` tool to create it at EXACTLY that path
+      2. If it exists, read the file to understand current content
+      3. Make targeted fixes using the `edit` tool - don't rewrite everything
+      4. NEVER create a file with a different name like "generated-workflow-fixed.yaml"
+      5. Do NOT run this agent/workflow directly from this step.
+      6. Only the validate and test commands are allowed for verification.
+
+      If you need to verify after fixing, use ONLY these commands:
+      npx @probelabs/visor@latest validate --config {{ workflowPath }}
+      npx @probelabs/visor@latest test --config {{ workflowPath }}
+
+      Keep iterating until validation passes.
+
+    on_success:
+      goto: validate-workflow
+    on_fail:
+      goto: validate-workflow
+
+  # 7. Run validation (lint subcommand not available in @latest)
+  lint-workflow:
+    type: command
+    group: validation
+    criticality: internal
+    depends_on: [validate-workflow]
+
+    assume:
+      - "outputs['validate-workflow'] != null"
+
+    exec: |
+      {% assign r = outputs['interpret-request'] %}
+      WORKFLOW_PATH={{ r.workflow_path | default: './generated-workflow.yaml' | shell_escape }}
+      if [ -f "$WORKFLOW_PATH" ]; then
+        npx @probelabs/visor@latest validate --config "$WORKFLOW_PATH" 2>&1
+      else
+        echo "Error: $WORKFLOW_PATH not found" >&2
+        exit 1
+      fi
+
+    guarantee: "output != null"
+    fail_if: "output.exit_code !== 0"
+
+    on_fail:
+      run: [fix-lint-errors]
+
+    on_success:
+      goto: run-tests
+
+  # 8. Fix lint errors using AI
+  fix-lint-errors:
+    type: ai
+    group: fixes
+    criticality: internal
+    depends_on: [lint-workflow]
+
+    assume:
+      - "outputs['interpret-request']?.workflow_path != null || true"
+
+    guarantee: "output != null"
+    timeout: 300000
+
+    ai:
+      allowEdit: true
+      allowBash: true
+      bashConfig:
+        allow:
+          - "npx:*"
+          - "visor:*"
+          - "cat:*"
+          - "ls:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      The workflow has validation issues. Fix them.
+
+      Workflow path: {{ workflowPath }}
+
+      Lint output:
+      {{ outputs['lint-workflow'].stdout }}
+      {{ outputs['lint-workflow'].stderr }}
+
+      AVAILABLE TOOLS - You can ONLY use these tools:
+      - `edit` - Edit an existing file. Arguments: file_path (string), old_string (string), new_string (string)
+      - `search` - Search for files or content
+      - `bash` - Run shell commands (only npx, visor, cat, ls are allowed)
+
+      Instructions:
+      1. Read {{ workflowPath }} to understand current content
+      2. Fix validation errors using the `edit` tool - warnings can be left if minor
+      3. Make targeted fixes, don't rewrite everything
+      4. Do NOT run this agent/workflow directly from this step.
+      5. Only the validate and test commands are allowed for verification.
+
+      If you need to verify after fixing, use ONLY these commands:
+      npx @probelabs/visor@latest validate --config {{ workflowPath }}
+      npx @probelabs/visor@latest test --config {{ workflowPath }}
+
+      IMPORTANT: Use "npx @probelabs/visor@latest" - NOT just "visor".
+
+      Keep iterating until validation passes.
+
+    on_success:
+      goto: lint-workflow
+    on_fail:
+      goto: lint-workflow
+
+  # 9. Run YAML tests
+  run-tests:
+    type: command
+    group: testing
+    criticality: internal
+    depends_on: [lint-workflow]
+
+    assume:
+      - "outputs['lint-workflow'] != null"
+
+    exec: |
+      {% assign r = outputs['interpret-request'] %}
+      WORKFLOW_PATH={{ r.workflow_path | default: './generated-workflow.yaml' | shell_escape }}
+      if grep -q "^tests:" -- "$WORKFLOW_PATH" 2>/dev/null; then
+        npx @probelabs/visor@latest test --config "$WORKFLOW_PATH" 2>&1
+      else
+        echo "Warning: No inline tests found. Skipping test execution."
+        echo '{"skipped": true, "reason": "no tests section in workflow"}'
+      fi
+
+    output_format: text
+    guarantee: "output != null"
+    fail_if: "output.exit_code !== 0"
+
+    on_fail:
+      run: [fix-test-failures]
+
+    on_success:
+      goto: review-workflow
+
+  # 10. Fix test failures using AI
+  fix-test-failures:
+    type: ai
+    group: fixes
+    criticality: internal
+    depends_on: [run-tests]
+
+    assume:
+      - "outputs['interpret-request']?.workflow_path != null || true"
+
+    guarantee: "output != null"
+    timeout: 300000
+
+    ai:
+      allowEdit: true
+      allowBash: true
+      bashConfig:
+        allow:
+          - "npx:*"
+          - "visor:*"
+          - "cat:*"
+          - "ls:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      The workflow tests failed. Analyze and fix.
+
+      Workflow: {{ workflowPath }}
+      Tests are inline in the same file (look for the "tests:" section)
+
+      Test output:
+      {{ outputs['run-tests'].stdout }}
+      {{ outputs['run-tests'].stderr }}
+
+      AVAILABLE TOOLS - You can ONLY use these tools:
+      - `edit` - Edit an existing file. Arguments: file_path (string), old_string (string), new_string (string)
+      - `search` - Search for files or content
+      - `bash` - Run shell commands (only npx, visor, cat, ls are allowed)
+
+      Instructions:
+      1. Read the workflow file to understand the steps and inline tests
+      2. Analyze the test failures
+      3. Fix either the workflow steps (if logic is wrong) or the inline tests using the `edit` tool
+      4. Ensure tests cover ALL intended use-cases (happy paths, error paths, edge cases)
+      5. Do NOT run this agent/workflow directly from this step.
+      6. Only the validate and test commands are allowed for verification.
+
+      After fixing, verify with this EXACT command:
+      npx @probelabs/visor@latest test --config {{ workflowPath }}
+
+      IMPORTANT: Use "npx @probelabs/visor@latest" - NOT just "visor".
+
+      Keep iterating until tests pass.
+
+    on_success:
+      goto: run-tests
+    on_fail:
+      goto: run-tests
+
+  # 11. Code review the generated workflow
+  review-workflow:
+    type: ai
+    group: review
+    criticality: policy
+    depends_on: [run-tests]
+
+    guarantee: "output && Array.isArray(output.issues) && typeof output.summary === 'string' && typeof output.approval === 'boolean'"
+
+    timeout: 180000
+
+    ai:
+      allowBash: true
+      bashConfig:
+        allow:
+          - "cat:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      Review the {% if r.mode == 'edit' %}edited{% else %}generated{% endif %} workflow for:
+
+      1. **Security Issues** - guards, credentials, input sanitization
+      2. **Missing Edge Cases** - failure handling, loop bounds, timeouts
+      3. **Test Coverage** - happy path, failures, meaningful assertions
+      4. **Style Guide** - key ordering, single-responsibility, guards/contracts
+
+      Original requirements:
+      {{ r.requirements }}
+
+      Workflow file: {{ workflowPath }}
+
+      First read the workflow file, then provide your review.
+      Be constructive and specific. Flag critical issues.
+      Do NOT run this agent/workflow directly from this step.
+      Only the validate and test commands are allowed for verification if you must run one.
+
+    schema:
+      type: object
+      properties:
+        issues:
+          type: array
+          items:
+            type: object
+            properties:
+              severity:
+                type: string
+                enum: [critical, error, warning, info]
+              category:
+                type: string
+                enum: [security, edge-case, coverage, style, other]
+              message:
+                type: string
+              suggestion:
+                type: string
+            required: [severity, category, message]
+        summary:
+          type: string
+          description: Overall review summary
+        approval:
+          type: boolean
+          description: Whether the workflow is ready for use
+      required: [issues, summary, approval]
+
+    fail_if: "output.issues?.some(i => i.severity === 'critical' || i.severity === 'error')"
+
+    on_fail:
+      run: [apply-review-fixes]
+
+    on_success:
+      goto: publish-workflow
+
+  # 12. Publish workflow to original working directory
+  publish-workflow:
+    type: command
+    group: output
+    criticality: info
+    depends_on: [review-workflow]
+
+    assume:
+      - "outputs['review-workflow'] != null"
+
+    exec: |
+      {% assign r = outputs['interpret-request'] %}
+      WORKFLOW_PATH={{ r.workflow_path | default: './generated-workflow.yaml' | shell_escape }}
+      ORIG_DIR="${VISOR_ORIGINAL_WORKDIR:-$PWD}"
+      if [ -f "$WORKFLOW_PATH" ]; then
+        mkdir -p "$ORIG_DIR"
+        cp "$WORKFLOW_PATH" "$ORIG_DIR/$(basename "$WORKFLOW_PATH")"
+        echo "Copied to $ORIG_DIR/$(basename "$WORKFLOW_PATH")"
+      else
+        echo "Error: $WORKFLOW_PATH not found" >&2
+        exit 1
+      fi
+
+    guarantee: "output != null"
+    fail_if: "output.exit_code !== 0"
+
+    on_success:
+      goto: finalize
+
+  # 13. Apply review fixes using AI
+  apply-review-fixes:
+    type: ai
+    group: fixes
+    criticality: internal
+    depends_on: [review-workflow]
+
+    if: "outputs['review-workflow']?.issues?.length > 0"
+
+    guarantee: "output != null"
+    timeout: 300000
+
+    ai:
+      allowEdit: true
+      allowBash: true
+      bashConfig:
+        allow:
+          - "npx:*"
+          - "visor:*"
+          - "cat:*"
+          - "ls:*"
+
+    prompt: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign review = outputs['review-workflow'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      Apply these review suggestions to the workflow:
+
+      {% for issue in review.issues %}
+      - [{{ issue.severity | upcase }}] {{ issue.category }}: {{ issue.message }}
+      {% if issue.suggestion %}  Suggestion: {{ issue.suggestion }}{% endif %}
+      {% endfor %}
+
+      Summary: {{ review.summary }}
+
+      AVAILABLE TOOLS - You can ONLY use these tools:
+      - `edit` - Edit an existing file. Arguments: file_path (string), old_string (string), new_string (string)
+      - `search` - Search for files or content
+      - `bash` - Run shell commands (only npx, visor, cat, ls are allowed)
+
+      Instructions:
+      Fix the issues in {{ workflowPath }} using the `edit` tool (workflow steps and inline tests are in the same file).
+
+      - Critical/Error issues must be fixed
+      - Warning issues should be addressed if straightforward
+      - Info issues are optional improvements
+      - Ensure tests cover ALL intended use-cases after changes
+      - Do NOT run this agent/workflow directly from this step
+      - Only the validate and test commands are allowed for verification
+
+    on_success:
+      goto: run-tests
+    on_fail:
+      goto: run-tests
+
+  # 14. Final output
+  finalize:
+    type: log
+    group: output
+    criticality: info
+    depends_on: [publish-workflow]
+
+    message: |
+      {% assign r = outputs['interpret-request'] %}
+      {% assign workflowPath = r.workflow_path | default: './generated-workflow.yaml' %}
+
+      Workflow {% if r.mode == 'edit' %}updated{% else %}created{% endif %} successfully!
+
+      File: {{ workflowPath }}
+      (Tests included inline in the same file)
+      Published: {{ outputs['publish-workflow'] | default: 'copy step did not run' }}
+
+      Review Summary:
+      {{ outputs['review-workflow'].summary }}
+
+      {% assign issues = outputs['review-workflow'].issues %}
+      {% if issues.size > 0 %}
+      Remaining Notes:
+      {% for issue in issues %}
+      - [{{ issue.severity }}] {{ issue.message }}
+      {% endfor %}
+      {% endif %}
+
+      Next Steps:
+      {% if r.mode == 'edit' %}
+      1. Review the changes made to {{ workflowPath }}
+      2. Run tests: npx @probelabs/visor@latest test --config {{ workflowPath }}
+      3. Commit the changes when satisfied
+      {% else %}
+      1. Review the generated workflow
+      2. Move it to your project's defaults/ or workflows/ directory
+      3. Configure it in your .visor.yaml
+      4. Run it with: npx @probelabs/visor@latest --config {{ workflowPath }}
+      {% endif %}
+
+    level: info
+    include_pr_context: false
+    include_dependencies: false
+    include_metadata: false