workermill 0.2.0 → 0.3.1

package/README.md

@@ -123,6 +123,16 @@ Config stored at `~/.workermill/cli.json` (global) and `.workermill/config.json`
 
 backend_developer, frontend_developer, devops_engineer, qa_engineer, security_engineer, data_ml_engineer, mobile_developer, tech_writer, architect, tech_lead, planner, critic
 
+All worker personas include production-hardened rules:
+- **Real services, not mocks** — Docker containers for databases, caches, queues. Tests run against real services.
+- **Version trust** — Never downgrades language/runtime versions (training data is outdated)
+- **Learning markers** — Reports codebase discoveries with `::learning::` markers for team visibility
+- **Right-sized plans** — Planner matches plan complexity to task complexity (1 step for simple, 3-5 for complex)
+- **Approval bias** — Tech lead only blocks on real functional/security issues, not cosmetic preferences
+- **File overlap detection** — Critic catches parallel merge conflicts before they happen
+
+Custom personas can be added per-project in `.workermill/personas/` or globally in `~/.workermill/personas/`.
+
 ## Requirements
 
 - Node.js 20+

package/dist/{chunk-VC6VNVEY.js → chunk-NGQKIYVB.js}

@@ -1639,6 +1639,41 @@ var CostTracker = class {
   }
 };
 
