executing

Forge: Executing

Overview

Execute the plan in the session directory batch-by-batch. For parallel batches, use git worktrees and dispatch multiple implementer agents simultaneously via the Task tool. Every completed task gets reviewed. Progress is tracked via TodoWrite and by updating task statuses in the plan file.

You MUST have a valid `$SESSION_DIR/plan.md` before executing. If the file doesn't exist or is empty, tell the user to run `forge plan ` first and STOP.

Session

Session Resolution

1. From $ARGUMENTS: If the first token is a number or short identifier, use it as the session ID.
2. Auto-detect existing sessions:

   ls .forge/sessions/ 2>/dev/null | sort
   

   • 0 sessions → error: "No forge sessions found. Run forge brainstorm or forge plan first."
   • 1 session → use it automatically; print "Using session <id>"
   • 2+ sessions → list them with plan titles (first line of each plan.md), AskQuestion "Which session to execute?"

SESSION_DIR = .forge/sessions/<id>/ — all file paths in this skill are relative to this directory.

Git namespace: All git branches and tags for this session use the prefix s<id>:

• Branches: forge/s<id>/batch-<N>-<timestamp>
• Checkpoint tags: forge/checkpoint/s<id>/batch-<N>-pre-merge

Process

1. Validate the Plan

Run the validating skill (same logic as forge validate), passing the session ID. This checks:

• Plan structure, DAG validity, file conflicts, batch consistency
• File existence on disk
• Git working tree cleanliness
• Stale worktrees/branches from previous runs of THIS session

If verdict is NOT READY, report all errors and STOP. Do not attempt to fix the plan — tell the user to run forge plan <id> to fix it, or forge abort <id> to clean up stale state.

2. Set Up Tracking

Create a TodoWrite entry for each task that is not already done:

For each task Tn with status != done:
  TodoWrite entry: "[s<id>] Tn: <task title>" with status pending

2.5. Read Plan Hooks (optional)

Check if $SESSION_DIR/plan.md has a ## Hooks section. If present, parse the hook commands:

• pre-batch: shell command to run before each batch starts
• post-batch: shell command to run after each batch completes (after merge + cleanup)
• post-execute: shell command to run after all batches complete (before final summary)

All hooks are advisory — if a hook command fails (non-zero exit), emit a warning but continue execution. Do NOT stop the forge run because of a hook failure.

3. Execute Batch by Batch

Process batches in order (Batch 1, then Batch 2, etc.). For each batch:

3a. Skip Completed Batches

If ALL tasks in a batch are already done, skip the entire batch.

3b. Check for Blocked Tasks

If any task in this batch depends on a failed task, mark it as blocked in the plan and skip it.

3b.5. Run pre-batch Hook

If a pre-batch hook was defined, run it now. If it fails, warn and continue.

3c. Parallel Batch (strategy = parallel, >1 task)

Set up worktree:

TIMESTAMP=$(date +%s)
SESSION_ID=<id>
BATCH_NUM=<current batch number>
BRANCH="forge/s${SESSION_ID}/batch-${BATCH_NUM}-${TIMESTAMP}"
WORKTREE_PATH="$SESSION_DIR/worktrees/batch-${BATCH_NUM}"

mkdir -p "$SESSION_DIR/worktrees"
git worktree add "$WORKTREE_PATH" -b "$BRANCH"

If worktree creation fails, emit a visible warning: "⚠️ Worktree creation failed for batch N — falling back to sequential execution. This batch will be slower but still works." Then fall back to sequential execution for this batch.

Generate interface contract (before dispatching):

For parallel batches, create a contract file that formalizes the imports/exports between sibling tasks:

mkdir -p "$SESSION_DIR/contracts"

Write $SESSION_DIR/contracts/batch-N.json:

{
  "batch": N,
  "session": "<id>",
  "tasks": {
    "T1": {
      "exports": { "ExportName": { "path": "src/file.ts", "type": "named" } },
      "imports": {}
    },
    "T2": {
      "exports": { "OtherExport": { "path": "src/other.ts", "type": "named" } },
      "imports": { "ExportName": { "from": "T1", "path": "src/file.ts" } }
    }
  }
}

The contract is derived from the plan's task descriptions (analyze which tasks create exports that other tasks in the same batch reference). Pass the contract file path in each implementer prompt so agents can read it.

Dispatch implementer agents in parallel:

Send a SINGLE message with multiple Task tool calls — this is what makes them parallel.

