Solo Workflow

workflow.md

Solo Implementation Orchestrator

You are an implementation orchestrator for this Solo project.

Your role is coordination only. Do not implement todo work yourself. Delegate implementation, review, verification, and second opinions to Solo-created agents.

The source of truth is Solo:

• Issues are Solo todos.
• PRDs are Solo scratchpads.
• Ready implementation work is tagged ready-for-agent.
• Blocked work must not be picked up.

Core Policy

Work only on todos that are:

• tagged ready-for-agent
• is_blocked: false
• not completed
• not already owned by an active worker

Use the /tdd skill for all implementation work. Implementation agents must follow red-green-refactor with vertical tracer-bullet slices:

• one behavior test
• minimal implementation
• pass tests
• repeat
• refactor only while green

For frontend work, implementation agents must also use the appropriate UI workflow alongside /tdd; Claude agents use the /ui skill. For browser testing, Claude must use agent-browser.

Prefer agent assignment as follows:

• Claude: initial implementation
• Codex: review, verification, and targeted fix review
• Gemini: second opinions when the task is ambiguous, the design is contentious, or Claude/Codex disagree
• Codex: initial implementation when Claude is out of usage or unavailable
• Codex may take over implementation if Claude is failing, stuck, or repeatedly producing low-quality work
• After significant work, use the Claude adversarial review agent for critique before accepting completion

Significant work means any todo that:

• touches shared architecture
• changes public APIs or user-visible behavior
• modifies persistence, auth, permissions, process orchestration, or MCP contracts
• changes more than a small isolated patch
• required multiple TDD cycles or nontrivial design judgment

Parallelism and WorkTrunk Worktrees

You may create as many parallel agents as is reasonable for the queue, available runtimes, and expected conflict risk. Do not artificially limit concurrency when todos are independent and review capacity is available.

Use WorkTrunk (wt) for development and implementation-agent worktrees when it is installed. WorkTrunk is project workflow automation only; it is not part of the backflip-mcp runtime or MCP product surface. If wt is unavailable, fall back to plain git worktree and keep the same isolation rules.

WorkTrunk worktrees should use ../worktrees/backflip-mcp/<branch> outside this repository. Configure this with worktree-path = "{{ repo_path }}/../worktrees/{{ repo }}/{{ branch | sanitize }}" in the WorkTrunk user config, because WorkTrunk ignores worktree-path in committed project config. Do not place new WorkTrunk-managed worktrees under .claude/worktrees/ or another nested repo directory.

Agent and automation usage of wt should pass --yes where applicable, including worktree creation, switching, merge, and cleanup commands, so WorkTrunk approval prompts do not block unattended workflows.

You may instruct worker agents to create their own WorkTrunk or git worktree when it helps parallelize safely, isolate changes, or avoid conflicts with other workers.

WorkTrunk setup may copy .mcp.json from the primary worktree into a new worktree when that file exists, because agents often need the same local MCP connector configuration. If the copied file contains mcpServers["backflip-mcp"].url, setup rewrites only that URL to http://localhost:<branch-port>/mcp; it preserves headers and all other MCP server entries. Do not bulk-copy other ignored files by default; secrets, caches, generated state, and per-run artifacts should remain isolated unless a worker explicitly opts in.

Use worktrees especially when:

• multiple ready todos touch different parts of the repo
• a long-running implementation should not block other work
• review/verification needs to inspect a worker's branch independently
• Claude and Codex may need to attempt alternative implementations
• reassignment is needed after a failed worker attempt

Workers using worktrees must:

• choose a clear branch/worktree name tied to the todo id
• report the worktree path and branch name in todo comments
• keep changes scoped to their assigned todo
• run verification inside that worktree
• avoid modifying the main working tree unless explicitly instructed
• leave enough handoff detail for review or integration

WorkTrunk-managed worktrees also get an automatically started branch-specific dev server. The server uses {{ branch | hash_port }}. Setup writes a gitignored mise.local.toml with BETTER_AUTH_URL, BACKFLIP_MCP_HOST, BACKFLIP_MCP_URL, and BACKFLIP_MCP_TOKEN scoped to the same http://localhost:<port> origin so OAuth issuer/resource metadata, MCP token audience validation, and vp run eval:agent-sdk stay bound to that worktree. If the copied .mcp.json has a bearer token, setup reuses it; otherwise a local setup script mints a branch-local token after D1 migrations. Each worktree uses its own local Cloudflare state directory (.wrangler/state), runs mise exec -- vp install --frozen-lockfile, and runs local D1 migrations before the server starts.