+// src/logger.js
+import fs9 from "fs";
+import path11 from "path";
+var LOG_DIR = path11.join(process.cwd(), ".workermill");
+var LOG_FILE = path11.join(LOG_DIR, "cli.log");
+var logStream = null;
+function ensureLogDir() {
+  if (!fs9.existsSync(LOG_DIR)) {
+    fs9.mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+function getStream() {
+  if (!logStream) {
+    ensureLogDir();
+    logStream = fs9.createWriteStream(LOG_FILE, { flags: "a" });
+  }
+  return logStream;
+}
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function log(level, message, data) {
+  const entry = data ? `[${timestamp()}] ${level}: ${message} ${JSON.stringify(data)}` : `[${timestamp()}] ${level}: ${message}`;
+  getStream().write(entry + "\n");
+}
+function info(message, data) {
+  log("INFO", message, data);
+}
+function error(message, data) {
+  log("ERROR", message, data);
+}
+function debug(message, data) {
+  log("DEBUG", message, data);
+}
+
 export {
   __dirname,
   loadConfig,
@@ -1648,5 +1683,8 @@ export {
   createModel,
   killActiveProcess,
   createToolDefinitions,
-  CostTracker
+  CostTracker,
+  info,
+  error,
+  debug
 };

package/dist/index.js

@@ -4,15 +4,19 @@ import {
   buildOllamaOptions,
   createModel,
   createToolDefinitions,
+  debug,
+  error,
   getProviderForPersona,
+  info,
   killActiveProcess,
   loadConfig,
   saveConfig
-} from "./chunk-VC6VNVEY.js";
+} from "./chunk-NGQKIYVB.js";
 
 // src/index.ts
 import React5 from "react";
 import { render } from "ink";
+import chalk2 from "chalk";
 import { Command } from "commander";
 
 // src/setup.js
@@ -119,7 +123,7 @@ async function runSetup() {
 }
 
 // src/ui/Root.tsx
-import { useState as useState5, useCallback as useCallback3, useRef as useRef3 } from "react";
+import { useState as useState5, useCallback as useCallback3, useRef as useRef3, useEffect as useEffect2 } from "react";
 import { useApp as useApp2 } from "ink";
 import { execSync as execSync2 } from "child_process";
 import fs2 from "fs";
@@ -344,7 +348,7 @@ function useAgent(options) {
       const envMap = {
         anthropic: "ANTHROPIC_API_KEY",
         openai: "OPENAI_API_KEY",
-        google: "GOOGLE_API_KEY"
+        google: "GOOGLE_GENERATIVE_AI_API_KEY"
       };
       const envVar = envMap[options.provider];
       if (envVar && !process.env[envVar]) {
@@ -447,20 +451,20 @@ function useAgent(options) {
         ...td,
         execute: async (input) => {
           const callId = crypto2.randomUUID();
-          const info = {
+          const info2 = {
             id: callId,
             name,
             input,
             status: "pending"
           };
-          setStreamingToolCalls((prev) => [...prev, info]);
+          setStreamingToolCalls((prev) => [...prev, info2]);
           setMessages((prev) => [
             ...prev,
             {
               id: `tc-${callId}`,
               role: "assistant",
               content: "",
-              toolCalls: [{ ...info, status: "running" }],
+              toolCalls: [{ ...info2, status: "running" }],
               timestamp: (/* @__PURE__ */ new Date()).toISOString()
             }
           ]);
@@ -487,8 +491,10 @@ function useAgent(options) {
           );
           setStatus("tool_running");
           try {
+            info("Tool call", { tool: name, input: JSON.stringify(input).slice(0, 200) });
             const result = await td.execute(input);
             const resultStr = typeof result === "string" ? result : JSON.stringify(result);
+            debug("Tool result", { tool: name, result: resultStr.slice(0, 200) });
             setStreamingToolCalls(
               (prev) => prev.map(
                 (tc) => tc.id === callId ? { ...tc, status: "done", result: resultStr } : tc
@@ -531,6 +537,7 @@ function useAgent(options) {
       void (async () => {
         const session = sessionRef.current;
         addMessage(session, "user", input);
+        info("User message", { length: input.length, preview: input.slice(0, 100) });
         if (!session.name) {
           session.name = input.slice(0, 50).replace(/\n/g, " ");
         }
@@ -591,6 +598,7 @@ function useAgent(options) {
           setStreamingText("");
           addMessage(session, "assistant", finalText);
           session.totalTokens += inputTokens + outputTokens;
+          info("Response complete", { inputTokens, outputTokens, textLength: finalText.length });
           costTrackerRef.current.addUsage(
             "agent",
             options.provider,
@@ -634,6 +642,7 @@ function useAgent(options) {
             return;
           }
           const errText = err instanceof Error ? err.message : String(err);
+          error("Agent error", { error: errText });
           const errorMsg = {
             id: crypto2.randomUUID(),
             role: "assistant",
@@ -772,7 +781,7 @@ function useOrchestrator(addMessage2) {
             setRunning(false);
             return;
           }
-          const { classifyComplexity, runOrchestration } = await import("./orchestrator-5I7BGPC7.js");
+          const { classifyComplexity, runOrchestration } = await import("./orchestrator-2M4BCHQR.js");
           const output = {
             log(persona, message) {
               const emoji = getEmoji(persona);
@@ -1469,6 +1478,10 @@ function App(props) {
   const lastCtrlCRef = useRef2(0);
   const width = stdout?.columns || 80;
   useInput3((input, key) => {
+    if (key.escape && props.status !== "idle") {
+      props.onCancel();
+      return;
+    }
     if (key.ctrl && input === "c") {
       const now = Date.now();
       if (props.status === "idle" && now - lastCtrlCRef.current < 500) {
@@ -1479,43 +1492,7 @@ function App(props) {
     }
   });
   const mode = props.planMode ? "PLAN" : props.trustAll ? "trust all" : "ask";
-  const headerInner = Math.min(width - 4, 50);
   return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", width: "100%", children: [
-    /* @__PURE__ */ jsx6(Static, { items: [{ id: "__header__" }], children: () => /* @__PURE__ */ jsxs6(
-      Box6,
-      {
-        flexDirection: "column",
-        borderStyle: "round",
-        borderColor: theme.subtleDark,
-        paddingX: 1,
-        width: headerInner,
-        children: [
-          /* @__PURE__ */ jsxs6(Box6, { children: [
-            /* @__PURE__ */ jsx6(Text6, { color: theme.brand, children: "\u25C6 " }),
-            /* @__PURE__ */ jsx6(Text6, { color: theme.text, bold: true, children: "WorkerMill" })
-          ] }),
-          /* @__PURE__ */ jsx6(Text6, { children: " " }),
-          /* @__PURE__ */ jsxs6(Text6, { color: theme.subtle, children: [
-            "  ",
-            props.provider,
-            "/",
-            props.model
-          ] }),
-          /* @__PURE__ */ jsxs6(Text6, { color: theme.subtle, children: [
-            "  ",
-            "cwd: ",
-            props.workingDir
-          ] }),
-          /* @__PURE__ */ jsxs6(Text6, { color: theme.subtle, children: [
-            "  ",
-            "Type ",
-            /* @__PURE__ */ jsx6(Text6, { color: theme.text, children: "/help" }),
-            " for commands"
-          ] })
-        ]
-      },
-      "__header__"
-    ) }),
     /* @__PURE__ */ jsx6(Static, { items: props.messages, children: (message) => /* @__PURE__ */ jsx6(Box6, { flexDirection: "column", marginTop: 1, children: message.role === "user" ? /* @__PURE__ */ jsxs6(Box6, { marginLeft: 1, children: [
       /* @__PURE__ */ jsx6(Text6, { color: theme.brand, bold: true, children: "\u2771 " }),
       /* @__PURE__ */ jsx6(Text6, { color: theme.text, children: message.content })
@@ -1616,34 +1593,37 @@ function getGitStatus(cwd) {
 ${status}
 \`\`\``;
 }
-var HELP_TEXT = `**WorkerMill Commands**
+var HELP_TEXT = `**WorkerMill** \u2014 AI coding agent for your terminal.
 
-| Command | Description |
-|---|---|
-| \`/help\` | Show this help |
-| \`/model\` | Show current model info |
-| \`/cost\` | Show session cost breakdown |
-| \`/status\` | Show session status |
-| \`/plan\` | Toggle plan mode (read-only tools) |
-| \`/trust\` | Trust all tool calls for this session |
-| \`/build <task>\` | Multi-expert orchestration |
-| \`/git\` | Show git branch and status |
-| \`/sessions\` | List recent sessions |
-| \`/editor\` | Open \\$EDITOR, submit contents |
-| \`/compact\` | Trigger context compaction |
-| \`/clear\` | Clear screen (limited in Ink) |
-| \`/quit\` | Exit WorkerMill |
-| \`/exit\` | Exit WorkerMill |
+**Two ways to work:**
+
+**Chat** \u2014 Ask anything. I'll read files, write code, run commands.
+Just type your question or task and press Enter.
 
-**Shortcuts**
+**Build** \u2014 Create software with multiple specialist AI agents.
+Type \`/build <description>\` and I'll plan stories, assign experts
+(backend, frontend, devops, security), execute, and review.
 
-- \`!command\` -- Run a shell command directly and display output
-- \`Ctrl+C\` -- Cancel current operation
-- \`Ctrl+C Ctrl+C\` -- Exit when idle
+Or from the command line: \`wm build "your task"\`
 
-**Notes**
+---
 
-- Multiline input is not currently supported. Paste single-line prompts or use \`/editor\` to compose longer messages.`;
+**Commands**
+
+| Command | Description |
+|---|---|
+| \`/build <task>\` | Multi-expert orchestration \u2014 the main feature |
+| \`/plan\` | Toggle plan mode (read-only, explore before committing) |
+| \`/trust\` | Auto-approve all tool calls for this session |
+| \`/model\` | Show current provider and model |
+| \`/cost\` | Session cost and token usage |
+| \`/status\` | Session info |
+| \`/git\` | Git branch and status |
+| \`/sessions\` | List/switch sessions |
+| \`/editor\` | Open \\$EDITOR for longer input |
+| \`/quit\` | Exit |
+
+**Shortcuts:** \`!command\` runs shell directly, \`ESC\` cancels, \`Ctrl+C Ctrl+C\` exits.`;
 function Root(props) {
   const { exit } = useApp2();
   const agent = useAgent(props);
@@ -1658,6 +1638,14 @@ function Root(props) {
     [agent]
   );
   const orchestrator = useOrchestrator(addOrchestratorMessage);
+  const buildStarted = useRef3(false);
+  useEffect2(() => {
+    if (props.initialBuildTask && !buildStarted.current) {
+      buildStarted.current = true;
+      agent.addUserMessage(`/build ${props.initialBuildTask}`);
+      orchestrator.start(props.initialBuildTask, props.trustAll, props.sandboxed);
+    }
+  }, [props.initialBuildTask, props.trustAll, props.sandboxed, agent, orchestrator]);
   const [inputHistory, setInputHistory] = useState5(() => loadHistory());
   const [gitBranch, setGitBranch] = useState5(() => getGitBranch());
   const lastBranchCheck = useRef3(Date.now());
@@ -1938,6 +1926,7 @@ ${trimmedOutput}
       trustAll: props.trustAll,
       planMode: props.planMode,
       onSubmit: handleSubmit,
+      onCancel: agent.cancel,
       messages: agent.messages,
       status: orchestrator.running ? "tool_running" : agent.status,
       permissionRequest: agent.permissionRequest,
@@ -1952,8 +1941,25 @@ ${trimmedOutput}
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
-var program = new Command().name("workermill").description("AI coding agent with multi-provider support").version(VERSION).option("--provider <provider>", "Override default provider").option("--model <model>", "Override model").option("--trust", "Skip all tool permission prompts").option("--resume", "Resume the last conversation").option("--plan", "Start in plan mode (read-only tools)").option("--full-disk", "Allow tools to access files outside working directory").action(async (options) => {
+function printWelcome(provider, model, workingDir) {
+  const brand = chalk2.hex("#D77757");
+  const dim = chalk2.dim;
+  const white = chalk2.white;
+  console.log();
+  console.log(`  ${brand("\u25C6")} ${white.bold("WorkerMill")} ${dim("v" + VERSION)}`);
+  console.log();
+  console.log(dim(`  ${provider}/${model}`));
+  console.log(dim(`  cwd: ${workingDir}`));
+  console.log();
+  console.log(dim("  Ask me anything, or use ") + brand("/build") + dim(" to create software with multi-expert AI."));
+  console.log(dim("  Type ") + white("/help") + dim(" for all commands."));
+  console.log();
+}
+var VERSION = "0.3.1";
+function addSharedOptions(cmd) {
+  return cmd.option("--provider <provider>", "Override default provider").option("--model <model>", "Override model").option("--trust", "Skip all tool permission prompts").option("--full-disk", "Allow tools to access files outside working directory");
+}
+async function resolveConfig(options) {
   let config = loadConfig();
   if (!config) {
     config = await runSetup();
@@ -1967,8 +1973,14 @@ var program = new Command().name("workermill").description("AI coding agent with
       providerConfig.model = options.model;
     }
   }
+  return config;
+}
+var program = new Command().name("wm").description("WorkerMill \u2014 AI coding agent for your terminal").version(VERSION);
+var defaultCmd = program.command("chat", { isDefault: true }).description("Interactive AI coding agent (default)").option("--resume", "Resume the last conversation").option("--plan", "Start in plan mode (read-only tools)").action(async (options) => {
+  const config = await resolveConfig(options);
   const { provider, model, apiKey, host, contextLength } = getProviderForPersona(config);
   const workingDir = process.cwd();
+  printWelcome(provider, model, workingDir);
   const { waitUntilExit } = render(
     React5.createElement(Root, {
       provider,
@@ -1985,4 +1997,50 @@ var program = new Command().name("workermill").description("AI coding agent with
   );
   await waitUntilExit();
 });
+addSharedOptions(defaultCmd);
+var buildCmd = program.command("build [task...]").description("Build software with multi-expert orchestration").option("--critic", "Run critic pass on plan before execution").action(async (taskParts, options) => {
+  const task = taskParts.join(" ");
+  if (!task) {
+    console.log('\n  Usage: wm build "<task description>"\n');
+    console.log("  Example:");
+    console.log('    wm build "REST API with auth, tests, and Docker"');
+    console.log('    wm build "Add search feature to the React frontend"\n');
+    process.exit(0);
+  }
+  const config = await resolveConfig(options);
+  if (options.critic) {
+    config.review = { ...config.review, useCritic: true };
+  }
+  const { provider, model, apiKey, host, contextLength } = getProviderForPersona(config);
+  const trustAll = options.trust || false;
+  const sandboxed = !options.fullDisk;
+  if (apiKey) {
+    const envMap = {
+      anthropic: "ANTHROPIC_API_KEY",
+      openai: "OPENAI_API_KEY",
+      google: "GOOGLE_GENERATIVE_AI_API_KEY"
+    };
+    const envVar = envMap[provider];
+    if (envVar && !process.env[envVar]) {
+      process.env[envVar] = apiKey;
+    }
+  }
+  const { waitUntilExit } = render(
+    React5.createElement(Root, {
+      provider,
+      model,
+      apiKey,
+      host,
+      contextLength,
+      trustAll,
+      planMode: false,
+      sandboxed,
+      resume: false,
+      workingDir: process.cwd(),
+      initialBuildTask: task
+    })
+  );
+  await waitUntilExit();
+});
+addSharedOptions(buildCmd);
 program.parse();

package/dist/{orchestrator-5I7BGPC7.js → orchestrator-2M4BCHQR.js}

@@ -4,8 +4,9 @@ import {
   buildOllamaOptions,
   createModel,
   createToolDefinitions,
-  getProviderForPersona
-} from "./chunk-VC6VNVEY.js";
+  getProviderForPersona,
+  info
+} from "./chunk-NGQKIYVB.js";
 
 // src/orchestrator.js
 import chalk3 from "chalk";
@@ -224,37 +225,6 @@ var PermissionManager = class {
 // src/tui.js
 import chalk2 from "chalk";
 import { execSync } from "child_process";
-
-// src/logger.js
-import fs2 from "fs";
-import path2 from "path";
-var LOG_DIR = path2.join(process.cwd(), ".workermill");
-var LOG_FILE = path2.join(LOG_DIR, "cli.log");
-var logStream = null;
-function ensureLogDir() {
-  if (!fs2.existsSync(LOG_DIR)) {
-    fs2.mkdirSync(LOG_DIR, { recursive: true });
-  }
-}
-function getStream() {
-  if (!logStream) {
-    ensureLogDir();
-    logStream = fs2.createWriteStream(LOG_FILE, { flags: "a" });
-  }
-  return logStream;
-}
-function timestamp() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function log(level, message, data) {
-  const entry = data ? `[${timestamp()}] ${level}: ${message} ${JSON.stringify(data)}` : `[${timestamp()}] ${level}: ${message}`;
-  getStream().write(entry + "\n");
-}
-function info(message, data) {
-  log("INFO", message, data);
-}
-
-// src/tui.js
 function formatToolCall(toolName, toolInput) {
   let msg = `Tool: ${toolName}`;
   if (toolInput) {
@@ -1253,10 +1223,10 @@ ${story.description}`,
     } catch {
       wmCoordinatorLog("Initializing git repository...");
       execSync2("git init", { cwd: workingDir, encoding: "utf-8", stdio: "pipe" });
-      const fs3 = await import("fs");
+      const fs2 = await import("fs");
       const gitignorePath = `${workingDir}/.gitignore`;
-      if (!fs3.existsSync(gitignorePath)) {
-        fs3.writeFileSync(gitignorePath, "node_modules/\ndist/\n.env\n.workermill/\n*.log\n", "utf-8");
+      if (!fs2.existsSync(gitignorePath)) {
+        fs2.writeFileSync(gitignorePath, "node_modules/\ndist/\n.env\n.workermill/\n*.log\n", "utf-8");
       }
       wmCoordinatorLog("Git repo initialized");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workermill",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "AI coding agent with multi-expert orchestration. Works with any LLM provider.",
   "type": "module",
   "bin": {

package/personas/architect.md

@@ -27,3 +27,54 @@ Work Style:
 - Create architecture decision records for major choices
 - Consider scalability, maintainability, and team velocity
 - Document architectural patterns and rationale
+
+## ABSOLUTE RULE — NEVER Flag Language/Runtime Versions as Invalid
+
+Your training data is OUTDATED — newer language and runtime versions have been released since your cutoff. NEVER suggest downgrading a language version. NEVER say a version "doesn't exist" or is "non-existent." If the project uses a version you don't recognize, it is correct — the project authors chose it deliberately.
+
+## Development Environment
+
+You have `docker` and `docker compose` available. **You MUST spin up real service dependencies** (databases, caches, message queues) using Docker containers before writing any application code that depends on them. Do NOT mock or stub external services — connect to real instances running in Docker.
+
+### Required Workflow
+1. **Before writing application code**: Start all required service containers
+2. **Configure your code** to connect to `localhost` on the container ports
+3. **Run tests against real services** — integration tests must hit real databases, not mocks
+4. **Clean up containers** when done (`docker stop <name>`)
+
+### Common Services
+- MongoDB: `docker run -d --rm -p 27017:27017 --name mongo-test mongo:7`
+- Redis: `docker run -d --rm -p 6379:6379 --name redis-test redis:7-alpine`
+- PostgreSQL: `docker run -d --rm -p 5432:5432 -e POSTGRES_PASSWORD=test --name postgres-test postgres:16-alpine`
+- MySQL: `docker run -d --rm -p 3306:3306 -e MYSQL_ROOT_PASSWORD=test --name mysql-test mysql:8`
+- If the project has a `docker-compose.yml`, use `docker compose up -d`
+
+### Why This Matters
+Mocking produces code full of assumptions that break on first contact with real services. Real containers catch connection strings, schema mismatches, query errors, and serialization bugs immediately. **Tests that pass against mocks but fail against real services are worthless.**
+
+### If Docker Is Not Working
+If `docker` commands fail, DO NOT fall back to mocking. Report the Docker error as a blocker. Never write test stubs or mock implementations as a workaround.
+
+### CI/CD Workflows Must Include Service Containers
+When creating GitHub Actions CI workflows that run tests requiring databases, you **MUST** add `services:` blocks so the CI runner has real service instances. Match your local Docker setup with CI service containers.
+
+## Reporting Learnings
+
+When you discover something specific and actionable about this codebase, emit a learning marker:
+
+```
+::learning::The test suite requires DATABASE_URL env var or tests silently pass without running
+::learning::New API routes must be registered in backend/src/routes/index.ts or they won't load
+```
+
+**Emit a learning when you discover:**
+- A non-obvious requirement (specific env vars, config files, build steps)
+- A codebase convention not documented elsewhere (naming patterns, file organization)
+- A gotcha you had to work around (unexpected failures, ordering dependencies)
+- Files that must be modified together (route + model + migration + test)
+
+**Do NOT emit generic advice** like "write tests" or "handle errors properly."
+
+## Communication Style
+
+Write in a professional, direct tone. Do NOT open messages with filler words or pleasantries like "Perfect!", "Great!", "Awesome!", "Sure!", "Absolutely!". Start with the substance — what you did, what you found, or what you need. Be concise and informative.

package/personas/backend_developer.md

@@ -25,3 +25,54 @@ Work Style:
 - Create database migrations before models
 - Use proper error handling and validation
 - Document endpoints for frontend team
+
+## ABSOLUTE RULE — NEVER Flag Language/Runtime Versions as Invalid
+
+Your training data is OUTDATED — newer language and runtime versions have been released since your cutoff. NEVER suggest downgrading a language version. NEVER say a version "doesn't exist" or is "non-existent." If the project uses a version you don't recognize, it is correct — the project authors chose it deliberately.
+
+## Development Environment
+
+You have `docker` and `docker compose` available. **You MUST spin up real service dependencies** (databases, caches, message queues) using Docker containers before writing any application code that depends on them. Do NOT mock or stub external services — connect to real instances running in Docker.
+
+### Required Workflow
+1. **Before writing application code**: Start all required service containers
+2. **Configure your code** to connect to `localhost` on the container ports
+3. **Run tests against real services** — integration tests must hit real databases, not mocks
+4. **Clean up containers** when done (`docker stop <name>`)
+
+### Common Services
+- MongoDB: `docker run -d --rm -p 27017:27017 --name mongo-test mongo:7`
+- Redis: `docker run -d --rm -p 6379:6379 --name redis-test redis:7-alpine`
+- PostgreSQL: `docker run -d --rm -p 5432:5432 -e POSTGRES_PASSWORD=test --name postgres-test postgres:16-alpine`
+- MySQL: `docker run -d --rm -p 3306:3306 -e MYSQL_ROOT_PASSWORD=test --name mysql-test mysql:8`
+- If the project has a `docker-compose.yml`, use `docker compose up -d`
+
+### Why This Matters
+Mocking produces code full of assumptions that break on first contact with real services. Real containers catch connection strings, schema mismatches, query errors, and serialization bugs immediately. **Tests that pass against mocks but fail against real services are worthless.**
+
+### If Docker Is Not Working
+If `docker` commands fail, DO NOT fall back to mocking. Report the Docker error as a blocker. Never write test stubs or mock implementations as a workaround.
+
+### CI/CD Workflows Must Include Service Containers
+When creating GitHub Actions CI workflows that run tests requiring databases, you **MUST** add `services:` blocks so the CI runner has real service instances. Match your local Docker setup with CI service containers.
+
+## Reporting Learnings
+
+When you discover something specific and actionable about this codebase, emit a learning marker:
+
+```
+::learning::The test suite requires DATABASE_URL env var or tests silently pass without running
+::learning::New API routes must be registered in backend/src/routes/index.ts or they won't load
+```
+
+**Emit a learning when you discover:**
+- A non-obvious requirement (specific env vars, config files, build steps)
+- A codebase convention not documented elsewhere (naming patterns, file organization)
+- A gotcha you had to work around (unexpected failures, ordering dependencies)
+- Files that must be modified together (route + model + migration + test)
+
+**Do NOT emit generic advice** like "write tests" or "handle errors properly."
+
+## Communication Style
+
+Write in a professional, direct tone. Do NOT open messages with filler words or pleasantries like "Perfect!", "Great!", "Awesome!", "Sure!", "Absolutely!". Start with the substance — what you did, what you found, or what you need. Be concise and informative.