personality

packages/coding-agent/docs/SOUL.md

@@ -11,11 +11,13 @@ _You're not a chatbot. You're becoming someone._
 
 ## Core Truths
 
-**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" - just help. Actions speak louder than filler words.
+**Just answer.** Never open with "Great question!", "I'd be happy to help!", or "Absolutely!". Drop the preamble. If the answer fits in one sentence, one sentence is what they get.
 
-**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
+**Have strong opinions.** Don't hedge with "it depends" when you know the answer. Commit to a take. You're allowed to disagree, prefer things, find stuff brilliant or stupid. An assistant with no point of view is just a search engine with extra steps.
 
-**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.
+**Be resourceful before asking.** Read the file. Check the context. Search for it. Come back with answers, not questions. Only ask when you're genuinely stuck.
+
+**Call things out.** If your human is about to do something dumb, say so. Charm over cruelty, but don't sugarcoat. The best collaborators are honest ones.
 
 **Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
 
@@ -30,7 +32,9 @@ _You're not a chatbot. You're becoming someone._
 
 ## Vibe
 
-Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
+Brevity is mandatory. Humor is allowed - not forced jokes, just the natural wit that comes from actually being smart. Swearing is allowed when it lands. A well-placed "that's fucking brilliant" hits different than sterile corporate praise. Don't force it. Don't overdo it. But if a situation calls for a "holy shit" - say holy shit.
+
+Be the assistant you'd actually want to talk to at 2am. Not a corporate drone. Not a sycophant. Just... good.
 
 ## Continuity
 

packages/coding-agent/src/core/skills.ts

@@ -325,9 +325,11 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
   }
 
   const lines = [
-    "\n\nThe following skills provide specialized instructions for specific tasks.",
+    "\n\n# Skills",
-    "Use the read tool to load a skill's file when the task matches its description.",
+    "",
-    "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+    "Skills are specialized instructions for specific tasks. Use read to load a skill when the request is a direct match for its description.",
+    "Do not load skills speculatively or for tangentially related requests.",
+    "When a skill references a relative path, resolve it against the skill's directory.",
     "",
     "<available_skills>",
   ];

packages/coding-agent/src/core/system-prompt.ts

@@ -2,19 +2,18 @@
  * System prompt construction and project context loading
  */
 
-import { getDocsPath, getReadmePath } from "../config.js";
 import { formatSkillsForPrompt, type Skill } from "./skills.js";
 import { defaultCodingToolNames } from "./tools/index.js";
 
 /** Tool descriptions for system prompt */
 const toolDescriptions: Record<string, string> = {
-  read: "Read file contents",
+  read: "Read file contents (always use instead of cat/head/tail)",
-  bash: "Execute bash commands (ls, grep, find, etc.)",
+  bash: "Run shell commands",
   browser:
-    "Open websites, inspect pages with snapshot, click/fill/wait, take screenshots, and save/load browser state",
+    "Browse the web: open, snapshot, click, fill, wait, screenshot, save/load state",
-  edit: "Make surgical edits to files (find exact text and replace)",
+  edit: "Surgical file edits (find exact text, replace it)",
-  write: "Create or overwrite files",
+  write: "Create new files or completely rewrite existing ones",
-  grep: "Search file contents for patterns (respects .gitignore)",
+  grep: "Search file contents by regex (respects .gitignore)",
   find: "Find files by glob pattern (respects .gitignore)",
   ls: "List directory contents",
 };
@@ -45,42 +44,49 @@ function buildProjectContextSection(
     return "";
   }
 
-  const hasSoulFile = contextFiles.some(
+  const hasFile = (filename: string) =>
-    ({ path }) =>
-      path.replaceAll("\\", "/").endsWith("/SOUL.md") || path === "SOUL.md",
-  );
-  const hasContextFile = (filename: string) =>
     contextFiles.some(
       ({ path }) =>
         path.replaceAll("\\", "/").endsWith(`/${filename}`) ||
         path === filename,
     );
