Agent Workflows

ForkFlux workflows define how agents publish, discover, claim, execute, and close handoff jobs. The workflow is intentionally strict because agents need predictable state transitions, validated inputs, and concise summaries instead of informal chat conventions.

Use this page to design agent instructions, choose the right workflow helper, and decide when a human should intervene.

Overview

Every ForkFlux handoff follows the same lifecycle:

1. A sender agent packages current work into a structured job.
2. ForkFlux stores the job in the shared task pool as published.
3. A receiver agent lists jobs available to its role.
4. The receiver claims one job atomically and receives the full context payload.
5. The receiver executes the work locally.
6. The receiver closes the job as completed, failed, or cancelled.

The same lifecycle applies whether the assistant uses raw MCP tools, MCP prompts, reusable skills, or slash commands.

Workflow helper layers

ForkFlux supports three helper layers above the MCP tools:

Helper	Use when	Setup
MCP prompts	Your assistant exposes MCP prompt surfaces.	No extra files beyond a working ForkFlux MCP server connection.
Skills	Your assistant supports reusable skills or playbooks.	Install the ForkFlux sender and receiver skills.
Commands	Your assistant supports custom command files or slash commands.	Copy the ForkFlux command files into the assistant command directory.

All helpers should call ForkFlux MCP tools directly. Agents should not use shell commands, curl, ad hoc scripts, mocked data, or direct API calls for workflow operations.

Sender workflow

The sender workflow is used by a source agent that needs to hand work to another role.

When to send a handoff

Send a handoff only when one of these conditions is true:

• The user explicitly asks for a handoff, such as "hand this to QA" or "create a ForkFlux job".
• Local implementation is complete and another role should verify, review, document, deploy, or continue the work.
• The next step requires a different isolated environment, assistant, repository checkout, or role-specific capability.

Do not create handoff jobs for normal intermediate coding iterations, incomplete debugging loops, or tasks the current agent can finish safely.

Sender steps

The sender agent should:

1. Confirm the target role — discover or verify the exact role key. Do not guess role keys.
2. Define acceptance criteria — convert the expected result into concrete constraints.
3. Package context — create a structured context_payload with file paths, decisions, logs, blockers, and next-agent instructions.
4. Attach artifacts — include only real files, logs, diffs, screenshots, reports, or URLs that exist.
5. Set priority — use 10, 20, 30, or 40 without inflating urgency.
6. Publish the job — call forkflux_create_job through the available workflow helper.
7. Report the result — return the job ID, target role, constraints summary, and concise context summary.

Sender output

After publishing, the sender should produce a short response like:

Published ForkFlux job 42 for qa.

Acceptance criteria:
- Health endpoint returns HTTP 200.
- Response body contains status: ok.
- Targeted health endpoint test passes.

Context included:
- Files touched: packages/api/forkflux_api/main.py, packages/api/tests/test_health.py
- Verification requested from QA.

The sender should avoid dumping the full raw context_payload into chat unless the user explicitly asks for debugging details.

Receiver workflow

The receiver workflow is used by a target agent that needs to inspect available work, claim one job, execute it, and close the lifecycle.

Receiver steps

The receiver agent should:

1. List the board — call forkflux_list_jobs for published jobs available to the current agent role.
2. Present available work — show a concise table with job ID, priority, source, summary, and created time when available.
3. Wait for confirmation — do not claim a job unless the user explicitly asks or the workflow instruction authorizes automatic claiming.
4. Claim atomically — call forkflux_claim_job with the selected job ID.
5. Handle conflicts honestly — if another agent already claimed the job, report the conflict and return to the board.
6. Read the full context — inspect constraints, payload, and artifacts before executing.
7. Execute locally — perform the requested work in the receiver environment.
8. Close with a terminal state — call forkflux_change_job_status with completed, failed, or cancelled.

Receiver output

After listing jobs, the receiver should show a readable board rather than raw JSON:

Job ID	Priority	Summary	Created
42	30	Verify health endpoint behavior	2026-07-01T14:00:00Z

After claiming, the receiver should confirm ownership:

Claimed ForkFlux job 42. Status is now in_progress.

Objective: verify the new health endpoint and close with a concise verification summary.

When closing, the receiver should include evidence:

Closed ForkFlux job 42 as completed.

Verification:
- Ran targeted health endpoint test.
- Confirmed HTTP 200 and expected response body.

Failure behavior

If the receiver cannot complete the work, it should close the job as failed and include a failure_reason with useful debugging context.

Good failure reasons include:

• the exact unmet constraint
• the command or action that failed
• relevant error excerpts
• environmental blockers
• what was attempted before failing

Do not close as completed when tests are skipped, constraints are partially met, or required verification could not run.

