process-builder

# Process Builder

Create new process definitions for the babysitter event-sourced orchestration framework.

## Quick Reference

```
Processes live in: library/
├── methodologies/          # Reusable development approaches (TDD, BDD, Scrum, etc.)
│   └── [name]/
│       ├── README.md       # Documentation
│       ├── [name].js       # Main process
│       └── examples/       # Sample inputs
│
└── specializations/        # Domain-specific processes
    ├── [category]/         # Engineering specializations (direct children)
    │   └── [process].js
    └── domains/
        └── [domain]/       # Business, Science, Social Sciences
            └── [spec]/
                ├── README.md
                ├── references.md
                ├── processes-backlog.md
                └── [process].js
```

## 3-Phase Workflow

### Phase 1: Research & Documentation

Create foundational documentation:

```bash
# Check existing specializations
ls library/specializations/

# Check methodologies
ls library/methodologies/
```

**Create:**
- `README.md` - Overview, roles, goals, use cases, common flows
- `references.md` - External references, best practices, links to sources

### Phase 2: Identify Processes

Create `processes-backlog.md` with identified processes:

```markdown
# Processes Backlog - [Specialization Name]

## Identified Processes

- [ ] **process-name** - Short description of what this process accomplishes
  - Reference: [Link to methodology or standard]
  - Inputs: list key inputs
  - Outputs: list key outputs

- [ ] **another-process** - Description
  ...
```

### Phase 3: Create Process Files

Create `.js` process files following SDK patterns (see below).

---

## Process File Structure

Every process file follows this pattern:

```javascript
/**
 * @process [category]/[process-name]
 * @description Clear description of what the process accomplishes end-to-end
 * @inputs { inputName: type, optionalInput?: type }
 * @outputs { success: boolean, outputName: type, artifacts: array }
 *
 * @graph
 *   domains: [domain:software-engineering]
 *   skillAreas: [skill-area:your-skill-area]
 *   topics: [topic:your-topic]
 *   roles: [role:your-role]
 *   workflows: [workflow:your-workflow]
 *
 * @example
 * const result = await orchestrate('[category]/[process-name]', {
 *   inputName: 'value',
 *   optionalInput: 'optional-value'
 * });
 *
 * @references
 * - Book: "Relevant Book Title" by Author
 * - Article: [Title](https://link)
 * - Standard: ISO/IEEE reference
 */

import { defineTask } from '@a5c-ai/babysitter-sdk';

/**
 * [Process Name] Process
 *
 * Methodology: Brief description of the approach
 *
 * Phases:
 * 1. Phase Name - What happens
 * 2. Phase Name - What happens
 * ...
 *
 * Benefits:
 * - Benefit 1
 * - Benefit 2
 *
 * @param {Object} inputs - Process inputs
 * @param {string} inputs.inputName - Description of input
 * @param {Object} ctx - Process context (see SDK)
 * @returns {Promise<Object>} Process result
 */
export async function process(inputs, ctx) {
  const {
    inputName,
    optionalInput = 'default-value',
    // ... destructure with defaults
  } = inputs;

  const artifacts = [];

  // ============================================================================
  // PHASE 1: [PHASE NAME]
  // ============================================================================

  ctx.log?.('info', 'Starting Phase 1...');

  const phase1Result = await ctx.task(someTask, {
    // task inputs
  });

  artifacts.push(...(phase1Result.artifacts || []));

  // Breakpoint for human review (when needed)
  await ctx.breakpoint({
    question: 'Review the results and approve to continue?',
    title: 'Phase 1 Review',
    context: {
      runId: ctx.runId,
      files: [
        { path: 'artifacts/output.md', format: 'markdown', label: 'Output' }
      ]
    }
  });

  // ============================================================================
  // PHASE 2: [PHASE NAME] - Parallel Execution Example
  // ============================================================================

  const [result1, result2, result3] = await ctx.parallel.all([
    () => ctx.task(task1, { /* args */ }),
    () => ctx.task(task2, { /* args */ }),
    () => ctx.task(task3, { /* args */ })
  ]);

  // ============================================================================
  // PHASE 3: [ITERATION EXAMPLE]
  // ============================================================================

  let iteration = 0;
  let targetMet = false;

  while (!targetMet && iteration < maxIterations) {
    iteration++;

    const iterResult = await ctx.task(iterativeTask, {
      iteration,
      previousResults: /* ... */
    });

    targetMet = iterResult.meetsTarget;

    if (!targetMet && iteration % 3 === 0) {
      // Periodic checkpoint
      await ctx.breakpoint({
        question: `Iteration ${iteration}: Target not met. Continue?`,
        title: 'Progress Checkpoint',
        context: { /* ... */ }
      });
    }
  }

  // ============================================================================
  // COMPLETION
  // ============================================================================

  return {
    success: targetMet,
    iterations: iteration,
    artifacts,
    // ... other outputs matching @outputs
  };
}

// ============================================================================
// TASK DEFINITIONS
// ============================================================================

/**
 * Task: [Task Name]
 * Purpose: What this task accomplishes
 */
const someTask = defineTask({
  name: 'task-name',
  description: 'What this task does',

  // Task definition - executed externally by orchestrator
  // This returns a TaskDef that describes HOW to run the task

  inputs: {
    inputName: { type: 'string', required: true },
    optionalInput: { type: 'number', default: 10 }
  },

  outputs: {
    result: { type: 'object' },
    artifacts: { type: 'array' }
  },

  async run(inputs, taskCtx)