planning

Forge: Planning

Overview

Transform a brainstorm (or direct input) into an executable, dependency-aware task plan. The plan is written to the session directory — this file IS the single source of truth for execution.

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 → create a new session (ID: 1), then mkdir -p .forge/sessions/1/
   • 1 session → use it automatically; print "Using session <id>"
   • 2+ sessions → list them with their brainstorm/plan titles, AskQuestion "Which session?"

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

Input Sources (in priority order)

1. Existing brainstorm: Read $SESSION_DIR/brainstorm.md if it exists
2. Existing plan (re-planning): Read $SESSION_DIR/plan.md if it exists and modify it
3. Linear issues: If .forge/config.json has a linear key and no brainstorm exists → offer to import Linear issues (AskQuestion: "Linear-Issues als Tasks importieren?" → "Ja" / "Nein, direkt eingeben"). If yes, load linear-sync → Operation C.
4. Direct input: Use the user's inline description from the command arguments

If the input is ambiguous or underspecified, ask clarifying questions using AskQuestion before proceeding. Do NOT guess at requirements.

Process

1. Gather Context

• Read input source (brainstorm.md, existing plan, or user input)
• If the input is vague or missing critical details, ask clarifying questions:
  • What exactly should change?
  • What files are involved?
  • Are there constraints or preferences?
• Explore the codebase using the Explore agent (Task with subagent_type="Explore"):
  • Verify files mentioned in the brainstorm actually exist
  • Understand current code structure and patterns
  • Identify hidden dependencies (imports, shared types, etc.)

1.5. Research (Optional)

After gathering codebase context, assess whether external research would help with technical decisions:

• Do tasks involve libraries/APIs we need to look up?
• Are there implementation patterns we should follow?
• Do we need version-specific API details for accurate task descriptions?

If yes, ask the user using AskQuestion:

• Question: "Brauchen wir Research für die technischen Details? (API-Docs, Patterns, etc.)"
• Options: "Ja, recherchiere zu " / "Nein, reicht so"

If the user says yes:

1. Load and follow the research skill instructions (pass the same session ID)
2. Research findings are saved to $SESSION_DIR/research.md
3. Use findings to write more precise task descriptions (e.g., exact API calls, correct config keys)
4. Reference $SESSION_DIR/research.md in task descriptions where relevant

If $SESSION_DIR/research.md already exists (from brainstorming), read it and use its findings — don't re-research the same topics.

2. Decompose into Tasks

Break the work into bite-sized tasks. Each task should:

• Take 2-5 minutes to implement
• Touch a small, well-defined set of files
• Have a clear, specific description (implementable without additional context)
• Be independently verifiable

Task sizing rules:

• If a task touches more than 3 files → split it
• If a task description is longer than 3 sentences → split it
• If a task has both "create" and "integrate" steps → split into two tasks

2.5. Completeness Check

After decomposing, verify the task list is complete. Run through this checklist and add missing tasks automatically:

Backend Wiring (if applicable — check if the project has routes/, handlers/, controllers/, middleware/, or similar):

• API route/endpoint registered?
• Handler/Controller created?
• Middleware integrated (auth, validation, etc.)?
• DB schema/migration present?
• Service layer wired up?

Tests (if applicable — check if the project has a test framework: vitest, jest, playwright, etc.):

• Unit tests for new functions/classes?
• Integration tests for service interactions?
• E2E tests (Playwright) for user-facing flows?

How to determine "if applicable":

• Check if the project has a test framework (vitest, jest, playwright, etc.) — if not, skip test tasks
• Check if the project has backend patterns (routes/, handlers/, controllers/, middleware/) — if not, skip wiring tasks
• Check if the project has DB patterns (schema/, migrations/, models/) — if not, skip DB tasks
• Do NOT create framework setup tasks — only add tasks for patterns that already exist in the project

Missing tasks are auto-added. Test tasks always depend on the implementation tasks they test. Wiring tasks depend on the implementation tasks they wire up.

3. Build the Dependency Graph

For each task, determine what it depends on:

• No dependency: Can run in the first batch
• Data dependency: Task B needs output/changes from Task A (e.g., B imports a type created by A)
• File dependency: Task B modifies a file that Task A also modifies → they CANNOT be parallel

Validation rules:

• Dependencies must form a DAG (directed acyclic graph) — no cycles allowed
• If you detect a cycle, restructure the tasks to eliminate it
• Every task must be reachable from the root (no orphans)

4. Group into Execution Batches

Apply topological sort to create batches:

