Background Implementer

Multi-LLM background implementation with context-safe parallel execution.

Quick Start

# 1. Analyze planning doc → extract tasks
# 2. Create output dir: .context/impl/
# 3. Determine round: R01, R02, ...
# 4. Run agents in background → {round}-{agent}.md
# 5. Guide user to check results manually

Output Convention

.context/impl/
├── R01-tasks.md               # Round 1: task decomposition
├── R01-claude.md              # Round 1: Claude's implementation notes
├── R01-codex.md               # Round 1: Codex's implementation notes
├── R01-gemini.md              # Round 1: Gemini's implementation notes
├── R01-summary.md             # Round 1: merged summary
├── R02-claude.md              # Round 2: fixes/iterations
└── R02-summary.md

Round number increments each implementation iteration:

mkdir -p .context/impl
ROUND=$(printf "R%02d" $(( $(ls .context/impl/R*-*.md 2>/dev/null | sed 's/.*\/R\([0-9]*\)-.*/\1/' | sort -rn | head -1 | sed 's/^0*//') + 1 )))

Provider Selection

Gemini v0.26+: Use -p "prompt" for non-interactive mode. Use --yolo for auto-approve file writes. Use -o text for clean output. Redirect stdout to capture: > output.md. Do NOT use -s (that's --sandbox, not silent). Codex v0.101+ (model: gpt-5.3-codex): Use codex exec --full-auto for non-interactive. Use -C dir to set working directory. Use -o file.md to save last message. Use nohup ... > log 2>&1 & for background. Sandbox is workspace-write by default (reads anywhere, writes only to workspace + /tmp). For parallel Codex agents, use git worktrees to give each agent an isolated workspace — this prevents file conflicts. Use --add-dir <path> if agents need to write outside the workspace. Claude subagents are the most reliable for complex implementation. Always prefer Claude for tasks touching 3+ files or requiring deep codebase understanding.

Workflow

Step 1: Analyze & Decompose

Extract from planning docs:

• DB migrations (independent)
• Models (depends on migration)
• Handlers (depends on models)
• Frontend (often independent)

Step 2: Wave Execution

Wave 1 (parallel): Migration + Frontend + Types
Wave 2 (after migration): Models
Wave 3 (after models): Handlers

Step 3: Run Agents

mkdir -p .context/impl
ROUND=$(printf "R%02d" $(( $(ls .context/impl/R*-*.md 2>/dev/null | sed 's/.*\/R\([0-9]*\)-.*/\1/' | sort -rn | head -1 | sed 's/^0*//') + 1 )))

Claude (complex logic):

Task({
  subagent_type: "general-purpose",
  prompt: `Read task file: .context/impl/${ROUND}-tasks.md
Implement the assigned tasks and save implementation notes to .context/impl/${ROUND}-claude.md`,
  run_in_background: true
})

Codex (code generation):

For parallel Codex agents, create git worktrees first:

# Create isolated worktree per agent
git worktree add -b impl/{feature} /path/to/worktree-{feature} main
cd /path/to/worktree-{feature} && pnpm install

Then run Codex in each worktree:

PROJ_DIR="$(pwd)"
nohup codex exec --full-auto \
  -C /path/to/worktree-{feature} \
  --add-dir "${PROJ_DIR}/.context/impl" \
  -o "${PROJ_DIR}/.context/impl/${ROUND}-codex.md" \
  "Read task file at ${PROJ_DIR}/.context/impl/${ROUND}-tasks.md and implement all described changes. Run tests to verify." \
  > "${PROJ_DIR}/.context/impl/${ROUND}-codex.log" 2>&1 &

Key Codex notes:

• Use -C dir for working directory (must be a git repo), -o file for last message, nohup ... & for background
• Always redirect both stdout and stderr to a log file (> log 2>&1 &)
• Sandbox: workspace-write (reads anywhere, writes only to workspace + /tmp)
• Use absolute paths for task files and log files (they're outside the worktree)
• Use --add-dir <path> if agent needs to write to additional directories
• Codex DOES write files successfully — don't mistake slow log output for failure; check worktree for actual file writes
• After completion, copy files from worktree to main, then clean up: git worktree remove /path/to/worktree --force

Gemini (tests/docs/review):

# For planning/review output (no file writes needed):
nohup gemini -p "Review and generate test plan for: .context/impl/${ROUND}-tasks.md" \
  -o text > .context/impl/${ROUND}-gemini.md 2>/dev/null &

# For file-writing tasks (auto-approve):
nohup gemini -p "Implement tasks from .context/impl/${ROUND}-tasks.md" \
  --yolo -o text > .context/impl/${ROUND}-gemini.log 2>/dev/null &

Use --yolo when Gemini needs to write files. Without it, Gemini prompts for approval and hangs in background.

Step 4: Guide User (NO MONITORING)

IMPORTANT: Don't poll for completion. Output this guide:

## Agents Running (${ROUND})

| Agent  | Output |
|--------|--------|
| Claude | .context/impl/${ROUND}-claude.md |
| Codex  | .context/impl/${ROUND}-codex.md |
| Gemini | .context/impl/${ROUND}-gemini.md |

Check results manually:
- `ls .context/impl/${ROUND}-*.md`
- `git status`

When done, ask me to "확인해줘" or "빌드 체크"

Token Efficiency

1. Input: Write task instructions to .md file, pass path only
2. Output: Agents save structured markdown summaries
3. Verify: Read summaries only, not full output

See references/token-efficiency.md for details.

Output Structure

.context/impl/
├── R01-tasks.md              # Round 1: task decomposition
├── R01-claude.md             # Round 1: Claude implementation notes
├── R01-codex.md              # Round 1: Codex implementation notes
├── R01-gemini.md             # Round 1: Gemini test/review notes
├── R01-summary.md            # Round 1: merged summary
├── R02-tasks.md              # Round 2: follow-up tasks
├── R02-claude.md
└── R02-summary.md

Best Practices

DO:

• Use markdown files for task instructions
• Respect dependency order (migration → models → handlers)
• Let user check completion manually

DON'T:

• Poll TaskOutput repeatedly (token waste)
• Run 10+ agents simultaneously
• Have multiple agents edit same file

References

• Provider setup & CLI install
• Agent prompt templates
• Wave execution strategy
• Token efficiency patterns