Skip to main content

Agent-Driven Planning & Implementation Workflow

A guide to using Claude Code as a coordinator for parallel planning, review, and implementation of engineering tasks — based on a real session that produced 9 approved plans, 3 PRs (1 merged), and ~500 lines of dead code removed across the Shopify integration platform.

Overview​

The workflow turns a list of tasks into reviewed, approved implementation plans and PRs with minimal human supervision. The human steers scope and architecture; agents handle investigation, planning, review iteration, implementation, and PR feedback loops.

Tasks (CSV/list)
  |
  v
Planning Agents (parallel) --> .md plan files
  |
  v
Review Agents (independent) --> APPROVED or CHANGES REQUESTED
  |                                    |
  v                                    v
Human Feedback (optional)       Revision Agents --> re-review
  |
  v
Implementation Agents (worktree) --> PR
  |
  v
PR Review Loop Agent (autonomous) --> iterate until approved

Step 1: Define the Work​

Start with a clear list of tasks. Can be a CSV, a list of tickets, or just a conversation.

I have a bunch of tasks. Here's the list:
1. Fix race condition on settings saves (High)
2. Add staging/prod gating (High)
3. Generalize Vue customization (Medium)
...

All except #6 which I'm working on.

Key inputs:

  • Task title and brief description
  • Priority (helps order planning and implementation)
  • Exclusions (what you're already working on, what's out of scope)
  • Target repo and any architectural context

Step 2: Launch Planning Agents​

Planning agents investigate the codebase and write detailed implementation plans as .md files.

Prompt pattern for the coordinator:

Start background agents to investigate and plan changes for each item.
Have them output .md files to a common plans/ directory.

What each planning agent does:

  1. Reads CLAUDE.md / AGENTS.md for project conventions
  2. Explores the codebase — finds relevant files, traces data flows, reads models
  3. Identifies the current architecture and root cause
  4. Designs a solution with specific code changes (files, functions, line numbers)
  5. Writes the plan to plans/<number>-<slug>.md

Parallelism: Launch 3-4 planning agents simultaneously. They explore different parts of the codebase so they don't conflict.

Plan structure:

# Task Title
## Problem Statement
## Current Architecture (files, models, endpoints involved)
## Root Cause Analysis
## Proposed Solution
### Phase 1: Backend Changes
### Phase 2: Frontend Changes
## Backward Compatibility
## Testing Strategy
## Risks and Edge Cases
## Implementation Order
## Files to Change (Summary Table)

Step 3: Automated Review Loop​

Once a plan lands, spin up a review agent with fresh context (no knowledge of the planning process). This is critical — the reviewer must evaluate independently.

Review agent prompt pattern:

You are reviewing an implementation plan. Read the plan at plans/<file>.md.
Read the actual source files referenced to verify claims are accurate.
Evaluate: accuracy, feasibility, completeness, risks, proportionality.
Output: "APPROVED" or "CHANGES REQUESTED" with specific, actionable feedback.
Do NOT modify any files.

What reviewers check:

  • Are file paths, line numbers, and architecture claims correct?
  • Are there missing steps or overlooked dependencies?
  • Are there unaddressed risks or edge cases?
  • Is the solution over/under-engineered for the problem?
  • Does it follow project conventions (CLAUDE.md)?

If CHANGES REQUESTED: Spin up a revision agent with the specific feedback, then send the revised plan to a fresh reviewer. Never give the reviewer context that it reviewed before — it must evaluate independently each time.

Typical iteration: Plans go through 2-4 review rounds. Early rounds catch architectural issues; later rounds are precision fixes (line numbers, naming, edge cases).

Step 4: Human Steering​

The human provides architectural feedback between review rounds when needed:

  • Scope corrections: "The UI Customization page in admin_ui is deprecated. Retarget to storefront_admin."
  • Design direction: "We need a plugin system for ProductCard, not individual config extractions."
  • Cross-plan dependencies: "Plan #5 must assume #3 and #4 are merged first."
  • Domain knowledge: "We don't use KV for UI settings — they go through Shopify metafields."

When to intervene:

  • When agents make wrong assumptions about the system
  • When you want a different architectural approach
  • When tasks have dependencies the agents don't know about
  • When code is deprecated/dead and agents plan around it

