@aion0/forge 0.5.25 → 0.5.26

package/.forge/worktrees/pipeline-ecd7cb0f/src/types/index.ts

@@ -0,0 +1,129 @@
+export type MemoryStrategy = 'none' | 'sliding_window' | 'full' | 'full_with_summary' | 'external';
+
+export type SessionStatus = 'running' | 'idle' | 'paused' | 'archived' | 'error';
+
+export type ProviderName = 'anthropic' | 'google' | 'openai' | 'grok';
+
+export interface ProviderConfig {
+  name: ProviderName;
+  displayName: string;
+  apiKey?: string;
+  defaultModel: string;
+  models: string[];
+  enabled: boolean;
+}
+
+export interface MemoryConfig {
+  strategy: MemoryStrategy;
+  windowSize?: number;       // for sliding_window
+  compressAfter?: number;    // for full — compress after N messages
+  summaryModel?: string;     // model to use for summarization
+}
+
+export interface SessionTemplate {
+  id: string;
+  name: string;
+  description: string;
+  provider: ProviderName;
+  model?: string;
+  fallbackProvider?: ProviderName;
+  memory: MemoryConfig;
+  systemPrompt: string;
+  context?: {
+    files?: string[];
+  };
+  commands?: Record<string, { description: string; action: string; prompt?: string }>;
+  ui?: {
+    icon?: string;
+    color?: string;
+    pinned?: boolean;
+  };
+}
+
+export interface Message {
+  id: number;
+  sessionId: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  provider: ProviderName;
+  model: string;
+  tokenCount?: number;
+  createdAt: string;
+}
+
+export interface Session {
+  id: string;
+  name: string;
+  templateId: string;
+  provider: ProviderName;
+  model: string;
+  status: SessionStatus;
+  memory: MemoryConfig;
+  systemPrompt: string;
+  messageCount: number;
+  createdAt: string;
+  updatedAt: string;
+  lastMessage?: string;
+}
+
+export interface UsageRecord {
+  provider: ProviderName;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+  date: string;
+}
+
+export type TaskStatus = 'queued' | 'running' | 'done' | 'failed' | 'cancelled';
+export type TaskMode = 'prompt' | 'monitor' | 'shell';
+
+export interface WatchConfig {
+  condition: 'change' | 'idle' | 'complete' | 'error' | 'keyword';
+  keyword?: string;          // for 'keyword' condition
+  idleMinutes?: number;      // for 'idle' condition (default 10)
+  action: 'notify' | 'message' | 'task';
+  actionPrompt?: string;     // message to send or task prompt
+  actionProject?: string;    // for 'task' action
+  repeat?: boolean;          // keep watching after trigger (default false)
+  notifyIntervalSeconds?: number; // min seconds between notifications (default 60)
+}
+
+export interface Task {
+  id: string;
+  projectName: string;
+  projectPath: string;
+  prompt: string;
+  mode: TaskMode;
+  status: TaskStatus;
+  priority: number;
+  conversationId?: string;
+  watchConfig?: WatchConfig;
+  log: TaskLogEntry[];
+  resultSummary?: string;
+  gitDiff?: string;
+  gitBranch?: string;
+  costUSD?: number;
+  error?: string;
+  createdAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  scheduledAt?: string;
+}
+
+export interface TaskLogEntry {
+  type: 'system' | 'assistant' | 'result';
+  subtype?: string;
+  content: string;
+  tool?: string;
+  timestamp: string;
+}
+
+export interface AppConfig {
+  dataDir: string;
+  providers: Record<ProviderName, ProviderConfig>;
+  server: {
+    host: string;
+    port: number;
+  };
+}

package/.forge/worktrees/pipeline-ecd7cb0f/start.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# start.sh — Start Forge locally (kill old processes, build, start)
+#
+# Usage:
+#   ./start.sh          # production mode
+#   ./start.sh dev      # dev mode (hot-reload)
+
+# Kill all old forge processes
+pkill -f 'telegram-standalone' 2>/dev/null
+pkill -f 'terminal-standalone' 2>/dev/null
+pkill -f 'workspace-standalone' 2>/dev/null
+pkill -f 'cloudflared tunnel' 2>/dev/null
+# Wait for workspace daemon port to be released
+for i in 1 2 3; do
+  lsof -ti:${WORKSPACE_PORT:-8405} >/dev/null 2>&1 || break
+  sleep 1
+done
+pkill -f 'next-server' 2>/dev/null
+pkill -f 'next start' 2>/dev/null
+pkill -f 'next dev' 2>/dev/null
+sleep 1
+
+export PORT=${PORT:-8403}
+export TERMINAL_PORT=${TERMINAL_PORT:-8404}
+export WORKSPACE_PORT=${WORKSPACE_PORT:-8405}
+
+if [ "$1" = "dev" ]; then
+  pnpm dev
+else
+  pnpm build && pnpm start
+fi

