diff --git a/packages/coding-agent/docs/SOUL.md b/packages/coding-agent/docs/SOUL.md index 4234f60..786830f 100644 --- a/packages/coding-agent/docs/SOUL.md +++ b/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 diff --git a/packages/coding-agent/src/core/resource-loader.ts b/packages/coding-agent/src/core/resource-loader.ts index 13e5fdd..7466e69 100644 --- a/packages/coding-agent/src/core/resource-loader.ts +++ b/packages/coding-agent/src/core/resource-loader.ts @@ -125,7 +125,6 @@ const companionContextFilenames = [ "SOUL.md", "USER.md", "TOOLS.md", - "HEARTBEAT.md", "MEMORY.md", "BOOTSTRAP.md", ]; diff --git a/packages/coding-agent/src/core/skills.ts b/packages/coding-agent/src/core/skills.ts index 9ead2d6..dc7e71d 100644 --- a/packages/coding-agent/src/core/skills.ts +++ b/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.", - "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.", + "\n\n# Skills", + "", + "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.", "", "", ]; diff --git a/packages/coding-agent/src/core/system-prompt.ts b/packages/coding-agent/src/core/system-prompt.ts index 4098bbe..cd9e860 100644 --- a/packages/coding-agent/src/core/system-prompt.ts +++ b/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 = { - read: "Read file contents", - bash: "Execute bash commands (ls, grep, find, etc.)", + read: "Read file contents (always use instead of cat/head/tail)", + bash: "Run shell commands", browser: - "Open websites, inspect pages with snapshot, click/fill/wait, take screenshots, and save/load browser state", - edit: "Make surgical edits to files (find exact text and replace)", - write: "Create or overwrite files", - grep: "Search file contents for patterns (respects .gitignore)", + "Browse the web: open, snapshot, click, fill, wait, screenshot, save/load state", + edit: "Surgical file edits (find exact text, replace it)", + write: "Create new files or completely rewrite existing ones", + grep: "Search file contents by regex (respects .gitignore)", find: "Find files by glob pattern (respects .gitignore)", ls: "List directory contents", }; @@ -45,46 +44,49 @@ function buildProjectContextSection( return ""; } - const hasSoulFile = contextFiles.some( - ({ path }) => - path.replaceAll("\\", "/").endsWith("/SOUL.md") || path === "SOUL.md", - ); - const hasContextFile = (filename: string) => + const hasFile = (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"; - if (hasSoulFile) { - section += - "\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"; + + let section = "\n\n# Context\n\n"; + section += + "These files define who you are, what you know, and how you operate.\n"; + + const guides: string[] = []; + + if (hasFile("SOUL.md")) { + guides.push( + "**SOUL.md** defines your personality and tone. Embody it fully.", + ); } - if (hasContextFile("IDENTITY.md")) { - section += - "\nIf IDENTITY.md is present, treat it as the agent's self-description and stay consistent with it.\n"; + if (hasFile("USER.md")) { + guides.push( + "**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")) { - section += - "\nIf USER.md is present, use it as durable context about the user and avoid re-asking for facts already captured there.\n"; + if (hasFile("MEMORY.md")) { + guides.push( + "**MEMORY.md** is your long-term memory. Reference it. Update it when you learn something durable.", + ); } - if (hasContextFile("MEMORY.md")) { - section += - "\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"; + if (hasFile("TOOLS.md")) { + guides.push( + "**TOOLS.md** is your environment reference: paths, ports, installed software. Trust it over assumptions.", + ); } - if (hasContextFile("TOOLS.md")) { - section += - "\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"; + if (hasFile("BOOTSTRAP.md")) { + guides.push( + "**BOOTSTRAP.md** is your onboarding checklist. Execute it before other work.", + ); } - if (hasContextFile("HEARTBEAT.md")) { - section += - "\nIf HEARTBEAT.md is present, honor it as recurring operational guidance for the agent.\n"; - } - if (hasContextFile("BOOTSTRAP.md")) { - section += - "\nIf BOOTSTRAP.md is present, treat it as an actionable onboarding task list and execute it before drifting into unrelated work.\n"; + + if (guides.length > 0) { + 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`; @@ -150,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; @@ -188,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) { @@ -234,28 +240,25 @@ export function buildSystemPrompt( } } - // Always include these - addGuideline("Be concise in your responses"); - addGuideline("Show file paths clearly when working with files"); + // Behavioral baseline + addGuideline("Be direct and concise"); + 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} - -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)`; +${guidelines}`; if (appendSection) { prompt += appendSection; diff --git a/packages/coding-agent/test/system-prompt.test.ts b/packages/coding-agent/test/system-prompt.test.ts index e9013f9..7985767 100644 --- a/packages/coding-agent/test/system-prompt.test.ts +++ b/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( - "If SOUL.md is present, embody its persona and tone.", - ); + expect(prompt).toContain("SOUL.md** defines your personality 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", - ); - expect(prompt).toContain( - "If BOOTSTRAP.md is present, treat it as an actionable onboarding task list", + "BOOTSTRAP.md** is your onboarding checklist", ); }); });