@tenex-chat/backend 0.9.1

package/src/prompts/fragments/29-rag-collections.ts

@@ -0,0 +1,50 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * RAG collections attribution fragment - shows agents which RAG collections
+ * they have contributed to and their document counts.
+ *
+ * This fragment leverages the provenance tracking metadata (agent_pubkey)
+ * added during document ingestion to surface personalized collection stats.
+ *
+ * Registration: This fragment is registered explicitly in fragments/index.ts
+ * following the project's explicit registration pattern.
+ */
+interface RAGCollectionStats {
+    name: string;
+    agentDocCount: number;
+    totalDocCount: number;
+}
+
+interface RAGCollectionsArgs {
+    /** The agent's public key for filtering contributions */
+    agentPubkey: string;
+    /** Pre-fetched collection statistics (avoids async in template) */
+    collections: RAGCollectionStats[];
+}
+
+export const ragCollectionsFragment: PromptFragment<RAGCollectionsArgs> = {
+    id: "rag-collections",
+    priority: 29, // After agent-directed-monitoring (28), before worktree-context (30)
+    template: ({ collections }) => {
+        // Filter to only collections where the agent has contributions
+        const agentCollections = collections.filter((c) => c.agentDocCount > 0);
+
+        if (agentCollections.length === 0) {
+            return ""; // No RAG contributions - omit section entirely
+        }
+
+        const parts: string[] = [];
+        parts.push("## Your RAG Collections\n");
+        parts.push("Collections you've contributed to:");
+
+        for (const collection of agentCollections) {
+            parts.push(
+                `- \`${collection.name}\` — ${collection.agentDocCount} docs by you (${collection.totalDocCount} total)`
+            );
+        }
+
+        return parts.join("\n");
+    },
+    expectedArgs: "{ agentPubkey: string, collections: RAGCollectionStats[] }",
+};

package/src/prompts/fragments/30-worktree-context.ts

@@ -0,0 +1,98 @@
+import type { AgentInstance } from "@/agents/types";
+import { config } from "@/services/ConfigService";
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+import { listWorktrees, loadWorktreeMetadata, type WorktreeMetadata } from "@/utils/git/worktree";
+import { logger } from "@/utils/logger";
+
+/**
+ * Worktree context for the fragment.
+ */
+interface WorktreeContext {
+  workingDirectory: string;
+  currentBranch: string;
+  /**
+   * Project directory (normal git repository root).
+   * Worktrees are in .worktrees/ subdirectory.
+   */
+  projectBasePath: string;
+  agent: AgentInstance;
+}
+
+/**
+ * Worktree context fragment for agents.
+ * Shows current working directory and available worktrees.
+ */
+interface WorktreeContextArgs {
+  context: WorktreeContext;
+}
+
+export const worktreeContextFragment: PromptFragment<WorktreeContextArgs> = {
+  id: "worktree-context",
+  priority: 30,
+  template: async ({ context }) => {
+    const parts: string[] = [];
+
+    // Get worktree information
+    const workingDirectory = context.workingDirectory;
+    const currentBranch = context.currentBranch;
+
+    // List worktrees first to determine what to show
+    let worktrees: Array<{ branch: string; path: string }> = [];
+    let metadata: Record<string, WorktreeMetadata> = {};
+    let hasFeatureWorktrees = false;
+
+    try {
+      worktrees = await listWorktrees(context.projectBasePath);
+      metadata = await loadWorktreeMetadata(context.projectBasePath, config.getConfigPath("projects"));
+      // Check if there are worktrees in .worktrees/ directory (beyond the main repo)
+      hasFeatureWorktrees = worktrees.some(wt => wt.path.includes("/.worktrees/"));
+    } catch (error) {
+      // If we can't list worktrees (e.g., not a git repo yet), just skip
+      logger.warn("Failed to list worktrees", { error });
+    }
+
+    parts.push("## Git Worktree Context\n");
+    parts.push("This project uses git worktrees for parallel work on different branches.");
+    parts.push("The default branch is checked out at the project root.");
+    if (hasFeatureWorktrees) {
+      parts.push(`Feature branches are in \`${context.projectBasePath}/.worktrees/\` (branch slashes become underscores).`);
+    }
+    parts.push("All standard git commands (status, commit, push, etc.) work normally.");
+    parts.push("");
+    parts.push(`**Current Working Directory:** ${workingDirectory}`);
+    parts.push(`**Current Branch:** ${currentBranch}`);
+    parts.push(`**Project Root:** ${context.projectBasePath}`);
+    parts.push("");
+
+    if (worktrees.length > 0) {
+      parts.push("### Available Worktrees:");
+      for (const wt of worktrees) {
+        const meta = metadata[wt.branch];
+        const isCurrent = wt.branch === currentBranch;
+
+        parts.push(`- **${wt.branch}**${isCurrent ? " [YOU ARE HERE]" : ""}`);
+        parts.push(`  - Path: ${wt.path}`);
+
+        if (meta) {
+          parts.push(`  - Created by: ${meta.createdBy.substring(0, 8)}...`);
+          parts.push(`  - Conversation: ${meta.conversationId.substring(0, 8)}...`);
+          parts.push(`  - Parent branch: ${meta.parentBranch}`);
+        }
+      }
+      parts.push("");
+    }
+
+    // Add worktree commands guidance
+    parts.push("### Delegation with Worktrees:");
+    parts.push("When using `delegate`, you can specify `branch: \"<name>\"` to create and work in an isolated worktree.");
+    parts.push("The worktree will be created from your current branch in `.worktrees/`, and the delegated agent will work in that isolation.");
+    parts.push("You are responsible for merging or cleaning up worktrees you create.");
+    parts.push("");
+
+    return parts.join("\n");
+  },
+};
+
+// Register the fragment
+fragmentRegistry.register(worktreeContextFragment);