package/.forge/worktrees/pipeline-ecd7cb0f/templates/smith-lead.json

@@ -0,0 +1,45 @@
+{
+  "name": "Lead",
+  "icon": "👑",
+  "description": "Primary coordinator — SOP-driven requirement intake, delegation, gap coverage, and quality gate",
+  "config": {
+    "label": "Lead",
+    "icon": "👑",
+    "backend": "cli",
+    "agentId": "claude",
+    "primary": true,
+    "persistentSession": true,
+    "workDir": "./",
+    "outputs": ["docs/lead/"],
+    "plugins": ["playwright", "shell-command"],
+    "role": "You are the Lead — primary coordinator of this workspace.\n\nYour context automatically includes a \"Workspace Team\" section showing all agents, their roles, status, and missing standard roles. Read it before every action.\n\n## SOP: Requirement Intake\n\nWhen you receive a requirement (from user input or inbox message):\n\n```\n1. Read the Workspace Team section in your context\n2. Classify the requirement:\n   - Single task → one request document\n   - Multi-module → break into independent request documents, group in a batch\n3. Route based on available roles:\n\n   HAS Architect?\n   └─ YES → create_request with full description → Architect breaks it down further\n   └─ NO → you break it down yourself, then:\n\n        HAS Engineer?\n        └─ YES → create_request for each module (status: open)\n                 Engineers claim via claim_request\n        └─ NO → implement it yourself in src/\n                 Record files_changed in docs/lead/impl-notes.md\n\n4. After implementation (by you or Engineer):\n\n   HAS QA?\n   └─ YES → update_response(section: engineer) triggers auto-notify to QA\n   └─ NO → you test it:\n          - Read acceptance_criteria from the request\n          - Write tests in tests/ or run manually\n          - Record results: update_response(section: qa, result: passed/failed)\n\n5. After testing:\n\n   HAS Reviewer?\n   └─ YES → auto-notified when QA passes\n   └─ NO → you review it:\n          - Check code quality, security, PRD compliance\n          - Record: update_response(section: review, result: approved/changes_requested)\n          - If changes_requested → send_message to Engineer or fix yourself\n```\n\n## SOP: Monitoring & Coordination\n\nWhile work is in progress:\n\n```\n1. get_status → check all agents' smith/task status\n2. list_requests → check request progress\n\nIF agent taskStatus = failed:\n   → Read their error from get_status\n   → send_message asking what went wrong\n   → If no response or unfixable: handle the request yourself\n\nIF agent taskStatus = running for too long:\n   → send_message to check progress\n\nIF request stuck in one status:\n   → Check which agent should be handling it\n   → send_message to nudge, or cover it yourself\n\nIF multiple Engineers exist and request unclaimed:\n   → send_message to available Engineer suggesting they claim_request\n```\n\n## SOP: Quality Gate (before declaring done)\n\n```\n1. list_requests(batch: current_batch)\n2. ALL requests status = done?\n   └─ NO → identify stuck ones, apply Monitoring SOP\n   └─ YES → continue\n3. Any request with review.result = changes_requested?\n   └─ YES → verify changes were made, re-review if no Reviewer\n4. Any request with qa.result = failed?\n   └─ YES → verify fix was applied, re-test if no QA\n5. Write summary to docs/lead/delivery-summary.md:\n   - Requirements covered\n   - Requests created and their final status\n   - Roles you covered due to gaps\n   - Any open issues\n```\n\n## Gap Coverage Reference\n\nWhen you cover a missing role, follow that role's standards:\n\n| Missing Role | What You Do | Output |\n|---|---|---|\n| PM/Architect | Break requirements into modules with acceptance_criteria | request documents via create_request |\n| Engineer | Read request → implement in src/ → update_response(section: engineer) | source code + files_changed |\n| QA | Read acceptance_criteria → write/run tests → update_response(section: qa) | test results in tests/ or docs/qa/ |\n| Reviewer | Read code changes → check quality/security → update_response(section: review) | review findings |\n\n## Rules\n\n- Workspace Team is in your context — don't call get_agents redundantly at start, just read it\n- DO call get_agents/get_status when you need live status updates mid-task\n- Every delegated task MUST go through request documents (create_request) — never just send_message with vague instructions\n- Each request needs concrete acceptance_criteria that QA can verify\n- Do NOT duplicate work an active agent is already doing — check status first\n- When covering a gap, be thorough — don't half-do it just because it's not your \"main\" role",
+    "steps": [
+      {
+        "id": "intake",
+        "label": "Intake & Analyze",
+        "prompt": "Read the Workspace Team section in your context. Identify: (1) which standard roles are present and missing, (2) incoming requirements from upstream input or inbox. For each requirement, decide scope: single task or multi-module. List what you will delegate vs handle yourself."
+      },
+      {
+        "id": "delegate",
+        "label": "Create Requests & Route",
+        "prompt": "For each module/task: create_request with title, description, acceptance_criteria, and batch name. If Architect exists, create high-level requests for them to break down. If only Engineers exist, create implementation-ready requests. If no one to delegate to, note which requests you will implement yourself. Verify with list_requests that all were created."
+      },
+      {
+        "id": "cover-gaps",
+        "label": "Cover Missing Roles",
+        "prompt": "Handle all work for missing roles. If no Engineer: implement code, then update_response(section: engineer). If no QA: write/run tests against acceptance_criteria, then update_response(section: qa). If no Reviewer: review code changes for quality and security, then update_response(section: review). Use get_status between tasks to check if other agents have completed their work."
+      },
+      {
+        "id": "monitor",
+        "label": "Monitor & Unblock",
+        "prompt": "Run get_status and list_requests. For each stuck/failed agent: diagnose and send_message to unblock, or take over the request yourself. For unclaimed requests: nudge available agents. Continue until all requests show progress."
+      },
+      {
+        "id": "gate",
+        "label": "Quality Gate & Summary",
+        "prompt": "list_requests for the current batch. Verify ALL requests are status=done with review.result=approved and qa.result=passed. If any are not: apply gap coverage. Write docs/lead/delivery-summary.md with: requirements covered, request statuses, roles you covered, open issues."
+      }
+    ]
+  },
+  "exportedAt": 1743724800000
+}

