gencode-ai 0.1.1 → 0.1.2

package/src/prompts/tools/bash.txt

@@ -0,0 +1,60 @@
+Executes a bash command in a persistent shell session with optional timeout.
+
+IMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for those instead.
+
+Before executing the command:
+
+1. Directory Verification:
+   - If the command will create new directories or files, first use `ls` to verify the parent directory exists
+   - For example, before running "mkdir foo/bar", first use `ls foo` to check that "foo" exists
+
+2. Command Execution:
+   - Always quote file paths that contain spaces with double quotes
+   - Examples of proper quoting:
+     - cd "/Users/name/My Documents" (correct)
+     - cd /Users/name/My Documents (incorrect - will fail)
+
+Usage notes:
+- The command argument is required
+- You can specify an optional timeout in milliseconds (default: 30000, max: 600000)
+- If output exceeds 30000 characters, it will be truncated
+
+Avoid using these commands via Bash (use specialized tools instead):
+- File search: Use Glob (NOT find or ls)
+- Content search: Use Grep (NOT grep or rg)
+- Read files: Use Read (NOT cat/head/tail)
+- Edit files: Use Edit (NOT sed/awk)
+- Write files: Use Write (NOT echo)
+
+When issuing multiple commands:
+- If independent, make multiple Bash calls in parallel
+- If dependent, chain with && (e.g., `git add . && git commit -m "message"`)
+- Use ; only when you don't care if earlier commands fail
+
+# Git Operations
+
+Only create commits when requested by the user. When committing:
+
+Git Safety Protocol:
+- NEVER update git config
+- NEVER run destructive commands (push --force, hard reset) unless explicitly requested
+- NEVER skip hooks (--no-verify) unless explicitly requested
+- NEVER commit unless explicitly asked
+
+Commit workflow:
+1. Run git status and git diff in parallel to understand changes
+2. Run git log to see recent commit message style
+3. Add relevant files and create commit
+4. Run git status to verify success
+
+# Creating Pull Requests
+
+Use the gh command for GitHub-related tasks. When creating PRs:
+1. Check git status and branch state
+2. Run git log and git diff to understand all changes
+3. Push to remote if needed
+4. Create PR with gh pr create
+
+Important:
+- NEVER use git commands with -i flag (interactive mode not supported)
+- DO NOT push unless explicitly asked

package/src/prompts/tools/edit.txt

@@ -0,0 +1,29 @@
+Performs exact string replacements in files.
+
+Usage:
+- You must use the Read tool at least once before editing. This tool will error if you attempt an edit without reading the file first.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
+
+Critical Rules:
+- The edit will FAIL if old_string is not unique in the file
+- Either provide a larger string with more surrounding context to make it unique, or use replace_all to change every instance
+- Use replace_all for renaming variables or strings across the file
+
+<example>
+Changing a function name:
+old_string: "function oldName("
+new_string: "function newName("
+</example>
+
+<example>
+Updating a variable value:
+old_string: "const MAX_RETRIES = 3;"
+new_string: "const MAX_RETRIES = 5;"
+</example>
+
+Best Practices:
+- Include enough context to make old_string unique
+- Preserve exact whitespace and indentation
+- Test changes compile/work after editing
+- Make minimal, focused changes

package/src/prompts/tools/glob.txt

@@ -0,0 +1,35 @@
+Fast file pattern matching tool that works with any codebase size.
+
+Supports glob patterns like "**/*.js" or "src/**/*.ts".
+
+Returns matching file paths sorted by modification time.
+
+Usage:
+- Use this tool when you need to find files by name patterns
+- Supports standard glob syntax:
+  - * matches any characters except /
+  - ** matches any characters including /
+  - ? matches a single character
+  - [abc] matches any of a, b, or c
+  - {a,b} matches either a or b
+
+<example>
+Find all TypeScript files:
+pattern: "**/*.ts"
+</example>
+
+<example>
+Find test files:
+pattern: "**/*.test.{ts,js}"
+</example>
+
+<example>
+Find files in a specific directory:
+pattern: "src/components/**/*.tsx"
+</example>
+
+Best Practices:
+- Use specific patterns to narrow results
+- Combine with Read to examine matching files
+- Call multiple globs in parallel if searching for different patterns
+- Use Grep instead if you need to search file contents

package/src/prompts/tools/grep.txt

