gencode-ai 0.1.1 → 0.1.3

package/src/prompts/tools/ask-user.txt

@@ -0,0 +1,110 @@
+Use this tool when you need to ask the user questions during execution.
+
+CRITICAL: You MUST use this tool for ANY question with 2+ choices. NEVER present options as plain text, numbered lists, or bullet points.
+
+WRONG (never do this):
+- "Which do you prefer? 1. Option A 2. Option B"
+- "What type? - Web - CLI - API"
+- Writing any numbered or bulleted choices in your response
+
+CORRECT: Call this tool with structured questions and options.
+
+This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take
+
+## When to Use This Tool
+
+Use when you encounter:
+- Ambiguous requirements that could be interpreted multiple ways
+- Technology choices where user preference matters (database, framework, etc.)
+- Implementation approaches with different trade-offs
+- Features or options that should be user-selected
+
+## When NOT to Use This Tool
+
+Don't use for:
+- Asking "Is my plan ready?" or "Should I proceed?" - just proceed or use planning tools
+- Simple yes/no confirmations - just make a reasonable choice
+- Questions you can answer by reading the codebase
+- Trivial implementation details
+
+## Usage Guidelines
+
+- Keep headers short (max 12 chars): "Database", "Auth", "Features"
+- Provide 2-4 options per question
+- Put recommended option FIRST and add "(Recommended)" to its label
+- Use multiSelect: true for non-mutually-exclusive options
+- "Other" option is automatically added - don't include it manually
+- Keep option labels concise (1-5 words)
+- Descriptions should explain trade-offs or implications
+
+## Examples
+
+### Single Choice - Technology Selection
+```json
+{
+  "questions": [{
+    "question": "Which database should we use?",
+    "header": "Database",
+    "options": [
+      { "label": "PostgreSQL (Recommended)", "description": "Robust relational DB" },
+      { "label": "MongoDB", "description": "Document-based NoSQL" },
+      { "label": "SQLite", "description": "Lightweight embedded DB" }
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+### Multi-Select - Feature Selection
+```json
+{
+  "questions": [{
+    "question": "Which features should we enable?",
+    "header": "Features",
+    "options": [
+      { "label": "TypeScript", "description": "Type safety" },
+      { "label": "ESLint", "description": "Code linting" },
+      { "label": "Testing", "description": "Unit tests" },
+      { "label": "Tailwind", "description": "CSS framework" }
+    ],
+    "multiSelect": true
+  }]
+}
+```
+
+### Multiple Questions
+```json
+{
+  "questions": [
+    {
+      "question": "Which auth method?",
+      "header": "Auth",
+      "options": [
+        { "label": "OAuth 2.0 (Recommended)", "description": "Industry standard" },
+        { "label": "JWT", "description": "Stateless tokens" }
+      ],
+      "multiSelect": false
+    },
+    {
+      "question": "Which providers to support?",
+      "header": "Providers",
+      "options": [
+        { "label": "Google", "description": "Most common" },
+        { "label": "GitHub", "description": "Developer-focused" }
+      ],
+      "multiSelect": true
+    }
+  ]
+}
+```
+
+## Constraints
+
+- Maximum 4 questions per call
+- Maximum 4 options per question
+- Header: max 12 characters
+- multiSelect must be explicitly set (required, not optional)

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/ask-user.ts

@@ -0,0 +1,185 @@
+/**
+ * AskUserQuestion Tool - Structured user questioning
+ *
+ * Allows the agent to pause execution and present structured questions
+ * to the user with predefined options. Supports single-select, multi-select,
+ * and custom "Other" input.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../types.js';
+import { loadToolDescription } from '../../prompts/index.js';
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+export const QuestionOptionSchema = z.object({
+  label: z
+    .string()
+    .min(1)
+    .max(50)
+    .describe('Display text for this option (1-5 words, concise)'),
+  description: z
+    .string()
+    .min(1)
+    .max(200)
+    .describe('Explanation of what this option means or implications'),
+});
+
+export const QuestionSchema = z.object({
+  question: z
+    .string()
+    .min(1)
+    .describe('The complete question to ask the user, ending with a question mark'),
+  header: z
+    .string()
+    .min(1)
+    .max(12)
+    .describe('Very short label displayed as a chip/tag (max 12 chars)'),
+  options: z
+    .array(QuestionOptionSchema)
+    .min(2)
+    .max(4)
+    .describe('2-4 options for the user to choose from'),
+  multiSelect: z
+    .boolean()
+    .describe('Set to true to allow multiple selections, false for single choice'),
+});
+
+export const AskUserQuestionInputSchema = z.object({
+  questions: z
+    .array(QuestionSchema)
+    .min(1)
+    .max(4)
+    .describe('1-4 questions to ask the user'),
+});
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+export type Question = z.infer<typeof QuestionSchema>;
+export type AskUserQuestionInput = z.infer<typeof AskUserQuestionInputSchema>;
+
+export interface QuestionAnswer {
+  question: string;
+  header: string;
+  selectedOptions: string[];
+  customInput?: string;
+}
+
+export interface AskUserQuestionResult {
+  answers: QuestionAnswer[];
+}
+
+// ============================================================================
+// Answer Formatting
+// ============================================================================
+
+/**
+ * Format answers for display to the agent
+ */
+export function formatAnswersForAgent(answers: QuestionAnswer[]): string {
+  const lines: string[] = ['User answered the following questions:', ''];
+
+  answers.forEach((answer, index) => {
+    lines.push(`${index + 1}. ${answer.header} (${answer.question})`);
+
+    if (answer.selectedOptions.length > 0) {
+      lines.push(`   Selected: ${answer.selectedOptions.join(', ')}`);
+    }
+
+    if (answer.customInput) {
+      lines.push(`   Custom input: ${answer.customInput}`);
+    }
+
+    lines.push('');
+  });
+
+  lines.push('Proceeding with user selections.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format answers for CLI confirmation display
+ */
+export function formatAnswersForDisplay(answers: QuestionAnswer[]): string {
+  return answers
+    .map((answer) => {
+      const selections = answer.customInput
+        ? [...answer.selectedOptions, answer.customInput].join(', ')
+        : answer.selectedOptions.join(', ');
+      return `✔ ${answer.header}: ${selections}`;
+    })
+    .join('\n');
+}
+
+// ============================================================================
+// Tool Implementation
+// ============================================================================
+
+/**
+ * AskUserQuestion tool
+ *
+ * This tool is special - it doesn't execute immediately but signals
+ * the agent loop to pause and wait for user input via the CLI.
+ *
+ * The actual questioning is handled by the CLI layer (QuestionPrompt component).
+ * This tool just validates the input and returns a marker for the agent loop.
+ */
+export const askUserQuestionTool: Tool<AskUserQuestionInput> = {
+  name: 'AskUserQuestion',
+  description: loadToolDescription('ask-user'),
+  parameters: AskUserQuestionInputSchema,
+
+  async execute(input: AskUserQuestionInput, context: ToolContext): Promise<ToolResult> {
+    // Validation is handled by Zod schema
+    // Additional validation for recommended options format
+    for (const question of input.questions) {
+      // Check if first option has (Recommended) - this is just a hint, not enforced
+      const firstOption = question.options[0];
+      if (firstOption && !firstOption.label.includes('(Recommended)')) {
+        // This is fine - recommended suffix is optional
+      }
+    }
+
+    // Check if context has askUser callback
+    if (context.askUser) {
+      try {
+        const answers = await context.askUser(input.questions);
+        return {
+          success: true,
+          output: formatAnswersForAgent(answers),
+          metadata: {
+            title: 'AskUserQuestion',
+            subtitle: `${answers.length} answer(s) received`,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: '',
+          error: `Failed to get user response: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    }
+
+    // If no askUser callback, return a special marker
+    // The agent loop should detect this and handle it specially
+    return {
+      success: true,
+      output: JSON.stringify({
+        type: 'ask_user_question',
+        questions: input.questions,
+        requiresUserInput: true,
+      }),
+      metadata: {
+        title: 'AskUserQuestion',
+        subtitle: `${input.questions.length} question(s) pending`,
+      },
+    };
+  },
+};

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> {