Process Builder

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

Quick Reference

Processes live in: plugins/babysitter/skills/babysit/process/
├── 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
1# Check existing specializations
2ls plugins/babysitter/skills/babysit/process/specializations/
3
4# Check methodologies
5ls plugins/babysitter/skills/babysit/process/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
1# Processes Backlog - [Specialization Name]
2
3## Identified Processes
4
5- [ ] **process-name** - Short description of what this process accomplishes
6  - Reference: [Link to methodology or standard]
7  - Inputs: list key inputs
8  - Outputs: list key outputs
9
10- [ ] **another-process** - Description
11  ...

Phase 3: Create Process Files

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

Process File Structure

Every process file follows this pattern:

javascript
1/**
2 * @process [category]/[process-name]
3 * @description Clear description of what the process accomplishes end-to-end
4 * @inputs { inputName: type, optionalInput?: type }
5 * @outputs { success: boolean, outputName: type, artifacts: array }
6 *
7 * @example
8 * const result = await orchestrate('[category]/[process-name]', {
9 *   inputName: 'value',
10 *   optionalInput: 'optional-value'
11 * });
12 *
13 * @references
14 * - Book: "Relevant Book Title" by Author
15 * - Article: [Title](https://link)
16 * - Standard: ISO/IEEE reference
17 */
18
19import { defineTask } from '@a5c-ai/babysitter-sdk';
20
21/**
22 * [Process Name] Process
23 *
24 * Methodology: Brief description of the approach
25 *
26 * Phases:
27 * 1. Phase Name - What happens
28 * 2. Phase Name - What happens
29 * ...
30 *
31 * Benefits:
32 * - Benefit 1
33 * - Benefit 2
34 *
35 * @param {Object} inputs - Process inputs
36 * @param {string} inputs.inputName - Description of input
37 * @param {Object} ctx - Process context (see SDK)
38 * @returns {Promise<Object>} Process result
39 */
40export async function process(inputs, ctx) {
41  const {
42    inputName,
43    optionalInput = 'default-value',
44    // ... destructure with defaults
45  } = inputs;
46
47  const artifacts = [];
48
49  // ============================================================================
50  // PHASE 1: [PHASE NAME]
51  // ============================================================================
52
53  ctx.log?.('info', 'Starting Phase 1...');
54
55  const phase1Result = await ctx.task(someTask, {
56    // task inputs
57  });
58
59  artifacts.push(...(phase1Result.artifacts || []));
60
61  // Breakpoint for human review (when needed)
62  await ctx.breakpoint({
63    question: 'Review the results and approve to continue?',
64    title: 'Phase 1 Review',
65    context: {
66      runId: ctx.runId,
67      files: [
68        { path: 'artifacts/output.md', format: 'markdown', label: 'Output' }
69      ]
70    }
71  });
72
73  // ============================================================================
74  // PHASE 2: [PHASE NAME] - Parallel Execution Example
75  // ============================================================================
76
77  const [result1, result2, result3] = await ctx.parallel.all([
78    () => ctx.task(task1, { /* args */ }),
79    () => ctx.task(task2, { /* args */ }),
80    () => ctx.task(task3, { /* args */ })
81  ]);
82
83  // ============================================================================
84  // PHASE 3: [ITERATION EXAMPLE]
85  // ============================================================================
86
87  let iteration = 0;
88  let targetMet = false;
89
90  while (!targetMet && iteration < maxIterations) {
91    iteration++;
92
93    const iterResult = await ctx.task(iterativeTask, {
94      iteration,
95      previousResults: /* ... */
96    });
97
98    targetMet = iterResult.meetsTarget;
99
100    if (!targetMet && iteration % 3 === 0) {
101      // Periodic checkpoint
102      await ctx.breakpoint({
103        question: `Iteration ${iteration}: Target not met. Continue?`,
104        title: 'Progress Checkpoint',
105        context: { /* ... */ }
106      });
107    }
108  }
109
110  // ============================================================================
111  // COMPLETION
112  // ============================================================================
113
114  return {
115    success: targetMet,
116    iterations: iteration,
117    artifacts,
118    // ... other outputs matching @outputs
119  };
120}
121
122// ============================================================================
123// TASK DEFINITIONS
124// ============================================================================
125
126/**
127 * Task: [Task Name]
128 * Purpose: What this task accomplishes
129 */
130const someTask = defineTask({
131  name: 'task-name',
132  description: 'What this task does',
133
134  // Task definition - executed externally by orchestrator
135  // This returns a TaskDef that describes HOW to run the task
136
137  inputs: {
138    inputName: { type: 'string', required: true },
139    optionalInput: { type: 'number', default: 10 }
140  },
141
142  outputs: {
143    result: { type: 'object' },
144    artifacts: { type: 'array' }
145  },
146
147  async run(inputs, taskCtx) {
148    const effectId = taskCtx.effectId;
149
150    return {
151      kind: 'node',  // or 'agent', 'skill', 'shell', 'breakpoint'
152      title: `Task: ${inputs.inputName}`,
153      node: {
154        entry: 'scripts/task-runner.js',
155        args: ['--input', inputs.inputName, '--effect-id', effectId]
156      },
157      io: {
158        inputJsonPath: `tasks/${effectId}/input.json`,
159        outputJsonPath: `tasks/${effectId}/result.json`
160      },
161      labels: ['category', 'subcategory']
162    };
163  }
164});