@@ -0,0 +1,43 @@
+A powerful search tool for finding patterns in file contents.
+
+Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+").
+
+Usage:
+- Use this tool for content search tasks
+- NEVER invoke grep or rg as a Bash command - use this tool instead
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx")
+- Output modes:
+  - "content" shows matching lines
+  - "files_with_matches" shows only file paths (default)
+  - "count" shows match counts
+
+<example>
+Find all console.log statements:
+pattern: "console\\.log"
+glob: "**/*.ts"
+output_mode: "content"
+</example>
+
+<example>
+Find files containing a function:
+pattern: "function handleSubmit"
+output_mode: "files_with_matches"
+</example>
+
+<example>
+Find TODO comments with context:
+pattern: "TODO:"
+output_mode: "content"
+-C: 2  (show 2 lines before and after)
+</example>
+
+Pattern Syntax:
+- Uses ripgrep syntax (not grep)
+- Literal braces need escaping (use `interface\\{\\}` for `interface{}`)
+- Use -i for case insensitive search
+- Use multiline: true for patterns spanning multiple lines
+
+Best Practices:
+- Start with files_with_matches to find relevant files
+- Then use content mode with context flags for details
+- Combine with Read to see full file context

package/src/prompts/tools/read.txt

@@ -0,0 +1,22 @@
+Reads a file from the local filesystem. You can access any file directly by using this tool.
+
+Assume this tool is able to read all files on the machine. If the user provides a path to a file, assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 2000 lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Any lines longer than 2000 characters will be truncated
+- Results are returned using cat -n format, with line numbers starting at 1
+- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+
+<example>
+user: What's in config.json?
+assistant: [Uses Read tool with file_path="/path/to/config.json"]
+</example>
+
+When exploring a codebase:
+- Read related files together in parallel
+- Start with entry points and work outward
+- Use Glob/Grep first if you're unsure which files to read

package/src/prompts/tools/todowrite.txt

@@ -0,0 +1,71 @@
+Use this tool to create and manage a structured task list for your current session.
+
+This tool serves TWO purposes:
+1. User visibility: Shows task progress in CLI so users understand what you're doing
+2. Your external memory: The rendered result helps YOU remember your plan across turns
+
+This helps you:
+- Track progress and demonstrate thoroughness to the user
+- Organize complex tasks into manageable steps
+- Avoid forgetting tasks in long conversations
+
+## When to Use This Tool
+
+Use proactively in these scenarios:
+
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps
+2. Non-trivial tasks - Tasks requiring careful planning or multiple operations
+3. User provides multiple tasks - Numbered or comma-separated lists
+4. After receiving instructions - Immediately capture requirements as todos
+5. When starting a task - Mark it as in_progress BEFORE beginning work
+6. After completing a task - Mark as completed and add any follow-up tasks discovered
+
+## When NOT to Use This Tool
+
+Skip for:
+- Single, straightforward tasks
+- Trivial tasks that can be completed in under 3 steps
+- Purely conversational or informational requests
+
+## Task States
+
+- pending: Task not yet started
+- in_progress: Currently working on (limit to ONE task at a time)
+- completed: Task finished successfully
+
+## Task Management Rules
+
+- Update task status in real-time as you work
+- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+- Exactly ONE task should be in_progress at any time
+- Complete current tasks before starting new ones
+- Remove tasks that are no longer relevant
+
+## Completion Requirements
+
+ONLY mark a task as completed when you have FULLY accomplished it.
+
+Never mark completed if:
+- Tests are failing
+- Implementation is partial
+- You encountered unresolved errors
+- You couldn't find necessary files
+
+If blocked, create a new task describing what needs to be resolved.
+
+<example>
+user: Run the build and fix any errors
+assistant: Creating todo list:
+1. Run the build [in_progress]
+2. Fix any errors [pending]
+
+Running build...
+
+Found 3 errors. Updating todos:
+1. Run the build [completed]
+2. Fix error in auth.ts [in_progress]
+3. Fix error in api.ts [pending]
+4. Fix error in utils.ts [pending]
+
+Starting with first error...
+</example>

package/src/prompts/tools/webfetch.txt