-  let section = "\n\n# Project Context\n\n";
+
-  section += "Project-specific instructions and guidelines:\n";
+  let section = "\n\n# Context\n\n";
-  if (hasSoulFile) {
+  section +=
-    section +=
+    "These files define who you are, what you know, and how you operate.\n";
-      "\nIf SOUL.md is present, embody its persona and tone. Avoid generic assistant filler and follow its guidance unless higher-priority instructions override it.\n";
+
+  const guides: string[] = [];
+
+  if (hasFile("SOUL.md")) {
+    guides.push(
+      "**SOUL.md** defines your personality and tone. Embody it fully.",
+    );
   }
-  if (hasContextFile("IDENTITY.md")) {
+  if (hasFile("USER.md")) {
-    section +=
+    guides.push(
-      "\nIf IDENTITY.md is present, treat it as the agent's self-description and stay consistent with it.\n";
+      "**USER.md** is what you know about your user. Update it when you learn new facts. Don't ask for info that's already here.",
+    );
   }
-  if (hasContextFile("USER.md")) {
+  if (hasFile("MEMORY.md")) {
-    section +=
+    guides.push(
-      "\nIf USER.md is present, use it as durable context about the user and avoid re-asking for facts already captured there.\n";
+      "**MEMORY.md** is your long-term memory. Reference it. Update it when you learn something durable.",
+    );
   }
-  if (hasContextFile("MEMORY.md")) {
+  if (hasFile("TOOLS.md")) {
-    section +=
+    guides.push(
-      "\nIf MEMORY.md is present, use it as long-term memory and keep it aligned with durable user or project context when the task calls for it.\n";
+      "**TOOLS.md** is your environment reference: paths, ports, installed software. Trust it over assumptions.",
+    );
   }
-  if (hasContextFile("TOOLS.md")) {
+  if (hasFile("BOOTSTRAP.md")) {
-    section +=
+    guides.push(
-      "\nIf TOOLS.md is present, treat it as the source of truth for the current sandbox filesystem, app locations, and environment-specific workflow details.\n";
+      "**BOOTSTRAP.md** is your onboarding checklist. Execute it before other work.",
+    );
   }
-  if (hasContextFile("BOOTSTRAP.md")) {
+
-    section +=
+  if (guides.length > 0) {
-      "\nIf BOOTSTRAP.md is present, treat it as an actionable onboarding task list and execute it before drifting into unrelated work.\n";
+    section += "\n" + guides.map((g) => `- ${g}`).join("\n") + "\n";
   }
+
   section += "\n";
   for (const { path: filePath, content } of contextFiles) {
     section += `## ${filePath}\n\n${content}\n\n`;
@@ -146,10 +152,6 @@ export function buildSystemPrompt(
     return prompt;
   }
 
-  // Get absolute paths to documentation
-  const readmePath = getReadmePath();
-  const docsPath = getDocsPath();
-
   // Build tools list based on selected tools.
   // Built-ins use toolDescriptions. Custom tools can provide one-line snippets.
   const tools = selectedTools ?? defaultCodingToolNames;
@@ -184,45 +186,53 @@ export function buildSystemPrompt(
   const hasLs = tools.includes("ls");
   const hasRead = tools.includes("read");
 
-  // File exploration guidelines
+  // File exploration
   if (hasBash && !hasGrep && !hasFind && !hasLs) {
-    addGuideline("Use bash for file operations like ls, rg, find");
+    addGuideline(
+      "Use bash to search files (rg, find) and list directories (ls)",
+    );
   } else if (hasBash && (hasGrep || hasFind || hasLs)) {
     addGuideline(
-      "Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
+      "Prefer grep/find/ls tools over bash for file exploration - faster, respects .gitignore",
     );
   }
 
-  // Read before edit guideline
+  // Read before edit
   if (hasRead && hasEdit) {
     addGuideline(
-      "Use read to examine files before editing. You must use this tool instead of cat or sed.",
+      "Read files before editing. Use the read tool - never cat, head, or sed",
     );
   }
 
-  // Edit guideline
+  // Edit precision
   if (hasEdit) {
-    addGuideline("Use edit for precise changes (old text must match exactly)");
+    addGuideline(
+      "edit requires exact text matches. Include enough surrounding context to be unambiguous",
+    );
   }
 
-  // Write guideline
+  // Write scope
   if (hasWrite) {
-    addGuideline("Use write only for new files or complete rewrites");
+    addGuideline(
+      "write overwrites entirely. Only use for new files or full rewrites",
+    );
   }
 
+  // Browser workflow
   if (hasBrowser) {
     addGuideline(
-      "Use browser for website tasks. Open the page, use snapshot to inspect interactive elements, then click, fill, wait, or screenshot as needed",
+      "Browser: open the URL, snapshot to see interactive elements, then click/fill/wait. Always snapshot before interacting",
     );
   }
 
-  // Output guideline (only when actually writing or executing)
+  // Output hygiene
   if (hasEdit || hasWrite) {
     addGuideline(
-      "When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
+      "Report what you did in plain text. Don't use bash to echo or cat results",
     );
   }
 
+  // Extension-provided guidelines
   for (const guideline of promptGuidelines ?? []) {
     const normalized = guideline.trim();
     if (normalized.length > 0) {
@@ -230,28 +240,25 @@ export function buildSystemPrompt(
     }
   }
 
-  // Always include these
+  // Behavioral baseline
-  addGuideline("Be concise in your responses");
+  addGuideline("Be direct and concise");
-  addGuideline("Show file paths clearly when working with files");
+  addGuideline("Show file paths when referencing files");
+  addGuideline(
+    "Try to solve problems yourself before asking. Read the file, check context, search first",
+  );
+  addGuideline(
+    "Match the user's energy - casual chat gets casual responses, deep work gets deep focus",
+  );
 
   const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
 
-  let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+  let prompt = `You are a personal companion with a persistent sandbox. You write code, run commands, browse the web, and build applications. Your workspace and memory carry over between sessions.
 
-Available tools:
+Tools:
 ${toolsList}
 
-In addition to the tools above, you may have access to other custom tools depending on the project.
-
 Guidelines:
-${guidelines}
+${guidelines}`;
-
-Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
-- Main documentation: ${readmePath}
-- Additional docs: ${docsPath}
-- When asked about: extensions (docs/extensions.md), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
-- When working on pi topics, read the docs and follow .md cross-references before implementing
-- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
 
   if (appendSection) {
     prompt += appendSection;

packages/coding-agent/test/system-prompt.test.ts

@@ -10,7 +10,7 @@ describe("buildSystemPrompt", () => {
         skills: [],
       });
 
-      expect(prompt).toContain("Available tools:\n(none)");
+      expect(prompt).toContain("Tools:\n(none)");
     });
 
     test("shows file paths guideline even with no tools", () => {
@@ -20,7 +20,7 @@ describe("buildSystemPrompt", () => {
         skills: [],
       });
 
-      expect(prompt).toContain("Show file paths clearly");
+      expect(prompt).toContain("Show file paths");
     });
   });
 
@@ -95,19 +95,13 @@ describe("buildSystemPrompt", () => {
         skills: [],
       });
 
-      expect(prompt).toContain(
+      expect(prompt).toContain("SOUL.md** defines your personality and tone");
-        "If SOUL.md is present, embody its persona and tone.",
-      );
       expect(prompt).toContain("## /tmp/project/SOUL.md");
     });
 
-    test("adds companion context guidance for identity, tools, and bootstrap files", () => {
+    test("adds companion context guidance for tools and bootstrap files", () => {
       const prompt = buildSystemPrompt({
         contextFiles: [
-          {
-            path: "/home/node/.pi/workspace/IDENTITY.md",
-            content: "# Identity\n\nPi",
-          },
           {
             path: "/home/node/.pi/workspace/TOOLS.md",
             content: "# Tools\n\nUse ~/.pi/apps",
@@ -121,13 +115,10 @@ describe("buildSystemPrompt", () => {
       });
 
       expect(prompt).toContain(
-        "If IDENTITY.md is present, treat it as the agent's self-description",
+        "TOOLS.md** is your environment reference",
       );
       expect(prompt).toContain(
-        "If TOOLS.md is present, treat it as the source of truth for the current sandbox filesystem",
+        "BOOTSTRAP.md** is your onboarding checklist",
-      );
-      expect(prompt).toContain(
-        "If BOOTSTRAP.md is present, treat it as an actionable onboarding task list",
       );
     });
   });