zillacore 0.0.1

data/lib/zillacore/planning.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+# Planning mode: interactive requirement gathering and task breakdown.
+#
+# Triggered by [plan] tag in Discord or 'plan' tag in Fizzy cards.
+# Agent asks clarifying questions, logs Q&A to memory, generates a plan
+# markdown file, and creates Fizzy steps for each task.
+
+PLANS_DIR = File.join(ZILLACORE_DIR, "plans")
+FileUtils.mkdir_p(PLANS_DIR)
+
+# Detect if a message/card should trigger planning mode.
+# Returns: { mode: :planning, card_id: '...', card_number: 123 } or nil
+def detect_planning_mode(text:, tags: [], card_internal_id: nil, card_number: nil)
+  # Discord: [plan] anywhere in message
+  # Fizzy: 'plan' tag on card
+  has_plan_tag = text.match?(/\[plan\]/i) || tags.any? { |t| (t.is_a?(Hash) ? t["name"] : t).to_s.downcase == "plan" }
+  return nil unless has_plan_tag
+
+  {
+    mode: :planning,
+    card_id: card_internal_id || "discord-#{Time.now.to_i}",
+    card_number: card_number
+  }
+end
+
+# Check if planning is complete for a given card.
+# Planning is complete when:
+# 1. A plan file exists at PLANS_DIR/card-{id}-plan.md
+# 2. Memory file indicates planning_complete: true
+def planning_complete?(card_id, agent_name)
+  memory_file = File.join(memory_dir_for(agent_name), "card-#{card_id}.md")
+  return false unless File.exist?(memory_file)
+
+  memory_content = File.read(memory_file)
+  memory_content.match?(/planning_complete:\s*true/i)
+end
+
+# Generate plan markdown from memory Q&A and create Fizzy steps.
+# This is called when the agent determines it has enough information.
+def finalize_plan(card_id:, card_number:, agent_name:, project_key:, repo_path:)
+  memory_file = File.join(memory_dir_for(agent_name), "card-#{card_id}.md")
+  unless File.exist?(memory_file)
+    LOG.error "[Planning] Cannot finalize plan — no memory file found for card #{card_id}"
+    return { success: false, error: "No memory file found" }
+  end
+
+  memory_content = File.read(memory_file)
+
+  # Extract Q&A from memory (agents should format it consistently)
+  # Expected format in memory:
+  # ## Planning Q&A
+  # Q: What's the goal?
+  # A: Build a feature that does X
+  # Q: Should it support Y?
+  # A: Yes, and also Z
+
+  plan_file = File.join(PLANS_DIR, "card-#{card_id}-plan.md")
+
+  # The agent should have already written the plan to the file during its session.
+  # This function just validates it exists and creates Fizzy steps.
+  unless File.exist?(plan_file)
+    LOG.error "[Planning] Plan file not found at #{plan_file}"
+    return { success: false, error: "Plan file not generated by agent" }
+  end
+
+  plan_content = File.read(plan_file)
+
+  # Parse tasks from plan markdown.
+  # Expected format:
+  # ## Task Breakdown
+  # ### Task 1: Title
+  # ### Task 2: Title
+  tasks = []
+  plan_content.scan(/^###\s+Task\s+\d+:\s+(.+)$/i) do |match|
+    tasks << match[0].strip
+  end
+
+  if tasks.empty?
+    LOG.warn "[Planning] No tasks found in plan file #{plan_file}"
+    return { success: false, error: "No tasks found in plan" }
+  end
+
+  # Create Fizzy steps for each task
+  if card_number
+    LOG.info "[Planning] Creating #{tasks.size} Fizzy steps for card ##{card_number}"
+    tasks.each do |task_title|
+      run_cmd("fizzy", "step", "create", "--card", card_number.to_s, "--content", task_title,
+              chdir: repo_path, env: fizzy_env_for(agent_name))
+      LOG.info "[Planning] Created step: #{task_title}"
+    rescue StandardError => e
+      LOG.error "[Planning] Failed to create step '#{task_title}': #{e.message}"
+    end
+  end
+
+  # Mark planning as complete in memory
+  updated_memory = memory_content.sub(/planning_complete:\s*false/i, "planning_complete: true")
+  updated_memory += "\n\nplanning_complete: true\n" unless updated_memory.include?("planning_complete: true")
+  File.write(memory_file, updated_memory)
+
+  LOG.info "[Planning] Plan finalized for card #{card_id}: #{plan_file}"
+  { success: true, plan_file: plan_file, tasks: tasks }
+end
+
+# Planning mode prompt — prepended to the core prompt.
+PROMPT_PLANNING_MODE = <<~PROMPT
+  ## Planning Mode (ACTIVE)
+
+  You are in **planning mode**. Your job is to gather requirements and break down the work into actionable tasks.
+
+  ### Your Role
+  - Ask clarifying questions to understand the problem, constraints, and desired outcome
+  - Continue asking until you have a clear picture (don't rush to a plan)
+  - Understand user intent naturally — "go ahead", "that's enough", "proceed" all mean the same thing
+  - When you have enough information OR the user signals they're ready, generate the plan
+
+  ### Question Guidelines
+  - Ask specific, focused questions (not generic "anything else?")
+  - Build on previous answers — reference what you've learned
+  - Prioritize questions that would significantly change the approach
+  - If you're 90% confident, proceed. If you're 60% confident, ask.
+
+  ### When to Stop Asking
+  The user will signal they're ready in natural language:
+  - "go ahead", "proceed", "that's enough", "looks good", "yeah do it"
+  - "I think you have enough", "start working", "make the plan"
+
+  You should also stop if:
+  - You've asked 5+ questions and have a clear understanding
+  - The user is getting impatient or frustrated
+  - The remaining unknowns are minor details you can decide yourself
+
+  ### Generating the Plan
+  When ready, create a plan file at `{{PLAN_FILE}}` with this structure:
+
+  ```markdown
+  # Feature: [Title]
+
+  ## Problem Statement
+  [What we're solving and why]
+
+  ## Requirements
+  - Requirement 1
+  - Requirement 2
+  - Requirement 3
+
+  ## Approach
+  [High-level strategy and key decisions]
+
+  ## Task Breakdown
+  ### Task 1: [Clear, actionable title]
+  - **Objective**: [What this task accomplishes]
+  - **Approach**: [How to implement it]
+  - **Demo**: [What "done" looks like]
+
+  ### Task 2: [Clear, actionable title]
+  - **Objective**: [What this task accomplishes]
+  - **Approach**: [How to implement it]
+  - **Demo**: [What "done" looks like]
+
+  [Continue for all tasks...]
+  ```
+
+  ### Memory Management
+  Log every question and answer to your memory file in this format:
+
+  ```
+  ## Planning Q&A
+  Q: [Your question]
+  A: [User's answer]
+
+  Q: [Next question]
+  A: [User's answer]
+  ```
+
+  Also track:
+  - `planning_complete: false` (update to `true` when plan is generated)
+  - Key decisions and constraints discovered
+  - Any blockers or unknowns that remain
+
+  ### After Planning
+  Once you've written the plan file:
+  1. Update memory with `planning_complete: true`
+  2. Post a comment summarizing the plan and linking to the file
+  3. The system will automatically create Fizzy steps from your task breakdown
+
+  ### Important
+  - You are READ-ONLY during planning — no code changes, no commits
+  - Focus on understanding the problem, not solving it yet
+  - The plan should be detailed enough that any agent could execute it
+  - Task titles should be clear and actionable (they become Fizzy step names)
+
+PROMPT
+
+# Render planning mode prompt with appropriate channel rules.
+def render_planning_prompt(situation_template, vars = {}, brain_context: "", card_context: "", agent_name: AI_AGENT_NAME, channel: :fizzy,
+                           board_key: nil)
+  result = ""
+  result += "#{brain_context}\n" unless brain_context.empty?
+  result += card_context unless card_context.empty?
+  result += PROMPT_CORE
+
+  # Add planning mode instructions BEFORE channel rules
+  plan_file = File.join(PLANS_DIR, "card-#{vars["CARD_ID"]}-plan.md")
+  planning_vars = vars.merge("PLAN_FILE" => plan_file)
+  result += PROMPT_PLANNING_MODE.gsub("{{PLAN_FILE}}", plan_file)
+
+  result += CHANNEL_PROMPTS.fetch(channel, PROMPT_FIZZY_CHANNEL)
+  result += situation_template
+  result += PROMPT_REFLECTION
+
+  planning_vars["KNOWLEDGE_DIR"] ||= KNOWLEDGE_DIR
+  planning_vars["MEMORY_DIR"] ||= memory_dir_for(agent_name)
+  planning_vars["PERSONA_DIR"] ||= persona_dir_for(agent_name)
+  planning_vars["PERSONA_COLLECTION"] ||= persona_collection_for(agent_name)
+  planning_vars["AGENT_NAME"] ||= agent_name
+
+  # Populate column IDs from board config, falling back to defaults
+  DEFAULT_COLUMN_IDS.each do |col_name, default_id|
+    var_name = "#{col_name.upcase}_COLUMN_ID"
+    planning_vars[var_name] ||= (board_key && board_column_id(board_key, col_name)) || default_id
+  end
+
+  # Touch memory file if CARD_ID is present — ensures file exists before agent tries to read it
+  if vars["CARD_ID"]
+    memory_file = File.join(planning_vars["MEMORY_DIR"], "card-#{vars["CARD_ID"]}.md")
+    FileUtils.mkdir_p(planning_vars["MEMORY_DIR"])
+    FileUtils.touch(memory_file)
+  end
+
+  roster = agent_roster
+  roster_lines = roster.map { |_key, display| "  - @#{display}" }.join("\n")
+  planning_vars["AGENT_ROSTER"] ||= roster_lines
+
+  planning_vars.each { |key, val| result.gsub!("{{#{key}}}", val.to_s) }
+  result
+end