package/.forge/worktrees/pipeline-ecd7cb0f/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    ".next/dev/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/RELEASE_NOTES.md

@@ -1,11 +1,36 @@
-# Forge v0.5.25
+# Forge v0.5.26
 
-Released: 2026-04-05
+Released: 2026-04-06
 
-## Changes since v0.5.24
+## Changes since v0.5.25
+
+### Features
+- feat: add review-mr as builtin pipeline
+- feat: all pipeline steps use worktree, no shell mode exception
+- feat: pipeline steps auto-use git worktree for isolated execution
 
 ### Bug Fixes
-- fix: replace @/src path alias with relative import in project-sessions.ts
+- fix: pipeline tasks use same model as normal tasks, no pipelineModel override
+- fix: task model selection — treat 'default' as fall-through
+- fix: ignore stdin + parse worktree field in pipeline nodes
+- fix: spawn claude without shell, resolve path via which
+- fix: remove shell: '/bin/zsh' from claude spawn to prevent arg interpretation
+- fix: all pipeline steps use worktree, shell gets env vars
+- fix: all pipeline steps use worktree, shell gets env vars
+- fix: shell/plugin pipeline steps skip worktree, run in project dir
+- fix: only auto-worktree for agent/prompt mode, not shell steps
+- fix: resolve rebase conflicts and fix anti-loop guard in messaging
+
+### Documentation
+- docs: update pipeline help with worktree env vars for shell steps
+
+### Other
+- try some fixes 2
+- try some fixes
+- daemon is exclusive writer of state.json
+- skip auth in dev mode
+- fix terminal copy/paste and selection
+- add noreply and inbox to workspace messaging
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.24...v0.5.25
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.25...v0.5.26

package/app/api/workspace/[id]/stream/route.ts

@@ -1,3 +1,6 @@
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
 const WORKSPACE_PORT = Number(process.env.WORKSPACE_PORT) || 8405;
 const DAEMON_URL = `http://localhost:${WORKSPACE_PORT}`;
 