• Batch 1: All tasks with no dependencies
• Batch N: Tasks whose ALL dependencies are in batches < N

Within each batch, determine the execution strategy:

• parallel: Tasks in this batch touch different files → can run simultaneously
• sequential: Tasks touch overlapping files → must run one at a time

Conflict detection: Two tasks conflict if they share ANY file in their file lists. Conflicting tasks must be in different batches or marked sequential.

Max parallel cap: No more than 4 tasks per parallel batch (to avoid context explosion).

5. Identify Critical Path

The critical path is the longest chain of dependent tasks through the batch structure. Report it so the user knows the minimum number of batches required.

6. Write the Plan

Save to $SESSION_DIR/plan.md:

# Plan: <title>

## Summary
<1-2 sentence overview of what this plan accomplishes>

## Tasks

### T1: <short descriptive title>
- **Status**: pending
- **Category**: implementation | wiring | test:unit | test:integration | test:e2e
- **Depends on**: none
- **Files**: `path/to/file.ts`, `path/to/other.ts`
- **Complexity**: low | medium | high
- **Description**: <specific instructions — what to create/change/delete, enough detail to implement without additional context>

### T2: <short descriptive title>
- **Status**: pending
- **Category**: implementation
- **Depends on**: none
- **Files**: `path/to/another.ts`
- **Complexity**: low
- **Description**: <specific instructions>

### T3: <short descriptive title>
- **Status**: pending
- **Category**: wiring
- **Depends on**: T1, T2
- **Files**: `path/to/combined.ts`
- **Complexity**: medium
- **Description**: <specific instructions>

## Execution Batches

| Batch | Tasks | Strategy | Worktree |
|-------|-------|----------|----------|
| 1 | T1, T2 | parallel | forge/s<id>/batch-1-* |
| 2 | T3 | sequential | main |

## Critical Path
T1 → T3 (2 batches)

## Notes
- <caveats, risks, assumptions>

## Hooks (optional)
- pre-batch: <shell command to run before each batch, e.g., `pnpm build`>
- post-batch: <shell command to run after each batch, e.g., `pnpm test --run`>
- post-execute: <shell command to run after all batches, e.g., `pnpm typecheck`>

6.5. Integration Sync (if configured)

After writing $SESSION_DIR/plan.md, check .forge/config.json and run syncs in parallel (both are non-blocking):

Notion (if notion key in config):

• Load notion-sync → Operation B (Push Plan to Notion)
• Stores planPageId in $SESSION_DIR/integration.json

Linear (if linear key in config):

• Load linear-sync → Operation A (Create Issues from Plan)
• Creates one Linear issue per task, stores issueIds in $SESSION_DIR/integration.json

If either fails, warn and continue.

7. Present to User

After writing the plan, show a summary:

• Total tasks and batch count
• Critical path length
• Any risks or assumptions
• If Linear sync ran: show number of created issues + project link
• If Notion sync ran: show Notion page link
• Ask the user to review $SESSION_DIR/plan.md and confirm or request changes
• Remind them: run forge execute <id> to start execution

Re-Planning Mode

When $SESSION_DIR/plan.md already exists:

1. Read the existing plan
2. Show the user what exists (summary + task statuses)
3. Ask what they want to change (AskQuestion with options like: add tasks, remove tasks, reorder, start fresh)
4. Modify the plan accordingly
5. Recalculate batches and critical path
6. Preserve status of already-completed tasks (don't reset done tasks)

Rules

• Tasks MUST be bite-sized (2-5 minutes each)
• Every task MUST list exact files it touches
• Every task MUST have a Category (implementation, wiring, test:unit, test:integration, test:e2e)
• No two parallel tasks may share a file
• Dependencies MUST form a DAG
• Max 4 tasks per parallel batch
• Plan markdown IS the state — no sidecar files
• If input is ambiguous → ask, don't guess
• Completed tasks in re-planning → preserve their status
• Backend wiring tasks (routes, handlers, middleware, DB) MUST be included if the project has these patterns
• Test tasks MUST be included if the project has a test framework — unit, integration, and E2E (Playwright) as applicable
• Test tasks always depend on the implementation tasks they test
• Do NOT create framework/tooling setup tasks — only plan tasks for patterns already present in the project
• NEVER plan tasks that produce fake data, stubs, mocks, or placeholder implementations in production code — every task must produce real, working code. If a dependency isn't available yet, make it a dependency in the plan rather than stubbing it out. Tests are always required and may use standard test utilities (mocks, fixtures, test doubles) as appropriate