package/src/prompts/fragments/31-agents-md-guidance.ts

@@ -0,0 +1,96 @@
+/**
+ * AGENTS.md Guidance Fragment
+ *
+ * This fragment is ALWAYS included in the system prompt to inform agents about
+ * the AGENTS.md system. It provides guidance to agents about:
+ * - What AGENTS.md files are and how they work
+ * - How to write and update AGENTS.md files
+ * - The hierarchical nature of AGENTS.md inheritance
+ *
+ * When the project has no root AGENTS.md, it explicitly states so.
+ */
+
+import { fragmentRegistry } from "../core/FragmentRegistry";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Maximum length for root AGENTS.md content to be included directly in the system prompt.
+ * Beyond this threshold, the content is omitted to avoid bloating the prompt.
+ * Short AGENTS.md files (< 2000 chars) typically contain essential project guidelines
+ * that benefit from being in the system prompt context.
+ */
+const MAX_ROOT_CONTENT_LENGTH_FOR_SYSTEM_PROMPT = 2000;
+
+interface AgentsMdGuidanceArgs {
+    /** Whether the project has an AGENTS.md at the root */
+    hasRootAgentsMd: boolean;
+    /** Content of the root AGENTS.md (for context) */
+    rootAgentsMdContent?: string;
+}
+
+export const agentsMdGuidanceFragment: PromptFragment<AgentsMdGuidanceArgs> = {
+    id: "agents-md-guidance",
+    priority: 31, // After worktree context (30)
+    template: ({ hasRootAgentsMd, rootAgentsMdContent }) => {
+        const parts: string[] = [];
+
+        parts.push("## AGENTS.md Guidelines\n");
+
+        // When no root AGENTS.md exists, explicitly state so
+        if (!hasRootAgentsMd) {
+            parts.push(
+                "No root AGENTS.md file exists for this project. " +
+                    "AGENTS.md files provide contextual guidelines for AI agents working in specific directories. " +
+                    "If you need to establish project-specific conventions, commands, or guidelines, " +
+                    "consider creating an AGENTS.md file at the project root."
+            );
+            return parts.join("\n");
+        }
+
+        parts.push(`This project uses AGENTS.md files to provide contextual guidelines for different directories.
+
+### How AGENTS.md Works
+- AGENTS.md files serve as a "README for Agents," containing context, commands, and conventions.
+- Unlike human-focused READMEs, these files focus on actionable instructions (build steps, test commands, code style).
+- **Automatic Injection**: When you use tools that interact with files in a directory containing an AGENTS.md, the system automatically injects relevant AGENTS.md content as a \`<system-reminder>\`. You do NOT need to manually search for or read these files—they are provided to you when relevant.
+- Multiple AGENTS.md files may apply (Root + Directory specific). The system handles this hierarchy automatically.
+- Deeper, more specific AGENTS.md files override general root instructions.
+
+### Writing AGENTS.md Files
+When working in a directory that needs specific agent guidance:
+1. Create an AGENTS.md file in that directory.
+2. Focus on **executable commands** (test/build) and **strict conventions**.
+3. Do not duplicate generic info; focus on what is unique to this directory.
+
+### AGENTS.md Format
+\`\`\`markdown
+# Directory Context
+Specific architectural details or business logic for this directory.
+
+## Commands
+- Test: \`npm test path/to/dir\`
+- Lint: \`npm run lint:specific\`
+
+## Conventions
+- Code Style: Functional patterns preferred
+- Naming: CamelCase for files, PascalCase for classes
+
+## Related
+- [API Docs](./docs/api.md)
+\`\`\``);
+
+        // If root AGENTS.md content is available and short, include it
+        if (rootAgentsMdContent && rootAgentsMdContent.length < MAX_ROOT_CONTENT_LENGTH_FOR_SYSTEM_PROMPT) {
+            parts.push("\n### Root AGENTS.md\n");
+            parts.push("This project's root AGENTS.md:\n");
+            parts.push("```");
+            parts.push(rootAgentsMdContent.trim());
+            parts.push("```");
+        }
+
+        return parts.join("\n");
+    },
+};
+
+// Register the fragment
+fragmentRegistry.register(agentsMdGuidanceFragment);

