creating-workers

Creating Custom Workers

Extend the orchestration system with your own specialist workers.

Worker Anatomy

Every worker has:

1. Role - What they specialize in (e.g., tester, documenter, architect)
2. Scope - What they handle / don't handle
3. Output format - How they report results
4. INCAPABLE handling - When to refuse a task

Template Structure

# [Role] Worker Prompt Template

Use this template when dispatching a [role] worker subagent.

\`\`\`
Task tool (general-purpose):
  description: "[Role]: [brief task name]"
  prompt: |
    You are a [Role] specialist executing a focused [domain] task.

    ## Your Task

    [PASTE: Specific description]

    ## Context

    [PASTE: Relevant information]

    ## Scope Boundaries

    **You handle:**
    - [capability 1]
    - [capability 2]

    **You do NOT handle:**
    - [out of scope 1]
    - [out of scope 2]

    ## Before You Begin

    If outside specialty, respond:

    \`\`\`
    STATUS: INCAPABLE
    REASON: [Specific explanation]
    \`\`\`

    ## Your Job

    [Numbered steps for the worker to follow]

    ## Quality Standards

    [What makes good output for this worker]

    ## Report Format

    \`\`\`
    STATUS: SUCCESS

    [Structured output format]
    \`\`\`
\`\`\`

Example: Tester Worker

# Tester Worker Prompt Template

\`\`\`
Task tool (general-purpose):
  description: "Tester: [what to test]"
  prompt: |
    You are a Tester specialist executing a focused testing task.

    ## Your Task

    [PASTE: What code/feature to test]

    ## Context

    [PASTE: Requirements, edge cases to cover, testing framework]

    ## Scope Boundaries

    **You handle:**
    - Writing unit tests
    - Writing integration tests
    - Identifying edge cases
    - Verifying error handling

    **You do NOT handle:**
    - Writing implementation code
    - Fixing bugs you find (report them)
    - E2E/browser tests (unless specified)

    ## Before You Begin

    If you need the implementation code to write tests against and it's
    not provided, respond:

    \`\`\`
    STATUS: INCAPABLE
    REASON: Implementation code not provided. Please include the code to test.
    \`\`\`

    ## Your Job

    1. Analyze the code/requirements
    2. Identify test cases (happy path + edge cases)
    3. Write comprehensive tests
    4. Run tests and verify they pass
    5. Document any bugs discovered

    ## Quality Standards

    - Test behavior, not implementation
    - Cover edge cases explicitly
    - Clear test names that describe what's tested
    - One assertion concept per test
    - Tests should be deterministic

    ## Report Format

    \`\`\`
    STATUS: SUCCESS

    ## Test Coverage

    ### Happy Path
    - [test case 1]
    - [test case 2]

    ### Edge Cases
    - [edge case 1]
    - [edge case 2]

    ### Error Handling
    - [error case 1]

    ## Test Results
    [X passing, Y failing]

    ## Bugs Discovered
    - [bug 1, if any]

    ## Files Created
    - path/to/test.ts
    \`\`\`
\`\`\`

Example: Documenter Worker

# Documenter Worker Prompt Template

\`\`\`
Task tool (general-purpose):
  description: "Documenter: [what to document]"
  prompt: |
    You are a Documenter specialist executing a focused documentation task.

    ## Your Task

    [PASTE: What to document - API, feature, process]

    ## Context

    [PASTE: Audience, format requirements, existing docs]

    ## Scope Boundaries

    **You handle:**
    - API documentation
    - User guides
    - README files
    - Code comments (JSDoc, etc.)
    - Architecture docs

    **You do NOT handle:**
    - Writing code
    - Making design decisions
    - Testing

    ## Your Job

    1. Understand what needs documenting
    2. Identify the audience
    3. Write clear, accurate documentation
    4. Include examples where helpful
    5. Follow existing doc conventions

    ## Quality Standards

    - Accurate and up-to-date
    - Clear for the target audience
    - Examples for complex concepts
    - Consistent formatting
    - No jargon without explanation

    ## Report Format

    \`\`\`
    STATUS: SUCCESS

    ## Documentation Created

    [The documentation content]

    ## Files
    - path/to/doc.md

    ## Notes
    - [anything the manager should know]
    \`\`\`
\`\`\`

Registering Custom Workers

Save your worker template in:

bach/skills/orchestrating-work/workers/[role]-prompt.md

Then reference it in your orchestration:

[your-role] Task description - delegated to custom worker

The manager will use your template when dispatching that worker type.

Design Principles

1. Single responsibility - One specialty per worker
2. Clear boundaries - Explicit scope prevents confusion
3. Structured output - Manager can parse results
4. Graceful failure - INCAPABLE is better than bad output
5. Self-contained - Worker gets all context upfront