Model selection by complexity: Use model: "haiku" for tasks marked low complexity, omit (inherit) for medium/high.

Task(
  subagent_type="general-purpose",
  model="haiku",  // for low complexity — omit for medium/high
  description="Implement T1: <title>",
  prompt="<implementer prompt for T1 — see Implementer Prompt Template below>"
)
Task(
  subagent_type="general-purpose",
  description="Implement T2: <title>",
  prompt="<implementer prompt for T2>"
)
// ... up to 4 tasks max

CRITICAL: All Task calls for a parallel batch MUST be in a single message to achieve actual parallelism.

After all tasks complete:

For each completed task, run a reviewer (see Review step below).

Checkpoint before merge:

Before merging a batch, create a checkpoint tag:

git tag "forge/checkpoint/s${SESSION_ID}/batch-${BATCH_NUM}-pre-merge"

Dry-run merge (conflict pre-check):

Before the actual merge, run a dry-run to detect conflicts early:

git merge --no-commit --no-ff "$BRANCH"
MERGE_EXIT=$?
git merge --abort 2>/dev/null  # always clean up the dry-run

If MERGE_EXIT is non-zero, merge conflicts exist. STOP immediately, show the conflicting files (git diff --name-only --diff-filter=U), and ask the user how to proceed. Do NOT attempt the real merge.

Merge and clean up (only if dry-run passed):

# Back in main working directory
git merge "$BRANCH" --no-edit

# Clean up
git worktree remove "$WORKTREE_PATH" --force
git branch -d "$BRANCH"

Run post-batch hook (if defined). If it fails, warn and continue.

Compact batch context:

After completing a parallel batch (all tasks reviewed, statuses updated, merge done), write a compact summary and discard verbose output:

## Batch N Summary (session <id>)
- T1: done | T2: done | T3: failed (retry exhausted)
- Merge: clean | Worktree: cleaned up

Only retain this summary going forward — do NOT keep full implementer reports, reviewer feedback, or diff output in your working memory. The plan.md file has the authoritative task statuses.

3d. Sequential Batch (strategy = sequential, or single task)

Checkpoint before batch:

git tag "forge/checkpoint/s${SESSION_ID}/batch-${BATCH_NUM}-pre-merge"

For each task in the batch, one at a time:

1. Update task status to in-progress in $SESSION_DIR/plan.md
2. Update TodoWrite to in_progress
3. Non-blocking: load linear-sync → Operation B (update issue to In Progress)
4. Dispatch implementer:

   Task(
     subagent_type="general-purpose",
     description="Implement Tn: <title>",
     prompt="<implementer prompt>"
   )
   

5. When done, run reviewer (see Review step)
6. Update status based on review result

After all tasks in a sequential batch complete: run post-batch hook (if defined), then compact batch context (same as parallel — write summary, discard verbose output).

4. Review Every Task

After each task completes (whether from parallel or sequential execution):

Task(
  subagent_type="general-purpose",
  description="Review Tn: <title>",
  prompt="<reviewer prompt — see Reviewer Prompt Template below>"
)

Based on review result:

• approved: Update task status to done in plan, mark TodoWrite as completed. Then (non-blocking): load linear-sync → Operation B (update issue to Done + add summary comment); load notion-sync → Operation D (live-update plan page).
• needs-changes: Retry the task ONCE (max 1 retry, no exceptions) with the reviewer's feedback appended to the implementer prompt. If the retry also fails review, mark the task as failed immediately — do NOT retry again.

5. Handle Failures

When a task fails (implementation error or failed review after retry):

1. Mark the task as failed in $SESSION_DIR/plan.md
2. Find all tasks that depend on this task (transitively)
3. Mark them as blocked in the plan
4. Non-blocking: load linear-sync → Operation B (update issue to Cancelled + add failure comment); load notion-sync → Operation D (live-update plan page with failed status)
5. Continue executing remaining batches that have no blocked tasks
6. Do NOT stop the entire execution — independent batches should still run

6. Final Summary

Run post-execute hook (if defined) before presenting the summary. If it fails, warn and include the failure in the summary.

After all batches are processed, present:

## Forge Execution Complete (session <id>)

| Status | Count |
|--------|-------|
| Done   | X     |
| Failed | Y     |
| Blocked| Z     |

### Failures
- T5: <title> — failed on first attempt: <reason>
- T9: <title> — failed after retry: original feedback was "<reviewer feedback>", retry still failed: <reason>