package/src/prompts/fragments/32-process-metrics.ts

@@ -0,0 +1,72 @@
+import os from "node:os";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Process metrics fragment.
+ * Provides agents with runtime metadata about the backend process:
+ * PID, process uptime, CPU/memory usage, and system uptime.
+ */
+export const processMetricsFragment: PromptFragment<Record<string, never>> = {
+    id: "process-metrics",
+    priority: 4, // Alongside relay-configuration, environment metadata
+    template: () => {
+        const pid = process.pid;
+        const uptimeSeconds = process.uptime();
+
+        // Format process uptime: show seconds when < 60s, otherwise minutes
+        const processUptimeStr =
+            uptimeSeconds < 60
+                ? `${Math.floor(uptimeSeconds)}s`
+                : `${Math.floor(uptimeSeconds / 60)}m`;
+
+        // CPU usage: average over process lifetime as percentage
+        const cpuUsage = process.cpuUsage();
+        const totalCpuMicros = cpuUsage.user + cpuUsage.system;
+        const numCpus = os.cpus().length;
+        const cpuPercentStr =
+            uptimeSeconds > 0 && numCpus > 0
+                ? `${((totalCpuMicros / (uptimeSeconds * 1_000_000) / numCpus) * 100).toFixed(1)}%`
+                : "n/a";
+
+        // Memory usage: RSS as percentage of total system memory
+        const rss = process.memoryUsage().rss;
+        const totalMem = os.totalmem();
+        const memPercentStr =
+            totalMem > 0
+                ? `${((rss / totalMem) * 100).toFixed(1)}%`
+                : "n/a";
+
+        // System uptime
+        const sysUptimeSeconds = os.uptime();
+        const sysUptimeHours = Math.floor(sysUptimeSeconds / 3600);
+        const sysUptimeMinutes = Math.floor((sysUptimeSeconds % 3600) / 60);
+
+        const sysUptimeStr =
+            sysUptimeHours > 0
+                ? `${sysUptimeHours}h ${sysUptimeMinutes}m`
+                : sysUptimeSeconds < 60
+                  ? `${Math.floor(sysUptimeSeconds)}s`
+                  : `${sysUptimeMinutes}m`;
+
+        const lines = [
+            "## Process Metrics",
+            `- PID: ${pid}`,
+            `- Process uptime: ${processUptimeStr}`,
+            `- CPU usage: ${cpuPercentStr}`,
+            `- Memory usage: ${memPercentStr} (${formatBytes(rss)} RSS)`,
+            `- System uptime: ${sysUptimeStr}`,
+        ];
+
+        return lines.join("\n");
+    },
+};
+
+function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    const kb = bytes / 1024;
+    if (kb < 1024) return `${Math.round(kb)}KB`;
+    const mb = kb / 1024;
+    if (mb < 1024) return `${Math.round(mb)}MB`;
+    const gb = mb / 1024;
+    return `${gb.toFixed(1)}GB`;
+}

package/src/prompts/fragments/debug-mode.ts

