Skip to main content

​
What are Workflows?

Workflows in sudocode allow you to execute linked issues, specs, or sets of issues in dependency order. Instead of manually dispatching agents one issue at a time, workflows automatically process dependency chains. Manual execution:
  1. Dispatch agent for issue 1
  2. Wait for completion
  3. Dispatch agent for issue 2
  4. Wait for completion
  5. Repeat for each dependent issue
Workflow execution:
  1. Select the final issue in a dependency chain
  2. Start workflow
  3. sudocode automatically processes all blocking issues in topological order
  4. Agents work in parallel where possible
  5. Review and merge results when complete

​
Example: Bug Fix with TDD Workflow

Let’s walk through fixing a modal bug using a test-driven development approach with workflows. This example demonstrates how to break down a bug into testable issues, establish dependencies, and execute them as a coordinated workflow.

​
The Bug

When opening a submodal within an issue modal, pressing “Esc” collapses both modals and stops execution. The bug only occurs with the Esc key, not when clicking outside the modal.

​
Phase 1: Planning the Fix with an Agent

Step 1: Describe the bug and ask the agent to create issues 
> Can you fix this bug for me? In my case, when I open an issue modal,
  and start an execution, and then open a submodal (like the settings icon,
  or a file viewer icon), if I press "Esc" both modals collapse, and the
  execution stops (because the Esc propagates into the submodal). The both
  modal collapsing bug does not happen when clicking outside the modal, only
  when pressing Esc.

  First, we should have an issue for building two tests, one for each of
  these failure cases. The tests should fail (we're using a TDD approach).
  Don't overmock components, if a real component can be used, use it.

  Second, let's describe several strategies we could use to fix this bug.
  Let's just update the issue with a list of strategies, and recommendations
  as to how to fix it.

  Third, have an issue that attempts to fix this based on the strategies
  presented in the previous issue.

  Last, let's have an issue that evaluates whether the solution and tests
  fix the original bug.

  Let's create issues for this.

⏺ Agent: I'll create a set of issues following a TDD approach to fix this
  modal bug. Let me break this down into four issues with proper dependencies.
Step 2: Agent creates issues and establishes dependencies 
⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Write failing tests for modal Esc key propagation bug", ...)
  ⎿  { "id": "i-test1", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Research and document fix strategies for modal Esc propagation", ...)
  ⎿  { "id": "i-strat1", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Implement fix for modal Esc key propagation", ...)
  ⎿  { "id": "i-impl1", ... }

⏺ plugin:sudocode:sudocode - upsert_issue (MCP)
  (title: "Validate fix resolves original bug", ...)
  ⎿  { "id": "i-valid1", ... }

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-test1", to_id: "i-strat1", type: "blocks")

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-strat1", to_id: "i-impl1", type: "blocks")

⏺ plugin:sudocode:sudocode - link (MCP)
  (from_id: "i-impl1", to_id: "i-valid1", type: "blocks")

⏺ Agent: I've created 4 issues with the following dependency chain:

  i-test1 (Write failing tests)
    ↓ blocks
  i-strat1 (Research fix strategies)
    ↓ blocks
  i-impl1 (Implement fix)
    ↓ blocks
  i-valid1 (Validate fix)
Step 3: Review issues on the issue board
Issue board showing the four TDD issues ready to execute
Open localhost:3000 and navigate to the Issues board:
  • Review all 4 issues created by the agent
  • Verify the dependency chain is correct
  • Modify issue descriptions if needed
If you want to save the state of your issues board, you can commit the changes to your git repository:
git add .
git commit -m "Add TDD issues for modal Esc propagation bug fix"

​
Phase 2: Execute the Workflow

Step 5: Start the workflow
Starting a workflow by selecting the final validation issue
To start the workflow:
  1. Navigate to the workflow board at localhost:3000
  2. Select “From Root Issue” and select the final issue in the chain (i-valid1)
  3. Click the “Start Workflow” button
  4. sudocode automatically identifies all blocking dependencies and creates an execution plan
Step 6: Monitor workflow progress
Workflow executing with agents processing issues in dependency order
As the workflow executes:
  • The first issue (i-test1) starts immediately since it has no blockers
  • Subsequent issues automatically start when their blockers complete
  • Each issue runs in the same isolated worktree
  • Progress updates appear in real-time on the issue board
Step 7: Review individual issue progress
Viewing details of an in-progress issue
Click on any issue to see:
  • Current execution status
  • Agent conversation and decision-making
  • Files being modified
  • Test results and validation
Step 8: Inspect file changes
Reviewing files modified by the agent within an issue
Within each issue, you can:
  • View all modified files
  • See diffs of changes made
  • Review test results
  • Stop the agent, and chat with it directly

​
Phase 3: Merge Results

Step 9: Merge worktree changes
Merging agent changes from worktree to main branch
Once the workflow completes:
  1. Review the changes made across all issues
  2. Click “Merge Worktree” to integrate changes into your main branch
  3. sudocode merges all commits from the worktree into your main branch
Step 10 [Optional]: Ask an agent about the implementation After merging, you can open an agent and ask questions about what was implemented: 
> What approach did the agent use to fix the modal bug?

⏺ plugin:sudocode:sudocode - show_issue (MCP)(issue_id: "i-impl1")
  ⎿  { "id": "i-impl1", ... }

⏺ Based on issue i-impl1, the agent implemented event.stopPropagation()
  on the submodal's Esc key handler. This prevents the Esc keypress from
  bubbling up to the parent modal, which was causing both to close.

  The fix was chosen because it's minimally invasive and follows the
  strategy recommendations from i-strat1, which identified event
  propagation as the root cause.

​
Benefits of Workflows

Automated Coordination

No manual orchestration needed
  • sudocode handles execution order
  • Parallel work runs concurrently
  • Dependencies respected automatically
  • Hands-off execution

Isolated Execution

Safe, conflict-free processing
  • Each issue in separate worktree
  • No interference between agents
  • Easy rollback per issue
  • Clean merge points

Visibility

Track progress in real-time
  • See all issues in workflow
  • Monitor agent decisions
  • Review files as they’re modified
  • Understand implementation choices

​
When to Use Workflows

Workflows are ideal for:
  • Multi-step bug fixes: Test writing, implementation, validation
  • Feature development: Database → domain → API → testing phases
  • Refactoring projects: Multiple coordinated code changes
  • Migration tasks: Sequential steps with clear dependencies
Workflows are less useful for:
  • Single, standalone issues with no dependencies
  • Exploratory work without clear structure
  • Tasks requiring frequent human decision-making

​
Best Practices

Break complex tasks into small, focused issues with explicit dependencies.Good structure:
✅ Issue 1: Write failing test (no blockers)
✅ Issue 2: Research fix strategies (blocked by Issue 1)
✅ Issue 3: Implement fix (blocked by Issue 2)
✅ Issue 4: Validate solution (blocked by Issue 3)
Poor structure:
❌ Issue 1: Fix the bug and test it (too large, unclear ordering)
Clear dependencies enable workflows to automatically determine the correct execution order.
When starting a workflow, select the last issue in the dependency chain. sudocode will automatically identify and execute all blocking dependencies.Why this works:
  • The workflow engine traces backwards through blocks relationships
  • All necessary work is discovered automatically
  • You don’t need to manually select each issue
  • Ensures nothing is missed
Always review worktree changes before merging into your main branch.What to check:
  • Implementation matches issue requirements
  • Tests are passing
  • No unintended side effects
  • Code quality meets standards
  • Agent decisions make sense
You can inspect individual issues and files during workflow execution to catch issues early.

​
Troubleshooting

Cause: Multiple worktrees modified the same issues or specsSolution:
# Run the sudocode conflict resolver
sudocode resolve-conflicts

# This intelligently merges changes from both versions
# Then commit the resolved files
git add .sudocode/
git commit -m "Resolve sudocode conflicts from workflow"
The resolve-conflicts command automatically handles concurrent modifications to sudocode metadata files.
Cause: Agent encountered an error or needs human inputSolution:
  1. Click on the stuck issue to view details
  2. Review the agent conversation to identify the blocker
  3. If the agent needs clarification, provide it in the issue chat
  4. If the agent errored, you can restart the issue or manually fix and continue
Workflows pause when an issue can’t make progress, allowing you to intervene.
Cause: Need to stop execution due to errors or changed requirementsSolution:
  1. Navigate to the workflow view
  2. Click “Cancel Workflow” or cancel individual issues
  3. Review any completed work in their worktrees
  4. Delete worktrees for cancelled issues or merge partial work if useful
Cancelled workflows don’t affect your main branch since work is isolated in worktrees.

Spec-Driven Development

Full workflow from spec to implementation

Issue Management

Deep dive into issues and dependencies

Web UI Overview

Complete web interface guide

Dependency Graph

Understanding relationships

MCP Workflows

Multi-agent coordination patterns