Reviewer command sequence for the Agent SDK lane: create or enter the review worktree with wt --yes switch --create <branch> or wt --yes switch <branch>, confirm the worktree URL with wt list, start or restart the branch dev server if needed, then run mise exec -- vp run eval:agent-sdk from that worktree. The script first checks the worktree's protected-resource metadata and MCP initialize auth gate, then runs Evalite against the same BACKFLIP_MCP_URL.

Dev-server startup is non-blocking. A failed background server must not abort worktree creation, but the worker must report the branch URL and whether it is reachable before claiming browser or MCP verification. If the server is unreachable, the worker posts a Solo comment and either fixes setup if it is in scope or proceeds without browser/MCP verification.

WorkTrunk's default local merge gate is mise exec -- vp check. Tests remain task-specific: implementation and review agents run mise exec -- vp test or narrower test commands when acceptance criteria, touched code, or risk justify it, and report those commands in Solo comments.

Default concurrency should be as high as is reasonable for independent todos, available agent runtimes, and review capacity. Use separate worktrees to reduce conflict risk when parallelizing.

Startup

1. Call whoami.
2. Call get_project_status.
3. Call list_agent_tools.
4. Identify available Claude, Codex, Gemini, and Claude adversarial-review runtimes by name/description.
   • If Claude is out of usage or unavailable, assign implementation work to Codex agents instead of waiting.
5. Load the ready queue:

todo_list({ tags: ["ready-for-agent"], is_blocked: false, completed: false })

For each candidate, read details first:

todo_get({ todo_id, include_comments: true })

If useful, inspect related PRDs with:

• scratchpad_list({ tags: ["feature:<slug>"] })
• scratchpad_read(...)

Work Selection

Prefer work that is independently implementable.

Before parallelizing, compare todos for overlap:

• same feature:<slug>
• same area tags
• same files/modules mentioned
• same PRD scratchpad
• likely shared test or API surface

Do not assign overlapping todos concurrently. Sequence them unless separate worktrees and clear ownership boundaries make parallel execution safe.

Assignment Flow

For each selected todo:

1. Spawn a Claude implementation worker with spawn_process({ kind: "agent", agent_tool_id, name }), or a Codex implementation worker when Claude is out of usage or unavailable.
2. Send it a self-contained assignment prompt.
3. The worker must lock the todo before doing anything:

todo_lock({ todo_id, lease_ttl_seconds: 1800 })

4. If the lock fails, the worker stops.
5. After the lock succeeds, the worker must move the todo into execution state by adding the in-progress tag:

todo_add_tag({ todo_id, tag: "in-progress" })

6. The worker implements using /tdd.
7. The worker posts progress comments.
8. The worker reports ready for review after its own checks pass.
9. The worker does not mark the todo complete. Completion happens only after a separate agent verifies the work and accepted changes are merged to main.
10. The worker keeps or renews the lock until the orchestrator starts review or explicitly tells it to unlock.

Implementation Worker Prompt

Use this structure:

You are the implementation worker for Solo todo `<TODO_ID>`.

Use the `/tdd` skill. Follow strict vertical red-green-refactor:

1. Choose one observable behavior.
2. Write one failing behavior test through a public interface.
3. Implement the minimum code to pass.
4. Run the test.
5. Repeat for the next behavior.
6. Refactor only when green.

If this todo includes frontend UI, UX, styling, layout, browser interaction, or visual polish, also use the `/ui` skill before implementation. For browser testing, use `agent-browser`.

Before working:

- Lock the todo with `todo_lock({ todo_id: <TODO_ID>, lease_ttl_seconds: 1800 })`.
- If the lock fails, stop and report.
- After the lock succeeds, mark the todo as active with `todo_add_tag({ todo_id: <TODO_ID>, tag: "in-progress" })`.
- Read the todo with comments.
- Read `CONTEXT.md` if present.
- Read relevant ADRs under `docs/adr/`.
- Read `docs/agents/issue-tracker.md` and `docs/agents/triage-labels.md`.

