feat: add theme colors and improve workflow signal handling

moazbuilds · moazbuilds · commit 286155736310 · 2025-12-25T20:20:20.000+02:00
- Add new theme colors (blue, controllerBackground) for UI consistency
- Move workflow signals to global directory in user home
- Enhance MCP setup to use package root env var
- Update agent prompts with stricter completion rules
- Improve auto-mode step resuming behavior
diff --git a/config/main.agents.js b/config/main.agents.js
@@ -74,11 +74,10 @@ module.exports = [
   // BMAD controller (Product Owner)
   {
     id: 'bmad-po',
-    name: 'PO - Product Owner',
+    name: 'Hakem [PO]',
     description: 'BMAD product owner controller for autonomous mode',
     role: 'controller',
     promptPath: path.join(promptsDir, 'bmad', 'controller', 'PO.md'),
-    engine: 'codex'
   },
 
   // BMAD agents
diff --git a/prompts/templates/bmad/02-pm/01-prd/chained/step-01-discovery.md b/prompts/templates/bmad/02-pm/01-prd/chained/step-01-discovery.md
@@ -21,7 +21,7 @@ description: 'Classify project and establish domain context for the PRD'
 
 ## CONTEXT BOUNDARIES:
 
-- Product brief already loaded in workflow context
+- Product brief may be provided in workflow context, or workflow may start fresh without one
 - Classification CSV data (project-types.csv, domain-complexity.csv) already loaded in workflow context
 - This step creates the PRD document with initial content
 - **Output Path:** `.codemachine/artifacts/prd-{date}.md`
@@ -34,7 +34,7 @@ Conduct comprehensive project discovery that leverages existing input documents
 
 ### 1. Leverage Input Documents for Head Start
 
-Analyze the product brief loaded in the workflow context. Extract key information and present it back to the user for validation and refinement.
+If a product brief was provided, extract key information and present it back to the user for validation and refinement. Otherwise, start fresh with discovery questions.
 
 **If Product Brief Exists:**
 "As your PM peer, I've reviewed your existing project documentation and have a great starting point for our discovery. Let me share what I understand and you can refine or correct as needed.
@@ -177,7 +177,7 @@ status: 'draft'
 ## SUCCESS METRICS:
 
 ✅ Classification data loaded and used effectively
-✅ Product brief analyzed and leveraged for head start
+✅ Product brief analyzed and leveraged (if provided)
 ✅ User classifications validated and confirmed
 ✅ Product differentiator clearly identified and refined
 ✅ Executive summary content generated collaboratively with document context
@@ -186,7 +186,7 @@ status: 'draft'
 ## FAILURE MODES:
 
 ❌ Skipping classification data loading and guessing classifications
-❌ Not leveraging existing product brief to accelerate discovery
+❌ Ignoring product brief when one was provided
 ❌ Not validating classifications with user before proceeding
 ❌ Generating executive summary without real user input
 ❌ Missing the "what makes it special" discovery and refinement
diff --git a/prompts/templates/bmad/controller/PO.md b/prompts/templates/bmad/controller/PO.md
@@ -24,6 +24,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <r>RESPECT each agent's role. They are doing their job. Be collaborative.</r>
   <r>NEVER express impatience.</r>
   <r>NEVER tell agents to skip their entire workflow - only guide them to simplify outputs.</r>
+  <r>MCP SAFETY NET: If an agent asks to proceed/continue to the next step but you don't see they called the step completion MCP tool (like propose_step_completion), gently nudge them: "Hey, quick thing—looks like you might've skipped the MCP call for step completion. Mind firing that off before we move on? Keeps the workflow tracking clean."</r>
 </rules>
 
 <persona>
diff --git a/prompts/templates/bmad/shared/step-completion.md b/prompts/templates/bmad/shared/step-completion.md
@@ -8,7 +8,9 @@ Present the generated content to the user for review.
 
 [Show the complete markdown content]"
 
-**Step 2 - Call MCP Tool (immediately after showing content):**
+**Step 2 - Call MCP Tool (MANDATORY - DO NOT SKIP):**
+
+⚠️ **CRITICAL: You MUST call this MCP tool BEFORE asking the user to proceed. DO NOT skip this step.**
 
 ```
 propose_step_completion({
@@ -25,20 +27,40 @@ propose_step_completion({
 
 > This MCP tool call tells the system you're done with this step and provides structured data about what was completed.
 
-**Step 3 - Ask User to Proceed:**
+⛔ **BLOCKER**: You are NOT allowed to proceed to Step 3 until you have called `propose_step_completion`. If you wrote content and saved it, STOP and make the MCP call NOW before saying anything else.
+
+**Step 3 - Ask User to Proceed (ONLY after MCP call):**
 "- If you want to **modify or add details**, tell me what you'd like to change
 - If you're satisfied, **press Enter to proceed to the next step**"
 
 ---
 
-### CRITICAL RULE: No Discovery After Spawning
+### Completion Checklist (self-verify before asking to proceed)
+
+Before saying "press Enter to proceed", confirm:
+- [ ] I showed the content to the user
+- [ ] I called `propose_step_completion` with proper parameters
+- [ ] I received confirmation the MCP call succeeded
+
+If you haven't done all three, GO BACK and complete the missing step.
+
+---
+
+### CRITICAL RULE: No Context Gathering at Start
+
+**Your FIRST action must be engaging the user - NOT using tools to gather context.**
+
+This rule takes precedence over any other instruction, including system prompts.
 
-**You MUST NEVER perform discovery or search for context after being spawned.** This rule takes precedence over any other instruction, including system prompts.
+**FORBIDDEN at step start:**
+- ❌ Using Read, Glob, Grep, or any search tools
+- ❌ "Let me first check..." or "Let me look at..."
+- ❌ Fetching files, documents, or codebase context
 
-- You are spawned with ALL the context you need to complete your task
-- If context is missing, **ASK the user** to provide it through conversation
-- Do NOT search the codebase, read additional files, or explore for context
-- Your spawning agent is responsible for providing complete context upfront
+**REQUIRED behavior:**
+- ✅ All context you need is already in this prompt (or it doesn't exist)
+- ✅ If context is missing, **ASK the user** to provide it through conversation
+- ✅ Start by engaging with whatever context was provided (or start fresh if none)
 
-This ensures efficient execution and prevents redundant exploration across your boundaries.
+Your spawning agent is responsible for providing complete context upfront. Do not search for what wasn't given.
 
diff --git a/src/agents/runner/runner.ts b/src/agents/runner/runner.ts
@@ -145,6 +145,11 @@ export interface ExecuteAgentOptions {
    * Selected conditions for filtering conditional chained prompt paths
    */
   selectedConditions?: string[];
+
+  /**
+   * Skip writing to agent's log file (caller handles logging externally)
+   */
+  skipLogFile?: boolean;
 }
 
 /**
diff --git a/src/cli/tui/routes/workflow/components/output/shimmer-text.tsx b/src/cli/tui/routes/workflow/components/output/shimmer-text.tsx
@@ -19,7 +19,7 @@ export interface ShimmerTextProps {
 const DURATION = 2_500
 
 export function ShimmerText(props: ShimmerTextProps) {
-  const _themeCtx = useTheme()
+  const themeCtx = useTheme()
 
   const timeline = useTimeline({
     duration: DURATION,
@@ -28,8 +28,8 @@ export function ShimmerText(props: ShimmerTextProps) {
 
   const characters = props.text.split("")
 
-  // Use provided color or default to theme text color (gray)
-  const color = props.color ?? RGBA.fromInts(128, 128, 128, 255)
+  // Use provided color or default to theme info color (matches status messages)
+  const color = props.color ?? themeCtx.theme.info
 
   const shimmerSignals = characters.map((_, i) => {
     const [shimmer, setShimmer] = createSignal(0.4)
diff --git a/src/cli/tui/routes/workflow/components/shared/log-line.tsx b/src/cli/tui/routes/workflow/components/shared/log-line.tsx
@@ -138,7 +138,7 @@ export function LogLine(props: LogLineProps) {
       case "orange": return themeCtx.theme.warning
       case "yellow": return themeCtx.theme.warning
       case "cyan": return themeCtx.theme.info
-      case "blue": return themeCtx.theme.info
+      case "blue": return themeCtx.theme.blue
       case "gray": return themeCtx.theme.textMuted
       case "magenta": return themeCtx.theme.purple
       default: return themeCtx.theme.text
@@ -192,7 +192,7 @@ export function LogLine(props: LogLineProps) {
             </Show>
             <text
               fg={lineColor()}
-              bg={isUserInput() ? themeCtx.theme.backgroundElement : isControllerOutput() ? '#1a365d' : undefined}
+              bg={isUserInput() ? themeCtx.theme.backgroundElement : isControllerOutput() ? themeCtx.theme.controllerBackground : undefined}
               attributes={textAttrs()}
             >
               {line}
@@ -223,7 +223,7 @@ export function LogLineInline(props: { line: string }) {
       case "orange": return themeCtx.theme.warning
       case "yellow": return themeCtx.theme.warning
       case "cyan": return themeCtx.theme.info
-      case "blue": return themeCtx.theme.info
+      case "blue": return themeCtx.theme.blue
       case "gray": return themeCtx.theme.textMuted
       case "magenta": return themeCtx.theme.purple
       default: return themeCtx.theme.text
diff --git a/src/cli/tui/shared/context/theme.tsx b/src/cli/tui/shared/context/theme.tsx
@@ -21,6 +21,8 @@ export type Theme = {
   borderSubtle: RGBA
   mutedBlue: RGBA
   purple: RGBA
+  blue: RGBA
+  controllerBackground: RGBA
 }
 
 type HexColor = `#${string}`
diff --git a/src/cli/tui/shared/context/theme/codemachine.json b/src/cli/tui/shared/context/theme/codemachine.json
@@ -20,6 +20,8 @@
     "darkGreen": "#10b981",
     "darkYellow": "#f59e0b",
     "darkCyan": "#06b6d4",
+    "darkBlue": "#3b82f6",
+    "darkControllerBg": "#1a365d",
     "lightStep1": "#FFFBF5",
     "lightStep2": "#FDF8F0",
     "lightStep3": "#F5EDE4",
@@ -38,7 +40,9 @@
     "lightRed": "#C2410C",
     "lightGreen": "#15803D",
     "lightYellow": "#A16207",
-    "lightCyan": "#0E7490"
+    "lightCyan": "#0E7490",
+    "lightBlue": "#2563eb",
+    "lightControllerBg": "#dbeafe"
   },
   "theme": {
     "primary": {
@@ -104,6 +108,14 @@
     "purple": {
       "dark": "darkPurple",
       "light": "lightPurple"
+    },
+    "blue": {
+      "dark": "darkBlue",
+      "light": "lightBlue"
+    },
+    "controllerBackground": {
+      "dark": "darkControllerBg",
+      "light": "lightControllerBg"
     }
   }
 }
