Skip to content

13-parallel-workflow.md

Latest commit

 

History

History
173 lines (112 loc) · 5.07 KB

13-parallel-workflow.md

File metadata and controls

173 lines (112 loc) · 5.07 KB

Claude + Codex Parallel Workflow

This document defines the recommended way to run Claude and Codex in parallel on SkillHub without letting them overwrite each other.

Legacy aliases agent-worktrees and agent-sync still work as compatibility shims, but the canonical command set is parallel-init, parallel-sync, parallel-up, and parallel-down.

Goals

  • Keep Claude and Codex isolated while they write code.
  • Reserve a single browser test environment at http://localhost:3000.
  • Make integration predictable before opening a pull request.

Core Rule

Do not let two agents write to the same checkout at the same time.

Instead, use three sibling git worktrees per task:

  • ...-claude-<task>: Claude writes code here
  • ...-codex-<task>: Codex writes code here
  • ...-integration-<task>: merged result, browser verification, final regression

Only the integration worktree should run make dev-all. That keeps http://localhost:3000 and http://localhost:8080 as a single source of truth for the merged feature.

All worktrees share the same local Docker dependency project name, so make dev and make dev-all reuse one set of Postgres, Redis, and MinIO containers across checkouts.

One-Time Setup Per Task

From the main repository:

make parallel-init TASK=legal-pages

This creates:

  • ../skillhub-claude-legal-pages
  • ../skillhub-codex-legal-pages
  • ../skillhub-integration-legal-pages

And matching local branches:

  • agent/claude/legal-pages
  • agent/codex/legal-pages
  • agent/integration/legal-pages

You can override the base branch or destination root:

make parallel-init TASK=legal-pages PARALLEL_BASE_REF=origin/main PARALLEL_WORKTREE_ROOT=/Users/wowo/workspace

If you are iterating on this workflow itself before it lands on origin/main, create the worktrees from your current branch instead:

make parallel-init TASK=legal-pages PARALLEL_BASE_REF=HEAD

Recommended Responsibility Split

Keep the split coarse and explicit before either agent starts:

  • Claude: requirements, review, copy, UI structure, edge cases, regression review
  • Codex: implementation, wiring, scripts, tests, refactors, fixes

Avoid assigning the same file to both agents. If both agents must touch one file, switch to sequential editing for that file.

Daily Loop

1. Parallel implementation

Run each agent only in its assigned worktree:

  • Claude works in ../skillhub-claude-<task>
  • Codex works in ../skillhub-codex-<task>

Each agent should commit its own work before integration.

2. Merge into integration

From the integration worktree:

cd ../skillhub-integration-legal-pages
make parallel-up

This does both routine steps in one command:

  • merges the default source branches into the current integration branch
  • starts the integration worktree with make dev-all

The default source branches are:

  • agent/claude/legal-pages
  • agent/codex/legal-pages

If you need manual control, you can still split the flow:

cd ../skillhub-integration-legal-pages
make parallel-sync
make dev-all

If needed, you can override the source list on either command:

make parallel-sync SOURCES="agent/claude/legal-pages agent/codex/legal-pages"
make parallel-up SOURCES="agent/claude/legal-pages agent/codex/legal-pages"

If a merge conflict happens, resolve it in the integration worktree. Do not resolve it inside the Claude or Codex worktree unless you intentionally want to rewrite that branch.

3. Browser verification

Run the local stack only in the integration worktree:

cd ../skillhub-integration-legal-pages
make parallel-up

Then verify the merged result in the browser:

  • Web UI: http://localhost:3000
  • Backend: http://localhost:8080

When you are done:

make parallel-down

Validation Checklist

Before opening a PR from the integration branch:

  1. Run the smallest relevant local verification first, for example pnpm --dir web typecheck or backend tests.
  2. From the integration worktree, run make parallel-up.
  3. Verify the final merged behavior in http://localhost:3000.
  4. Run make staging if the change needs Docker-path or smoke-test confidence.

Recovery Rules

  • If one agent’s branch goes in the wrong direction, reset or discard that branch only in its own worktree.
  • If integration becomes messy, recreate only the integration worktree branch from the original base and merge again.
  • If ports are already in use, make sure no Claude or Codex worktree is running its own local stack.

PR Strategy

There are two safe choices:

  • Open the PR from the integration branch after merged verification passes.
  • Or cherry-pick the validated commits onto a clean feature branch and open the PR from there.

For this repository, the simplest path is usually:

  1. Claude branch commits
  2. Codex branch commits
  3. In the integration worktree, run make parallel-up
  4. Verify on localhost:3000
  5. Open the PR from integration

Commands Summary

make parallel-init TASK=legal-pages
cd ../skillhub-integration-legal-pages
make parallel-up
open http://localhost:3000
make parallel-down