process-builder

プロセスビルダー

babysitter イベントソース型オーケストレーションフレームワーク向けに、新しいプロセス定義を作成します。

クイックリファレンス

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 フェーズのワークフロー

フェーズ 1：調査とドキュメント作成

基盤となるドキュメントを作成します。

# Check existing specializations
ls library/specializations/

# Check methodologies
ls library/methodologies/

作成するもの：

• README.md - 概要、役割、目標、ユースケース、一般的なフロー
• references.md - 外部資料、ベストプラクティス、参照先へのリンク

フェーズ 2：プロセスの特定

特定したプロセスを記載した processes-backlog.md を作成します。

# 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
  ...

フェーズ 3：プロセスファイルの作成

以下の SDK パターンに従って、プロセスの .js ファイルを作成します。

---

プロセスファイルの構造

すべてのプロセスファイルは、次のパターンに従います。

/**
 * @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 コンテキスト API リファレンス

ctx オブジェクトは、次の組み込み関数を提供します。

メソッド	目的	動作
ctx.task(taskDef, args, opts?)	タスクを実行	結果を返すか、型付き例外をスローします
ctx.breakpoint(payload)	人による承認ゲート	人による承認が得られるまで一時停止します
ctx.sleepUntil(isoOrEpochMs)	時間ベースのゲート	指定時刻まで一時停止します
ctx.parallel.all([...thunks])	並列実行	独立したタスクを並行して実行します
ctx.parallel.map(items, fn)	並列マップ	タスク関数を使って項目をマップします
ctx.now()	決定論的な時刻	現在の Date（または指定された時刻）を返します
ctx.log?.(level, msg, data?)	ログ記録	任意のログ記録ヘルパーです
ctx.runId	実行 ID	現在の実行に固有の ID です

タスクの種類

種類	用途	実行環境
node	スクリプト、ビルド、テスト	Node.js プロセス
agent	LLM を利用した分析、生成	Claude Code エージェント
skill	Claude Code スキル	スキルの呼び出し
shell	システムコマンド	シェルの実行
breakpoint	人による承認	ブレークポイントの UI／サービス
sleep	時間ゲート	オーケストレーターによるスケジューリング
orchestrator_task	オーケストレーター内部の処理	自己ルーティング

---

ブレークポイントのパターン

基本的な承認ゲート

await ctx.breakpoint({
  question: 'Approve to continue?',
  title: 'Checkpoint',
  context: { runId: ctx.runId }
});

ファイル参照付き（UI 表示用）

await ctx.breakpoint({
  question: 'Review the generated specification. Does it meet requirements?',
  title: 'Specification Review',
  context: {
    runId: ctx.runId,
    files: [
      { path: 'artifacts/spec.md', format: 'markdown', label: 'Specification' },
      { path: 'artifacts/spec.json', format: 'json', label: 'JSON Schema' },
      { path: 'src/implementation.ts', format: 'code', language: 'typescript', label: 'Implementation' }
    ]
  }
});

条件付きブレークポイント

if (qualityScore < targetScore) {
  await ctx.breakpoint({
    question: `Quality score ${qualityScore} is below target ${targetScore}. Continue iterating or accept current result?`,
    title: 'Quality Gate',
    context: {
      runId: ctx.runId,
      data: { qualityScore, targetScore, iteration }
    }
  });
}

---

一般的なパターン

品質収束ループ

let quality = 0;
let iteration = 0;
const targetQuality = inputs.targetQuality || 85;
const maxIterations = inputs.maxIterations || 10;

while (quality < targetQuality && iteration < maxIterations) {
  iteration++;
  ctx.log?.('info', `Iteration ${iteration}/${maxIterations}`);

  // Execute improvement tasks
  const improvement = await ctx.task(improveTask, { iteration });

  // Score quality (parallel checks)
  const [coverage, lint, security, tests] = await ctx.parallel.all([
    () => ctx.task(coverageTask, {}),
    () => ctx.task(lintTask, {}),
    () => ctx.task(securityTask, {}),
    () => ctx.task(runTestsTask, {})
  ]);

  // Agent scores overall quality
  const score = await ctx.task(agentScoringTask, {
    coverage, lint, security, tests, iteration
  });

  quality = score.overall;
  ctx.log?.('info', `Quality: ${quality}/${targetQuality}`);

  if (quality >= targetQuality) {
    ctx.log?.('info', 'Quality target achieved!');
    break;
  }
}

return {
  success: quality >= targetQuality,
  quality,
  iterations: iteration
};

レビュー付き段階的ワークフロー

// Phase 1: Research
const research = await ctx.task(researchTask, { topic: inputs.topic });

await ctx.breakpoint({
  question: 'Review research findings before proceeding to planning.',
  title: 'Research Review',
  context: { runId: ctx.runId }
});

// Phase 2: Planning
const plan = await ctx.task(planningTask, { research });

await ctx.breakpoint({
  question: 'Review plan before implementation.',
  title: 'Plan Review',
  context: { runId: ctx.runId }
});

// Phase 3: Implementation
const implementation = await ctx.task(implementTask, { plan });

// Phase 4: Verification
const verification = await ctx.task(verifyTask, { implementation, plan });

await ctx.breakpoint({
  question: 'Final review before completion.',
  title: 'Final Approval',
  context: { runId: ctx.runId }
});

return { success: verification.passed, plan, implementation };

集約を伴う並列ファンアウト

// Fan out to multiple parallel analyses
const analyses = await ctx.parallel.map(components, component =>
  ctx.task(analyzeTask, { component }, { label: `analyze:${component.name}` })
);

// Aggregate results
const aggregated = await ctx.task(aggregateTask, { analyses });

return { analyses, summary: aggregated.summary };

---

プロセスのテスト

CLI コマンド

# Create a new run
babysitter run:create \
  --process-id methodologies/my-process \
  --entry ./library/methodologies/my-process.js#process \
  --inputs ./test-inputs.json \
  --json

# Iterate the run
babysitter run:iterate .a5c/runs/<runId> --json

# List pending tasks
babysitter task:list .a5c/runs/<runId> --pending --json

# Post a task result
babysitter task:post .a5c/runs/<runId> <effectId> \
  --status ok \
  --value ./result.json

# Check run status
babysitter run:status .a5c/runs/<runId>

# View events
babysitter run:events .a5c/runs/<runId> --limit 20 --reverse

テスト入力ファイルの例

{
  "feature": "User authentication with JWT",
  "acceptanceCriteria": [
    "Users can register with email and password",
    "Users can login and receive a JWT token",
    "Invalid credentials are rejected"
  ],
  "testFramework": "jest",
  "targetQuality": 85,
  "maxIterations": 5
}

---

プロセスビルダーのワークフロー

1. 要件の収集

ユーザーに次の質問をします。

質問	目的
ドメイン／カテゴリ	ディレクトリの場所を決定します
プロセス名	kebab-case の識別子です
目標	プロセスで達成することは何ですか？
入力	プロセスに必要なデータは何ですか？
出力	どのような成果物／結果を生成しますか？
フェーズ	主な手順は何ですか？
品質ゲート	どの段階で人がレビューしますか？
反復戦略	固定フェーズですか、それとも収束ループですか？

2. 類似プロセスの調査

# Find similar processes
ls library/methodologies/
ls library/specializations/

# Read similar process for patterns
cat library/methodologies/atdd-tdd/atdd-tdd.js | head -200

# Check methodology README structure
cat library/methodologies/atdd-tdd/README.md

3. 方法論バックログの確認

cat library/methodologies/backlog.md

4. プロセスの作成

方法論の場合：

1. methodologies/[name]/README.md（包括的なドキュメント）を作成します
2. methodologies/[name]/[name].js（プロセスの実装）を作成します
3. methodologies/[name]/examples/（入力例）を作成します

特化領域の場合：

1. ドメイン固有の場合：specializations/domains/[domain]/[spec]/
2. エンジニアリングの場合：specializations/[category]/[process].js
3. まず README.md、references.md、processes-backlog.md を作成します
4. 次に個々の process.js ファイルを作成します

5. 構造を検証する

チェックリスト：

• @process、@description、@inputs、@outputs、@example、@references を含む JSDoc ヘッダー
• 関連するアトラスノード ID を含む @graph ブロック（最低 1 つのドメイン）
• @a5c-ai/babysitter-sdk からインポートしている
• メインの export async function process(inputs, ctx)
• デフォルト値を指定した入力の分割代入
• 明確なフェーズコメント（// === PHASE N: NAME ===）
• ctx.log?.('info', message) によるログ記録
• ctx.task(taskDef, inputs) によるタスク実行
• 重要な意思決定ポイントでのブレークポイント
• 全体を通じた成果物の収集
• @outputs スキーマに一致する戻り値オブジェクト

---

種類別の例

方法論プロセス（ATDD-TDD スタイル）

/**
 * @process methodologies/my-methodology
 * @description My development methodology with quality convergence
 * @inputs { feature: string, targetQuality?: number }
 * @outputs { success: boolean, quality: number, artifacts: array }
 */