When NOT to intervene:

  • Line number accuracy, naming consistency, edge case coverage — let the review loop handle these

Step 5: Implementation​

Once a plan is approved, spin up an implementation agent in a git worktree (isolated branch, doesn't conflict with your work).

Implementation agent prompt pattern:

You are implementing an approved plan. Work in the worktree at <path>.
Read the plan at plans/<file>.md. Follow it precisely.
Read CLAUDE.md for project conventions.
Implementation order: [list from plan]
After: commit, push, create PR with gh pr create.

Key rules for implementation agents:

  • Follow the plan precisely — it's been through multiple review rounds
  • Make atomic commits (one per phase if multi-phase)
  • Run linting and tests
  • Don't add features not in the plan
  • Don't skip steps

Step 6: PR Review Loop​

After the PR is created, spin up an autonomous agent that polls for reviewer feedback and iterates.

PR review loop prompt pattern:

You are managing a PR review loop for PR #<number>.
Poll for comments every 3 minutes.
Read comments, make fixes, push, repeat.
Stop when approved or after N rounds.

What the loop agent does:

  1. Checks gh pr view <N> --json reviews,comments
  2. Reads inline comments from gh api repos/.../pulls/<N>/comments
  3. Makes requested fixes in the worktree
  4. Runs linting/tests
  5. Commits, pushes
  6. Waits, checks again

Guidelines & Lessons Learned​

Planning​

  • Back up plans — they're unstaged local files. Copy to a safe location outside the repo.
  • Include the plan in the PR when implementing (copy to docs/plans/) so reviewers understand the rationale.
  • Cross-reference dependencies — if Plan #4 depends on Plan #3, the plan must explicitly list every class, method, and field from #3 that must exist.
  • Gate plans on prerequisites — "Plan #18 is gated on #1 and #17 being approved" prevents planning around deprecated features.

Review​

  • Never give reviewers prior context — each review round must be independent. This prevents confirmation bias.
  • Reviewers should read source files — a plan that claims "ShopifySettings has no version field" must be verified by reading the actual model.
  • Let reviews be thorough — some plans went through 7 rounds. Each round caught real issues (DDB stream mismatches, backward-compat breaks, security gaps, type mismatches).
  • Direct owner feedback skips the review loop — if you tell the agent "selectors are deprecated," that's authoritative. No need to re-review.

Implementation​

  • Use worktrees — each implementation gets its own branch in an isolated worktree. Doesn't conflict with your work or other agents.
  • Fix CI issues immediately — a failing test or deployment issue should be fixed by an agent, not deferred.
  • Address ALL review comments — even on approved PRs, open comments should be resolved before merging.

Architecture​

  • Challenge agent assumptions — agents will propose solutions based on incomplete understanding. Push back when they miss the real architecture ("KV is not used for UI settings").
  • Demand proper solutions — never accept quick fixes that hide problems. If something needs an IAM change, say so. If CloudFormation can't handle a resource lifecycle, find the right CDK pattern.
  • Think about all environments — a fix that works on redeploy but breaks first deploy (or vice versa) isn't a fix.

Coordination​

  • The coordinator (Claude) tracks everything — maintains a status table, processes review verdicts, launches revision/review agents, handles dependencies.
  • Parallel is default — launch multiple planning agents, review agents, or even implementations simultaneously when they don't conflict.
  • Human interrupts are normal — the coordinator should handle "stop everything," scope changes, and priority shifts gracefully.

Example Status Table​

The coordinator maintains a live tracker:

| # | Task                  | Priority | Plan         | Implementation          |
|---|-----------------------|----------|--------------|-------------------------|
| 3 | Race condition fix    | High     | Approved     | PR #2897 — APPROVED     |
| 5 | Staging/prod gating   | High     | Approved     | —                       |
| 1 | Generalize Vue        | Medium   | Approved     | —                       |
| 9 | Better CSS editor     | Low      | Approved     | PR #2896 — MERGED       |
| 17| Dead code cleanup     | Low      | Approved     | PR #2903 — APPROVED     |

Scaling​

This workflow scales to any number of tasks. The bottleneck is human attention for architectural steering, not agent capacity. In practice:

  • 9 tasks planned, reviewed, and approved in one session
  • ~50 agent runs across planning, review, revision, implementation, and PR loops
  • 3 PRs raised, reviewed, and approved (1 merged)
  • Human input was architectural direction, scope corrections, and domain knowledge — not line-by-line code review

The agents handle the grunt work (codebase exploration, plan writing, cross-referencing source files, running tests, addressing PR comments). The human handles the judgment calls (is this the right architecture? is this in scope? does this match how we actually deploy?).

Reusable Skill Prompts​

The five patterns below were used 30+ times across this session with nearly identical structure. They can be turned into Claude Code skills (.claude/skills/) for reuse.

1. /plan-task — Investigate & Write a Plan​

When to use: Starting a new task. Produces a .md plan file.

Inputs: Task number, title, description, scope constraints.

You are investigating a codebase and writing an implementation plan.
The repo is at <REPO_PATH>.

**Task**: "<TASK_TITLE>" — <TASK_DESCRIPTION>

**Scope**: <ANY_CONSTRAINTS — e.g. "scoped to components/shopify/ only">

**What to do**:
1. Read `CLAUDE.md` / `AGENTS.md` for project conventions.
2. Find the relevant code — trace data flows, read models, identify
   all files involved in the current behavior.
3. Understand the current architecture and root cause (if it's a bug).
4. Design a solution with specific code changes (files, functions,
   what to add/modify, line numbers where helpful).
5. Consider: backward compatibility, migration path, edge cases.

**Output**: Write a detailed implementation plan to
`<REPO_PATH>/plans/<NUMBER>-<SLUG>.md` with:
- Current architecture (files, models, endpoints involved)
- Root cause analysis (if applicable)
- Proposed solution with specific code changes
- Backward compatibility strategy
- Testing strategy (unit, integration, manual checklist)
- Risks and edge cases
- Implementation order
- Files to change (summary table)

Do NOT make any code changes. Only investigate and write the plan file.

2. /review-plan — Independent Plan Review​

When to use: After a plan is written. The reviewer must have NO prior context about the planning process — it evaluates independently.

Inputs: Plan file path, task description.

You are reviewing an implementation plan for a codebase change.
The repo is at <REPO_PATH>.

**Task being planned**: "<TASK_TITLE>" — <BRIEF_DESCRIPTION>

**Your job**:
1. Read the plan at `<PLAN_FILE_PATH>`
2. Read the actual source files referenced in the plan to verify
   the claims about current architecture are accurate.
3. Evaluate the plan on:
   - **Accuracy**: Does the plan correctly describe the current
     codebase? Are file paths, component names, and architecture
     claims correct?
   - **Feasibility**: Is the proposed solution technically sound?
     Will it work with the existing stack?
   - **Completeness**: Are there missing steps, overlooked
     dependencies, or gaps in the migration path?
   - **Risks**: Are there unaddressed risks or edge cases?
   - **Proportionality**: Is the solution appropriately scoped for
     the problem, or is it over/under-engineered?

**Output your verdict**:
- If the plan is solid and ready for implementation, write
  "APPROVED" at the top, followed by a brief summary of strengths.
- If the plan needs changes, write "CHANGES REQUESTED" at the top,
  followed by specific, actionable feedback on what to fix. Be
  concrete — cite files, line numbers, and specific issues.

Do NOT modify any files. Only read and evaluate.

3. /revise-plan — Apply Reviewer Feedback​

When to use: After a review returns CHANGES REQUESTED. The revision agent reads the feedback and updates the plan.

Inputs: Plan file path, numbered list of reviewer issues.

You are revising an implementation plan based on reviewer feedback.
The repo is at <REPO_PATH>.

**Task**: "<TASK_TITLE>"

**Current plan**: Read `<PLAN_FILE_PATH>`

**Reviewer feedback — <N> required changes**:

1. **<ISSUE_TITLE>** — <DESCRIPTION_OF_WHAT_TO_FIX>
2. **<ISSUE_TITLE>** — <DESCRIPTION_OF_WHAT_TO_FIX>
...

**What to do**:
1. Read the current plan
2. Read the relevant source files to understand the reviewer's points
3. Revise the plan addressing all <N> issues
4. Write the updated plan back to the same file: `<PLAN_FILE_PATH>`

Keep the plan's existing structure and strengths. Only change what
the reviewer flagged.

4. /implement-plan — Worktree Implementation + PR​

When to use: After a plan is approved. Creates a worktree, implements, and raises a PR.

Inputs: Plan file path, branch name.

Prerequisites: Run git worktree add -b <BRANCH> .claude/worktrees/<BRANCH> origin/main before invoking.

You are implementing an approved implementation plan. Work in the
worktree at: `<WORKTREE_PATH>`

**Task**: <TASK_TITLE>

**Plan**: Read the full approved plan at `<PLAN_FILE_PATH>`

**CLAUDE.md**: Read `<REPO_PATH>/CLAUDE.md` for project conventions.

**Implementation order**: [copy from plan]

**Rules**:
- Follow the plan precisely — it has been through multiple review rounds
- Follow CLAUDE.md conventions (fail fast, model everything, test everything)
- Run linting on changed files
- Run tests after each phase
- Make atomic commits with conventional commit messages

**After implementation**:
1. Commit all changes
2. Push the branch: `git push -u origin <BRANCH>`
3. Create a PR with `gh pr create` targeting `main`,
   title: `<CONVENTIONAL_COMMIT_TITLE>`,
   body summarizing the changes
4. Report the PR number when done

Do NOT skip any step from the plan. Do NOT add features not in the plan.

5. /pr-review-loop — Autonomous PR Iteration​

When to use: After a PR is created. Polls for reviewer feedback, fixes issues, and pushes until approved.

Inputs: PR number, worktree path.

You are autonomously managing a PR review loop.

**PR**: #<PR_NUMBER> in `<REPO_OWNER>/<REPO_NAME>`
**Branch**: `<BRANCH_NAME>`
**Worktree**: `<WORKTREE_PATH>`

**Your job**: Poll for reviewer feedback, fix issues, and push
until the PR is approved or you've done <MAX_ROUNDS> rounds.

**Loop**:
1. Get inline comments:
   `gh api repos/<OWNER>/<REPO>/pulls/<N>/comments \
     --jq '.[] | "[\(.created_at)] \(.user.login) \
     (line \(.line // .original_line) in \(.path)):\n\(.body)\n---"'`
2. Get review verdicts:
   `gh pr view <N> --repo <OWNER>/<REPO> --json reviews \
     --jq '.reviews[] | "\(.author.login) (\(.state)): \(.body)"'`
3. If latest review is APPROVED with no outstanding comments →
   report success and stop
4. If there are comments requesting changes:
   - Read the source files referenced
   - Check if current code already addresses the comment
   - If not, make the fix
   - Run linting on changed files
   - Commit with a descriptive message
   - Push: `git push`
5. Wait 3 minutes (`sleep 180`), then check again
6. Repeat up to <MAX_ROUNDS> rounds

**Context files if needed**:
- Plan: `<PLAN_FILE_PATH>`
- CLAUDE.md: `<REPO_PATH>/CLAUDE.md`

**When done**: Report final status — approved, changes still
pending, or max rounds reached.

Composing Skills into a Full Cycle​

For a single task, the full cycle is:

/plan-task "fix: race condition on settings saves" --scope "components/shopify/"
  ↓ (plan written)
/review-plan plans/03-race-condition-settings-save.md
  ↓ (CHANGES REQUESTED with 6 issues)
/revise-plan plans/03-race-condition-settings-save.md --feedback "1. Fix X, 2. Fix Y, ..."
  ↓ (plan revised)
/review-plan plans/03-race-condition-settings-save.md
  ↓ (APPROVED)
/implement-plan plans/03-race-condition-settings-save.md --branch fix/settings-race
  ↓ (PR #2897 created)
/pr-review-loop 2897 --worktree .claude/worktrees/fix-settings-race
  ↓ (iterate until approved)

The coordinator (Claude or human) orchestrates these in parallel across multiple tasks. The review→revise→review loop runs autonomously until approved; the human intervenes only for architectural steering.