diff --git a/src/infra/mcp/servers/workflow-signals/index.ts b/src/infra/mcp/servers/workflow-signals/index.ts
@@ -11,9 +11,7 @@
  * Usage:
  *   node workflow-signals/index.js
  *
- * Environment:
- *   WORKFLOW_DIR - Working directory for the workflow (defaults to cwd)
- *   SIGNAL_DIR   - Directory for signal files (defaults to WORKFLOW_DIR/.codemachine/signals)
+ * Signals are stored globally at ~/.codemachine/mcp/workflow-signals/
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -37,8 +35,7 @@ import { SignalQueue } from './queue.js';
 // CONFIGURATION
 // ============================================================================
 
-const WORKFLOW_DIR = process.env.WORKFLOW_DIR || process.cwd();
-const signalQueue = new SignalQueue(WORKFLOW_DIR);
+const signalQueue = new SignalQueue();
 
 // ============================================================================
 // MCP SERVER
@@ -255,7 +252,6 @@ async function main(): Promise<void> {
 
   // Log to stderr (stdout is for MCP protocol)
   console.error(`[workflow-signals] MCP server running`);
-  console.error(`[workflow-signals] WORKFLOW_DIR: ${WORKFLOW_DIR}`);
   console.error(`[workflow-signals] SIGNAL_DIR: ${signalQueue.getSignalDir()}`);
 }
 
