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) { const effectId = taskCtx.effectId; return { kind: 'node', // or 'agent', 'skill', 'shell', 'breakpoint' title: `Task: ${inputs.inputName}`, node: { entry: 'scripts/task-runner.js', args: ['--input', inputs.inputName, '--effect-id', effectId] }, io: { inputJsonPath: `tasks/${effectId}/input.json`, outputJsonPath: `tasks/${effectId}/result.json` }, labels: ['category', 'subcategory'] }; } }); ``` --- ## SDK Context API Reference The `ctx` object provides these intrinsics: | Method | Purpose | Behavior | |--------|---------|----------| | `ctx.task(taskDef, args, opts?)` | Execute a task | Returns result or throws typed exception | | `ctx.breakpoint(payload)` | Human approval gate | Pauses until approved via human | | `ctx.sleepUntil(isoOrEpochMs)` | Time-based gate | Pauses until specified time | | `ctx.parallel.all([...thunks])` | Parallel execution | Runs independent tasks concurrently | | `ctx.parallel.map(items, fn)` | Parallel map | Maps items through task function | | `ctx.now()` | Deterministic time | Returns current Date (or provided time) | | `ctx.log?.(level, msg, data?)` | Logging | Optional logging helper | | `ctx.runId` | Run identifier | Current run's unique ID | ### Task Kinds | Kind | Use Case | Executor |