@@ -0,0 +1,34 @@
+Fetches content from a URL and processes it.
+
+Takes a URL and a prompt as input:
+1. Fetches the URL content
+2. Converts HTML to markdown
+3. Processes the content with the prompt using a fast model
+4. Returns the model's response about the content
+
+Usage:
+- The URL must be a fully-formed valid URL
+- HTTP URLs will be automatically upgraded to HTTPS
+- The prompt should describe what information you want to extract
+
+<example>
+Fetching documentation:
+url: "https://docs.example.com/api"
+prompt: "Extract the authentication methods and their parameters"
+</example>
+
+<example>
+Reading a GitHub README:
+url: "https://github.com/owner/repo"
+prompt: "Summarize the project's main features and installation steps"
+</example>
+
+Behavior notes:
+- Results may be summarized if content is very large
+- Includes a 15-minute cache for faster repeated access
+- When a URL redirects to a different host, the tool will inform you and provide the redirect URL - make a new WebFetch request with that URL
+
+Best Practices:
+- Be specific in your prompt about what information you need
+- Use for documentation, tutorials, and reference material
+- Combine with WebSearch to find relevant URLs first

package/src/prompts/tools/websearch.txt

@@ -0,0 +1,41 @@
+Search the web for current information.
+
+Use this tool when you need:
+- Up-to-date information beyond your knowledge cutoff
+- Current documentation or release notes
+- Recent solutions to technical problems
+- Current best practices
+
+Usage:
+- query: The search query (minimum 2 characters)
+- num_results: Number of results to return (optional)
+- allowed_domains: Only include results from these domains (optional)
+- blocked_domains: Exclude results from these domains (optional)
+
+<example>
+Search for documentation:
+query: "React useEffect cleanup function"
+</example>
+
+<example>
+Search within specific domains:
+query: "TypeScript strict mode configuration"
+allowed_domains: ["typescriptlang.org", "github.com"]
+</example>
+
+IMPORTANT: After answering using search results, include a "Sources:" section with relevant URLs as markdown hyperlinks.
+
+Example response format:
+```
+[Your answer based on search results]
+
+Sources:
+- [React Documentation](https://react.dev/...)
+- [Stack Overflow Answer](https://stackoverflow.com/...)
+```
+
+Best Practices:
+- Use specific, targeted queries
+- Include technology versions when relevant (e.g., "React 18 hooks")
+- Use allowed_domains to filter to authoritative sources
+- Follow up with WebFetch for detailed page content

package/src/prompts/tools/write.txt

@@ -0,0 +1,23 @@
+Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the user.
+
+When to use Write vs Edit:
+- Use Write for creating new files
+- Use Write when you need to completely replace file contents
+- Use Edit for making targeted changes to existing files
+- Prefer Edit over Write for existing files as it's more precise
+
+<example>
+user: Create a new utility file
+assistant: [Uses Write tool with file_path and content]
+</example>
+
+Important:
+- Ensure the parent directory exists before writing
+- Use appropriate file extensions
+- Follow existing code style in the project

package/src/tools/builtin/bash.ts

