agent-relay 2.3.13 → 2.4.0

package/packages/sdk/src/workflows/builtin-templates/documentation.yaml

@@ -0,0 +1,120 @@
+version: "1.0"
+name: documentation
+description: "Blueprint-style documentation workflow with deterministic file operations."
+swarm:
+  pattern: handoff
+  maxConcurrency: 1
+  timeoutMs: 3000000
+  channel: swarm-documentation
+  idleNudge:
+    nudgeAfterMs: 120000
+    escalateAfterMs: 120000
+    maxNudges: 1
+agents:
+  - name: lead
+    cli: claude
+    role: "Owns final editorial sign-off"
+  - name: researcher
+    cli: codex
+    role: "Collects technical context and source details"
+    interactive: false
+  - name: writer
+    cli: codex
+    role: "Drafts user-facing documentation"
+    interactive: false
+  - name: editor
+    cli: claude
+    role: "Edits for accuracy, clarity, and structure"
+workflows:
+  - name: docs-production
+    description: "Gather context, draft docs, edit, and publish summary."
+    onError: skip
+    preflight:
+      - command: git status --porcelain
+        failIf: non-empty
+        description: "Ensure working directory is clean"
+    steps:
+      # Deterministic: List existing docs
+      - name: list-docs
+        type: deterministic
+        command: find . -name "*.md" -o -name "*.mdx" 2>/dev/null | head -50 || echo "No docs found"
+
+      # Agent: Gather context
+      - name: gather-context
+        type: agent
+        agent: researcher
+        dependsOn: [list-docs]
+        task: |
+          Collect source context and required updates:
+          {{task}}
+
+          Existing documentation files:
+          {{steps.list-docs.output}}
+        verification:
+          type: output_contains
+          value: CONTEXT_COMPLETE
+
+      # Deterministic: Create docs branch
+      - name: create-branch
+        type: deterministic
+        dependsOn: [gather-context]
+        command: git checkout -b docs/{{branch-name}}
+
+      # Agent: Draft documentation
+      - name: draft
+        type: agent
+        agent: writer
+        dependsOn: [create-branch]
+        task: |
+          Draft documentation updates based on gathered context:
+          {{steps.gather-context.output}}
+        verification:
+          type: output_contains
+          value: DRAFT_COMPLETE
+
+      # Agent: Edit draft
+      - name: edit
+        type: agent
+        agent: editor
+        dependsOn: [draft]
+        task: |
+          Edit the draft for technical accuracy and readability:
+          {{steps.draft.output}}
+        verification:
+          type: output_contains
+          value: EDIT_COMPLETE
+
+      # Deterministic: Commit docs
+      - name: commit
+        type: deterministic
+        dependsOn: [edit]
+        command: 'git add -A && git commit -m "docs: {{steps.gather-context.output | first-line}}"'
+
+      # Deterministic: Push
+      - name: push
+        type: deterministic
+        dependsOn: [commit]
+        command: git push origin docs/{{branch-name}}
+
+      # Agent: Publish summary
+      - name: publish-summary
+        type: agent
+        agent: lead
+        dependsOn: [push]
+        task: |
+          Publish a final summary of documentation changes and open items.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: docs-ready
+      waitFor: [gather-context, draft, edit]
+      timeoutMs: 600000
+state:
+  backend: memory
+  ttlMs: 259200000
+  namespace: documentation
+errorHandling:
+  strategy: continue
+  notifyChannel: swarm-documentation

package/packages/sdk/src/workflows/builtin-templates/feature-dev.yaml

