In a previous article, How I Use Claude Code and Codex Together to Build .NET Features Faster, I described a workflow in which Claude Code and codex linked together to achieve my codings tasks.
The link between those steps was a file called task.md.
Claude Code -> task.md -> Codex -> Claude review
I treated that file as a contract between the agents. It recorded the problem, the relevant files, the proposed implementation, and the checks that needed to pass. It gave Codex a clear starting point without requiring it to repeat all of Claude's investigation.
That workflow worked well, and I still use it when a feature needs a detailed written handoff. But it also meant creating and maintaining a task file for every piece of work, especially when a GitHub issue/Azure Devops task already described the problem and its acceptance criteria.
After moving this workflow into Orca, I stopped treating task.md as a mandatory step. Orca is open source, so its repository is also a useful place to explore the project, read its documentation, and follow its development.
Orca gives me a workspace for organizing coding agents around a repository. I can review the work that needs to be done, create a separate worktree for an issue, and open Claude Code or Codex in that isolated environment. I can also save the instructions I repeat as quick commands instead of rewriting the same prompts each time. If your don't know about git worktrees, you can find out more here.
Orca does not automatically carry a conversation from one agent to another, but not every piece of context needs to live in the conversation. A well-written issue defines the task, while repository files such as AGENTS.md and CLAUDE.md provide project instructions, including coding conventions, instructions for building and testing. Orca gives the work an isolated boundary, and quick commands provide repeatable directions.
For many focused issues, that is enough context to go straight from investigation to implementation.
This article is not a tour of everything Orca can do. It covers the small part I use in my day-to-day workflow: reviewing issues, creating isolated worktrees, opening an agent, running quick commands, keeping an eye on agent usage limits, and verifying the result.
Why task.md Started to Feel Like an Extra Step
In my original workflow, task.md solved a real problem. Claude Code and Codex were separate agents, so I needed a reliable way to carry the result of one agent's investigation into the other agent's implementation session.
The file did that job, but the surrounding process still involved a lot of manual setup. I had to switch between terminals, confirm that both agents were in the correct repository and branch, and keep unrelated changes from becoming mixed together.
I was also repeating the same prompts:
- Investigate the issue without changing anything.
- Implement the smallest appropriate fix.
- Follow the repository conventions.
- Run the relevant tests.
- Review the diff for unintended changes.
Then there was the task file itself. For a complex feature, writing it was useful because it forced the investigation into a concrete plan. For a smaller well defined issue, however, it often duplicated information that was already in GitHub. If the investigation changed the implementation plan, I either had to update the file or regenerate it before moving to the next agent.
The result was that I sometimes spent more time preparing the workflow than starting the fix.
Why Orca Makes task.md Optional
The easiest way to explain the change is to look at the pieces of context an agent actually needs.
First, it needs to know what to do. For focused work, that can come from a GitHub issue with a clear problem statement, useful comments, and acceptance criteria.
Second, it needs to know how the project expects work to be done. Files such as AGENTS.md, CLAUDE.md, and other repository documentation can provide build commands, testing expectations, architecture notes, and coding conventions.
Third, it needs a safe place to work. Orca gives the issue its own worktree, so the agent starts on the correct branch with an isolated set of files. Work for one issue does not have to share a directory with unfinished work for another.
Finally, the agent needs clear directions for the current stage of the workflow. Orca quick commands let me reuse the same investigation, implementation, review, and verification prompts instead of composing them again for every issue.
Issue + repository instructions + worktree + quick commands
= enough context for many focused fixes
None of these pieces makes the final decision for me. I still choose the issue, decide whether it is sufficiently scoped, select the appropriate agent, inspect the diff, and judge whether the result satisfies the acceptance criteria. Orca simply gives those decisions a cleaner and more repeatable structure.
The Example Project
You'lll have noticed I'm using *JobSearchBuilder * as the running example. It is a .NET Framework WinForms application that builds targeted Google queries for job searches, but the application itself is not the focus here, it is simply the repository in which I am demonstrating my workflow. If you'd like to see more about this project check it out here
Step One: Start From the Issue List
My workflow now begins with the project's issue list, before I open an agent or change any code.
gh issue list --state open --limit 20
You can also view the issue list from Orca itself by clicking Tasks in the top left pane.
I look for an issue that has a clear boundary and can be completed independently. A useful issue explains the current behavior, the desired behavior, and any constraints that affect the fix. Labels and comments can also contain important context, so I read those before deciding that the issue is ready.
For this example, I selected issue #47.
gh issue view 47
Or just select it from Orca.
Before creating a worktree, I decide what evidence will show that the issue is fixed. That evidence might be a new automated test, an existing test that starts passing, a successful build, or a specific change in the application's behavior. Defining that evidence early makes it easier to verify the agent's result later.
If the issue is vague, I do not assume that Orca will make it clear. I either improve the issue first or use a planning pass to turn the ambiguity into a more detailed task. The quality of the workflow still depends on the quality of the input.
Step Two: Create a Worktree for the Issue
Once I have selected an issue, I create a dedicated Orca worktree for it. I name the worktree or branch after the issue number or the purpose of the change so that its scope remains obvious.
You can also choose what coding agent you want to start with, and also open multiple worktrees in parallel with different agents to see which one performs the best.
My main workspace stays clean, and changes for separate issues do not become mixed together. An agent can investigate or implement in this worktree without touching unfinished changes elsewhere.
This also reduces one of the most common sources of confusion in a multi-agent workflow: an agent operating in the wrong directory or on the wrong branch. I still verify the branch with git status, but Orca makes the task's boundary visible from the beginning.
The worktree does not contain the issue's reasoning by itself. Its role is isolation. The issue explains the goal, the repository explains the conventions, and the worktree answers a different question: where does this change belong?
Step Three: Open the Right Agent(or multiple) in the Worktree
With the worktree ready, I open Claude Code or Codex inside it.
The agent starts with the correct branch and isolated files. It can read the issue, inspect the repository instructions, and explore the relevant code without a separate task-file ceremony.
There is no automatic task.md step. I first ask the agent to investigate the issue, then I review its explanation before allowing it to make changes. That preserves the useful separation between understanding a problem and editing the code without requiring a new file for every handoff.
Some features still need a stronger handoff. If the requirements are ambiguous, the change touches several areas, or the implementation must happen in a particular sequence, I can ask Claude to produce a detailed plan and save it as task.md. Codex can then implement that plan in the same worktree.
Issue -> worktree -> Claude plan -> task.md -> Codex implementation
The difference is that I now create the task file because the work needs it, not because the workflow always demands it.
Step Four: Use Quick Commands
I use Orca's quick commands for the CLI commands I run repeatedly. For JobSearchBuilder, the two important ones build the test project and run its tests using the Release configuration.
The build command is:
dotnet build
The test command is:
dotnet test
Saving these as quick commands means I do not have to remember or retype the project path and configuration whenever I move to another issue worktree. More importantly, I verify each change with the same commands instead of relying on an agent's statement that the implementation should work.
Keep an Eye on Coding-Agent Limits
Running more than one coding agent makes provider usage limits easier to reach, especially when several worktrees are active at the same time. Another useful part of Orca is that I can see how much of my supported coding agents' usage allowance I have consumed and when those limits reset.
These are not extra limits created by Orca. They are the limits associated with the coding-agent accounts and subscriptions I have connected. Orca brings that information into the same workspace, so I do not have to wait for an agent to stop unexpectedly before realizing that an allowance is nearly exhausted.
This is particularly helpful when deciding which agent to use for the next issue. If one agent is close to its limit, I can account for that before opening another session, instead of discovering it halfway through an implementation or test run.
Step Five: Fix and Verify the Issue
The agent begins by inspecting the relevant files and tracing the behavior described in the issue. Only after the likely cause is clear does it edit the code.
For the selected JobSearchBuilder issue, the implementation stays focused on the failing behavior. The agent makes the smallest appropriate production change and adds or updates a test that demonstrates the corrected result.
When the agent finishes, I inspect the diff myself. I first use Git's summary and whitespace checks:
Then I run the saved build and test quick commands from the previous step. After they finish, I check the worktree status and finish up the task.
The last status check confirms exactly which files remain changed in the worktree. At this point I want a narrow diff, a test that covers the corrected behavior, and build and test results that support the agent's summary.
The isolated worktree makes this review easier. I am looking at the changes for one issue rather than separating them mentally from unrelated work in the same directory.
The Old and New Workflows Side by Side
My previous workflow looked like this:
Open repository
-> Start Claude Code
-> Plan the feature
-> Write task.md
-> Open Codex in the same directory
-> Implement
-> Return to Claude for review
With Orca, the common path now looks like this:
Open issue list
-> Select an issue
-> Create an isolated worktree
-> Open the appropriate agent
-> Run reusable quick commands
-> Fix and test
-> Review the isolated diff
In my new workflow, the issue provides the focused specification. Repository instructions provide stable project conventions. The worktree provides isolation. Quick commands reduce repeated prompting or CLI commands. Together, they remove the need to manufacture a separate handoff document for every issue.
When I Still Use task.md
I still use task.md when:
- The feature is larger than a single well-scoped issue.
- The requirements are ambiguous and need a dedicated planning pass.
- Several implementation steps must happen in a specific order.
- One agent needs to hand a detailed design to another.
- Important decisions are not already captured in the issue or repository documentation.
I usually skip it when:
- The issue already explains the problem and its acceptance criteria.
- The repository instructions already define the project conventions.
- The work fits cleanly inside one isolated worktree.
- A quick command supplies the remaining direction.
- The agent can investigate, implement, test, and summarize the change directly.
An Evolution of the Same Idea
I still keep a core part of my previous article, in that different coding agents can play different roles in the same development process. One can investigate and plan, another can implement, and another pass can review the result.
The shared task.md was the first version of the process. It gave those roles an explicit contract and solved an important context-handoff problem. I have not abandoned that pattern; I have narrowed the situations in which I use it.
Orca makes it practical to use the issue as the task, the worktree as the boundary, and quick commands as the reusable instructions. For a well-scoped issue, that gives the agent enough structure without creating another file to maintain.
The simplified loop is now:
Issue -> Worktree -> Agent -> Quick command -> Fix -> Test -> Review
For complex work, task.md can still sit between planning and implementation. For everything else, it no longer has to be the price of using more than one coding agent.
Happy Coding!!!









Top comments (0)