mirror of
https://github.com/iflytek/skillhub.git
synced 2026-08-28 11:25:00 +00:00
f8d96171f0
- Rename setup-agent-worktrees.sh -> parallel-init.sh - Rename sync-agent-integration.sh -> parallel-sync.sh - Rename 13-agent-parallel-workflow.md -> 13-parallel-workflow.md - Add parallel-common.sh with shared utilities - Add parallel-up.sh (sync + dev-all in one step) - Add parallel-down.sh (stop integration stack) - Remove agent-worktrees and agent-sync Makefile targets - Remove AGENT_BASE_REF and AGENT_WORKTREE_ROOT variables - Clean up compatibility shim references in docs
173 lines
5.1 KiB
Markdown
173 lines
5.1 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
cd ../skillhub-integration-legal-pages
|
||
make parallel-sync
|
||
make dev-all
|
||
```
|
||
|
||
If needed, you can override the source list on either command:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
make parallel-init TASK=legal-pages
|
||
cd ../skillhub-integration-legal-pages
|
||
make parallel-up
|
||
open http://localhost:3000
|
||
make parallel-down
|
||
```
|