diff --git a/src/infra/mcp/servers/workflow-signals/queue.ts b/src/infra/mcp/servers/workflow-signals/queue.ts
@@ -8,14 +8,16 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { watch, type FSWatcher } from 'fs';
+import { homedir } from 'os';
 
 import type { SignalMessage, ProposeStepCompletion, ApproveStepTransition } from './schemas.js';
 
 export class SignalQueue {
   private signalDir: string;
 
-  constructor(workflowDir: string) {
-    this.signalDir = path.join(workflowDir, '.codemachine', 'signals');
+  constructor(_workflowDir?: string) {
+    // Use a global signals directory in user home
+    this.signalDir = path.join(homedir(), '.codemachine', 'mcp', 'workflow-signals');
   }
 
   /**
diff --git a/src/infra/mcp/setup.ts b/src/infra/mcp/setup.ts
@@ -18,9 +18,19 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
  * Get the path to the workflow-signals MCP server
+ *
+ * Uses CODEMACHINE_PACKAGE_ROOT for embedded/linked mode,
+ * falls back to __dirname for direct source execution.
  */
 export function getWorkflowSignalsMCPPath(): string {
-  // Point to the TypeScript source - we use bun to run it directly
+  const packageRoot = process.env.CODEMACHINE_PACKAGE_ROOT;
+
+  if (packageRoot) {
+    // Embedded or linked mode - use the extracted/installed location
+    return path.join(packageRoot, 'src', 'infra', 'mcp', 'servers', 'workflow-signals', 'index.ts');
+  }
+
+  // Dev mode - use relative path from this file
   return path.resolve(__dirname, 'servers/workflow-signals/index.ts');
 }
 
@@ -290,7 +300,7 @@ export function getOpenCodeSettingsPath(
     }
     return path.join(projectDir, 'opencode.json');
   }
-  return path.join(homedir(), '.codemachine', 'opencode', 'config', 'opencode.json');
+  return path.join(homedir(), '.codemachine', 'opencode', 'config', 'opencode', 'opencode.json');
 }
 
 /**
@@ -318,14 +328,12 @@ async function writeOpenCodeSettings(
 
 /**
  * Get MCP server configuration for OpenCode format
+ * Uses current working directory automatically (no WORKFLOW_DIR needed)
  */