export async function process(inputs, ctx) {
  const { feature, targetQuality = 85 } = inputs;
  // ... implementation
}

専門分野プロセス（ゲーム開発スタイル）

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

ドメインプロセス（科学／研究スタイル）

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

---

アトラスグラフのメタデータ

生成されるすべてのプロセスファイルには、標準の @process、@description、@inputs、@outputs タグとともに、ファイルヘッダーコメント内に @graph JSDoc ブロックを含める必要があります。

形式

/**
 * @process specializations/my-domain/my-process
 * @description ...
 * @inputs { ... }
 * @outputs { ... }
 *
 * @graph
 *   domains: [domain:software-engineering, domain:devops]
 *   skillAreas: [skill-area:caching-strategies]
 *   topics: [topic:microservices, topic:event-sourcing]
 *   roles: [role:backend-engineer, role:sre]
 *   workflows: [workflow:code-review]
 */

ノード ID の選び方

アトラスグラフのドメインディレクトリ（packages/atlas/graph/domain/）を参照して、有効なノード ID を確認してください。このディレクトリには、カテゴリ別にグループ化された YAML ファイルが格納されています。

• domains/ — 高レベルのドメインノード（例：domain:software-engineering、domain:devops、domain:data-engineering）
• skill-areas/ — 具体的なスキル領域ノード
• topics/ — 詳細なトピックノード
• roles/ — 役割ノード（エンジニア、実務者、研究者）
• workflows/ — ワークフローノード

プロセスに実際に関連する2～4 個のエッジを選んでください。ID を推測せず、実際の YAML ファイルを参照して有効なものを確認してください。最低限、すべてのプロセスで少なくとも 1 つの domain: ノードを参照する必要があります。

重要な理由

このメタデータによって、プロセスがアトラスナレッジグラフに接続されます。ビルド前のジェネレータースクリプトが @graph ブロックを解析し、見つけやすくするためのグラフノードとエッジを作成します。このブロックがないプロセスは、グラフベースの検索結果やおすすめに表示されません。

---

リソース

• SDK リファレンス：library/reference/sdk.md
• 方法論バックログ：library/methodologies/backlog.md
• 専門分野バックログ：library/specializations/backlog.md
• 例：ATDD/TDD：library/methodologies/atdd-tdd/
• 例：Spec-Driven：library/methodologies/spec-driven-development.js
• README：フレームワークの全ドキュメントについてはルートの README.md を参照してください。