@@ -0,0 +1,142 @@
+version: "1.0"
+name: feature-dev
+description: "Blueprint-style feature development with deterministic quality gates."
+swarm:
+  pattern: hub-spoke
+  maxConcurrency: 2
+  timeoutMs: 3600000
+  channel: swarm-feature-dev
+  idleNudge:
+    nudgeAfterMs: 120000
+    escalateAfterMs: 120000
+    maxNudges: 1
+agents:
+  - name: lead
+    cli: claude
+    role: "Lead engineer coordinating delivery"
+  - name: planner
+    cli: codex
+    role: "Plans implementation and acceptance criteria"
+    interactive: false
+  - name: developer
+    cli: codex
+    role: "Implements planned changes"
+    interactive: false
+  - name: reviewer
+    cli: claude
+    role: "Reviews code quality and release risk"
+workflows:
+  - name: feature-delivery
+    description: "Plan, implement, review, and finalize a feature request with quality gates."
+    onError: retry
+    preflight:
+      - command: git status --porcelain
+        failIf: non-empty
+        description: "Ensure working directory is clean"
+      - command: npm run type-check 2>/dev/null || echo "skip"
+        description: "Run type checking if available"
+    steps:
+      # Agent: Planning
+      - name: plan
+        type: agent
+        agent: planner
+        task: |
+          Analyze the feature request and produce a concrete implementation plan:
+          {{task}}
+        retries: 1
+        verification:
+          type: output_contains
+          value: PLAN_COMPLETE
+
+      # Deterministic: Create feature branch
+      - name: create-branch
+        type: deterministic
+        dependsOn: [plan]
+        command: git checkout -b feature/{{branch-name}}
+
+      # Agent: Implementation
+      - name: implement
+        type: agent
+        agent: developer
+        dependsOn: [create-branch]
+        task: |
+          Implement the approved plan:
+          {{steps.plan.output}}
+        retries: 1
+        verification:
+          type: output_contains
+          value: IMPLEMENTATION_COMPLETE
+
+      # Deterministic: Lint
+      - name: lint
+        type: deterministic
+        dependsOn: [implement]
+        command: npm run lint:fix 2>/dev/null || npm run lint 2>/dev/null || echo "No lint configured"
+
+      # Deterministic: Run tests
+      - name: test
+        type: deterministic
+        dependsOn: [lint]
+        command: npm test 2>/dev/null || echo "No tests configured"
+
+      # Agent: Fix any failures (with iteration limit)
+      - name: fix-failures
+        type: agent
+        agent: developer
+        dependsOn: [test]
+        task: |
+          Review test results and fix any failures. If all tests passed, output TESTS_PASSED.
+          Test output: {{steps.test.output}}
+        maxIterations: 2
+        verification:
+          type: output_contains
+          value: TESTS_PASSED
+
+      # Deterministic: Stage and commit
+      - name: commit
+        type: deterministic
+        dependsOn: [fix-failures]
+        command: 'git add -A && git commit -m "feat: {{steps.plan.output | first-line}}"'
+
+      # Agent: Code review
+      - name: review
+        type: agent
+        agent: reviewer
+        dependsOn: [commit]
+        task: |
+          Review implementation quality, correctness, and test coverage:
+          {{steps.implement.output}}
+        verification:
+          type: output_contains
+          value: REVIEW_COMPLETE
+
+      # Deterministic: Push to remote
+      - name: push
+        type: deterministic
+        dependsOn: [review]
+        command: git push origin feature/{{branch-name}}
+
+      # Agent: Finalize
+      - name: finalize
+        type: agent
+        agent: lead
+        dependsOn: [push]
+        task: |
+          Summarize decisions and ship readiness for the feature.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: delivery-ready
+      waitFor: [plan, implement, review]
+      timeoutMs: 900000
+state:
+  backend: memory
+  ttlMs: 86400000
+  namespace: feature-dev
+errorHandling:
+  strategy: retry
+  maxRetries: 2
+  retryDelayMs: 5000
+  notifyChannel: swarm-feature-dev

package/packages/sdk/src/workflows/builtin-templates/refactor.yaml