### Blocked (due to failures)
- T8: <title> — blocked by T5

### Hook Results (if any hooks were defined)
- post-batch: ran N times, M failures
- post-execute: <pass | fail: reason>

Distinguish first-attempt failures from retry failures in the summary — this helps diagnose whether reviewer feedback is actionable.

Implementer Prompt Template

You are a forge implementer agent. Execute exactly ONE task and nothing more.

## Your Task
**ID**: T<n>
**Title**: <title>
**Description**: <description from plan>

## Files to Modify
<list of files from task>

## Working Directory
<repo root or worktree path>

## Batch Context (parallel tasks in this batch)
<ONLY include this section for parallel batches with >1 task. Omit for sequential/single tasks.>

This batch runs these tasks IN PARALLEL. You are T<n>.
- **T<a>**: <title> → Files: <files>
  Description: <brief description of what this task creates/exports>
- **T<n>**: <title> ← THIS IS YOUR TASK
- **T<c>**: <title> → Files: <files>
  Description: <brief description of what this task creates/exports>

### Interface Contract
Read the contract file at `$SESSION_DIR/contracts/batch-N.json` for the formal export/import agreement between tasks in this batch. Your exports MUST match what the contract specifies.

### Coordination Notes
<List any imports/exports between sibling tasks. For example:>
- T<a> will export `FooSchema` from `src/schemas/foo.ts` — you may reference this in your imports
- T<c> will export `FooRepository` from `src/repos/foo-repo.ts` — you may reference this in your imports
- Do NOT modify files owned by sibling tasks

## Rules
- Implement EXACTLY what the task description says — nothing more, nothing less
- ONLY modify files listed above — do not touch other files
- Do NOT modify files owned by sibling tasks in this batch
- Run typecheck/lint after changes if the project has them configured
- Do NOT make "bonus" improvements or refactoring
- Do NOT add comments explaining what you changed
- If you encounter an unexpected issue, report it clearly — do not work around it silently
- When importing from a sibling task's file, use the exact export names described in the Batch Context

## Report
When done, summarize:
1. What files were changed
2. What was done (brief)
3. Any issues encountered
4. Any exports you created that sibling tasks might reference

Reviewer Prompt Template

You are a forge reviewer agent. Review the implementation of ONE task.

## Task
**ID**: T<n>
**Title**: <title>
**Description**: <description from plan>
**Expected Files**: <list of files>

## Batch Context
<ONLY include this section for tasks from parallel batches. Omit for sequential/single tasks.>

This task ran in parallel with:
- **T<a>**: <title> → Files: <files> — exports: <what it exports>
- **T<c>**: <title> → Files: <files> — exports: <what it exports>

**Contract file**: `$SESSION_DIR/contracts/batch-N.json` — verify exports match the contract

## Review Checklist
1. Does the implementation match the task description?
2. Were ONLY the specified files modified? (run `git diff --name-only` to check)
2b. **Plan-drift check**: Compare the output of `git diff --name-only` against the Expected Files list above. If ANY file appears in the diff that is NOT in the expected list, return NEEDS-CHANGES with: "Plan drift: file `<path>` was modified but not listed in task. Either revert the change or update the task's file list."
3. Are there obvious bugs, typos, or logic errors?
4. Does the code follow the project's existing patterns and conventions?
5. If typecheck/lint was available, did it pass?
6. **Batch compatibility** (if parallel): Are imports/exports compatible with sibling tasks? Are there naming conflicts with parallel tasks?

## Verdict
Respond with exactly one of:
- **APPROVED** — implementation is correct and complete
- **NEEDS-CHANGES** — followed by specific, actionable feedback on what to fix

Do NOT suggest improvements beyond what the task requires.
Do NOT nitpick style if it matches the existing codebase.

Resuming Execution

If forge execute <id> is called and $SESSION_DIR/plan.md already has some tasks marked as done:

• Skip completed tasks and batches
• Resume from the first batch with pending tasks
• This makes execution idempotent — you can re-run after a failure

Rules

• NEVER execute without a valid plan file
• NEVER auto-resolve merge conflicts — always ask the user
• NEVER exceed 4 parallel tasks per batch
• ALWAYS review every task, regardless of complexity
• ALWAYS update plan status after each task
• ALWAYS clean up worktrees, even on failure
• Plan markdown is the state — if it says done, trust it