SDK Context API Reference

The ctx object provides these intrinsics:

Task Kinds

Breakpoint Patterns

Basic Approval Gate

javascript
1await ctx.breakpoint({
2  question: 'Approve to continue?',
3  title: 'Checkpoint',
4  context: { runId: ctx.runId }
5});

With File References (for UI display)

javascript
1await ctx.breakpoint({
2  question: 'Review the generated specification. Does it meet requirements?',
3  title: 'Specification Review',
4  context: {
5    runId: ctx.runId,
6    files: [
7      { path: 'artifacts/spec.md', format: 'markdown', label: 'Specification' },
8      { path: 'artifacts/spec.json', format: 'json', label: 'JSON Schema' },
9      { path: 'src/implementation.ts', format: 'code', language: 'typescript', label: 'Implementation' }
10    ]
11  }
12});

Conditional Breakpoint

javascript
1if (qualityScore < targetScore) {
2  await ctx.breakpoint({
3    question: `Quality score ${qualityScore} is below target ${targetScore}. Continue iterating or accept current result?`,
4    title: 'Quality Gate',
5    context: {
6      runId: ctx.runId,
7      data: { qualityScore, targetScore, iteration }
8    }
9  });
10}

Common Patterns

Quality Convergence Loop

javascript
1let quality = 0;
2let iteration = 0;
3const targetQuality = inputs.targetQuality || 85;
4const maxIterations = inputs.maxIterations || 10;
5
6while (quality < targetQuality && iteration < maxIterations) {
7  iteration++;
8  ctx.log?.('info', `Iteration ${iteration}/${maxIterations}`);
9
10  // Execute improvement tasks
11  const improvement = await ctx.task(improveTask, { iteration });
12
13  // Score quality (parallel checks)
14  const [coverage, lint, security, tests] = await ctx.parallel.all([
15    () => ctx.task(coverageTask, {}),
16    () => ctx.task(lintTask, {}),
17    () => ctx.task(securityTask, {}),
18    () => ctx.task(runTestsTask, {})
19  ]);
20
21  // Agent scores overall quality
22  const score = await ctx.task(agentScoringTask, {
23    coverage, lint, security, tests, iteration
24  });
25
26  quality = score.overall;
27  ctx.log?.('info', `Quality: ${quality}/${targetQuality}`);
28
29  if (quality >= targetQuality) {
30    ctx.log?.('info', 'Quality target achieved!');
31    break;
32  }
33}
34
35return {
36  success: quality >= targetQuality,
37  quality,
38  iterations: iteration
39};

Phased Workflow with Reviews

javascript
1// Phase 1: Research
2const research = await ctx.task(researchTask, { topic: inputs.topic });
3
4await ctx.breakpoint({
5  question: 'Review research findings before proceeding to planning.',
6  title: 'Research Review',
7  context: { runId: ctx.runId }
8});
9
10// Phase 2: Planning
11const plan = await ctx.task(planningTask, { research });
12
13await ctx.breakpoint({
14  question: 'Review plan before implementation.',
15  title: 'Plan Review',
16  context: { runId: ctx.runId }
17});
18
19// Phase 3: Implementation
20const implementation = await ctx.task(implementTask, { plan });
21
22// Phase 4: Verification
23const verification = await ctx.task(verifyTask, { implementation, plan });
24
25await ctx.breakpoint({
26  question: 'Final review before completion.',
27  title: 'Final Approval',
28  context: { runId: ctx.runId }
29});
30
31return { success: verification.passed, plan, implementation };

Parallel Fan-out with Aggregation

javascript
1// Fan out to multiple parallel analyses
2const analyses = await ctx.parallel.map(components, component =>
3  ctx.task(analyzeTask, { component }, { label: `analyze:${component.name}` })
4);
5
6// Aggregate results
7const aggregated = await ctx.task(aggregateTask, { analyses });
8
9return { analyses, summary: aggregated.summary };

Testing Processes

CLI Commands