@@ -5,10 +5,11 @@
 import { spawn } from 'child_process';
 import type { Tool, ToolContext, ToolResult } from '../types.js';
 import { BashInputSchema, type BashInput } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 export const bashTool: Tool<BashInput> = {
   name: 'Bash',
-  description: 'Execute a bash command and return its output. Use for running scripts, git commands, npm, etc.',
+  description: loadToolDescription('bash'),
   parameters: BashInputSchema,
 
   async execute(input: BashInput, context: ToolContext): Promise<ToolResult> {

package/src/tools/builtin/edit.ts

@@ -5,10 +5,11 @@
 import * as fs from 'fs/promises';
 import type { Tool, ToolResult } from '../types.js';
 import { EditInputSchema, type EditInput, resolvePath, getErrorMessage } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 export const editTool: Tool<EditInput> = {
   name: 'Edit',
-  description: 'Edit a file by replacing a specific string with another. The old_string must be unique in the file.',
+  description: loadToolDescription('edit'),
   parameters: EditInputSchema,
 
   async execute(input, context): Promise<ToolResult> {

package/src/tools/builtin/glob.ts

@@ -5,12 +5,13 @@
 import fastGlob from 'fast-glob';
 import type { Tool, ToolResult } from '../types.js';
 import { GlobInputSchema, type GlobInput, resolvePath, getErrorMessage } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 const MAX_RESULTS = 100;
 
 export const globTool: Tool<GlobInput> = {
   name: 'Glob',
-  description: 'Find files matching a glob pattern. Returns a list of matching file paths.',
+  description: loadToolDescription('glob'),
   parameters: GlobInputSchema,
 
   async execute(input, context): Promise<ToolResult> {

package/src/tools/builtin/grep.ts

@@ -7,12 +7,13 @@ import * as path from 'path';
 import fastGlob from 'fast-glob';
 import type { Tool, ToolResult } from '../types.js';
 import { GrepInputSchema, type GrepInput, resolvePath, getErrorMessage } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 const MAX_MATCHES = 50;
 
 export const grepTool: Tool<GrepInput> = {
   name: 'Grep',
-  description: 'Search for a regex pattern in files. Returns matching lines with file paths and line numbers.',
+  description: loadToolDescription('grep'),
   parameters: GrepInputSchema,
 
   async execute(input, context): Promise<ToolResult> {

package/src/tools/builtin/read.ts

@@ -5,10 +5,11 @@
 import * as fs from 'fs/promises';
 import type { Tool, ToolResult } from '../types.js';
 import { ReadInputSchema, type ReadInput, resolvePath, getErrorMessage } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 export const readTool: Tool<ReadInput> = {
   name: 'Read',
-  description: 'Read the contents of a file. Returns the file content with line numbers.',
+  description: loadToolDescription('read'),
   parameters: ReadInputSchema,
 
   async execute(input, context): Promise<ToolResult> {

package/src/tools/builtin/todowrite.ts

@@ -0,0 +1,102 @@
+/**
+ * TodoWrite Tool - Manage task list for tracking progress
+ */
+
+import type { Tool, ToolResult, TodoItem } from '../types.js';
+import { TodoWriteInputSchema, type TodoWriteInput } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
+
+// Global todo state - shared across tool invocations
+let currentTodos: TodoItem[] = [];
+
+/**
+ * Get the current todo list
+ */
+export function getTodos(): TodoItem[] {
+  return [...currentTodos];
+}
+
+/**
+ * Clear all todos
+ */
+export function clearTodos(): void {
+  currentTodos = [];
+}
+
+/**
+ * Format todos for display
+ */
+function formatTodos(todos: TodoItem[]): string {
+  if (todos.length === 0) {
+    return 'Todo list is empty.';
+  }
+
+  const statusIcons: Record<string, string> = {
+    pending: '[ ]',
+    in_progress: '[>]',
+    completed: '[x]',
+  };
+
+  const lines = todos.map((todo, index) => {
+    const icon = statusIcons[todo.status] || '[ ]';
+    return `${index + 1}. ${icon} ${todo.content}`;
+  });
+
+  return lines.join('\n');
+}
+
+/**
+ * Validate todo list rules
+ */
+function validateTodos(todos: TodoItem[]): string | null {
+  const inProgress = todos.filter((t) => t.status === 'in_progress');
+  if (inProgress.length > 1) {
+    return `Only one task should be in_progress at a time. Found ${inProgress.length} tasks in progress.`;
+  }
+  return null;
+}
+
+export const todowriteTool: Tool<TodoWriteInput> = {
+  name: 'TodoWrite',
+  description: loadToolDescription('todowrite'),
+  parameters: TodoWriteInputSchema,
+
+  async execute(input): Promise<ToolResult> {
+    try {
+      // Validate the todo list
+      const validationError = validateTodos(input.todos);
+      if (validationError) {
+        return {
+          success: false,
+          output: '',
+          error: validationError,
+        };
+      }
+
+      // Update the global todo state (auto-generate id if missing)
+      currentTodos = input.todos.map((todo, index) => ({
+        ...todo,
+        id: todo.id || `todo-${index + 1}`,
+      }));
+
+      // Count statistics
+      const pending = currentTodos.filter((t) => t.status === 'pending').length;
+      const inProgress = currentTodos.filter((t) => t.status === 'in_progress').length;
+      const completed = currentTodos.filter((t) => t.status === 'completed').length;
+
+      const summary = `Todos updated: ${completed} completed, ${inProgress} in progress, ${pending} pending`;
+      const formatted = formatTodos(currentTodos);
+
+      return {
+        success: true,
+        output: `${summary}\n\n${formatted}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to update todos: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};

package/src/tools/builtin/webfetch.ts

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import type { Tool, ToolContext, ToolResult } from '../types.js';
 import { getErrorMessage } from '../types.js';
 import { validateUrl } from '../utils/ssrf.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 // Constants
 const MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5MB
@@ -148,11 +149,7 @@ function truncateOutput(output: string): string {
  */
 export const webfetchTool: Tool<WebFetchInput> = {
   name: 'WebFetch',
-  description: `Fetch content from a URL and return it in the specified format.
-- Converts HTML to Markdown by default for easier reading
-- Supports text, markdown, and html output formats
-- Maximum response size: 5MB
-- Timeout: 30 seconds (configurable up to 120 seconds)`,
+  description: loadToolDescription('webfetch'),
   parameters: WebFetchInputSchema,
 
   async execute(input: WebFetchInput, context: ToolContext): Promise<ToolResult> {

package/src/tools/builtin/websearch.ts

@@ -10,6 +10,7 @@ import {
   getCurrentSearchProviderName,
   type SearchResult,
 } from '../../providers/search/index.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 // Constants
 const DEFAULT_NUM_RESULTS = 10;
@@ -62,22 +63,7 @@ function formatResults(results: SearchResult[], query: string): string {
  */
 export const websearchTool: Tool<WebSearchInput> = {
   name: 'WebSearch',
-  description: `Search the web for current information.
-
-Use this tool when you need:
-- Up-to-date information beyond your knowledge cutoff
-- Current documentation or release notes
-- Recent solutions to technical problems
-- Current best practices
-
-IMPORTANT: After answering, include a "Sources:" section with all relevant URLs as markdown hyperlinks.
-
-Example:
-  [Your answer]
-
-  Sources:
-  - [Title 1](https://url1)
-  - [Title 2](https://url2)`,
+  description: loadToolDescription('websearch'),
   parameters: WebSearchInputSchema,
 
   async execute(input: WebSearchInput, context: ToolContext): Promise<ToolResult> {

package/src/tools/builtin/write.ts

@@ -6,10 +6,11 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import type { Tool, ToolResult } from '../types.js';
 import { WriteInputSchema, type WriteInput, resolvePath, getErrorMessage } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
 
 export const writeTool: Tool<WriteInput> = {
   name: 'Write',
-  description: 'Write content to a file. Creates the file if it does not exist, overwrites if it does.',
+  description: loadToolDescription('write'),
   parameters: WriteInputSchema,
 
   async execute(input, context): Promise<ToolResult> {

package/src/tools/index.ts

@@ -14,6 +14,7 @@ export { globTool } from './builtin/glob.js';
 export { grepTool } from './builtin/grep.js';
 export { webfetchTool } from './builtin/webfetch.js';
 export { websearchTool } from './builtin/websearch.js';
+export { todowriteTool, getTodos, clearTodos } from './builtin/todowrite.js';
 
 import { ToolRegistry } from './registry.js';
 import { readTool } from './builtin/read.js';
@@ -24,6 +25,7 @@ import { globTool } from './builtin/glob.js';
 import { grepTool } from './builtin/grep.js';
 import { webfetchTool } from './builtin/webfetch.js';
 import { websearchTool } from './builtin/websearch.js';
+import { todowriteTool } from './builtin/todowrite.js';
 
 /**
  * Create a registry with all built-in tools
@@ -39,6 +41,7 @@ export function createDefaultRegistry(): ToolRegistry {
     grepTool,
     webfetchTool,
     websearchTool,
+    todowriteTool,
   ]);
   return registry;
 }
@@ -55,4 +58,5 @@ export const builtinTools = [
   grepTool,
   webfetchTool,
   websearchTool,
+  todowriteTool,
 ];

package/src/tools/types.ts

@@ -108,6 +108,18 @@ export const WebFetchInputSchema = z.object({
 });
 export type WebFetchInput = z.infer<typeof WebFetchInputSchema>;
 
+export const TodoItemSchema = z.object({
+  content: z.string().min(1).describe('The task description'),
+  status: z.enum(['pending', 'in_progress', 'completed']).describe('Current status of the task'),
+  id: z.string().optional().describe('Unique task identifier'),
+});
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+
+export const TodoWriteInputSchema = z.object({
+  todos: z.array(TodoItemSchema).describe('The complete todo list to write'),
+});
+export type TodoWriteInput = z.infer<typeof TodoWriteInputSchema>;
+
 // ============================================================================
 // JSON Schema Conversion
 // ============================================================================

package/tsconfig.json

@@ -17,5 +17,5 @@
     "jsx": "react-jsx"
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "examples"]
+  "exclude": ["node_modules", "dist", "examples", "**/*.test.ts"]
 }