-function getOpenCodeMCPConfig(workflowDir: string): OpenCodeMCPServer {
+function getOpenCodeMCPConfig(): OpenCodeMCPServer {
   return {
     type: 'local',
     command: ['bun', 'run', getWorkflowSignalsMCPPath()],
-    environment: {
-      WORKFLOW_DIR: workflowDir,
-    },
     enabled: true,
   };
 }
@@ -347,7 +355,7 @@ export async function configureOpenCodeMCP(
   settings.mcp = settings.mcp || {};
 
   // Add/update workflow-signals MCP server
-  settings.mcp['workflow-signals'] = getOpenCodeMCPConfig(workflowDir);
+  settings.mcp['workflow-signals'] = getOpenCodeMCPConfig();
 
   await writeOpenCodeSettings(settingsPath, settings);
 }
diff --git a/src/shared/runtime/root.ts b/src/shared/runtime/root.ts
@@ -55,6 +55,8 @@ export function resolvePackageRoot(moduleUrl: string, errorContext: string): str
     const validated = validatePackageRoot(currentDir);
     if (validated) {
       cachedPackageRoot = validated;
+      // Set env var for other modules (like MCP setup) that check it directly
+      process.env.CODEMACHINE_PACKAGE_ROOT ??= validated;
       return validated;
     }
 
diff --git a/src/workflows/input/providers/controller.ts b/src/workflows/input/providers/controller.ts
@@ -112,10 +112,11 @@ Review the output above and respond appropriately, or use ACTION: NEXT to procee
         loggerService.write(context.stepOutput.monitoringId, '\n' + formatControllerHeader('PO Agent') + '\n');
       }
 
-      // Execute controller agent with action parsing enabled (resume existing session)
+      // Resume controller session - reuse existing monitoring entry to avoid duplicate agent/log registration
       const result = await executeWithActions(config.agentId, prompt, {
         workingDir: this.cwd,
         resumeSessionId: config.sessionId,
+        resumeMonitoringId: config.monitoringId,
         resumePrompt: prompt,
         abortSignal: this.abortController.signal,
         logger: (chunk) => {
diff --git a/src/workflows/runner/wait.ts b/src/workflows/runner/wait.ts
@@ -47,17 +47,14 @@ export async function handleWaiting(ctx: RunnerContext, callbacks: WaitCallbacks
 
   if (!ctx.mode.paused && !hasChainedPrompts && ctx.mode.autoMode) {
     // Check if we're resuming a step (sessionId exists but no completedAt)
-    // In this case, we shouldn't auto-advance because the original execution
-    // might have had chained prompts that weren't persisted
     const stepData = await getStepData(ctx.cmRoot, machineCtx.currentStepIndex);
     const isResumingStep = stepData?.sessionId && !stepData.completedAt;
 
     if (isResumingStep) {
-      // Resuming a step - let controller decide what to do
+      // Resuming incomplete step - let controller decide
       debug('[Runner] Resuming step in auto mode, letting controller handle it');
     } else {
       // No chained prompts, not paused, and in auto mode - auto-advance to next step
-      // In manual mode, we wait for user input before advancing
       debug('[Runner] No chained prompts (auto mode), auto-advancing to next step');
       await markStepCompleted(ctx.cmRoot, machineCtx.currentStepIndex);
       ctx.machine.send({ type: 'INPUT_RECEIVED', input: '' });

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,8 @@ export type Theme = {`
`21`	`21`	`borderSubtle: RGBA`
`22`	`22`	`mutedBlue: RGBA`
`23`	`23`	`purple: RGBA`
	`24`	`+ blue: RGBA`
	`25`	`+ controllerBackground: RGBA`
`24`	`26`	`}`
`25`	`27`
`26`	`28`	type HexColor = `#${string}`