Use Case: Custom Development Workflow

The Problem

Asking an AI to "fix the login bug" often produces mediocre results because it starts coding immediately without understanding context. You want a structured pipeline: first understand the task, then gather context, then execute.

Solution

Create a workflow with multiple layers, each handling a different stage.

Architecture

User: "fix the login bug"
    |
    v
[task_refiner] Clarify the request, guess relevant files
    |
    v
[context_researcher] Read code, search patterns, gather context
    |
    v
Main AI Session: now has refined task + gathered context
    |
    v
Executes the fix with full understanding

Step 1: Define Layers

# In config.toml

[[layers]]
name = "task_refiner"
description = "Clarifies vague requests into actionable tasks"
model = "openrouter:openai/gpt-4.1-mini"
max_tokens = 2048
system_prompt = """
Take the user's request and make it clearer:
1. If vague, add specificity based on the project context
2. Guess which files might be relevant
3. Keep it concise -- you're refining, not solving

If the request is already clear, return it unchanged.

{{CONTEXT}}

Respond ONLY with the refined task. No questions.
"""
temperature = 0.3
top_p = 0.7
top_k = 20
input_mode = "last"
output_mode = "none"
output_role = "assistant"

[layers.mcp]
server_refs = []
allowed_tools = []

[layers.parameters]

[[layers]]
name = "context_researcher"
description = "Gathers codebase context for development tasks"
model = "openrouter:google/gemini-2.5-flash-preview"
max_tokens = 8192
system_prompt = """
You are a research assistant. Gather the most important information for the task.

Strategy:
1. Search for relevant files and functions
2. Read key interfaces and signatures (not full implementations)
3. Note patterns and conventions used in the codebase

Present findings as:
- **Starting Points**: Key files and functions
- **Patterns**: Relevant code conventions
- **Context**: Dependencies and related components

Stay focused. Get starting points, not full implementations.

{{SYSTEM}}
{{CONTEXT}}
"""
temperature = 0.3
top_p = 0.7
top_k = 20
input_mode = "last"
output_mode = "append"
output_role = "assistant"

[layers.mcp]
server_refs = ["filesystem"]
allowed_tools = ["view"]

[layers.parameters]

Step 2: Define the Workflow

[[workflows]]
name = "dev_workflow"
description = "Refine task, then research context before execution"

[[workflows.steps]]
name = "refine"
type = "once"
layer = "task_refiner"

[[workflows.steps]]
name = "research"
type = "once"
layer = "context_researcher"

Step 3: Bind to a Role

[[roles]]
name = "developer"
workflow = "dev_workflow"
temperature = 0.3
system = """
You are an expert developer.
Working directory: {{CWD}}
Git status: {{GIT_STATUS}}
"""

[roles.mcp]
server_refs = ["core", "filesystem", "agent"]
allowed_tools = ["core:*", "filesystem:*", "agent:*"]

Step 4: Use It

octomind run developer

Now when you type "fix the login bug":

1. task_refiner (gpt-4.1-mini, cheap) clarifies: "Fix the authentication failure in src/auth/login.rs. Likely files: src/auth/login.rs, src/auth/mod.rs, tests/auth_test.rs"
2. context_researcher (gemini-flash, fast) reads those files, finds the relevant functions and patterns
3. Main session (claude-sonnet, powerful) receives the refined task + gathered context and produces a high-quality fix

Advanced: Validation Loop

Add validation before the main AI acts:

[[workflows]]
name = "validated_dev"
description = "Refine, research, validate in a loop"

[[workflows.steps]]
name = "refine"
type = "once"
layer = "task_refiner"

[[workflows.steps]]
name = "validate_loop"
type = "loop"
max_iterations = 2
exit_pattern = "READY"

  [[workflows.steps.substeps]]
  name = "research"
  type = "once"
  layer = "context_researcher"

  [[workflows.steps.substeps]]
  name = "validate"
  type = "once"
  layer = "task_validator"

With a validator layer:

[[layers]]
name = "task_validator"
description = "Validates whether enough context has been gathered"
model = "openrouter:openai/gpt-4.1-mini"
max_tokens = 1024
system_prompt = """
Review the research output. Is there enough context to proceed?

If yes: respond with READY
If no: respond with what additional information is needed

{{CONTEXT}}
"""
temperature = 0.2
input_mode = "last"
output_mode = "none"
output_role = "assistant"

[layers.mcp]
server_refs = []
allowed_tools = []

[layers.parameters]

Cost Optimization

Each layer can use a different model optimized for its task:

Layer	Model	Cost	Why
Refiner	gpt-4.1-mini	$0.001	Simple text processing
Researcher	gemini-flash	$0.002	Fast, large context for code reading
Validator	gpt-4.1-mini	$0.001	Simple yes/no decision
Main session	claude-sonnet	$0.01+	Complex reasoning and code generation

Total pipeline overhead: ~$0.004 per task for much better results.

Key Points

• output_mode = "none" for intermediate layers that don't show output
• output_mode = "append" for layers that add context to the session
• Each layer can have different models, tools, and prompts
• Workflows run automatically when bound to a role via workflow = "..."
• Use /workflow to trigger manually
• Use cheap models for simple tasks, powerful models where it matters