@@ -0,0 +1,141 @@
+version: "1.0"
+name: refactor
+description: "Blueprint-style refactor workflow with deterministic quality gates."
+swarm:
+  pattern: hierarchical
+  maxConcurrency: 2
+  timeoutMs: 4500000
+  channel: swarm-refactor
+  idleNudge:
+    nudgeAfterMs: 120000
+    escalateAfterMs: 120000
+    maxNudges: 1
+agents:
+  - name: lead
+    cli: claude
+    role: "Owns scope, sequencing, and acceptance"
+  - name: architect
+    cli: codex
+    role: "Designs target architecture and migration plan"
+    interactive: false
+  - name: refactorer
+    cli: codex
+    role: "Executes scoped refactor changes"
+    interactive: false
+  - name: tester
+    cli: claude
+    role: "Validates behavior parity and risk"
+workflows:
+  - name: refactor-execution
+    description: "Analyze current system, design approach, refactor, and validate."
+    onError: retry
+    preflight:
+      - command: git status --porcelain
+        failIf: non-empty
+        description: "Ensure working directory is clean"
+      - command: npm test 2>/dev/null || echo "baseline"
+        description: "Capture baseline test results"
+    steps:
+      # Agent: Analyze current design
+      - name: analyze
+        type: agent
+        agent: architect
+        task: |
+          Analyze current design and identify refactor opportunities:
+          {{task}}
+        verification:
+          type: output_contains
+          value: ANALYSIS_COMPLETE
+
+      # Agent: Design refactor plan
+      - name: design
+        type: agent
+        agent: architect
+        dependsOn: [analyze]
+        task: |
+          Provide incremental refactor plan with rollback notes:
+          {{steps.analyze.output}}
+        verification:
+          type: output_contains
+          value: PLAN_COMPLETE
+
+      # Deterministic: Create refactor branch
+      - name: create-branch
+        type: deterministic
+        dependsOn: [design]
+        command: git checkout -b refactor/{{branch-name}}
+
+      # Agent: Execute refactor
+      - name: refactor-code
+        type: agent
+        agent: refactorer
+        dependsOn: [create-branch]
+        task: |
+          Execute the refactor plan while preserving behavior:
+          {{steps.design.output}}
+        retries: 2
+        verification:
+          type: output_contains
+          value: REFACTOR_COMPLETE
+
+      # Deterministic: Run linting
+      - name: lint
+        type: deterministic
+        dependsOn: [refactor-code]
+        command: npm run lint:fix 2>/dev/null || npm run lint 2>/dev/null || echo "No lint configured"
+
+      # Deterministic: Run tests
+      - name: test
+        type: deterministic
+        dependsOn: [lint]
+        command: npm test
+
+      # Agent: Validate behavior parity
+      - name: validate
+        type: agent
+        agent: tester
+        dependsOn: [test]
+        task: |
+          Validate no regressions and ensure tests/quality checks pass:
+          {{steps.refactor-code.output}}
+          Test results: {{steps.test.output}}
+        verification:
+          type: output_contains
+          value: VALIDATION_COMPLETE
+
+      # Deterministic: Commit
+      - name: commit
+        type: deterministic
+        dependsOn: [validate]
+        command: 'git add -A && git commit -m "refactor: {{steps.design.output | first-line}}"'
+
+      # Deterministic: Push
+      - name: push
+        type: deterministic
+        dependsOn: [commit]
+        command: git push origin refactor/{{branch-name}}
+
+      # Agent: Handoff
+      - name: handoff
+        type: agent
+        agent: lead
+        dependsOn: [push]
+        task: |
+          Produce final refactor summary and open follow-up items.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: refactor-ready
+      waitFor: [analyze, design, refactor-code, validate]
+      timeoutMs: 900000
+state:
+  backend: memory
+  ttlMs: 604800000
+  namespace: refactor
+errorHandling:
+  strategy: retry
+  maxRetries: 2
+  retryDelayMs: 5000
+  notifyChannel: swarm-refactor

package/packages/sdk/src/workflows/builtin-templates/review-loop.yaml