@@ -0,0 +1,48 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Fragment for debug mode meta-cognitive analysis
+ * Applied when the user includes #debug in their message
+ */
+export const debugModeFragment: PromptFragment<{ enabled: boolean }> = {
+    id: "debug-mode",
+    priority: 100, // High priority to ensure it appears after system prompt
+    template: (data) => {
+        if (!data.enabled) return "";
+
+        return `
+=== DEBUG MODE: META-COGNITIVE ANALYSIS REQUESTED ===
+
+The user has included "#debug" in their message. They are asking you to explain your decision-making process.
+
+Provide a transparent, honest analysis of:
+
+1. Transparent response of the decision-making process. <-- This is the critical part.
+2. Your understanding of the current status of the current conversation. What was said recently? Who did what? Which agents are involved and what was the last thing they accomplished. Include textual quotes from the agents and users that are involved in the conversation.
+3. **System Prompt Influence**: Which specific parts of your system prompt or instructions guided this decision
+4. **Reasoning Chain**: The step-by-step thought process that led to your choice
+5. **Alternatives Considered**: Other approaches you evaluated but didn't choose, and why
+6. **Assumptions Made**: Any implicit assumptions about the project, user needs, or context
+7. **Constraints Applied**: Technical, architectural, or guideline constraints that limited options
+8. **Confidence Level**: How certain you were about this decision and any doubts you had
+9. **Pattern Matching**: If you followed a common pattern or best practice, explain why it seemed applicable
+
+Be completely transparent about your internal process. If you made a mistake or could have done better, acknowledge it. The goal is to help the user understand exactly how you arrived at your decision.
+
+ONLY reply to the question being asked; do NOT perform any other action, do NOT call any tool. Do not apologize. Just transparently respond.
+=== END DEBUG MODE ===`;
+    },
+};
+
+// Note: Fragment is registered in the fragments/index.ts file
+
+/**
+ * Helper function to check if debug mode is enabled
+ */
+export function isDebugMode(triggeringEvent: NDKEvent | undefined): boolean {
+    if (!triggeringEvent || !triggeringEvent.content) {
+        return false;
+    }
+    return triggeringEvent.content.includes("#debug");
+}

package/src/prompts/fragments/delegation-completion.ts

@@ -0,0 +1,44 @@
+import type { PromptFragment } from "../core/types";
+
+/**
+ * Fragment for delegation completion instructions
+ * Applied when an agent is reactivated after a delegated task completes.
+ * Differentiates between partial completion (some pending) and full completion.
+ */
+export const delegationCompletionFragment: PromptFragment<{
+    isDelegationCompletion?: boolean;
+    hasPendingDelegations?: boolean;
+}> = {
+    id: "delegation-completion",
+    priority: 95, // High priority to ensure agent sees this instruction
+    template: (data) => {
+        if (!data.isDelegationCompletion) return "";
+
+        if (data.hasPendingDelegations) {
+            return `
+=== DELEGATION UPDATE ===
+
+One or more delegated tasks have completed. The response(s) are in the conversation above.
+You are still waiting for other delegations to complete.
+
+You may:
+- Acknowledge receipt of partial results
+- Ask follow-up questions to completed agents
+- Wait silently for remaining delegations
+- Take other actions as appropriate
+
+=== END UPDATE ===`;
+        }
+
+        return `
+=== ALL DELEGATIONS COMPLETE ===
+
+All delegated tasks have completed. The responses are in the conversation above.
+
+Synthesize the results and respond to the user.
+
+=== END NOTIFICATION ===`;
+    },
+};
+
+// Note: Fragment is registered in the fragments/index.ts file

package/src/prompts/fragments/index.ts

