DevTeam Orchestrator v1.0 is live. Read the changelog →
Templates
Creating Templates

Creating Templates

This guide walks you through authoring, testing, and publishing custom workflow templates.

Template Authoring Workflow

Design the Workflow

Before writing a template, sketch the DAG on paper:

  1. What are the inputs?
  2. What steps are needed?
  3. Which steps can run in parallel?
  4. Which steps need HITL approval?
  5. What is the final output format?

Write the Template File

Create a YAML file following the Template Schema:

weekly-report-v1.yaml
name: Weekly Project Report
description: >
  Generates a comprehensive weekly project status report from
  task data, meeting notes, and team updates.
version: "1.0.0"
industry: custom
tags:
  - reporting
  - project-management
  - weekly
visibility: organization
 
inputSchema:
  type: object
  required:
    - projectName
    - tasks
  properties:
    projectName:
      type: string
      description: Name of the project
    tasks:
      type: array
      items:
        type: object
        properties:
          title: { type: string }
          status: { type: string, enum: [done, in-progress, blocked, not-started] }
          assignee: { type: string }
          priority: { type: string }
      description: Array of task objects
    meetingNotes:
      type: string
      description: Optional meeting notes from the week
    period:
      type: string
      description: Report period (e.g., "Feb 10-14, 2026")
 
defaults:
  model: sonnet
  queue: default
  temperature: 0.4
 
steps:
  - id: categorize
    prompt: |
      Categorize and summarize the following project tasks:
 
      Project: {{input.projectName}}
      Period: {{input.period}}
 
      Tasks:
      {{input.tasks}}
 
      Group by status (Completed, In Progress, Blocked, Not Started).
      Include count and percentage for each category.
      Highlight any blocked items with reasons.
    maxTokens: 2048
 
  - id: extract-insights
    prompt: |
      Based on the categorized tasks and meeting notes, extract key insights:
 
      Task Summary:
      {{categorize.output}}
 
      Meeting Notes:
      {{input.meetingNotes}}
 
      Identify:
      1. Key accomplishments this week
      2. Major blockers and risks
      3. Team velocity trends
      4. Items requiring management attention
    dependsOn: [categorize]
    maxTokens: 2048
 
  - id: generate-report
    prompt: |
      Generate a professional weekly status report for {{input.projectName}}.
      Period: {{input.period}}
 
      Task Summary:
      {{categorize.output}}
 
      Insights:
      {{extract-insights.output}}
 
      Format as a structured report with:
      - Executive Summary (2-3 sentences)
      - Progress Dashboard (metrics and percentages)
      - Key Accomplishments
      - Risks and Blockers (with mitigation plans)
      - Next Week Priorities
      - Team Notes
    dependsOn: [categorize, extract-insights]
    maxTokens: 4096

Validate the Template

devteam templates validate --file weekly-report-v1.yaml

Expected output:

Validating: weekly-report-v1.yaml

Schema validation:    PASS
Step dependencies:    PASS (3 steps, no cycles)
Variable references:  PASS (all inputs and step refs valid)
Parallel analysis:    categorize -> [extract-insights] -> generate-report
Estimated cost:       $0.018

Validation passed. Ready to publish.

Test with Dry Run

Execute with --dry-run to validate the workflow without consuming model tokens:

devteam templates create --file weekly-report-v1.yaml
 
devteam templates deploy weekly-report-v1 \
  --input projectName="DevTeam Orchestrator" \
  --input 'tasks=[{"title":"Add HITL module","status":"done","assignee":"Alice"},{"title":"Fix WebSocket reconnect","status":"in-progress","assignee":"Bob"}]' \
  --input period="Feb 17-21, 2026" \
  --dry-run

Publish the Template

# Publish to your organization
devteam templates create --file weekly-report-v1.yaml
# Template weekly-report-v1 (v1.0.0) published to organization
 
# Or via SDK
const template = await client.createTemplate(
  loadTemplateFromFile('./weekly-report-v1.yaml')
);

Best Practices

Prompt Engineering for Templates

# BAD: Vague prompt
- id: analyze
  prompt: "Analyze this data: {{input.data}}"
 
# GOOD: Specific, structured prompt
- id: analyze
  prompt: |
    Analyze the following financial data for {{input.companyName}}.
 
    Data:
    {{input.data}}
 
    Perform the following analysis:
    1. Calculate key financial ratios (P/E, ROE, D/E, current ratio)
    2. Identify year-over-year trends
    3. Flag any anomalies or concerning patterns
    4. Compare against industry benchmarks for {{input.industry}}
 
    Output as structured JSON with fields:
    ratios, trends, anomalies, benchmarkComparison
  systemPrompt: >
    You are a CFA-certified financial analyst with 15 years of experience.
    Be precise with numbers. Flag uncertainty explicitly.
  temperature: 0.2
  maxTokens: 4096

Step Granularity

  • Keep each step focused on a single responsibility.
  • If a prompt exceeds 500 words, consider splitting it into two steps.
  • Use parallel steps when tasks are independent.
# Parallel pattern: analyze-risk and check-compliance run simultaneously
- id: extract
  prompt: "..."
 
- id: analyze-risk
  dependsOn: [extract]
  prompt: "..."
 
- id: check-compliance
  dependsOn: [extract]      # Same dependency = parallel execution
  prompt: "..."
 
- id: report
  dependsOn: [analyze-risk, check-compliance]  # Waits for both
  prompt: "..."

Error Handling

Add retry configuration to steps that may fail due to model rate limits or transient errors:

- id: critical-analysis
  prompt: "..."
  model: opus
  retry:
    maxAttempts: 3
    backoffMs: 2000
  timeoutMs: 120000

HITL Placement

Place HITL gates on steps where:

  • Errors have high business impact
  • The model confidence may be low
  • Regulatory compliance requires human sign-off
  • The output will be sent to external parties
hitl:
  requiredFor: [risk-assessment, final-report]
  confidenceThreshold: 0.85
  timeoutMs: 7200000  # 2 hours

Template Versioning

Update the version field when making changes:

  • Patch (1.0.0 to 1.0.1): Prompt improvements, typo fixes
  • Minor (1.0.0 to 1.1.0): New optional steps, additional outputs
  • Major (1.0.0 to 2.0.0): Input schema changes, step removals, breaking changes
# Update an existing template
devteam templates update --file weekly-report-v1.1.yaml
# Template weekly-report-v1 updated to v1.1.0
 
# List versions
devteam templates versions weekly-report-v1
# v1.1.0  2026-02-20  Added meeting notes integration
# v1.0.0  2026-02-15  Initial release
⚠️

Once a template version is published, it is immutable. Existing deployments continue to use their locked version. New deployments use the latest version unless a specific version is requested.

Next Steps

DevOps TemplatesHuman-in-the-Loop