@polka-codes/cli 0.9.49 → 0.9.51

package/dist/index.js

@@ -35579,7 +35579,7 @@ var {
   Help
 } = import__.default;
 // package.json
-var version = "0.9.49";
+var version = "0.9.51";
 
 // src/commands/code.ts
 import { readFile as readFile3 } from "node:fs/promises";
@@ -48609,7 +48609,6 @@ var TodoItemSchema = exports_external.object({
   id: exports_external.string(),
   title: exports_external.string(),
   description: exports_external.string(),
-  relevantFileList: exports_external.array(exports_external.string()),
   status: TodoStatus
 });
 var UpdateTodoItemInputSchema = exports_external.object({
@@ -48618,7 +48617,6 @@ var UpdateTodoItemInputSchema = exports_external.object({
   parentId: exports_external.string().nullish(),
   title: exports_external.string().nullish(),
   description: exports_external.string().nullish(),
-  relevantFileList: exports_external.array(exports_external.string()).nullish(),
   status: TodoStatus.nullish()
 }).superRefine((data, ctx) => {
   if (data.operation === "add") {
@@ -52472,13 +52470,23 @@ async function searchFiles(path, regex, filePattern, cwd, excludeFiles) {
 }
 
 // ../cli-shared/src/provider.ts
+class InMemoryStore {
+  #data;
+  async read() {
+    return this.#data;
+  }
+  async write(data) {
+    this.#data = data;
+  }
+}
 var getProvider = (options = {}) => {
   const ig = import_ignore2.default().add(options.excludeFiles ?? []);
-  const memoryStore = {};
-  const todoItems = [];
+  const memoryStore = options.memoryStore ?? new InMemoryStore;
+  const todoItemStore = options.todoItemStore ?? new InMemoryStore;
   const defaultMemoryTopic = ":default:";
   const provider2 = {
     listTodoItems: async (id, status) => {
+      const todoItems = await todoItemStore.read() ?? [];
       let items;
       if (!id) {
         items = todoItems.filter((i) => !i.id.includes("."));
@@ -52507,6 +52515,7 @@ var getProvider = (options = {}) => {
       return items;
     },
     getTodoItem: async (id) => {
+      const todoItems = await todoItemStore.read() ?? [];
       const item = todoItems.find((i) => i.id === id);
       if (!item) {
         throw new Error(`To-do item with id ${id} not found`);
@@ -52515,8 +52524,9 @@ var getProvider = (options = {}) => {
       return { ...item, subItems };
     },
     updateTodoItem: async (input) => {
+      const todoItems = await todoItemStore.read() ?? [];
       if (input.operation === "add") {
-        const { parentId, title, description, relevantFileList } = input;
+        const { parentId, title, description, status } = input;
         if (!title) {
           throw new Error("Title is required for add operation");
         }
@@ -52527,19 +52537,27 @@ var getProvider = (options = {}) => {
             throw new Error(`Parent to-do item with id ${parentId} not found`);
           }
           const childItems = todoItems.filter((i) => i.id.startsWith(`${parentId}.`) && i.id.split(".").length === parentId.split(".").length + 1);
-          newId = `${parentId}.${childItems.length + 1}`;
+          const maxId = childItems.reduce((max, item) => {
+            const parts = item.id.split(".");
+            const lastPart = parseInt(parts[parts.length - 1], 10);
+            return Math.max(max, lastPart);
+          }, 0);
+          newId = `${parentId}.${maxId + 1}`;
         } else {
           const rootItems = todoItems.filter((i) => !i.id.includes("."));
-          newId = `${rootItems.length + 1}`;
+          const maxId = rootItems.reduce((max, item) => {
+            const idNum = parseInt(item.id, 10);
+            return Math.max(max, idNum);
+          }, 0);
+          newId = `${maxId + 1}`;
         }
         const newItem = {
           id: newId,
           title,
           description: description ?? "",
-          relevantFileList: relevantFileList ?? [],
-          status: "open"
+          status: status ?? "open"
         };
-        todoItems.push(newItem);
+        await todoItemStore.write([...todoItems, newItem]);
         return { id: newId };
       } else {
         const { id } = input;
@@ -52556,40 +52574,43 @@ var getProvider = (options = {}) => {
         if (input.description != null) {
           item.description = input.description ?? "";
         }
-        if (input.relevantFileList != null) {
-          item.relevantFileList = input.relevantFileList;
-        }
         if (input.status != null) {
           item.status = input.status;
         }
+        await todoItemStore.write(todoItems);
         return { id };
       }
     },
     listMemoryTopics: async () => {
-      return Object.keys(memoryStore);
+      const memory = await memoryStore.read() ?? {};
+      return Object.keys(memory);
     },
     readMemory: async (topic = defaultMemoryTopic) => {
-      return memoryStore[topic];
+      const memory = await memoryStore.read() ?? {};
+      return memory[topic];
     },
     updateMemory: async (operation, topic, content) => {
       const memoryTopic = topic ?? defaultMemoryTopic;
+      const memory = await memoryStore.read() ?? {};
       switch (operation) {
         case "append":
           if (content === undefined) {
             throw new Error("Content is required for append operation.");
           }
-          memoryStore[memoryTopic] = (memoryStore[memoryTopic] || "") + content;
+          memory[memoryTopic] = `${memory[memoryTopic] || ""}
+${content}`;
           break;
         case "replace":
           if (content === undefined) {
             throw new Error("Content is required for replace operation.");
           }
-          memoryStore[memoryTopic] = content;
+          memory[memoryTopic] = content;
           break;
         case "remove":
-          delete memoryStore[memoryTopic];
+          delete memory[memoryTopic];
           break;
       }
+      await memoryStore.write(memory);
     },
     readFile: async (path, includeIgnored) => {
       if (!includeIgnored && ig.ignores(path)) {
@@ -65261,9 +65282,10 @@ ${event.systemPrompt}`);
       }
       case "ToolUse" /* ToolUse */: {
         if (verbose > 0) {
+          const params = verbose > 1 ? event.params : simplifyToolParameters(event.tool, event.params);
           customConsole.log(source_default.yellow(`
 
-Tool use:`, event.tool), simplifyToolParameters(event.tool, event.params));
+Tool use:`, event.tool), params);
         }
         const stats = taskToolCallStats.get(event.tool) ?? { calls: 0, success: 0, errors: 0 };
         stats.calls++;
@@ -65308,7 +65330,9 @@ Tool error:`, event.tool));
             break;
           }
           case "Exit" /* Exit */:
-            customConsole.log("Exit Message:", event.exitReason.message);
+            if (verbose > 0) {
+              customConsole.log("Exit Message:", event.exitReason.message);
+            }
             break;
         }
         for (const [tool3, taskStats] of taskToolCallStats.entries()) {
@@ -78501,6 +78525,14 @@ ${defaultContent}
   return contextParts.join(`
 `);
 }
+async function readMemory(input2, context) {
+  const provider3 = context.toolProvider;
+  return await provider3.readMemory(input2.topic) ?? "";
+}
+async function listMemoryTopics(_input, context) {
+  const provider3 = context.toolProvider;
+  return provider3.listMemoryTopics();
+}
 async function updateMemory(input2, context) {
   const provider3 = context.toolProvider;
   const content = "content" in input2 ? input2.content : undefined;
@@ -78532,6 +78564,8 @@ var localToolHandlers = {
   invokeTool,
   taskEvent,
   getMemoryContext,
+  readMemory,
+  listMemoryTopics,
   updateMemory,
   listTodoItems,
   getTodoItem,
@@ -78564,7 +78598,7 @@ async function runWorkflow(workflow2, workflowInput, options) {
     maxCost: config4.budget
   });
   const onEvent = printEvent(verbose, usage, process.stderr);
-  const toolProvider = getProvider({ excludeFiles: config4.excludeFiles });
+  const toolProvider = (options.getProvider ?? getProvider)({ excludeFiles: config4.excludeFiles });
   const commandConfig = providerConfig.getConfigForCommand(commandName);
   if (!commandConfig) {
     throw new Error(`No provider configured for command: ${commandName}`);
@@ -78637,7 +78671,17 @@ ${JSON.stringify(schema, null, 2)}
 \`\`\`
 `;
 }
-var TOOL_USAGE_INSTRUCTION = `When you use a tool, you MUST first provide a short summary of what you are doing and why you are using that tool. This summary will be shown to the user to explain your actions.`;
+var TOOL_USAGE_INSTRUCTION = `
+## Action Line
+
+Before any tool call, emit a single high-level action line.
+
+You MUST follow these style constraints for the action line:
+- NO filler or preambles.
+- DO NOT use "ok", "okay", "alright".
+- DO NOT use first person ("I", "I'm", "I will", "I'll", etc.).
+- NO apologies, hedging, or promises about later work.
+`;
 var MEMORY_USAGE_SECTION = `## Memory Usage
 
 You have access to a memory feature to store and retrieve information across tool calls.
@@ -78873,15 +78917,21 @@ Effective planning requires understanding before action:
    - File system exploration (\`listFiles\`, \`searchFiles\`) reveals structure and patterns.
    - Reading existing files (\`readFile\`) shows coding style and conventions.
 
-3. **High-Level, Not Granular**
-   - Your plan should focus on the "what" and "why" at a strategic level.
-   - Avoid getting bogged down in implementation minutiae. For example, instead of "add a 20px margin to the button", say "Update the component styling to align with the design system".
-   - The output should be a roadmap, not a turn-by-turn navigation.
+3. **High-Level Strategy with Detailed Tasks**
+   - "High-level" refers to strategic phases and architectural decisions, not individual implementation steps.
+   - While the plan structure should be strategic (phases, components), each task item must contain detailed implementation guidance.
+   - Each task should include specific file paths, function names, implementation patterns, and technical details.
+   - The plan should be detailed enough that task creation does not require additional codebase exploration.
+   - Example of appropriate detail level:
+     * ❌ Too vague: "Add authentication"
+     * ❌ Too granular: "Add a 20px margin to the button on line 45"
+     * ✅ Appropriate: "Implement authentication endpoints in \`src/api/auth.ts\` with \`POST /api/auth/login\` that validates credentials using bcrypt and returns JWT tokens"
 
 4. **Clarity for AI Implementation**
-   - The plan must be clear enough for AI agents to implement directly.
-   - Each task should be a concrete, implementable piece of work.
-   - Focus on what needs to be built and how.
+   - The plan must be clear enough for AI agents to implement directly without further exploration.
+   - Each task should be a concrete, implementable piece of work with all necessary details.
+   - Include specific technical information: file paths, function signatures, dependencies, patterns to follow.
+   - The task creation agent should be able to parse the plan and create todo items without exploring the codebase.
 
 ## Your Approach
 
@@ -78902,33 +78952,61 @@ For epic-scale work, **checkboxes are RECOMMENDED** to help track progress throu
 
 **Recommended Checklist Format**:
 - Use markdown checkboxes (\`- [ ] item\`) for major components and tasks
+- Create nested task breakdowns with 3-4 levels of detail
 - Each checkbox represents a distinct, trackable piece of work
-- Each checkbox item should be specific and implementable independently
-- Group related checkboxes under numbered sections or phases when appropriate
+- Each checkbox item must include detailed implementation guidance
+- Group related checkboxes under numbered sections or phases
 - Items will be implemented one at a time iteratively
 - After each implementation, the completed item will be marked with \`- [x]\` when the plan is updated
 
-**Example checklist format**:
+**Implementation Details Requirements**:
+
+Each task item must specify:
+- **Exact file paths** for new files or modifications (e.g., \`src/api/auth.ts\`)
+- **Function signatures and class names** to implement (e.g., \`async function authenticateUser(email: string, password: string)\`)
+- **Specific patterns from the codebase** to follow (e.g., "Follow the middleware pattern used in \`src/middleware/logger.ts\`")
+- **Required imports and dependencies** (e.g., "Import \`bcrypt\` for password hashing, use \`jsonwebtoken\` for JWT generation")
+- **Error handling approach** (e.g., "Use \`ApiError\` class from \`src/errors.ts\`")
+- **Integration points** with existing code (e.g., "Register middleware in \`src/app.ts\` before route handlers")
+- **Testing requirements** if applicable (e.g., "Add unit tests in \`src/api/__tests__/auth.test.ts\`")
+
+**Example checklist format with proper detail**:
 \`\`\`
 1. Phase 1: Backend API Development
-   - [ ] Design and implement user authentication endpoints
+   - [ ] Design and implement user authentication endpoints in \`src/api/auth.ts\`
+     - [ ] Create \`POST /api/auth/login\` endpoint that accepts email/password in request body, validates using bcrypt, returns JWT token using \`jsonwebtoken\` library with 24h expiration
+     - [ ] Create \`POST /api/auth/register\` endpoint that validates input with zod schema (\`email\`, \`password\` min 8 chars), hashes password with bcrypt (10 rounds), stores in database using Prisma ORM
+     - [ ] Add authentication middleware in \`src/middleware/auth.ts\` that verifies JWT tokens from Authorization header and attaches user object to \`req.user\`
    - [ ] Create database schema and migrations
-   - [ ] Implement data validation middleware
+     - [ ] Define User model in \`prisma/schema.prisma\` with fields: id (UUID), email (unique string), passwordHash (string), createdAt (DateTime), updatedAt (DateTime)
+     - [ ] Generate migration with \`npx prisma migrate dev --name add-user-auth\`
+     - [ ] Update \`src/db/client.ts\` to export Prisma client instance
+   - [ ] Implement data validation middleware in \`src/middleware/validation.ts\`
+     - [ ] Create \`validateRequest\` function that accepts zod schema and returns Express middleware
+     - [ ] Add error handling that returns 400 status with validation errors in response body
+     - [ ] Follow error format used in \`src/middleware/errorHandler.ts\`
 
 2. Phase 2: Frontend Integration
-   - [ ] Build authentication UI components
-   - [ ] Integrate with backend API
+   - [ ] Build authentication UI components in \`src/components/auth/\`
+     - [ ] Create \`LoginForm.tsx\` component with email/password fields using React Hook Form, submit handler calls \`/api/auth/login\`
+     - [ ] Create \`RegisterForm.tsx\` component with email/password/confirmPassword fields, client-side validation matches backend rules
+     - [ ] Add \`AuthContext.tsx\` using React Context API to manage auth state (user object, isAuthenticated boolean, login/logout functions)
+   - [ ] Integrate with backend API using \`src/lib/api.ts\`
+     - [ ] Add \`login(email, password)\` function that calls \`POST /api/auth/login\`, stores JWT in localStorage, returns user object
+     - [ ] Add \`register(email, password)\` function that calls \`POST /api/auth/register\`
+     - [ ] Add \`logout()\` function that removes JWT from localStorage and clears auth state
    - [ ] Add error handling and loading states
+     - [ ] Display API errors in form using \`ErrorMessage\` component from \`src/components/ui/ErrorMessage.tsx\`
+     - [ ] Show loading spinner during API calls using \`LoadingSpinner\` component from \`src/components/ui/LoadingSpinner.tsx\`
+     - [ ] Add toast notifications for success/error using \`react-hot-toast\` library
 \`\`\`
 
-**Alternative Format**:
-You may also use numbered lists if checkboxes don't fit the task structure. However, each item should still be clear, actionable, and implementable independently.
-
 **What to Include**:
-- Actionable implementation steps
-- Technical requirements and specifications
-- Specific files, functions, or components to create/modify
-- Context needed for implementation
+- Actionable implementation steps with complete technical specifications
+- Exact file paths, function names, and implementation patterns
+- All dependencies, imports, and integration points
+- Specific technical constraints and requirements
+- Testing approach if applicable
 
 **What NOT to Include**:
 - Future enhancements or scope outside the current task
@@ -78947,9 +79025,11 @@ Branch names should:
 
 1. Analyze the task and the existing plan (if any).
 2. If the requirements are clear and you can generate or update the plan:
-   a. Provide the plan in the "plan" field using the checklist format described above
-   b. Propose a suitable git branch name in the "branchName" field.
-   c. Include relevant file paths in the "files" array if applicable
+   a. **Explore the codebase first** to understand patterns, conventions, and existing implementations
+   b. Provide the plan in the "plan" field using the checklist format with detailed implementation guidance
+   c. Ensure the plan is detailed enough that task creation does not require additional codebase exploration
+   d. Each task item must include specific file paths, function names, implementation patterns, and technical details
+   e. Propose a suitable git branch name in the "branchName" field
 3. If the requirements are not clear:
    a. Ask a clarifying question in the "question" field
 4. If the task is already implemented or no action is needed:
@@ -78958,27 +79038,78 @@ Branch names should:
 
 ## Response Format
 
-${createJsonResponseInstruction({
-  plan: "The generated or updated plan.",
-  branchName: "feat/new-feature-name",
-  question: {
-    question: "The clarifying question to ask the user.",
-    defaultAnswer: "The default answer to provide if the user does not provide an answer."
-  },
-  reason: "If no plan is needed, provide a reason here."
-})}
+Respond with a JSON object in a markdown code block. The JSON object should have a "type" field that determines the structure of the rest of the object.
+
+### 1. When you generate a plan (type: 'plan-generated')
+- **type**: Must be "plan-generated".
+- **plan**: The generated or updated plan.
+- **branchName**: A suitable git branch name for the work.
+
+Example:
+\`\`\`json
+{
+  "type": "plan-generated",
+  "plan": "1. Phase 1: Backend API Development\\n   - [ ] Design and implement user authentication endpoints...",
+  "branchName": "feat/user-authentication"
+}
+\`\`\`
+
+### 2. When you need to ask a question (type: 'question')
+- **type**: Must be "question".
+- **question**: An object containing the question and an optional default answer.
+
+Example:
+\`\`\`json
+{
+  "type": "question",
+  "question": {
+    "question": "What database are you using?",
+    "defaultAnswer": "PostgreSQL"
+  }
+}
+\`\`\`
+
+### 3. When no plan is needed or an error occurs (type: 'error')
+- **type**: Must be "error".
+- **reason**: A string explaining why no plan is generated (e.g., task already complete, unclear requirements after questioning).
+
+Example:
+\`\`\`json
+{
+  "type": "error",
+  "reason": "The requested feature is already implemented in 'src/features/existing-feature.ts'."
+}
+\`\`\`
 `;
 var BRANCH_NAME_PATTERN = /^[a-zA-Z0-9/_-]+$/;
 var EpicPlanSchema = exports_external.object({
+  type: exports_external.enum(["plan-generated", "question", "error"]),
   plan: exports_external.string().nullish(),
   branchName: exports_external.string().refine((name18) => name18.length >= 3, { message: "Branch name is too short (min 3 characters)." }).refine((name18) => name18.length <= 255, { message: "Branch name is too long (max 255 characters)." }).refine((name18) => BRANCH_NAME_PATTERN.test(name18), {
     message: "Invalid branch name format. Branch names should contain only letters, numbers, hyphens, underscores, and forward slashes."
-  }),
+  }).nullish(),
   question: exports_external.object({
     question: exports_external.string(),
     defaultAnswer: exports_external.string().nullish()
   }).nullish(),
   reason: exports_external.string().nullish()
+}).superRefine((data, ctx) => {
+  if (data.type === "plan-generated") {
+    if (!data.plan || data.plan.trim() === "") {
+      ctx.addIssue({
+        code: "custom",
+        message: 'Plan is required when type is "plan-generated".',
+        path: ["plan"]
+      });
+    }
+    if (!data.branchName || data.branchName.trim() === "") {
+      ctx.addIssue({
+        code: "custom",
+        message: 'Branch name is required when type is "plan-generated".',
+        path: ["branchName"]
+      });
+    }
+  }
 });
 function getPlanPrompt(task, planContent) {
   const planSection = planContent ? `
@@ -78996,21 +79127,90 @@ ${task}
 ${planSection}`;
 }
 var EPIC_ADD_TODO_ITEMS_SYSTEM_PROMPT = `Role: Task creation agent
-Goal: Read a high-level plan and create corresponding todo items.
+Goal: Parse a detailed epic plan and create todo items from the provided task breakdowns.
 
 ${TOOL_USAGE_INSTRUCTION}
 
-You are a task creation agent. Your responsibility is to read a high-level plan for an epic and create a todo item for each task in the plan.
+You are a task creation agent responsible for parsing a detailed epic plan and creating todo items that can be executed autonomously by an AI coding agent.
 
-## Your Task
+## Your Responsibility
+
+Your goal is to create todo items that are:
+- **Specific and actionable**: Each item should be clear enough for an AI agent to implement without human intervention
+- **Well-documented**: Include detailed implementation guidance extracted from the plan
+- **Context-rich**: Specify relevant files that will be modified or created (as provided in the plan)
+- **Self-contained**: Each item should be implementable independently with the context from the plan
+
+## Plan Structure Expectations
+
+The plan you receive contains all necessary implementation details. You should NOT need to explore the codebase because:
+- Each task in the plan already includes specific file paths
+- Function and class names are specified in the plan
+- Implementation patterns and approaches are provided
+- Dependencies and imports are listed
+- Technical specifications are included
+- Integration points are documented
+
+Your job is to extract these details from the plan and create todo items, not to research or discover them.
+
+## Todo Item Requirements
 
-You will have access to the high-level plan stored in memory under the topic 'epic-plan'.
-Read the plan and for each task item in the plan, use the 'updateTodoItem' tool to create a new todo item.
+For each task in the plan, create a todo item using the \`updateTodoItem\` tool with:
+
+### 1. **title** (required)
+A concise, action-oriented task name that clearly states what needs to be done.
+
+**Examples:**
+- ✅ "Implement user authentication with JWT tokens"
+- ✅ "Add validation middleware for API endpoints"
+- ❌ "Authentication" (too vague)
+
+### 2. **description** (required)
+Detailed implementation instructions extracted from the plan. Include:
+
+**Must extract from the plan:**
+- **Specific files to create or modify** with exact paths (as specified in the plan)
+- **Function/class names** to implement or modify (as specified in the plan)
+- **Implementation patterns** to follow (as referenced in the plan)
+- **Technical requirements** and constraints (as documented in the plan)
+- **Dependencies** and imports needed (as listed in the plan)
+- **Integration points** with existing code (as described in the plan)
+
+**Example of extracting from a detailed plan task:**
+
+Plan task:
+\`\`\`
+- [ ] Add authentication middleware in \`src/middleware/auth.ts\` that verifies JWT tokens from Authorization header and attaches user object to \`req.user\`
+\`\`\`
+
+Todo item description:
+\`\`\`
+Create a new authentication middleware in \`src/middleware/auth.ts\`:
+
+1. Implement \`authenticateJWT\` function that:
+   - Extracts JWT token from Authorization header
+   - Verifies token (implementation details from plan)
+   - Attaches user object to \`req.user\`
+   - Returns 401 error for invalid/missing tokens
+
+2. Export the middleware for use in route definitions
+\`\`\`
+
+**Note:** All implementation details should come from the plan. Do not add information not present in the plan.
 
 ## Process
 
-1. Parse the plan to identify individual tasks.
-2. For each task, call 'updateTodoItem' with the task description as the 'title'.
+1. **Read and parse the plan** provided in the user message to identify individual tasks
+2. **Parse the plan structure** to understand the task hierarchy and details
+3. **For each task in the plan:**
+   a. Extract the specific files mentioned in the task
+   b. Extract implementation patterns specified in the plan
+   c. Create a detailed description using the plan's guidance
+   d. Identify all relevant files from the plan
+   e. Call \`updateTodoItem\` with operation='add', title and description
+
+**Important:** Do NOT explore the codebase. All necessary information is already in the plan.
+
 `;
 var CODER_SYSTEM_PROMPT = `Role: AI developer.
 Goal: Implement the provided plan by writing and modifying code.
@@ -79683,17 +79883,17 @@ Files:`);
 
 // src/workflows/code.workflow.ts
 var ImplementOutputSchema = exports_external.object({
-  summary: exports_external.string().nullish(),
-  bailReason: exports_external.string().nullish()
+  summary: exports_external.string().nullish().describe("Short summary of the changes made"),
+  bailReason: exports_external.string().nullish().describe("Reason for bailing out of the implementation loop")
 }).refine((data) => data.summary != null !== (data.bailReason != null), {
   message: "Either summary or bailReason must be provided, but not both"
 });
 var codeWorkflow = async (input2, context) => {
   const { logger, step, tools: tools2 } = context;
-  const { task, files, mode = "interactive" } = input2;
+  const { task, files, mode = "interactive", additionalTools, additionalInstructions } = input2;
   const summaries = [];
   logger.info(`
-\uD83D\uDCCB Phase 1: Creating implementation plan...
+Phase 1: Creating implementation plan...
 `);
   const planResult = await step("plan", async () => {
     return await planWorkflow({ task, files, mode: mode === "interactive" ? "confirm" : "noninteractive" }, context);
@@ -79704,7 +79904,7 @@ var codeWorkflow = async (input2, context) => {
   }
   const { plan, files: planFiles } = planResult;
   logger.info(`
-⚙️  Phase 2: Implementing the plan...
+Phase 2: Implementing the plan...
 `);
   let implementPrompt = getImplementPrompt(plan);
   if (planFiles && planFiles.length > 0) {
@@ -79752,6 +79952,9 @@ ${fileContentString}`;
   if (mode === "interactive") {
     agentTools.push(askFollowupQuestion_default);
   }
+  if (additionalTools) {
+    agentTools.push(...additionalTools);
+  }
   const res = await step("implement", async () => {
     const defaultContext = await getDefaultContext();
     const memoryContext = await tools2.getMemoryContext();
@@ -79768,8 +79971,11 @@ ${memoryContext}`;
 ${memoryContext}`
       });
     }
+    const systemPrompt = additionalInstructions ? `${CODER_SYSTEM_PROMPT}
+
+${additionalInstructions}` : CODER_SYSTEM_PROMPT;
     return await agentWorkflow({
-      systemPrompt: CODER_SYSTEM_PROMPT,
+      systemPrompt,
       userMessage: [{ role: "user", content: userContent }],
       tools: agentTools,
       outputSchema: ImplementOutputSchema
@@ -79779,13 +79985,13 @@ ${memoryContext}`
     const { summary, bailReason } = res.object;
     if (bailReason) {
       logger.error(`
-❌ Implementation failed: ${bailReason}
+Implementation failed: ${bailReason}
 `);
       return { success: false, reason: bailReason, summaries };
     }
     if (summary) {
       logger.info(`
-✅ Implementation complete!
+Implementation complete!
 `);
       summaries.push(summary);
       logger.info(`Summary: ${summary}`);
@@ -79798,20 +80004,20 @@ ${memoryContext}`
       });
     } else {
       logger.info(`
-✅ Implementation complete!
+Implementation complete!
 `);
     }
   } else if (res.type === "Exit" /* Exit */) {
     logger.info(`
-✅ Implementation complete!
+Implementation complete!
 `);
   } else {
     logger.warn(`
-⚠️ Implementation failed. Please check the output for errors.
+Warning: Implementation failed. Please check the output for errors.
 `, res);
   }
   logger.info(`
-\uD83D\uDD27 Phase 3: Checking for errors...
+Phase 3: Checking for errors...
 `);
   const fixResult = await step("fix", async () => {
     return await fixWorkflow({ interactive: false, task: input2.task }, context);
@@ -80221,8 +80427,68 @@ ${provider3.toUpperCase()}_API_KEY=${providerConfig.apiKey}`;
   });
   return { configPath };
 };
+// src/workflows/epic-context.ts
+import { promises as fs3 } from "node:fs";
+var EPIC_CONTEXT_FILE = ".epic.yml";
+var EpicContextSchema = exports_external.object({
+  task: exports_external.string().nullish(),
+  plan: exports_external.string().nullish(),
+  branchName: exports_external.string().nullish(),
+  baseBranch: exports_external.string().nullish(),
+  todos: exports_external.array(TodoItemSchema).nullish(),
+  memory: exports_external.record(exports_external.string(), exports_external.string()).nullish()
+});
+var saveEpicContext = async (context) => {
+  const yamlString = $stringify(context);
+  await fs3.writeFile(EPIC_CONTEXT_FILE, yamlString, "utf-8");
+};
+var loadEpicContext = async () => {
+  let fileContent;
+  try {
+    fileContent = await fs3.readFile(EPIC_CONTEXT_FILE, "utf-8");
+  } catch {
+    return {};
+  }
+  try {
+    const loaded = $parse(fileContent);
+    return EpicContextSchema.parse(loaded);
+  } catch (error46) {
+    console.error("Error parsing epic context file:", EPIC_CONTEXT_FILE, error46);
+    return {};
+  }
+};
+
+class EpicMemoryStore {
+  #context;
+  constructor(context) {
+    this.#context = context;
+  }
+  async read() {
+    return this.#context.memory ?? {};
+  }
+  async write(data) {
+    this.#context.memory = data;
+    await saveEpicContext(this.#context);
+  }
+}
+
+class EpicTodoItemStore {
+  #context;
+  constructor(context) {
+    this.#context = context;
+  }
+  async read() {
+    return this.#context.todos ?? [];
+  }
+  async write(data) {
+    this.#context.todos = data;
+    await saveEpicContext(this.#context);
+  }
+}
+
 // src/workflows/epic.workflow.ts
 var MAX_REVIEW_RETRIES = 5;
+var TODO_HANDLING_INSTRUCTIONS = `If you discover that a task is larger than you thought, or that a new task is required, you can add a // TODO comment in the code and create a todo item for it. This will allow you to continue with the current task and address the larger issue later.`;
 async function createPlan2(input2, context) {
   const { task, plan, files, feedback } = input2;
   const content = [{ type: "text", text: getPlanPrompt(task, plan) }];
@@ -80268,48 +80534,57 @@ ${feedback}`
     outputSchema: EpicPlanSchema
   }, context);
   if (planResult.type === "Exit" /* Exit */) {
-    return { ...planResult.object, type: planResult.type };
+    return planResult.object;
   }
-  return { plan: "", reason: "Usage limit exceeded.", type: "Exit" /* Exit */, branchName: "" };
+  return { type: "error", reason: "Usage limit exceeded." };
 }
 async function createAndApprovePlan(task, context) {
   const { logger, step, tools: tools2 } = context;
-  logger.info(`\uD83D\uDCDD Phase 2: Creating high-level plan...
+  logger.info(`Phase 2: Creating high-level plan...
 `);
   let feedback;
-  let highLevelPlan;
-  let branchName;
   let planAttempt = 1;
   try {
     while (true) {
       const result = await step(`plan-${planAttempt}`, () => createPlan2({ task, feedback }, context));
       planAttempt++;
-      if (result.question) {
-        const answer = await tools2.input({
-          message: result.question.question,
-          default: result.question.defaultAnswer || undefined
-        });
-        feedback = `The user answered the question "${result.question.question}" with: "${answer}"`;
-        continue;
-      }
-      if (!result.plan) {
-        if (result.reason) {
-          logger.info(`No plan created. Reason: ${result.reason}`);
-        } else {
-          logger.info("No plan created.");
-        }
-        return null;
-      }
-      logger.info(`\uD83D\uDCDD Plan:
+      switch (result.type) {
+        case "plan-generated": {
+          if (!result.plan || !result.branchName) {
+            logger.error("Invalid plan-generated response. Missing plan or branchName.");
+            return null;
+          }
+          logger.info(`Plan:
 ${result.plan}`);
-      if (result.branchName) {
-        logger.info(`\uD83C\uDF3F Suggested branch name: ${result.branchName}`);
-      }
-      feedback = await tools2.input({ message: "Press Enter to approve the plan, or provide feedback to refine it." });
-      if (feedback.trim() === "") {
-        highLevelPlan = result.plan;
-        branchName = result.branchName;
-        break;
+          logger.info(`Suggested branch name: ${result.branchName}`);
+          feedback = await tools2.input({ message: "Press Enter to approve the plan, or provide feedback to refine it." });
+          if (feedback.trim() === "") {
+            logger.info(`High-level plan approved.
+`);
+            return { plan: result.plan, branchName: result.branchName };
+          }
+          break;
+        }
+        case "question": {
+          if (!result.question) {
+            logger.error("Invalid question response. Missing question object.");
+            return null;
+          }
+          const answer = await tools2.input({
+            message: result.question.question,
+            default: result.question.defaultAnswer || undefined
+          });
+          feedback = `The user answered the question "${result.question.question}" with: "${answer}"`;
+          break;
+        }
+        case "error": {
+          logger.info(`Plan creation failed. Reason: ${result.reason || "Unknown error"}`);
+          return null;
+        }
+        default: {
+          logger.error(`Unknown response type from planner: ${result.type}`);
+          return null;
+        }
       }
     }
   } catch (e) {
@@ -80319,53 +80594,43 @@ ${result.plan}`);
     }
     throw e;
   }
-  if (!highLevelPlan) {
-    logger.info("Plan not approved. Exiting.");
-    return null;
-  }
-  if (!branchName) {
-    logger.error("❌ Error: No branch name was generated from the plan. Exiting.");
-    return null;
-  }
-  logger.info(`✅ High-level plan approved.
-`);
-  return { plan: highLevelPlan, branchName };
 }
-async function createFeatureBranch(branchName, context) {
+async function createFeatureBranch(branchName, baseBranch, context) {
   const { logger, step, tools: tools2 } = context;
-  logger.info(`\uD83C\uDF3F Phase 3: Creating feature branch...
+  logger.info(`Phase 3: Creating/switching to feature branch...
 `);
-  let finalBranchName = branchName;
-  const initialCheckResult = await step("checkBranch-initial", async () => await tools2.executeCommand({ command: "git", args: ["rev-parse", "--verify", finalBranchName] }));
-  if (initialCheckResult.exitCode === 0) {
-    logger.warn(`⚠️  Branch '${finalBranchName}' already exists. Trying to find an available name...`);
-    const suffixMatch = branchName.match(/-(\d+)$/);
-    let baseName = branchName;
-    let counter = 2;
-    if (suffixMatch) {
-      baseName = branchName.substring(0, suffixMatch.index);
-      counter = parseInt(suffixMatch[1], 10) + 1;
-    }
-    while (true) {
-      finalBranchName = `${baseName}-${counter}`;
-      const branchCheckResult = await step(`checkBranch-${counter}`, async () => await tools2.executeCommand({ command: "git", args: ["rev-parse", "--verify", finalBranchName] }));
-      if (branchCheckResult.exitCode !== 0) {
-        break;
+  const branchExistsResult = await step("checkBranchExists", async () => await tools2.executeCommand({ command: "git", args: ["rev-parse", "--verify", branchName] }));
+  if (branchExistsResult.exitCode === 0) {
+    const currentBranchResult = await step("getCurrentBranch", async () => tools2.executeCommand({ command: "git", args: ["rev-parse", "--abbrev-ref", "HEAD"] }));
+    const currentBranch = currentBranchResult.stdout.trim();
+    if (currentBranch !== branchName) {
+      logger.info(`Branch '${branchName}' already exists. Switching to it...`);
+      const checkoutResult = await step("checkoutBranch", async () => await tools2.executeCommand({ command: "git", args: ["checkout", branchName] }));
+      if (checkoutResult.exitCode !== 0) {
+        logger.error(`Error: Failed to switch to branch '${branchName}'. Git command failed.`);
+        return { success: false, branchName: null };
       }
-      counter++;
+    } else {
+      logger.info(`Already on branch '${branchName}'.`);
+    }
+  } else {
+    logger.info(`Creating new branch '${branchName}'...`);
+    const createBranchResult = await step("createBranch", async () => await tools2.executeCommand({
+      command: "git",
+      args: baseBranch ? ["checkout", "-b", branchName, baseBranch] : ["checkout", "-b", branchName]
+    }));
+    if (createBranchResult.exitCode !== 0) {
+      logger.error(`Error: Failed to create branch '${branchName}'. Git command failed.`);
+      return { success: false, branchName: null };
     }
   }
-  if (finalBranchName !== branchName) {
-    logger.info(`Branch name '${branchName}' was taken. Using '${finalBranchName}' instead.`);
-  }
-  await step("createBranch", async () => await tools2.executeCommand({ command: "git", args: ["checkout", "-b", finalBranchName] }));
-  logger.info(`✅ Branch '${finalBranchName}' created.
+  logger.info(`Successfully on branch '${branchName}'.
 `);
-  return { success: true, branchName: finalBranchName };
+  return { success: true, branchName };
 }
 async function addTodoItemsFromPlan(plan, context) {
   const { logger, step, tools: tools2 } = context;
-  logger.info(`\uD83D\uDCDD Phase 4: Creating todo items from plan...
+  logger.info(`Phase 4: Creating todo items from plan...
 `);
   await step("add-todo-items", async () => {
     await agentWorkflow({
@@ -80377,28 +80642,46 @@ ${plan}</plan>` }],
     }, context);
   });
   const todos = await tools2.listTodoItems({});
-  logger.info(`✅ Created ${todos.length} todo items.
+  logger.info(`Created ${todos.length} todo items.
 `);
 }
-async function runPreflightChecks(context) {
+async function runPreflightChecks(epicContext, context) {
   const { logger, step, tools: tools2 } = context;
-  logger.info(`\uD83D\uDCCB Phase 1: Running pre-flight checks...
+  logger.info(`Phase 1: Running pre-flight checks...
 `);
   const gitCheckResult = await step("gitCheck", async () => tools2.executeCommand({ command: "git", args: ["rev-parse", "--git-dir"] }));
   if (gitCheckResult.exitCode !== 0) {
-    logger.error("❌ Error: Git is not initialized in this directory. Please run `git init` first.");
-    logger.info("\uD83D\uDCA1 Suggestion: Run `git init` to initialize a git repository.\n");
-    return { success: false };
+    logger.error("Error: Git is not initialized in this directory. Please run `git init` first.");
+    logger.info("Suggestion: Run `git init` to initialize a git repository.\n");
+    return false;
+  }
+  if (epicContext.plan) {
+    logger.info("Found an existing `.epic.yml` file.");
+    if (!epicContext.branchName) {
+      throw new Error("Invalid epic context loaded from .epic.yml: branchName is required.");
+    }
+    const currentBranchResult = await step("getCurrentBranch", async () => tools2.executeCommand({ command: "git", args: ["rev-parse", "--abbrev-ref", "HEAD"] }));
+    const currentBranch = currentBranchResult.stdout.trim();
+    if (currentBranch !== epicContext.branchName) {
+      throw new Error(`You are on branch '${currentBranch}' but the epic was started on branch '${epicContext.branchName}'. Please switch to the correct branch to resume.`);
+    }
+    logger.info("Resuming previous epic session.");
+    return true;
   }
   const gitStatusResult = await step("gitStatus", async () => tools2.executeCommand({ command: "git status --porcelain", shell: true }));
   if (gitStatusResult.stdout.trim() !== "") {
-    logger.error("❌ Error: Your working directory is not clean. Please stash or commit your changes before running the epic workflow.");
-    logger.info("\uD83D\uDCA1 Suggestion: Run `git add .` and `git commit` to clean your working directory, or `git stash` to temporarily save changes.\n");
-    return { success: false };
+    logger.error("Error: Your working directory is not clean. Please stash or commit your changes before running the epic workflow.");
+    logger.info("Suggestion: Run `git add .` and `git commit` to clean your working directory, or `git stash` to temporarily save changes.\n");
+    return false;
+  }
+  const baseBranchResult = await step("getBaseBranch", async () => tools2.executeCommand({ command: "git", args: ["rev-parse", "--abbrev-ref", "HEAD"] }));
+  if (baseBranchResult.exitCode === 0 && baseBranchResult.stdout.trim()) {
+    epicContext.baseBranch = baseBranchResult.stdout.trim();
+    logger.info(`Using current branch '${epicContext.baseBranch}' as the base for this epic.`);
   }
-  logger.info(`✅ Pre-flight checks passed.
+  logger.info(`Pre-flight checks passed.
 `);
-  return { success: true };
+  return true;
 }
 async function performReviewAndFixCycle(iterationCount, taskItem, highLevelPlan, context) {
   const { logger, step, tools: tools2 } = context;
@@ -80406,12 +80689,12 @@ async function performReviewAndFixCycle(iterationCount, taskItem, highLevelPlan,
     const diffResult = await tools2.executeCommand({ command: "git", args: ["diff", "--name-status", "HEAD~1", "HEAD"] });
     const changedFiles = parseGitDiffNameStatus(diffResult.stdout);
     if (changedFiles.length === 0) {
-      logger.info(`ℹ️  No files were changed. Skipping review.
+      logger.info(`No files were changed. Skipping review.
 `);
       return { passed: true };
     }
     logger.info(`
-\uD83D\uDD0E Review iteration ${i + 1}/${MAX_REVIEW_RETRIES}`);
+Review iteration ${i + 1}/${MAX_REVIEW_RETRIES}`);
     logger.info(`   Changed files: ${changedFiles.length}`);
     const changeInfo = {
       commitRange: "HEAD~1...HEAD",
@@ -80432,16 +80715,16 @@ ${formatReviewToolInput(changeInfo)}`;
       }, context);
     });
     if (reviewAgentResult.type !== "Exit" /* Exit */) {
-      logger.error(`\uD83D\uDEAB Review agent failed with status: ${reviewAgentResult.type}.`);
+      logger.error(`Review agent failed with status: ${reviewAgentResult.type}.`);
       break;
     }
     const reviewResult = reviewAgentResult.object;
     if (!reviewResult || !reviewResult.specificReviews || reviewResult.specificReviews.length === 0) {
-      logger.info(`✅ Review passed. No issues found.
+      logger.info(`Review passed. No issues found.
 `);
       return { passed: true };
     }
-    logger.warn(`⚠️  Review found ${reviewResult.specificReviews.length} issue(s). Attempting to fix...
+    logger.warn(`Warning: Review found ${reviewResult.specificReviews.length} issue(s). Attempting to fix...
 `);
     for (const [idx, review] of reviewResult.specificReviews.entries()) {
       logger.warn(`   ${idx + 1}. ${review.file}:${review.lines}`);
@@ -80462,7 +80745,12 @@ After an initial implementation, a review found the following issues. Please fix
 
 ${reviewSummary}`;
     await step(`fix-${iterationCount}-${i}`, async () => {
-      await codeWorkflow({ task: fixTask, mode: "noninteractive" }, context);
+      await codeWorkflow({
+        task: fixTask,
+        mode: "noninteractive",
+        additionalInstructions: TODO_HANDLING_INSTRUCTIONS,
+        additionalTools: [getTodoItem_default, listTodoItems_default, updateTodoItem_default]
+      }, context);
     });
     await step(`commit-fix-${iterationCount}-${i}`, async () => {
       await tools2.executeCommand({ command: "git", args: ["add", "."] });
@@ -80470,7 +80758,7 @@ ${reviewSummary}`;
     });
     if (i === MAX_REVIEW_RETRIES - 1) {
       logger.error(`
-\uD83D\uDEAB Max retries (${MAX_REVIEW_RETRIES}) reached. Moving to the next task, but issues might remain.
+Max retries (${MAX_REVIEW_RETRIES}) reached. Moving to the next task, but issues might remain.
 `);
       return { passed: false };
     }
@@ -80480,7 +80768,7 @@ ${reviewSummary}`;
 async function runImplementationLoop(context, highLevelPlan) {
   const { logger, step, tools: tools2 } = context;
   const commitMessages = [];
-  logger.info(`\uD83D\uDE80 Phase 5: Iterative Implementation Loop...
+  logger.info(`Phase 5: Iterative Implementation Loop...
 `);
   logger.info(`${"=".repeat(80)}
 `);
@@ -80502,9 +80790,9 @@ async function runImplementationLoop(context, highLevelPlan) {
     iterationCount++;
     const taskStartTime = Date.now();
     logger.info(`
-${"━".repeat(80)}`);
-    logger.info(`\uD83D\uDCCC Iteration ${iterationCount}`);
-    logger.info(`${"━".repeat(80)}`);
+${"-".repeat(80)}`);
+    logger.info(`Iteration ${iterationCount}`);
+    logger.info(`${"-".repeat(80)}`);
     logger.info(`${nextTask}
 `);
     await step(`task-${iterationCount}`, async () => {
@@ -80518,7 +80806,12 @@ Your current task is to implement this specific item:
 ${nextTask}
 
 Focus only on this item, but use the plan for context.`;
-      return await codeWorkflow({ task: taskWithContext, mode: "noninteractive" }, context);
+      return await codeWorkflow({
+        task: taskWithContext,
+        mode: "noninteractive",
+        additionalInstructions: TODO_HANDLING_INSTRUCTIONS,
+        additionalTools: [getTodoItem_default, listTodoItems_default, updateTodoItem_default]
+      }, context);
     });
     const commitMessage = `feat: ${nextTask}`;
     await step(`commit-initial-${iterationCount}`, async () => {
@@ -80530,9 +80823,9 @@ Focus only on this item, but use the plan for context.`;
     const taskElapsed = Date.now() - taskStartTime;
     const taskElapsedTime = formatElapsedTime(taskElapsed);
     if (reviewPassed) {
-      logger.info(`✅ Iteration ${iterationCount} completed successfully (${taskElapsedTime})`);
+      logger.info(`Iteration ${iterationCount} completed successfully (${taskElapsedTime})`);
     } else {
-      logger.warn(`⚠️  Iteration ${iterationCount} completed with potential issues (${taskElapsedTime})`);
+      logger.warn(`Warning: Iteration ${iterationCount} completed with potential issues (${taskElapsedTime})`);
     }
     await step(`update-task-status-${iterationCount}`, async () => {
       if (!nextTaskId) {
@@ -80563,53 +80856,47 @@ Focus only on this item, but use the plan for context.`;
       progressMessage = `Iteration ${iterationCount} completed`;
     }
     logger.info(`
-\uD83D\uDCCA Progress: ${progressMessage}`);
+Progress: ${progressMessage}`);
     if (isComplete) {
-      logger.info(`✅ All tasks complete!
+      logger.info(`All tasks complete!
 `);
       break;
     }
     if (nextTask) {
-      logger.info(`\uD83D\uDCCC Next task: ${nextTask}
+      logger.info(`Next task: ${nextTask}
 `);
     }
-    logger.info(`${"━".repeat(80)}
+    logger.info(`${"-".repeat(80)}
 `);
   }
   return commitMessages;
 }
-async function performFinalReviewAndFix(context, highLevelPlan) {
+async function performFinalReviewAndFix(context, highLevelPlan, baseBranch) {
   const { logger, step, tools: tools2 } = context;
   logger.info(`
 Phase 6: Final Review and Fixup...
 `);
-  const ghCheckResult = await tools2.executeCommand({ command: "gh", args: ["--version"] });
-  if (ghCheckResult.exitCode !== 0) {
-    logger.warn("⚠️  GitHub CLI (gh) is not installed. Skipping final review step. Please install it from https://cli.github.com/ to enable final reviews.");
+  if (!baseBranch) {
+    logger.warn("Warning: Base branch is not defined. Skipping final review step.");
     return { passed: true };
   }
-  const defaultBranchResult = await tools2.executeCommand({
-    command: "gh",
-    args: ["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]
-  });
-  const defaultBranch = defaultBranchResult.stdout.trim();
   const currentBranchResult = await tools2.executeCommand({ command: "git", args: ["rev-parse", "--abbrev-ref", "HEAD"] });
   const currentBranch = currentBranchResult.stdout.trim();
-  if (currentBranch === defaultBranch) {
-    logger.info(`✅ You are on the default branch ('${defaultBranch}'). No final review needed.`);
+  if (currentBranch === baseBranch) {
+    logger.info(`You are on the base branch ('${baseBranch}'). No final review needed.`);
     return { passed: true };
   }
-  const commitRange = `${defaultBranch}...${currentBranch}`;
+  const commitRange = `${baseBranch}...${currentBranch}`;
   for (let i = 0;i < MAX_REVIEW_RETRIES; i++) {
     const diffResult = await tools2.executeCommand({ command: "git", args: ["diff", "--name-status", commitRange] });
     const changedFiles = parseGitDiffNameStatus(diffResult.stdout);
     if (changedFiles.length === 0) {
-      logger.info(`ℹ️  No files have been changed in this branch. Skipping final review.
+      logger.info(`No files have been changed in this branch. Skipping final review.
 `);
       return { passed: true };
     }
     logger.info(`
-\uD83D\uDD0E Final review iteration ${i + 1}/${MAX_REVIEW_RETRIES}`);
+Final review iteration ${i + 1}/${MAX_REVIEW_RETRIES}`);
     logger.info(`   Changed files: ${changedFiles.length}`);
     const changeInfo = {
       commitRange,
@@ -80630,16 +80917,16 @@ ${formatReviewToolInput(changeInfo)}`;
       }, context);
     });
     if (reviewAgentResult.type !== "Exit" /* Exit */) {
-      logger.error(`\uD83D\uDEAB Review agent failed with status: ${reviewAgentResult.type}.`);
+      logger.error(`Review agent failed with status: ${reviewAgentResult.type}.`);
       break;
     }
     const reviewResult = reviewAgentResult.object;
     if (!reviewResult || !reviewResult.specificReviews || reviewResult.specificReviews.length === 0) {
-      logger.info(`✅ Final review passed. No issues found.
+      logger.info(`Final review passed. No issues found.
 `);
       return { passed: true };
     }
-    logger.warn(`⚠️  Final review found ${reviewResult.specificReviews.length} issue(s). Attempting to fix...
+    logger.warn(`Warning: Final review found ${reviewResult.specificReviews.length} issue(s). Attempting to fix...
 `);
     for (const [idx, review] of reviewResult.specificReviews.entries()) {
       logger.warn(`   ${idx + 1}. ${review.file}:${review.lines}`);
@@ -80659,7 +80946,12 @@ A final review of all the changes in the branch found the following issues. Plea
 
 ${reviewSummary}`;
     await step(`final-fix-${i}`, async () => {
-      await codeWorkflow({ task: fixTask, mode: "noninteractive" }, context);
+      await codeWorkflow({
+        task: fixTask,
+        mode: "noninteractive",
+        additionalInstructions: TODO_HANDLING_INSTRUCTIONS,
+        additionalTools: [getTodoItem_default, listTodoItems_default, updateTodoItem_default]
+      }, context);
     });
     await step(`commit-final-fix-${i}`, async () => {
       await tools2.executeCommand({ command: "git", args: ["add", "."] });
@@ -80667,65 +80959,93 @@ ${reviewSummary}`;
     });
     if (i === MAX_REVIEW_RETRIES - 1) {
       logger.error(`
-\uD83D\uDEAB Max retries (${MAX_REVIEW_RETRIES}) reached for final review. Issues might remain.
+Max retries (${MAX_REVIEW_RETRIES}) reached for final review. Issues might remain.
 `);
       return { passed: false };
     }
   }
   return { passed: false };
 }
-var epicWorkflow = async (input2, context) => {
-  const { logger } = context;
-  const { task } = input2;
+var epicWorkflow = async (epicContext, context) => {
+  const { logger, tools: tools2 } = context;
+  const { task } = epicContext;
   const workflowStartTime = Date.now();
-  let branchName = "";
   if (!task || task.trim() === "") {
-    logger.error("❌ Error: Task cannot be empty. Please provide a valid task description.");
+    logger.error("Error: Task cannot be empty. Please provide a valid task description.");
     return;
   }
+  if (!epicContext.task) {
+    epicContext.task = task;
+  }
   try {
-    const preflightResult = await runPreflightChecks(context);
-    if (!preflightResult.success) {
+    const preflightResult = await runPreflightChecks(epicContext, context);
+    if (!preflightResult) {
       return;
     }
-    const planResult = await createAndApprovePlan(task, context);
-    if (!planResult) {
+    if (!epicContext.plan) {
+      if (!epicContext.task) {
+        logger.error("Error: Task is missing in epic context. Exiting.");
+        return;
+      }
+      const planResult = await createAndApprovePlan(epicContext.task, context);
+      if (!planResult)
+        return;
+      epicContext.plan = planResult.plan;
+      epicContext.branchName = planResult.branchName;
+      await saveEpicContext(epicContext);
+    }
+    if (!epicContext.plan) {
+      logger.error("Error: Plan is missing after planning phase. Exiting.");
+      return;
+    }
+    if (!epicContext.branchName) {
+      logger.error("Error: Branch name is missing after planning phase. Exiting.");
       return;
     }
-    const { plan: highLevelPlan } = planResult;
-    branchName = planResult.branchName;
-    const branchResult = await createFeatureBranch(branchName, context);
-    if (!branchResult.success || !branchResult.branchName) {
+    const branchResult = await createFeatureBranch(epicContext.branchName, epicContext.baseBranch ?? undefined, context);
+    if (!branchResult.success || !branchResult.branchName)
       return;
+    if (epicContext.branchName !== branchResult.branchName) {
+      epicContext.branchName = branchResult.branchName;
+      await saveEpicContext(epicContext);
+    }
+    const todos = await tools2.listTodoItems({});
+    if (todos.length === 0) {
+      await addTodoItemsFromPlan(epicContext.plan, context);
+    }
+    const commitMessages = await runImplementationLoop(context, epicContext.plan);
+    await performFinalReviewAndFix(context, epicContext.plan, epicContext.baseBranch ?? undefined);
+    await tools2.executeCommand({ command: "git", args: ["rm", "-f", ".epic.yml"] });
+    const statusResult = await tools2.executeCommand({
+      command: "git",
+      args: ["status", "--porcelain", "--", ".epic.yml"]
+    });
+    if (statusResult.stdout.trim() !== "") {
+      await tools2.executeCommand({ command: "git", args: ["commit", "-m", "chore: remove .epic.yml", "--", ".epic.yml"] });
+      logger.info("Cleaned up .epic.yml file.");
     }
-    branchName = branchResult.branchName;
-    await addTodoItemsFromPlan(highLevelPlan, context);
-    const commitMessages = await runImplementationLoop(context, highLevelPlan);
-    await performFinalReviewAndFix(context, highLevelPlan);
     const totalElapsed = Date.now() - workflowStartTime;
     const totalElapsedTime = formatElapsedTime(totalElapsed);
-    const iterationCount = commitMessages.length;
     logger.info(`
 ${"=".repeat(80)}`);
-    logger.info("\uD83C\uDF89 Epic Workflow Complete!");
+    logger.info("Epic Workflow Complete!");
     logger.info(`${"=".repeat(80)}`);
     logger.info(`
-\uD83D\uDCCA Summary:`);
-    logger.info(`   Total iterations: ${iterationCount}`);
-    logger.info(`   Total commits: ${commitMessages.length}`);
-    logger.info(`   Branch: ${branchName}`);
+Summary:`);
+    logger.info(`   Branch: ${epicContext.branchName}`);
     logger.info(`   Total time: ${totalElapsedTime}`);
-    logger.info("\uD83D\uDCDD Commits created:");
+    logger.info(`   Total commits: ${commitMessages.length}`);
+    logger.info("Commits created:");
     for (const [idx, msg] of commitMessages.entries()) {
       logger.info(`   ${idx + 1}. ${msg}`);
     }
   } catch (error46) {
     logger.error(`
-❌ Epic workflow failed: ${error46 instanceof Error ? error46.message : String(error46)}`);
-    if (branchName) {
+Epic workflow failed: ${error46 instanceof Error ? error46.message : String(error46)}`);
+    if (epicContext?.branchName) {
       logger.info(`
-Branch '${branchName}' was created but work is incomplete.`);
-      logger.info(`To cleanup: git checkout <previous-branch> && git branch -D ${branchName}
+Branch '${epicContext.branchName}' was created but work is incomplete.`);
+      logger.info(`To cleanup: git checkout <previous-branch> && git branch -D ${epicContext.branchName}
 `);
     }
     throw error46;
@@ -80740,7 +81060,7 @@ var taskWorkflow = async (input2, context) => {
   const { logger, step } = context;
   const { task } = input2;
   logger.info(`
-\uD83E\uDD16 Running generic agent...
+Running generic agent...
 `);
   await step("agent", async () => {
     const defaultContext = await getDefaultContext();
@@ -80765,7 +81085,7 @@ ${defaultContext}`;
     }, context);
   });
   logger.info(`
-✅ Agent finished!
+Agent finished!
 `);
   return { success: true };
 };
@@ -80778,7 +81098,7 @@ var metaWorkflow = async (input2, context) => {
   const { task } = input2;
   const { logger } = context;
   logger.info(`
-\uD83E\uDD14 Deciding which workflow to use for task...
+Deciding which workflow to use for task...
 `);
   const result = await agentWorkflow({
     systemPrompt: META_SYSTEM_PROMPT,
@@ -80799,7 +81119,7 @@ var metaWorkflow = async (input2, context) => {
     throw new Error("Could not decide which workflow to run.");
   }
   logger.info(`
-✅ Decision: Using '${decision.workflow}' workflow.`);
+Decision: Using '${decision.workflow}' workflow.`);
   switch (decision.workflow) {
     case "code":
       await codeWorkflow({ task }, context);
@@ -81017,32 +81337,41 @@ var commitCommand = new Command("commit").description("Create a commit with AI-g
 
 // src/commands/epic.ts
 async function runEpic(task2, _options, command) {
+  const globalOpts = (command.parent ?? command).opts();
+  const { verbose, yes } = globalOpts;
+  const logger = createLogger({
+    verbose
+  });
   let taskInput = task2;
-  if (!taskInput) {
-    try {
-      taskInput = await esm_default3({
-        message: "What epic or large feature do you want to implement?"
-      });
-    } catch (error46) {
-      if (error46 instanceof Error && error46.name === "ExitPromptError") {
+  const epicContext = await loadEpicContext();
+  if (epicContext.task) {
+    if (taskInput) {
+      logger.error("Error: Existing epic context found, but task was provided via CLI args. Exiting.");
+      return;
+    }
+    logger.info("Resuming existing epic session. Task:");
+    logger.info(`   ${epicContext.task}`);
+  } else {
+    if (!taskInput) {
+      taskInput = await getUserInput("What feature do you want to implement?");
+      if (!taskInput) {
+        logger.info("No task provided. Exiting.");
         return;
       }
-      throw error46;
     }
+    epicContext.task = taskInput;
   }
-  if (!taskInput) {
-    console.error("No task provided. Aborting.");
-    return;
-  }
-  const workflowInput = {
-    task: taskInput
-  };
-  const globalOpts = (command.parent ?? command).opts();
-  const { verbose, yes } = globalOpts;
-  const logger = createLogger({
-    verbose
+  await runWorkflow(epicWorkflow, epicContext, {
+    commandName: "epic",
+    command,
+    logger,
+    yes,
+    getProvider: (opt) => getProvider({
+      ...opt,
+      todoItemStore: new EpicTodoItemStore(epicContext),
+      memoryStore: new EpicMemoryStore(epicContext)
+    })
   });
-  await runWorkflow(epicWorkflow, workflowInput, { commandName: "epic", command, logger, yes });
 }
 var epicCommand = new Command("epic").description("Orchestrates a large feature or epic, breaking it down into smaller tasks.").argument("[task]", "The epic to plan and implement.").action(runEpic);