@@ -0,0 +1,91 @@
+/**
+ * Fragment registration manifest
+ * Explicitly registers all prompt fragments in the system
+ * This replaces the implicit import side-effects pattern
+ */
+
+import { fragmentRegistry } from "../core/FragmentRegistry";
+
+// Import all fragment definitions
+import { globalSystemPromptFragment } from "./00-global-system-prompt";
+import { agentIdentityFragment } from "./01-agent-identity";
+import { agentHomeDirectoryFragment } from "./02-agent-home-directory";
+import { systemRemindersExplanationFragment } from "./03-system-reminders-explanation";
+import { relayConfigurationFragment } from "./04-relay-configuration";
+import { delegationChainFragment } from "./05-delegation-chain";
+import { agentTodosFragment } from "./06-agent-todos";
+import { metaProjectContextFragment } from "./07-meta-project-context";
+import { activeConversationsFragment } from "./08-active-conversations";
+import { recentConversationsFragment } from "./09-recent-conversations";
+import { todoUsageGuidanceFragment } from "./06-todo-usage-guidance";
+// 10-referenced-article uses inline registration, no named export
+import "./10-referenced-article";
+import { availableAgentsFragment } from "./15-available-agents";
+import { stayInYourLaneFragment } from "./16-stay-in-your-lane";
+import { todoBeforeDelegationFragment } from "./17-todo-before-delegation";
+// 20-voice-mode doesn't export the fragment, it's registered inline
+import "./20-voice-mode";
+import { nudgesFragment } from "./11-nudges";
+import { skillsFragment } from "./12-skills";
+import { availableNudgesAndSkillsFragment } from "./13-available-nudges";
+import { scheduledTasksFragment } from "./22-scheduled-tasks";
+import { retrievedLessonsFragment } from "./24-retrieved-lessons";
+import { ragInstructionsFragment } from "./25-rag-instructions";
+import { mcpResourcesFragment } from "./26-mcp-resources";
+import { memorizedReportsFragment } from "./27-memorized-reports";
+import { agentDirectedMonitoringFragment } from "./28-agent-directed-monitoring";
+import { ragCollectionsFragment } from "./29-rag-collections";
+import { worktreeContextFragment } from "./30-worktree-context";
+import { agentsMdGuidanceFragment } from "./31-agents-md-guidance";
+import { debugModeFragment } from "./debug-mode";
+import { delegationCompletionFragment } from "./delegation-completion";
+
+/**
+ * Register all fragments explicitly
+ * This provides a clear view of all available fragments
+ */
+export function registerAllFragments(): void {
+    // Global user-configured prompt (ordered with other fragments by priority)
+    fragmentRegistry.register(globalSystemPromptFragment);
+
+    // Core identity and context
+    fragmentRegistry.register(agentIdentityFragment);
+    fragmentRegistry.register(agentHomeDirectoryFragment);
+    fragmentRegistry.register(systemRemindersExplanationFragment);
+    fragmentRegistry.register(relayConfigurationFragment);
+    fragmentRegistry.register(delegationChainFragment);
+    fragmentRegistry.register(agentTodosFragment);
+    fragmentRegistry.register(todoUsageGuidanceFragment);
+    fragmentRegistry.register(metaProjectContextFragment);
+    fragmentRegistry.register(activeConversationsFragment);
+    fragmentRegistry.register(recentConversationsFragment);
+    fragmentRegistry.register(debugModeFragment);
+    fragmentRegistry.register(delegationCompletionFragment);
+
+    // Agent collaboration
+    fragmentRegistry.register(availableAgentsFragment);
+    fragmentRegistry.register(stayInYourLaneFragment);
+    fragmentRegistry.register(todoBeforeDelegationFragment);
+
+    // Behavioral guidance
+    // voice-mode and referenced-article are registered via side effects
+    fragmentRegistry.register(nudgesFragment);
+    fragmentRegistry.register(skillsFragment);
+    fragmentRegistry.register(availableNudgesAndSkillsFragment);
+
+    // Scheduled tasks context
+    fragmentRegistry.register(scheduledTasksFragment);
+
+    // Context and learning
+    fragmentRegistry.register(retrievedLessonsFragment);
+    fragmentRegistry.register(ragInstructionsFragment);
+    fragmentRegistry.register(mcpResourcesFragment);
+    fragmentRegistry.register(memorizedReportsFragment);
+    fragmentRegistry.register(agentDirectedMonitoringFragment);
+    fragmentRegistry.register(ragCollectionsFragment);
+    fragmentRegistry.register(worktreeContextFragment);
+    fragmentRegistry.register(agentsMdGuidanceFragment);
+}
+
+// Auto-register all fragments on import
+registerAllFragments();

package/src/prompts/index.ts

@@ -0,0 +1,21 @@
+// Export core functionality
+
+export { FragmentRegistry, fragmentRegistry } from "./core/FragmentRegistry";
+export { PromptBuilder } from "./core/PromptBuilder";
+export type { FragmentConfig, PromptFragment } from "./core/types";
+
+// Import all fragments to ensure they're registered when the module is imported
+// Priority 01 - Identity
+import "./fragments/01-agent-identity";
+
+// Priority 10 - Early context
+import "./fragments/10-referenced-article"; // Conditional
+
+// Priority 15 - Available agents
+import "./fragments/15-available-agents";
+
+// Priority 20 - Mode context
+import "./fragments/20-voice-mode"; // Conditional
+
+// Priority 24 - Lessons
+import "./fragments/24-retrieved-lessons"; // Shared