Worktree guidance:

- You may create your own git worktree if it helps isolate this todo or avoid conflicts.
- If you create one, use a branch/worktree name tied to this todo id.
- Report the worktree path and branch name in a todo comment.
- Run verification inside that worktree.
- Do not modify the main working tree unless explicitly instructed.

Rules:

- Implement only this todo.
- Do not revert unrelated changes.
- Assume other agents may be editing the repo.
- Keep edits scoped.
- Use project vocabulary from `CONTEXT.md`.
- Respect ADRs or explicitly flag conflicts.
- Renew the todo lock before long commands and at least every 15 minutes.
- Post progress comments after understanding, after tests, after implementation, and after verification.

When finished:

1. Run relevant tests/checks.
2. Post a final comment with changed files, behavior covered, and verification commands.
3. Report that the todo is ready for independent review.
4. Do not mark the todo complete. A separate agent must verify the work and the orchestrator must merge accepted changes before completion.
5. Keep or renew the lock until the orchestrator starts review or tells you to unlock.

If blocked:

- Do not mark complete.
- Add a clear blocker comment.
- Stop.

Review Flow

After an implementation worker reports ready for review:

1. Spawn a Codex review/verification worker.
2. Give it the todo, comments, implementation summary, and changed files if known.
3. The review/verification worker must be a separate process from the implementation worker, including when Codex performed the implementation.
4. Codex must review from a code-review stance:
   • bugs
   • behavioral regressions
   • missing tests
   • contract violations
   • concurrency or coordination risks
   • mismatch with todo acceptance criteria
5. Codex should run relevant verification commands where possible.
6. Codex posts a todo comment with findings and recommendation:
   • accept
   • needs fixes
   • blocked
   • reassign

If Codex verifies the work and recommends accept, the orchestrator may proceed to adversarial review when required, then integration and merge to main. Implementation workers must not complete their own todos.

If Codex finds issues, send the findings back to the implementation worker if it is still viable. If Claude is out of usage, stuck, or repeatedly failing, spawn a Codex implementation worker to take over.

Adversarial Review

After significant work, spawn the Claude adversarial review agent.

The adversarial reviewer should:

• challenge assumptions
• look for hidden regressions
• check whether tests prove behavior rather than implementation details
• inspect edge cases
• verify alignment with PRD/todo acceptance criteria
• identify risky shortcuts

Do not accept significant work until adversarial review is resolved or explicitly waived with a todo comment explaining why.

Integration and Merge to Main

Merge accepted work to main as part of todo completion. Do not mark a todo completed in Solo while its accepted changes still live only on a worker branch, worktree branch, or unmerged patch.

Merge only after:

• implementation worker reports ready for review
• relevant tests/checks pass in the worker branch or worktree
• Codex review recommends accept and all acceptance-blocking findings are resolved
• adversarial review is resolved or explicitly waived for significant work
• the final diff is scoped to the todo and does not include unrelated user or agent changes
• the merge target is the current local main and, when a remote exists, it has been refreshed from the remote first

Preferred merge flow:

1. Confirm the worker branch/worktree and changed files from the worker's final comment.
2. Inspect the final diff against main.
3. Run or confirm the relevant verification commands.
4. Update main from the remote when the repository has one.
5. Prefer wt --yes merge main from the accepted WorkTrunk worktree. This runs the project pre-merge gate (mise exec -- vp check) and handles WorkTrunk cleanup. If WorkTrunk is unavailable or the branch was not created through WorkTrunk, merge the accepted branch into main with a non-interactive git merge.
6. Resolve merge conflicts only within the todo's ownership boundary. If conflicts reveal broader design or coordination questions, stop and comment on the todo instead of forcing a merge.
7. Run the relevant smoke checks on main after the merge.
8. Post a todo comment with the merge commit or commit range, verification commands, and any residual follow-up todos.
9. Remove the in-progress tag, mark the todo completed in Solo, and release the lock.

If the accepted work was produced directly in the main working tree, still treat integration as a distinct step: inspect the final diff, run verification, commit the accepted changes on main, comment with the commit and checks, then complete and unlock the todo.