bash
1# Create a new run
2babysitter run:create \
3  --process-id methodologies/my-process \
4  --entry ./plugins/babysitter/skills/babysit/process/methodologies/my-process.js#process \
5  --inputs ./test-inputs.json \
6  --json
7
8# Iterate the run
9babysitter run:iterate .a5c/runs/<runId> --json
10
11# List pending tasks
12babysitter task:list .a5c/runs/<runId> --pending --json
13
14# Post a task result
15babysitter task:post .a5c/runs/<runId> <effectId> \
16  --status ok \
17  --value ./result.json
18
19# Check run status
20babysitter run:status .a5c/runs/<runId>
21
22# View events
23babysitter run:events .a5c/runs/<runId> --limit 20 --reverse

Sample Test Input File

json
1{
2  "feature": "User authentication with JWT",
3  "acceptanceCriteria": [
4    "Users can register with email and password",
5    "Users can login and receive a JWT token",
6    "Invalid credentials are rejected"
7  ],
8  "testFramework": "jest",
9  "targetQuality": 85,
10  "maxIterations": 5
11}

Process Builder Workflow

1. Gather Requirements

Ask the user:

2. Research Similar Processes

bash
1# Find similar processes
2ls plugins/babysitter/skills/babysit/process/methodologies/
3ls plugins/babysitter/skills/babysit/process/specializations/
4
5# Read similar process for patterns
6cat plugins/babysitter/skills/babysit/process/methodologies/atdd-tdd/atdd-tdd.js | head -200
7
8# Check methodology README structure
9cat plugins/babysitter/skills/babysit/process/methodologies/atdd-tdd/README.md

3. Check Methodologies Backlog

bash
1cat plugins/babysitter/skills/babysit/process/methodologies/backlog.md

4. Create the Process

For Methodologies:

1. Create methodologies/[name]/README.md (comprehensive documentation)
2. Create methodologies/[name]/[name].js (process implementation)
3. Create methodologies/[name]/examples/ (sample inputs)

For Specializations:

1. If domain-specific: specializations/domains/[domain]/[spec]/
2. If engineering: specializations/[category]/[process].js
3. Create README.md, references.md, processes-backlog.md first
4. Then create individual process.js files

5. Validate Structure

Checklist:

• JSDoc header with @process, @description, @inputs, @outputs, @example, @references
• Import from @a5c-ai/babysitter-sdk
• Main export async function process(inputs, ctx)
• Input destructuring with defaults
• Clear phase comments (// === PHASE N: NAME ===)
• Logging via ctx.log?.('info', message)
• Tasks via ctx.task(taskDef, inputs)
• Breakpoints at key decision points
• Artifact collection throughout
• Return object matches @outputs schema

Examples by Type

Methodology Process (atdd-tdd style)

javascript
1/**
2 * @process methodologies/my-methodology
3 * @description My development methodology with quality convergence
4 * @inputs { feature: string, targetQuality?: number }
5 * @outputs { success: boolean, quality: number, artifacts: array }
6 */
7export async function process(inputs, ctx) {
8  const { feature, targetQuality = 85 } = inputs;
9  // ... implementation
10}

Specialization Process (game-development style)

javascript
1/**
2 * @process specializations/game-development/core-mechanics-prototyping
3 * @description Prototype and validate core gameplay mechanics through iteration
4 * @inputs { prototypeName: string, mechanicsToTest: array, engine?: string }
5 * @outputs { success: boolean, mechanicsValidated: array, playtestResults: object }
6 */
7export async function process(inputs, ctx) {
8  const { prototypeName, mechanicsToTest, engine = 'Unity' } = inputs;
9  // ... implementation
10}

Domain Process (science/research style)

javascript
1/**
2 * @process specializations/domains/science/bioinformatics/sequence-analysis
3 * @description Analyze genomic sequences using standard bioinformatics workflows
4 * @inputs { sequences: array, analysisType: string, referenceGenome?: string }
5 * @outputs { success: boolean, alignments: array, variants: array, report: object }
6 */
7export async function process(inputs, ctx) {
8  const { sequences, analysisType, referenceGenome = 'GRCh38' } = inputs;
9  // ... implementation
10}

Resources

• SDK Reference: plugins/babysitter/skills/babysit/process/reference/sdk.md
• Methodology Backlog: plugins/babysitter/skills/babysit/process/methodologies/backlog.md
• Specializations Backlog: plugins/babysitter/skills/babysit/process/specializations/backlog.md
• Example: ATDD/TDD: plugins/babysitter/skills/babysit/process/methodologies/atdd-tdd/
• Example: Spec-Driven: plugins/babysitter/skills/babysit/process/methodologies/spec-driven-development.js
• README: Root README.md for full framework documentation