workflowにてagent未指定でも起動できるようにする

[nrslib]

instruction_templateのみで指示を与えられる
これが可能になることによりシンプルなワークフローを作れる

[nrslib]

@Takt run

[github-actions]

TAKT ❌ 失敗

Workflow: default

出力

[INFO] Fetching issue #71...
Issue #71 fetched: "workflowにてagent未指定でも起動できるようにする"
[INFO] Creating branch: takt/issue-71-1769924090
Branch created: takt/issue-71-1769924090
[INFO] Running workflow: default

=== Running Workflow: default ===

[INFO] [1/30] plan (planner)
[planner] Model: claude-sonnet-4-5-20250929

[planner]:
I'll analyze this task to understand what needs to be implemented.

  ⠋ Glob **/workflow*.{ts,js,json,yaml,yml}
  ⠙ Glob **/workflow*.{ts,js,json,yaml,yml}
  ⠹ Glob **/workflow*.{ts,js,json,yaml,yml}
  ⠸ Glob **/workflow*.{ts,js,json,yaml,yml}
                                                                                                                        

  ⠋ Glob **/agent*.{ts,js,json,yaml,yml}
  ⠙ Glob **/agent*.{ts,js,json,yaml,yml}
  ⠹ Glob **/agent*.{ts,js,json,yaml,yml}
                                                                                                                        

  ⠋ Glob CLAUDE.md
  ⠙ Glob CLAUDE.md
  ⠹ Glob CLAUDE.md
                                                                                                                        

                                                                                                                        
  ✓ Glob {"filenames":["/home/runner/work/takt/takt/CLAUDE.md"],"d...
  ✓ Tool {"filenames":["/home/runner/work/takt/takt/src/__tests__/...
  ✓ Tool {"filenames":["/home/runner/work/takt/takt/src/config/age...
  ✓ Tool {"filenames":["/home/runner/work/takt/takt/README.md","/h...

  ⠋ Read /home/runner/work/takt/takt/CLAUDE.md
  ⠙ Read /home/runner/work/takt/takt/CLAUDE.md
  ⠹ Read /home/runner/work/takt/takt/CLAUDE.md
  ⠸ Read /home/runner/work/takt/takt/CLAUDE.md
  ⠼ Read /home/runner/work/takt/takt/CLAUDE.md
  ⠴ Read /home/runner/work/takt/takt/CLAUDE.md
                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

  ⠋ Read /home/runner/work/takt/takt/src/models/workflow.ts
  ⠙ Read /home/runner/work/takt/takt/src/models/workflow.ts
  ⠹ Read /home/runner/work/takt/takt/src/models/workflow.ts
  ⠸ Read /home/runner/work/takt/takt/src/models/workflow.ts
                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

  ⠋ Grep agent.*string
  ⠙ Grep agent.*string
  ⠹ Grep agent.*string
  ⠸ Grep agent.*string
  ⠼ Grep agent.*string
  ⠴ Grep agent.*string
  ⠦ Grep agent.*string
  ⠧ Grep agent.*string
                                                                                                                        
  ✓ Grep src/models/types.ts:30:  agent: string;

  ⠋ Read /home/runner/work/takt/takt/src/models/types.ts
  ⠙ Read /home/runner/work/takt/takt/src/models/types.ts
  ⠹ Read /home/runner/work/takt/takt/src/models/types.ts
  ⠸ Read /home/runner/work/takt/takt/src/models/types.ts
                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

  ⠋ Glob resources/global/**/*.yaml
  ⠙ Glob resources/global/**/*.yaml
  ⠹ Glob resources/global/**/*.yaml
  ⠸ Glob resources/global/**/*.yaml
  ⠼ Glob resources/global/**/*.yaml
  ⠴ Glob resources/global/**/*.yaml
  ⠦ Glob resources/global/**/*.yaml
  ⠧ Glob resources/global/**/*.yaml
  ⠇ Glob resources/global/**/*.yaml
                                                                                                                        
  ✓ Glob {"filenames":["/home/runner/work/takt/takt/resources/glob...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

                                                                                                                        
  ✓ Read {"type":"text","file":{"filePath":"/home/runner/work/takt...

[planner]:
Now I have enough context to analyze the task. Let me check how the workflow engine validates the agent field:

                                                                                                                        
  ✓ Grep src/models/schemas.ts:87:  agent_name: z.string().optiona...

[planner]:
Now I understand the issue. Let me analyze the requirements:

## Analysis

### 1. Requirements Understanding

**User's request:** Enable workflow execution without specifying an agent, allowing instructions through `instruction_template` only.

**Objective:** 
- Make workflow steps executable without requiring an `agent` field
- Allow simpler workflows that use only `instruction_template` to provide instructions
- Execution should work with instruction templates alone

**Current behavior:**
- Schema validation: `agent` is marked `.optional()` for normal steps (line 104 in schemas.ts)
- Refinement check: Step must have either `agent` OR `parallel` sub-steps (line 124 in schemas.ts)
- Normalizer: Uses `step.agent ?? ''` as fallback (line 183 in workflowLoader.ts)
- Runner: Throws error when agent is unknown (line 224 in runner.ts)

### 2. Impact Scope Identification

**Files that need modification:**
1. `/home/runner/work/takt/takt/src/models/schemas.ts` - Schema validation refinement
2. `/home/runner/work/takt/takt/src/config/workflowLoader.ts` - Agent field normalization
3. `/home/runner/work/takt/takt/src/workflow/engine.ts` - Step execution logic
4. `/home/runner/work/takt/takt/src/agents/runner.ts` - Agent resolution logic

**Dependencies:**
- Need to determine which agent/provider to use when agent is not specified
- Need to handle agentPath resolution when no agent is specified
- Need to ensure backward compatibility with existing workflows

### 3. Fact-Checking

✅ Schema already marks `agent` as optional (line 104)  
✅ Refinement requires either `agent` or `parallel` (line 123-126)  
✅ Normalizer provides empty string fallback for agent (line 183)  
❌ Runner does not handle empty agent case (line 224 throws error)  
❌ Engine always expects an agent to be specified

### 4. Spec & Constraint Verification

**Schema constraint (schemas.ts:123-126):**
```typescript
.refine(
  (data) => data.agent || (data.parallel && data.parallel.length > 0),
  { message: 'Step must have either an agent or parallel sub-steps' },
);

This needs to be relaxed to allow instruction_template without agent.

Type definitions (types.ts:97):

agent: string;  // Required, not optional

This should remain as-is for runtime type safety.

5. Implementation Approach

Steps:

1. Update schema validation - Remove or relax the refinement check to allow steps with only instruction_template
2. Update workflowLoader - Handle empty agent case, provide default agent or skip agent path resolution
3. Update engine - Execute step with default agent when agent field is empty/undefined
4. Update runner - Add fallback logic to use a default agent (e.g., 'coder' or 'supervisor') when agent is empty

Points requiring caution:

• Default agent selection: Which builtin agent should be used when none is specified? Probably 'coder' as it has the most general toolset
• Agent session management: Empty agent strings might break session tracking
• Display name: What should be shown in output when no agent is specified?

Items requiring confirmation:

• Which builtin agent should be the default when agent is not specified?
• Should we support fully agent-less execution, or always fall back to a builtin agent?
• How should agent sessions be managed when agent is not specified?

Decision

[PLAN:3]

Clarifications needed:

• Which builtin agent should be used as the default when agent is not specified? (e.g., 'coder', 'supervisor', or make it configurable)

• Should we support fully agent-less execution (direct API call with instruction_template), or always fall back to a builtin agent?

• How should the agent display name appear in the output when no agent is specified? (e.g., "default", "workflow", step name)

• Should agent sessions be shared across all agent-less steps, or should each step get its own session?[planner] Model: claude-sonnet-4-5-20250929
  I'll output my analysis results to the report file.

  ✓ Write # Task Plan

[planner]:
Report has been successfully output to the plan file. The analysis identified 4 key areas that need modification and outlined 4 critical clarification points that must be resolved before implementation can proceed.[planner] Model: claude-sonnet-4-5-20250929
[PLAN:3]

Clarifications needed:

• Which builtin agent should be used as the default when agent is not specified? (coder/supervisor/configurable)
• Should we support fully agent-less execution (direct API calls), or always fall back to a builtin agent?
• How should the agent display name appear in output when no agent is specified? (default/step name/fallback agent name)
• How should agent sessions be managed for agent-less steps? (shared session/per-step session/step-name-based session key)
  📄 Report: 00-plan.md

Task Plan

Original Request

workflowにてagent未指定でも起動できるようにする

instruction_templateのみで指示を与えられる
これが可能になることによりシンプルなワークフローを作れる

Analysis Results

Objective

Enable workflow steps to execute without requiring the agent field, allowing workflows to be defined using only instruction_template for simpler workflow definitions.

Scope

This change affects the following components:

1. Schema Validation (src/models/schemas.ts)

   • Current: Refinement check requires either agent or parallel sub-steps
   • Change: Relax validation to allow steps with only instruction_template

2. Workflow Loader (src/config/workflowLoader.ts)

   • Current: Uses empty string fallback for missing agent (step.agent ?? '')
   • Change: Properly handle undefined/empty agent cases, provide default agent logic

3. Workflow Engine (src/workflow/engine.ts)

   • Current: Assumes agent is always specified
   • Change: Handle execution when agent field is empty/undefined

4. Agent Runner (src/agents/runner.ts)

   • Current: Throws error for unknown agents (line 224)
   • Change: Add fallback to default builtin agent when agent is not specified

Implementation Approach

Phase 1: Schema & Type Updates

• Modify WorkflowStepRawSchema.refine() to remove the requirement for agent when instruction_template is present
• Keep runtime types unchanged for type safety

Phase 2: Default Agent Strategy

• Determine default builtin agent to use (pending clarification)
• Add logic to resolve empty/undefined agent to default agent
• Ensure agent session tracking works with default agent

Phase 3: Loader & Engine Updates

• Update normalizeStepFromRaw() to handle missing agent gracefully
• Update engine's agent execution logic to use default when agent is not specified
• Update display name logic for agent-less steps

Phase 4: Testing

• Test workflows with missing agent field
• Verify backward compatibility with existing workflows
• Ensure session management works correctly

Clarifications Needed

1. Default Agent Selection: Which builtin agent should be used as the default when agent is not specified?

   • Option A: 'coder' (most general toolset)
   • Option B: 'supervisor' (read-only, safer default)
   • Option C: Make it configurable via workflow-level setting (e.g., default_agent: coder)

2. Execution Model: Should we support fully agent-less execution, or always fall back to a builtin agent?

   • Option A: Always use a builtin agent as fallback
   • Option B: Support direct API calls without agent prompt (instruction_template only)

3. Display Name: How should the agent display name appear in output when no agent is specified?

   • Option A: "default"
   • Option B: Use step name
   • Option C: Show the fallback agent name (e.g., "coder")

4. Session Management: How should agent sessions be managed for agent-less steps?

   • Option A: Share one session across all agent-less steps
   • Option B: Each agent-less step gets its own session
   • Option C: Use step name as session key

Status: Requirements unclear, insufficient info (phase3_tag)
Session: 75e8ac46-e4b5-4d00-8165-12762d1389ef
[ERROR] Workflow aborted after 1 iterations (1m 19s): Workflow aborted by step transition
[INFO] Session log: /home/runner/work/takt/takt/.takt/logs/20260201-053450-f0740t.jsonl
[ERROR] Workflow 'default' failed

</details>

[nrslib]

実装完了しました。

実装内容

1. agent フィールドを optional に変更

• WorkflowStepRawSchema と ParallelSubStepRawSchema で agent を optional に
• 必須チェック制約を削除

2. 3つの実行モードをサポート

1. agentPath が存在する場合: ファイルからプロンプトをロード（従来の動作）
2. agentSpec が文字列でファイルが存在しない場合: インラインシステムプロンプトとして扱う
3. agent 未指定の場合: instruction_template のみで実行（システムプロンプトなし）

3. セッション管理の改善

• agent 未指定時は step.name をセッションキーとして使用

4. ドキュメント更新

• README.md と README.ja.md に「エージェントレスステップ」のセクションを追加
• 使用例とインラインプロンプトの説明を記載

実装箇所: コミット 18894e2