@@ -0,0 +1,223 @@
+version: "1.0"
+name: review-loop
+description: "Implement a task with automated multi-perspective code review loop. Inspired by claude-review-loop pattern."
+swarm:
+  pattern: review-loop
+  maxConcurrency: 4
+  timeoutMs: 3600000
+  channel: swarm-review-loop
+  idleNudge:
+    nudgeAfterMs: 180000
+    escalateAfterMs: 180000
+    maxNudges: 2
+agents:
+  - name: implementer
+    cli: claude
+    role: "Senior developer implementing the task and addressing review feedback"
+  - name: reviewer-diff
+    cli: codex
+    role: "Code quality reviewer focusing on git diff, tests, and potential bugs"
+    interactive: false
+  - name: reviewer-architecture
+    cli: claude
+    role: "Architecture and design reviewer assessing structure and maintainability"
+    interactive: false
+  - name: reviewer-security
+    cli: codex
+    role: "Security reviewer checking for OWASP Top 10 vulnerabilities"
+    interactive: false
+workflows:
+  - name: review-loop-workflow
+    description: "Implement task, run parallel reviews, consolidate feedback, and address issues."
+    onError: fail
+    steps:
+      # Phase 1: Implementation
+      - name: implement
+        type: agent
+        agent: implementer
+        task: |
+          Implement the following task:
+          {{task}}
+
+          When complete, output: IMPLEMENTATION COMPLETE
+        verification:
+          type: output_contains
+          value: IMPLEMENTATION COMPLETE
+
+      # Deterministic: Capture diff for review
+      - name: capture-diff
+        type: deterministic
+        dependsOn: [implement]
+        command: git diff HEAD~1 2>/dev/null || git diff 2>/dev/null || echo "No changes"
+        captureOutput: true
+
+      # Deterministic: Capture file list
+      - name: capture-files
+        type: deterministic
+        dependsOn: [capture-diff]
+        command: git diff --name-only HEAD~1 2>/dev/null || git diff --name-only 2>/dev/null || echo "No files"
+        captureOutput: true
+
+      # Phase 2: Parallel Reviews (fan-out)
+      - name: review-diff
+        type: agent
+        agent: reviewer-diff
+        dependsOn: [capture-files]
+        task: |
+          Review the git diff for code quality issues:
+
+          Focus areas:
+          - Code readability and clarity
+          - Test coverage (are new features tested?)
+          - Potential bugs or edge cases
+          - Error handling completeness
+
+          Changed files: {{steps.capture-files.output}}
+
+          Diff:
+          {{steps.capture-diff.output}}
+
+          Output format:
+          - If all looks good: REVIEW:PASS
+          - If issues found: REVIEW:ISSUES followed by numbered list of issues
+        verification:
+          type: output_contains
+          value: "REVIEW:"
+
+      - name: review-architecture
+        type: agent
+        agent: reviewer-architecture
+        dependsOn: [capture-files]
+        task: |
+          Review the architecture and design:
+
+          Focus areas:
+          - Design patterns and best practices
+          - Separation of concerns
+          - Code organization and maintainability
+          - API design (if applicable)
+
+          Changed files: {{steps.capture-files.output}}
+
+          Diff:
+          {{steps.capture-diff.output}}
+
+          Output format:
+          - If all looks good: REVIEW:PASS
+          - If issues found: REVIEW:ISSUES followed by numbered list of issues
+        verification:
+          type: output_contains
+          value: "REVIEW:"
+
+      - name: review-security
+        type: agent
+        agent: reviewer-security
+        dependsOn: [capture-files]
+        task: |
+          Security review for OWASP Top 10 vulnerabilities:
+
+          Focus areas:
+          - Injection vulnerabilities (SQL, command, XSS)
+          - Authentication and authorization issues
+          - Sensitive data exposure
+          - Security misconfiguration
+          - Input validation
+
+          Changed files: {{steps.capture-files.output}}
+
+          Diff:
+          {{steps.capture-diff.output}}
+
+          Output format:
+          - If secure: REVIEW:PASS
+          - If vulnerabilities found: REVIEW:ISSUES followed by numbered list with severity
+        verification:
+          type: output_contains
+          value: "REVIEW:"
+
+      # Phase 3: Consolidate reviews
+      - name: consolidate
+        type: agent
+        agent: implementer
+        dependsOn: [review-diff, review-architecture, review-security]
+        task: |
+          Review all feedback from the code reviewers and consolidate findings:
+
+          ## Diff Review
+          {{steps.review-diff.output}}
+
+          ## Architecture Review
+          {{steps.review-architecture.output}}
+
+          ## Security Review
+          {{steps.review-security.output}}
+
+          Tasks:
+          1. Analyze each review's findings
+          2. Identify which issues are valid and should be addressed
+          3. Note any conflicting feedback
+          4. Create a prioritized action plan
+
+          Output: CONSOLIDATED with summary of issues to address (or NO_ISSUES if all reviews passed)
+        verification:
+          type: output_contains
+          value: CONSOLIDATED
+
+      # Phase 4: Address feedback (the loop)
+      - name: address-feedback
+        type: agent
+        agent: implementer
+        dependsOn: [consolidate]
+        task: |
+          Address the consolidated review feedback:
+
+          {{steps.consolidate.output}}
+
+          For each valid issue:
+          1. Make the necessary code changes
+          2. Explain what was fixed and why
+
+          If there were no issues to address, confirm the implementation is complete.
+
+          Output: ADDRESSED followed by summary of changes made (or NO_CHANGES_NEEDED)
+        verification:
+          type: output_contains
+          value: ADDRESSED
+        retries: 2
+        maxIterations: 3
+
+      # Final step: Completion summary
+      - name: complete
+        type: agent
+        agent: implementer
+        dependsOn: [address-feedback]
+        task: |
+          Provide a final summary of the completed work:
+
+          Original task: {{task}}
+
+          Include:
+          1. What was implemented
+          2. Key decisions made
+          3. Review feedback that was addressed
+          4. Any remaining considerations or follow-up items
+
+          Output: DONE
+        verification:
+          type: output_contains
+          value: DONE
+
+coordination:
+  barriers:
+    - name: reviews-complete
+      waitFor: [review-diff, review-architecture, review-security]
+      timeoutMs: 900000
+  consensusStrategy: majority
+state:
+  backend: memory
+  ttlMs: 21600000
+  namespace: review-loop
+errorHandling:
+  strategy: continue
+  maxRetries: 2
+  notifyChannel: swarm-review-loop