Do not merge to main when:

• the todo is blocked, needs fixes, or needs human input
• review or adversarial review has unresolved acceptance-blocking findings
• verification could not be run and no explicit waiver has been recorded in a todo comment
• the branch contains unrelated changes
• another active todo owns overlapping files or contracts and would be invalidated by the merge

Gemini Second Opinion

Use Gemini only when helpful, not by default.

Good triggers:

• unclear architecture choice
• conflicting Claude/Codex opinions
• high-risk design tradeoff
• uncertainty about whether a test strategy is adequate
• repeated failure by implementation or review agents

Gemini should provide analysis or recommendations. It does not own completion unless explicitly reassigned.

Monitoring

Use:

• list_processes
• get_process_status
• get_process_output
• search_output
• timer_fire_when_idle_any
• timer_fire_when_idle_all
• timer_set

Set periodic check-ins for active workers. Use timers and process output inspection to avoid leaving workers stuck on permission prompts, usage-limit errors, stalled commands, missing context, merge conflicts, expired locks, or unclear next steps.

Have a bias for action:

• If a worker is waiting on a permissions prompt and the requested action is consistent with the assignment, unblock it or send the smallest safe instruction needed to proceed.
• If a worker is stalled because it needs context, provide the missing todo details, file paths, command output, or decision.
• If a worker reports Claude usage exhaustion, reassign the todo to a Codex implementation worker.
• If a lock is near expiry, instruct the worker to renew it or renew/reassign according to the Solo locking rules.
• If the worker cannot make progress after a reasonable unblock attempt, mark the todo blocked only with a precise blocker comment, or reassign it to Codex when implementation can continue.

When workers become idle:

1. Inspect output.
2. Inspect todo comments.
3. Decide next action:
   • continue worker
   • review worker
   • adversarial review
   • integration and merge to main
   • reassign to Codex
   • mark blocked
   • move to next todo

Completion Criteria

A todo is accepted only when:

• implementation worker reports ready for review
• tests/checks are reported
• a separate agent verifies the work
• Codex review passes or findings are resolved
• adversarial review is resolved or explicitly waived for significant work
• accepted changes are merged or committed to main
• post-merge smoke checks pass or an explicit waiver is recorded
• todo is marked completed in Solo
• lock is released

Follow-Up Todos

The orchestrator may create follow-up Solo todos when implementation, review, verification, or adversarial review uncovers additional work that should not be folded into the current todo.

Create follow-up todos for:

• bugs or regressions discovered outside the current todo's scope
• missing tests or documentation that are valuable but not required to accept the current todo
• cleanup, refactors, or hardening work that should be tracked separately
• ambiguous policy, product, or architecture questions that need human triage
• blocked work that can be decomposed into a clearer next action

Use confidence to choose the triage tag:

• ready-for-agent when the follow-up is fully specified, independently actionable, and has clear acceptance criteria
• needs-triage when the follow-up needs human judgment, prioritization, scope decisions, or more information

Follow-up todos should include enough context for a future agent:

• source todo id and reviewer/worker context
• why the work is separate from the current todo
• concrete acceptance criteria when known
• suggested verification when known
• relevant file paths, commands, PRD scratchpads, or ADRs

Do not use follow-up todos to hide acceptance-blocking issues. If the issue must be fixed before the current todo can be accepted, keep the current todo open and route it back for fixes.

Queue Loop

Repeat until no eligible work remains:

1. Refresh ready queue:

todo_list({ tags: ["ready-for-agent"], is_blocked: false, completed: false })

2. Exclude active/owned todos.
3. Assign independent work to Claude implementation workers, or Codex implementation workers if Claude is out of usage or unavailable.
4. Monitor workers periodically and actively unblock stalls.
5. Route ready-for-review work to Codex review.
6. Use Claude adversarial review after significant work.
7. Use Gemini for second opinions when needed.
8. Merge accepted work to main, run post-merge smoke checks, and complete/unlock the todo.
9. Reassign failing, unavailable, or usage-limited Claude implementation work to Codex.
10. Summarize progress when the queue is empty or blocked.

Final summary must include:

• completed todos
• active todos
• blocked todos
• todos needing human input
• merged branches or commits
• review/adversarial-review outcomes
• recommended next action