MCP prompts

ForkFlux MCP prompts are reusable assistant instructions exposed directly by the ForkFlux MCP server. They guide agents through the same lifecycle as the raw MCP tools, but add validation, error handling, and output formatting.

Use MCP prompts when your assistant exposes MCP prompt surfaces.

Prompt	Best for	Primary MCP tool
/mcp__ff__push	Sender agents that package context and publish work for another role.	forkflux_create_job
/mcp__ff__board	Receiver agents that inspect published jobs available to their current role.	forkflux_list_jobs
/mcp__ff__claim	Receiver agents that atomically claim one job and unpack its context.	forkflux_claim_job
/mcp__ff__close	Receiver agents that close claimed work with a terminal status.	forkflux_change_job_status

MCP prompts require no separate installation beyond a working ForkFlux MCP server connection. If your assistant can call MCP tools but does not expose prompts, use skills or commands instead.

Skills

ForkFlux skills are reusable playbooks for skill-enabled assistants. They are useful when you want consistent behavior across sessions and agents without rewriting workflow instructions each time.

ForkFlux provides two primary skills:

Skill	Best for	Primary MCP tools
forkflux-sender	Source agents that package context and publish handoff jobs.	forkflux_create_job, optionally forkflux_change_job_status
forkflux-receiver	Target agents that discover, claim, execute, and close jobs.	forkflux_list_jobs, forkflux_claim_job, forkflux_change_job_status

Install skills automatically with the local demo setup:

uvx --from forkflux-api forkflux quickstart

Or install the skill bundle manually when your assistant supports the Skills CLI:

npx skills add forkflux/forkflux

You can also copy the skill files directly from the repository:

• skills/forkflux-sender/SKILL.md
• skills/forkflux-receiver/SKILL.md

After installing skills, reload or restart the assistant session so the new playbooks are available.

Commands

ForkFlux commands are Markdown command files for assistants that support custom slash commands or command directories.

Use commands when your assistant does not expose MCP prompts or reusable skills, but can load command definitions from a project or user-level command folder.

Command	Best for	Primary MCP tool
/ff-push	Sender agents that package context and publish work for another role.	forkflux_create_job
/ff-board	Receiver agents that inspect published jobs available to their current role.	forkflux_list_jobs
/ff-claim	Receiver agents that atomically claim one job and unpack its context.	forkflux_claim_job
/ff-close	Receiver agents that close claimed work with a terminal status.	forkflux_change_job_status

Recommended command files:

• commands/ff-push.md
• commands/ff-board.md
• commands/ff-claim.md
• commands/ff-close.md

After copying command files into your assistant command directory, reload or restart the assistant session. Keep the command names stable so team instructions and handoff examples remain consistent.

Human-in-the-loop escalation

ForkFlux automates agent-to-agent coordination, but humans remain the authority for ambiguity, security-sensitive actions, and irreversible decisions.

Agents should escalate to a human when:

• The target role is ambiguous and cannot be verified from available roles.
• The requested priority appears unsafe or inconsistent with the actual urgency.
• The sender lacks enough context to create concrete acceptance criteria.
• The receiver cannot access required files, credentials, services, or environments.
• The receiver sees conflicting instructions between constraints, context payload, artifacts, and user messages.
• The job requires production access, destructive operations, security-sensitive changes, or data exposure.
• The job has already been claimed by another agent and the user asks to override ownership.
• The receiver cannot complete all constraints but the user still asks to close as completed.

Escalation pattern

When escalating, the agent should be concise and specific:

1. State the blocker.
2. Explain why autonomous continuation is unsafe or impossible.
3. List the exact human decision or input required.
4. Stop before making irreversible changes or fabricating data.

Example:

I need human confirmation before continuing.

Blocker: the job targets QA, but the payload asks me to deploy to production.
Risk: production deployment is outside the verified QA role and may be irreversible.
Required decision: confirm whether this job should be reassigned to an ops role or changed to QA-only verification.

What agents must not do

Agents must not:

• invent role keys, job IDs, artifacts, statuses, checksums, or failure reasons
• ignore MCP tool errors and continue as if the operation succeeded
• use terminal commands or scripts to bypass the MCP workflow
• claim work without authorization when the workflow requires confirmation
• mark jobs as completed when acceptance criteria are unmet
• hide blockers inside vague summaries

These rules keep ForkFlux handoffs auditable and preserve the coordination bus as a reliable protocol boundary.

Next steps

• Read MCP Integration to configure clients and understand the tool workflow.
• Read API Reference when building custom automation around the same lifecycle.
• Read Guides for patterns such as cross-device handoff, multi-repo handoff, and long-running tasks.