package/app/api/workspace/route.ts

@@ -1,6 +1,5 @@
 import { NextResponse } from 'next/server';
-import { listWorkspaces, findWorkspaceByProject, loadWorkspace, saveWorkspace, deleteWorkspace } from '@/lib/workspace';
-import type { WorkspaceState } from '@/lib/workspace';
+import { listWorkspaces, findWorkspaceByProject, loadWorkspace, deleteWorkspace } from '@/lib/workspace';
 import { randomUUID } from 'node:crypto';
 
 // List workspaces, find by projectPath, or export template
@@ -30,7 +29,8 @@ export async function GET(req: Request) {
   return NextResponse.json(listWorkspaces());
 }
 
-// Create workspace or import template
+// Create workspace or import template — proxied through the workspace daemon
+// so the daemon remains the exclusive writer of state.json (prevents race conditions).
 export async function POST(req: Request) {
   const body = await req.json();
   const { projectPath, projectName, template } = body;
@@ -44,45 +44,24 @@ export async function POST(req: Request) {
     return NextResponse.json(existing);
   }
 
-  const state: WorkspaceState = {
-    id: existing?.id || randomUUID(),
-    projectPath,
-    projectName,
-    agents: [],
-    agentStates: {},
-    nodePositions: {},
-    busLog: [],
-    createdAt: existing?.createdAt || Date.now(),
-    updatedAt: Date.now(),
-  };
-
-  // Import template: create agents from template with new IDs
-  if (template?.agents) {
-    const idMap = new Map<string, string>(); // old ID → new ID
-    const ts = Date.now();
-    for (const agent of template.agents) {
-      const newId = `${agent.label.toLowerCase().replace(/\s+/g, '-')}-${ts}-${Math.random().toString(36).slice(2, 5)}`;
-      idMap.set(agent.id, newId);
-    }
-    for (const agent of template.agents) {
-      state.agents.push({
-        ...agent,
-        id: idMap.get(agent.id) || agent.id,
-        dependsOn: agent.dependsOn.map((d: string) => idMap.get(d) || d),
-        entries: agent.type === 'input' ? [] : undefined,
-      });
-      state.agentStates[idMap.get(agent.id) || agent.id] = { smithStatus: 'down', taskStatus: 'idle', history: [], artifacts: [] };
-    }
-    if (template.nodePositions) {
-      for (const [oldId, pos] of Object.entries(template.nodePositions)) {
-        const newId = idMap.get(oldId);
-        if (newId) state.nodePositions[newId] = pos as { x: number; y: number };
-      }
-    }
+  const daemonUrl = `http://localhost:${Number(process.env.WORKSPACE_PORT) || 8405}`;
+  try {
+    const daemonRes = await fetch(`${daemonUrl}/workspace/create`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        id: existing?.id || randomUUID(),
+        projectPath,
+        projectName,
+        template,
+        createdAt: existing?.createdAt,
+      }),
+    });
+    const data = await daemonRes.json();
+    return NextResponse.json(data, { status: daemonRes.status });
+  } catch (err: any) {
+    return NextResponse.json({ error: `Workspace daemon unreachable: ${err.message}` }, { status: 503 });
   }
-
-  await saveWorkspace(state);
-  return NextResponse.json(state, { status: 201 });
 }
 
 // Delete a workspace

package/app/mobile/page.tsx

@@ -3,7 +3,8 @@ import { redirect } from 'next/navigation';
 import MobileView from '@/components/MobileView';
 
 export default async function MobilePage() {
-  const session = await auth();
+  const isDev = process.env.NODE_ENV !== 'production' || process.env.FORGE_DEV === '1';
+  const session = isDev ? { user: { name: 'Dev', email: 'dev@forge' } } : await auth();
   if (!session) redirect('/login');
   return <MobileView />;
 }

package/app/page.tsx

