Skip to content
Moira Documentation

Writing Directives

Directive Structure

Section titled “Directive Structure”

Every agent-directive node needs:

{
  "type": "agent-directive",
  "id": "unique-id",
  "directive": "What the agent should do",
  "completionCondition": "When the task is complete",
  "inputSchema": {
    /* expected response structure */
  },
  "connections": { "success": "next-node" }
}

Writing Clear Directives

Section titled “Writing Clear Directives”

Be Specific

Section titled “Be Specific”

❌ Bad:

"Fix the bugs"

✅ Good:

"Fix TypeScript compilation errors in src/auth/.\n\nSteps:\n1. Run tsc --noEmit\n2. Fix each error\n3. Verify compilation succeeds"

Include Context

Section titled “Include Context”

Use template variables:

"Implement step {{current_step_index}} of {{total_steps}}: {{current_step_name}}\n\nExpected outcome: {{expected_outcome}}"

Specify Output Requirements

Section titled “Specify Output Requirements”
"Run tests and report results.\n\nRequired output format:\n- Total tests\n- Passed count\n- Failed count\n- List of failed test names"

Completion Conditions

Section titled “Completion Conditions”

What Makes a Good Condition

Section titled “What Makes a Good Condition”
  • Measurable: Can be verified objectively
  • Specific: Clear pass/fail criteria
  • Complete: All requirements covered

Examples

Section titled “Examples”

❌ Vague:

"Task is done"

✅ Specific:

"All tests pass (npm test shows 0 failures)"

✅ Multi-criteria:

"Implementation complete:\n- Feature works as specified\n- Tests added and passing\n- No TypeScript errors"

Using InputSchema Effectively

Section titled “Using InputSchema Effectively”

Require Evidence

Section titled “Require Evidence”
{
  "inputSchema": {
    "properties": {
      "task_completed": { "type": "string", "enum": ["yes", "no"] },
      "evidence": {
        "type": "string",
        "description": "Concrete proof: command output, test results, etc."
      }
    },
    "required": ["task_completed", "evidence"]
  }
}

Force Explicit Choices

Section titled “Force Explicit Choices”
{
  "inputSchema": {
    "properties": {
      "quality_check": {
        "type": "string",
        "enum": ["pass", "fail"],
        "description": "Did implementation meet quality standards?"
      }
    },
    "required": ["quality_check"]
  }
}

Collect Structured Data

Section titled “Collect Structured Data”
{
  "inputSchema": {
    "properties": {
      "test_results": {
        "type": "object",
        "properties": {
          "total": { "type": "number" },
          "passed": { "type": "number" },
          "failed": { "type": "number" }
        },
        "required": ["total", "passed", "failed"]
      }
    },
    "required": ["test_results"]
  }
}

Directive Patterns

Section titled “Directive Patterns”

Step-by-Step Instructions

Section titled “Step-by-Step Instructions”
"Complete the following steps in order:\n\n1. [First action]\n2. [Second action]\n3. [Third action]\n\nReport which steps completed successfully."

Conditional Instructions

Section titled “Conditional Instructions”
"{{#if has_tests}}Run test suite: {{test_command}}{{else}}No tests configured, skip testing{{/if}}"

Verification Requirements

Section titled “Verification Requirements”
"Verify implementation:\n\n- [ ] Feature works as specified\n- [ ] Edge cases handled\n- [ ] Error messages clear\n\nProvide evidence for each checkbox."

Common Mistakes

Section titled “Common Mistakes”

Too Much Freedom

Section titled “Too Much Freedom”

❌ Problem:

"Make the code better"

✅ Solution:

"Refactor auth module:\n- Extract validation logic to separate function\n- Add error handling for null inputs\n- Add JSDoc comments"

Missing Context

Section titled “Missing Context”

❌ Problem:

"Fix the error"

✅ Solution:

"Fix error in {{file_path}}:\n\nError message: {{last_error}}\nIteration: {{current_iteration}}"

No Success Criteria

Section titled “No Success Criteria”

❌ Problem:

"completionCondition": "Done"

✅ Solution:

"completionCondition": "npm test passes with 0 failures, npm run build completes without errors"

See Also

Section titled “See Also”