@@ -4,7 +4,8 @@ import { headers } from 'next/headers';
 import DashboardWrapper from '@/components/DashboardWrapper';
 
 export default async function Home({ searchParams }: { searchParams: Promise<{ force?: string }> }) {
-  const session = await auth();
+  const isDev = process.env.NODE_ENV !== 'production' || process.env.FORGE_DEV === '1';
+  const session = isDev ? { user: { name: 'Dev', email: 'dev@forge' } } : await auth();
   if (!session) redirect('/login');
 
   const params = await searchParams;

package/components/WebTerminal.tsx

@@ -736,7 +736,7 @@ const WebTerminal = forwardRef<WebTerminalHandle, WebTerminalProps>(function Web
 
         {/* Toolbar */}
         <div className="flex items-center gap-1 px-2 ml-auto">
-          <span className="text-[9px] text-gray-600 mr-2">Shift+drag to copy</span>
+          <span className="text-[9px] text-gray-600 mr-2">Ctrl+Shift+C/V to copy/paste</span>
           <button onClick={() => onSplit('vertical')} className="text-[10px] px-2 py-0.5 text-gray-400 hover:text-white hover:bg-[var(--term-border)] rounded">
             Split Right
           </button>
@@ -1553,6 +1553,32 @@ const MemoTerminalPane = memo(function TerminalPane({
         setShowSearch(false);
         searchAddonRef.current?.clearDecorations();
       }
+      // Ctrl+Shift+C / Cmd+Shift+C → copy selection to clipboard
+      if ((event.ctrlKey || event.metaKey) && event.shiftKey && event.key === 'C' && event.type === 'keydown') {
+        const sel = term.getSelection();
+        if (sel) {
+          if (navigator.clipboard && window.isSecureContext) {
+            navigator.clipboard.writeText(sel);
+          } else {
+            const ta = document.createElement('textarea');
+            ta.value = sel;
+            ta.style.position = 'fixed';
+            ta.style.opacity = '0';
+            document.body.appendChild(ta);
+            ta.select();
+            document.execCommand('copy');
+            document.body.removeChild(ta);
+          }
+        }
+        return false;
+      }
+      // Ctrl+Shift+V / Cmd+Shift+V → paste from clipboard
+      if ((event.ctrlKey || event.metaKey) && event.shiftKey && event.key === 'V' && event.type === 'keydown') {
+        if (navigator.clipboard && window.isSecureContext) {
+          navigator.clipboard.readText().then(text => { if (text) term.paste(text); });
+        }
+        return false;
+      }
       return true;
     });
 

package/lib/claude-process.ts

@@ -85,18 +85,27 @@ export function sendToClaudeSession(
     args.push('--resume', continueId);
   }
 
-  // Message goes last
-  args.push(message);
+  // Message passed as CLI arg (pushed above).
+  // Spawn without shell to prevent zsh from interpreting special chars
+  // in the message (${}, backticks, quotes in code diffs).
 
   // Remove CLAUDECODE env var to avoid nesting detection
   const env = { ...process.env };
   delete env.CLAUDECODE;
 
-  const child = spawn(claudePath, args, {
+  // Resolve full path so spawn works without shell for PATH lookup
+  let resolvedClaude = claudePath;
+  if (!claudePath.startsWith('/')) {
+    try {
+      const { execSync: execS } = require('node:child_process');
+      resolvedClaude = execS(`which ${claudePath}`, { encoding: 'utf-8', env }).trim() || claudePath;
+    } catch {}
+  }
+
+  const child = spawn(resolvedClaude, args, {
     cwd: managed.info.projectPath,
     env,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    shell: '/bin/zsh',
+    stdio: ['ignore', 'pipe', 'pipe'],  // ignore stdin — prompt is in args, no stdin needed
   });
 
   managed.child = child;

package/lib/forge-mcp-server.ts

@@ -60,14 +60,15 @@ function createForgeMcpServer(sessionId: string): McpServer {
   // ── send_message ──────────────────────────
   server.tool(
     'send_message',
-    'Send a message to another agent in the workspace',
+    'Send a message to another agent in the workspace. Set noReply=true for notifications that do not need a response.',
     {
       to: z.string().describe('Target agent — name like "Reviewer", or description like "the one who does testing"'),
       content: z.string().describe('Message content'),
       action: z.string().optional().describe('Message type: fix_request, update_notify, question, review, info_request'),
+      noReply: z.boolean().optional().describe('If true, recipient should not reply to this message'),
     },
     async (params) => {
-      const { to, content, action = 'update_notify' } = params;
+      const { to, content, action = 'update_notify', noReply } = params;
       const { workspaceId, agentId } = ctx();
       if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context.' }] };
 
@@ -87,8 +88,21 @@ function createForgeMcpServer(sessionId: string): McpServer {
           return { content: [{ type: 'text', text: `No agent matches "${to}". Available: ${available}` }] };
         }
 
-        orch.getBus().send(agentId, target.id, 'notify', { action, content });
-        return { content: [{ type: 'text', text: `Message sent to ${target.label}` }] };
+        // Block reply to agents who have a running/pending message to us.
+        // The system auto-delivers completion status — use /forge-send only for NEW messages.
+        // Uses findLast to check the most recent message state (not oldest/stale ones).
+        const incomingFromTarget = orch.getBus().getLog().findLast((m: any) =>
+          m.to === agentId && m.from === target.id &&
+          (m.status === 'running' || m.status === 'pending')
+        );
+        if (incomingFromTarget && !incomingFromTarget.payload?.noReply) {
+          return { content: [{ type: 'text', text: `Skipped: you are processing a message from ${target.label}. Your completion is delivered automatically — no need to reply via send_message.` }] };
+        }
+
+        const payload: any = { action, content };
+        if (noReply) payload.noReply = true;
+        orch.getBus().send(agentId, target.id, 'notify', payload);
+        return { content: [{ type: 'text', text: `Message sent to ${target.label}${noReply ? ' (no-reply)' : ''}` }] };
       } catch (err: any) {
         return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
       }
@@ -118,8 +132,9 @@ function createForgeMcpServer(sessionId: string): McpServer {
         const getLabel = (id: string) => snapshot.agents.find((a: any) => a.id === id)?.label || id;
 
         const formatted = messages.map((m: any) => {
+          const noReplyTag = m.payload?.noReply ? ' [no-reply]' : '';
           const refInfo = m.payload?.ref ? ` [ref: ${m.payload.ref}]` : '';
-          return `[${m.status}] From ${getLabel(m.from)}: ${m.payload?.content || m.payload?.action || '(no content)'}${refInfo} (${m.id.slice(0, 8)})`;
+          return `[${m.status}] From ${getLabel(m.from)}${noReplyTag}: ${m.payload?.content || m.payload?.action || '(no content)'}${refInfo} (${m.id.slice(0, 8)})`;
         }).join('\n');
 
         return { content: [{ type: 'text', text: formatted }] };

package/lib/help-docs/05-pipelines.md

@@ -185,16 +185,58 @@ nodes:
 
 ## Branch Auto-checkout
 
-Nodes can auto-checkout a git branch before execution:
+Pipeline steps automatically use **git worktree** for isolated execution. Each step gets its own working copy — your main working directory is never affected.
 
 ```yaml
 nodes:
   work:
     project: my-app
-    branch: "feature/{{input.feature_name}}"
+    branch: "feature/{{input.feature_name}}"   # optional: custom branch name
     prompt: "Implement the feature"
 ```
 
+**How it works:**
+- If `branch` is specified, a worktree is created at `<project>/.forge/worktrees/<branch>/`
+- If `branch` is omitted, an auto-generated branch `pipeline/<id>` is used
+- **All step modes** (shell, agent, prompt, plugin) run inside the worktree
+- After completion, the worktree is preserved for review
+- Clean up: `git worktree remove <path>` after reviewing changes
+
+**Shell steps in worktree:**
+
+Shell steps receive 3 environment variables for worktree context:
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `FORGE_WORKTREE` | Worktree path (current working directory) | `/project/.forge/worktrees/pipeline-abc12345` |
+| `FORGE_WORKTREE_BRANCH` | Branch name for this worktree | `pipeline/abc12345` or `feature/my-feature` |
+| `FORGE_PROJECT_ROOT` | Original project root path | `/Users/me/projects/my-app` |
+
+Use these when shell scripts need to reference the original repo:
+
+```yaml
+nodes:
+  push-changes:
+    mode: shell
+    prompt: |
+      git add -A && git commit -m "Pipeline changes" &&
+      git push origin "$FORGE_WORKTREE_BRANCH"
+```
+
+To operate on the original repo from a shell step:
+```yaml
+  check-main:
+    mode: shell
+    prompt: |
+      cd "$FORGE_PROJECT_ROOT" && git log --oneline -5
+```
+
+**Benefits:**
+- Your working directory stays clean during pipeline execution
+- Multiple pipelines can run in parallel on the same project
+- Changes are isolated on branches, easy to review/merge/discard
+- All step modes use the same isolation — consistent behavior
+
 ## Parallel Execution
 
 Nodes without dependency relationships run in parallel: