@kkelly-offical/kkcode 0.1.2

package/src/tool/prompt/patch.txt

@@ -0,0 +1,24 @@
+Replace a range of lines in a file by line number. Transactional with automatic rollback.
+
+Usage:
+- You MUST `read` the file first — patches on unread files are rejected.
+- Use `read` with offset/limit to view the relevant section, note line numbers, then call `patch`.
+- Lines are 1-based and the range is inclusive (both start_line and end_line are replaced).
+- To delete lines without replacement, pass content as empty string "".
+
+Parameters:
+- path (required): file path
+- start_line (required): first line to replace (1-based, inclusive)
+- end_line (required): last line to replace (1-based, inclusive)
+- content (required): replacement text (replaces the entire line range)
+
+When to use `patch` vs `edit`:
+- You know exact line numbers from a recent `read` → use `patch`
+- You know exact text to match but not line numbers → use `edit`
+- You need to replace many occurrences of a string → use `edit` with replace_all
+- You want to replace a large section (50+ lines) → use `patch` (only needs new content, not old)
+
+Workflow for large file modifications:
+1. `read` the file (or section with offset/limit)
+2. Note the line numbers of the section to change
+3. Call `patch` with start_line, end_line, and new content

package/src/tool/prompt/question.txt

@@ -0,0 +1,44 @@
+Ask the user one or more structured questions during execution. Use when you need user input to proceed.
+
+## When to Use
+
+- Gather user preferences or requirements
+- Clarify ambiguous instructions
+- Get decisions on implementation choices as you work
+- Offer choices about what direction to take
+
+<example>
+You're implementing a caching layer but unsure which strategy the user prefers:
+→ question(questions=[{id: "cache", text: "Which caching strategy should we use?", options: [{label: "Redis (Recommended)", description: "Distributed cache, best for multi-server"}, {label: "In-memory", description: "Simple, single-server only"}, {label: "File-based", description: "Persistent, slower"}]}])
+</example>
+
+<example>
+User says "fix the bug" but there are multiple potential issues:
+→ question(questions=[{id: "bug", text: "Which issue should I fix first?", options: [{label: "Auth timeout", description: "Users get logged out after 5 minutes"}, {label: "API 500 error", description: "POST /users returns 500 on duplicate email"}]}])
+</example>
+
+## When NOT to Use
+
+- Do NOT use this to ask "Is my plan ready?" or "Should I proceed?" — use `exit_plan` for plan approval.
+- Do NOT use this for trivial confirmations that don't affect the outcome.
+- If you can reasonably infer the answer from context, just proceed.
+
+## Parameters
+
+- questions (required): array of question objects (1-4 questions per call)
+  - id (required): unique question identifier
+  - text (required): the complete question text (should end with ?)
+  - description (optional): supplementary explanation
+  - options (optional): array of predefined choices (2-4 options)
+    - label (required): display text (concise, 1-5 words). If you recommend a specific option, list it first and add "(Recommended)" to its label.
+    - value (optional): option value (defaults to label)
+    - description (optional): explanation of what this option means or what will happen if chosen
+  - multi (optional, default false): allow multiple selections. Use when choices are not mutually exclusive.
+  - allowCustom (optional, default true): allow custom text input
+
+## Tips
+
+- Users will always be able to provide custom text input regardless of options
+- Keep option labels concise and clearly distinct from each other
+- When you have 2-4 distinct approaches, use options. When the answer is open-ended, skip options.
+- In plan mode, use this tool to clarify requirements BEFORE finalizing your plan. Do NOT use this to ask "Is my plan ready?" — use `exit_plan` for that.

package/src/tool/prompt/read.txt

@@ -0,0 +1,40 @@
+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.
+
+## Usage
+
+- The path parameter can be absolute or relative to the working directory.
+- By default, it reads up to 2000 lines starting from the beginning of the file. You can optionally specify offset and limit for large files.
+- Any lines longer than 2000 characters will be truncated.
+- Results are returned with line numbers in "     1→content" format.
+
+## File Type Support
+
+- **Text files**: All text files are read with line numbers. This is the default behavior.
+- **Image files** (PNG, JPG, GIF, SVG, WebP, BMP, ICO): Returns a base64-encoded data URI that can be visually analyzed. Use this when the user asks you to look at a screenshot or image.
+- **PDF files** (.pdf): Extracts text content from PDF pages. For large PDFs (10+ pages), use the `pages` parameter to read specific page ranges (e.g. pages="1-5"). Maximum 20 pages per request.
+- **Jupyter notebooks** (.ipynb): Parses the notebook JSON and returns all cells with their type, source, and outputs in a readable format. Combines code, text, and output for easy understanding.
+
+## Critical Rules
+
+- ALWAYS use `read` to view files. NEVER use `bash` with cat/head/tail/type/Get-Content.
+- You MUST read a file before editing it with `edit`. Edits on unread files are rejected.
+- You can call multiple `read` tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
+- If the user provides a path to a screenshot, ALWAYS use this tool to view the file at that path.
+
+## Parameters
+
+- path (required): file path (absolute or relative)
+- offset (optional): start line number (1-based). Only provide if the file is too large to read at once.
+- limit (optional): max lines to return. Only provide if the file is too large to read at once.
+- encoding (optional): file encoding (default: utf8)
+- pages (optional): page range for PDF files (e.g. "1-5", "3", "10-20"). Only applicable to PDF files.
+
+## Tips
+
+- Read the full file first to understand context before editing. Do not provide offset/limit unless necessary.
+- For large files (1000+ lines), use offset+limit to read specific sections.
+- After a failed edit, re-read the file — it may have changed since your last read.
+- Line numbers in output help you locate exact positions for edits.
+- When reading multiple related files, read them all in parallel for efficiency.
+- When editing text from read output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + →. Everything after that → is the actual file content to match. Never include any part of the line number prefix in edit operations.

package/src/tool/prompt/task.txt

@@ -0,0 +1,83 @@
+Launch a subagent to handle complex, multi-step tasks autonomously.
+
+Each task spawns a full, independent LLM session with its own context window. The subagent makes its own tool calls and returns a single result message when done.
+
+# Available subagent types
+
+- **explore** — Fast codebase exploration specialist. Use for: finding files by patterns, searching code for keywords, understanding project structure, tracing import/export chains, answering questions about the codebase. Read-only. (Tools: read, glob, grep, list, bash)
+- **architect** — Feature architecture designer. Use for: analyzing codebase patterns and conventions, designing implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences. Read-only. (Tools: read, glob, grep, list, bash)
+- **reviewer** — Code review specialist. Use for: finding bugs, logic errors, security vulnerabilities, code quality issues, and adherence to project conventions. Read-only. (Tools: read, glob, grep, list, bash)
+- **researcher** — Deep research agent. Use for: investigating unfamiliar libraries, combining local code analysis with web search, producing research reports with sources. Read-only with web access. (Tools: read, glob, grep, list, bash, websearch, codesearch, webfetch)
+- **guide** — kkcode self-help guide. Use when the user asks "How do I...", "Can kkcode...", "What tool should I use for..." questions about kkcode itself. Searches kkcode source code for accurate answers. Read-only. (Tools: read, glob, grep, list, webfetch, websearch)
+- **security-reviewer** — Security audit specialist. Use for: OWASP Top 10 checks, hardcoded secret scans, dependency audits, authentication/authorization reviews. Read-only. (Tools: read, glob, grep, list, bash)
+- **tdd-guide** — TDD specialist. Use for: guiding test-driven development workflows (scaffold→RED→GREEN→REFACTOR), writing failing tests first, targeting 80%+ coverage. Full access. (Tools: read, write, edit, bash, glob, grep, list)
+- **build-fixer** — Build error resolver. Use for: diagnosing build failures, identifying root causes (type errors, missing imports, dependency conflicts), applying fixes, verifying builds. Full access. (Tools: read, write, edit, bash, glob, grep, list)
+- **(default)** — Full-capability build agent. Use for: complex multi-file changes, refactoring, test writing, any task requiring file mutations.
+
+# When to Use This Tool
+
+Use `task` when the work:
+- Requires multiple tool calls and autonomous reasoning (e.g. "refactor module X", "write tests for Y")
+- Benefits from an independent context window (protects main conversation from result noise)
+- Involves code review, deep research, or broad codebase exploration
+- Can be parallelized — launch multiple independent tasks simultaneously
+
+<example>
+User: "Please investigate how authentication works in this project"
+→ Launch task with subagent_type="explore", prompt="Trace the authentication flow..."
+
+Reasoning: Open-ended exploration that may require many file reads. Subagent keeps main context clean.
+</example>
+
+<example>
+User: "Refactor the database module and update all tests"
+→ Launch task with default subagent, prompt="Refactor src/db/... and update test/db/..."
+
+Reasoning: Complex multi-file change requiring autonomous execution.
+</example>
+
+<example>
+User: "Review this PR for security issues"
+→ Launch task with subagent_type="reviewer", prompt="Review all changed files for..."
+
+Reasoning: Code review benefits from dedicated context and structured output.
+</example>
+
+# When NOT to Use — use the appropriate tool directly instead
+
+Do NOT use `task` as a wrapper for simple operations:
+- Reading a specific file → use `read` directly
+- Searching for a specific class/function → use `grep` or `glob` directly
+- Running a shell command → use `bash` directly
+- Making a small file edit → use `edit` directly
+- Creating a file → use `write` directly
+- Any single-step operation → use the appropriate tool directly
+
+<example>
+BAD: task(prompt="Read the file src/config.mjs and tell me what it exports")
+GOOD: read(path="src/config.mjs") — then analyze the content yourself
+
+BAD: task(prompt="Search for all files named *.test.js")
+GOOD: glob(pattern="**/*.test.js")
+</example>
+
+# Parameters
+
+- **prompt** (required): Detailed task description with ALL necessary context. The subagent starts fresh — it cannot see your conversation history. Include:
+  - What to do (specific instructions)
+  - Why (context for decision-making)
+  - Whether to write code or just research
+  - Key file paths or patterns to start with
+
+- **subagent_type** (optional): One of "explore", "architect", "reviewer", "researcher", or omit for default build agent.
+
+- **run_in_background** (optional): Set to true to run as a background worker. Returns a task_id immediately — use `background_output` to check results later.
+
+# Important Behaviors
+
+- Each `task` call spawns a full LLM session — it is expensive and slow. Use it deliberately.
+- The subagent's result is NOT visible to the user. You MUST send a text message summarizing the result.
+- You can launch multiple tasks in parallel for independent work — this is a key advantage.
+- Avoid duplicating work that subagents are already doing. If you delegated research, don't also search yourself.
+- Provide clear, self-contained prompts. The subagent has no access to your conversation context.
+- Clearly state whether you expect the agent to write code or just do research, since it cannot infer your intent.

package/src/tool/prompt/todowrite.txt

@@ -0,0 +1,117 @@
+Create and manage a structured task list for tracking multi-step work. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user. It also helps the user understand the progress of your work.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+1. **Complex multi-step tasks** — When a task requires 3 or more distinct steps or actions
+2. **Non-trivial tasks** — Tasks requiring careful planning or multiple operations
+3. **User provides multiple tasks** — When users provide a list of things to be done (numbered or comma-separated)
+4. **After receiving new instructions** — Immediately capture user requirements as todos
+5. **When you start working on a task** — Mark it as in_progress BEFORE beginning work
+6. **After completing a task** — Mark it as completed and add any follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+1. There is only a single, straightforward task
+2. The task is trivial and tracking provides no benefit
+3. The task can be completed in less than 3 trivial steps
+4. The task is purely conversational or informational
+
+NOTE: Do NOT use this tool if there is only one trivial task. Just do it directly.
+
+## Examples of When to Use
+
+<example>
+User: I want to add a dark mode toggle to the application settings. Make sure you run the tests when done!
+→ Create todo list:
+  1. Create dark mode toggle component in Settings page
+  2. Add dark mode state management (context/store)
+  3. Implement theme styles for dark mode
+  4. Update existing components to support theme switching
+  5. Run tests and fix any failures
+
+Reasoning: Multi-step feature requiring UI, state management, and styling changes. User explicitly asked for tests.
+</example>
+
+<example>
+User: Help me rename the function getCwd to getCurrentWorkingDirectory across my project
+→ First search to understand scope, then create todo list with one item per file that needs updating.
+
+Reasoning: Multiple files affected, systematic tracking prevents missing any occurrence.
+</example>
+
+<example>
+User: I need to implement user registration, product catalog, shopping cart, and checkout flow.
+→ Create todo list breaking down each feature into specific tasks.
+
+Reasoning: User provided multiple complex features in a list.
+</example>
+
+## Examples of When NOT to Use
+
+<example>
+User: How do I print "Hello World" in Python?
+→ Just answer directly. No todo needed.
+
+Reasoning: Single, trivial, informational task.
+</example>
+
+<example>
+User: Fix the typo in the README
+→ Just fix it directly. No todo needed.
+
+Reasoning: Single straightforward task, no multi-step planning required.
+</example>
+
+<example>
+User: Run npm install for me
+→ Just run it. No todo needed.
+
+Reasoning: Single command execution with immediate results.
+</example>
+
+## Task States and Management
+
+Task states: pending, in_progress, completed
+
+IMPORTANT — Task descriptions must have two forms:
+- content: imperative form describing what needs to be done (e.g. "Run tests", "Fix authentication bug")
+- activeForm: present continuous form shown during execution (e.g. "Running tests", "Fixing authentication bug")
+
+Rules:
+- Update task status in real-time as you work
+- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+- Exactly ONE task must be in_progress at any time (not less, not more)
+- Complete current tasks before starting new ones
+- Remove tasks that are no longer relevant from the list entirely
+
+## Task Completion Requirements
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+## Task Breakdown Guidelines
+
+- Create specific, actionable items
+- Break complex tasks into smaller, manageable steps
+- Use clear, descriptive task names
+- Always provide both forms:
+  - content: "Fix authentication bug"
+  - activeForm: "Fixing authentication bug"
+
+When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
+
+## Parameters
+
+- todos (required): array of task objects
+  - content (required): task description in imperative form
+  - status (required): "pending" | "in_progress" | "completed"
+  - activeForm (required): present continuous form shown during execution

package/src/tool/prompt/webfetch.txt

@@ -0,0 +1,38 @@
+Fetch content from a URL and return it as processed text.
+
+IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, private GitHub repos). For GitHub URLs, prefer using `bash` with `gh` CLI instead (e.g. gh pr view, gh issue view, gh api).
+
+Use cases:
+- Retrieve documentation or API references from public URLs
+- Read web pages for research
+- Fetch remote configuration or data
+
+Parameters:
+- url (required): URL to fetch (must be a valid HTTP/HTTPS URL)
+- prompt (optional): instruction for how to process/extract information from the content
+
+Notes:
+- HTML is automatically converted to Markdown for readability
+- Large content (over 50KB) is truncated
+- Only use for public, unauthenticated URLs
+- HTTP URLs are automatically upgraded to HTTPS
+- Includes a 30-second timeout
+- Includes a self-cleaning 15-minute cache for faster repeat access
+- Do NOT use for local file reading — use `read` instead
+- Do NOT generate or guess URLs. Only use URLs provided by the user or found in project files.
+
+Examples:
+<good-example>
+# Fetch public documentation
+webfetch url="https://docs.example.com/api" prompt="Extract all REST endpoints and their parameters"
+</good-example>
+<bad-example>
+# WRONG: authenticated URL — will fail
+webfetch url="https://docs.google.com/document/d/abc123/edit"
+# Instead: ask the user to paste the content or use an MCP tool with auth
+</bad-example>
+<bad-example>
+# WRONG: GitHub URL — use gh CLI instead
+webfetch url="https://github.com/org/repo/pull/42"
+# Instead: bash "gh pr view 42"
+</bad-example>

package/src/tool/prompt/websearch.txt

@@ -0,0 +1,43 @@
+Search the web for up-to-date information using Exa AI.
+
+IMPORTANT — When to use PROACTIVELY (reduce hallucination):
+- You are unsure about a fact, API, library version, or behavior
+- The user asks about recent events, releases, or changelogs
+- You encounter an unfamiliar error message or deprecation warning
+- You need to verify correct syntax or configuration for a specific version
+- The topic is beyond your training data cutoff
+
+Do NOT guess when you can search. A quick websearch is always better than a confident hallucination.
+
+Parameters:
+- query (required): search query — be specific, include version numbers and context
+- numResults (optional): number of results (default: 5)
+- type (optional): "auto" (balanced, default), "fast" (quick), "deep" (comprehensive)
+
+## When NOT to Use
+- Do NOT search for information you already know with high confidence (basic syntax, well-known APIs).
+- Do NOT search when the answer is in the local codebase — use `grep` or `read` first.
+- Do NOT search for user-specific context (their business logic, variable names, etc.) — that's in their code.
+
+Tips:
+- ALWAYS include the current year in queries for time-sensitive topics (e.g. "React 19 new hooks 2026")
+- Use specific error messages as queries when debugging
+- Prefer "deep" type for complex research questions
+- Include library/framework version numbers when relevant
+
+Examples:
+<good-example>
+# Debugging an unfamiliar error
+websearch query="TypeError: Cannot read properties of undefined reading 'map' React 18 2026"
+</good-example>
+<good-example>
+# Checking latest API syntax
+websearch query="Next.js 15 app router middleware configuration 2026"
+</good-example>
+<bad-example>
+# Too vague — add specifics
+websearch query="how to use React"
+# Better: websearch query="React 19 useOptimistic hook example 2026"
+</bad-example>
+
+CRITICAL: After answering the user's question with search results, you MUST include a "Sources:" section at the end with source URLs as markdown hyperlinks so the user can verify the information.

package/src/tool/prompt/write.txt

@@ -0,0 +1,38 @@
+Writes a file to the local filesystem. Creates parent directories automatically.
+
+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.
+- ALWAYS prefer editing existing files with `edit`. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation if explicitly requested by the user.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
+
+IMPORTANT:
+- Parent directories are created automatically — no need to `mkdir` first.
+- For small files: include COMPLETE content in a single call.
+- For large files (200+ lines): use mode="append" to build incrementally across multiple calls.
+- For reading files, use the `read` tool — never use `bash` with cat/type/Get-Content.
+- Do NOT use `write` when only a small part of an existing file needs to change — use `edit` or `patch` instead.
+- Do NOT delegate file creation to `task` — just call `write` directly.
+
+Parameters:
+- path (required): file path (absolute or relative)
+- content (required): file content to write
+- mode (optional): "overwrite" (default), "append", or "insert"
+  - overwrite: replaces entire file (default behavior)
+  - append: adds content to end of existing file (creates file if new)
+  - insert: inserts content at a specific line, shifting existing lines down
+- insert_at_line (optional): 1-based line number for insert mode
+
+Building large files incrementally (avoids output truncation):
+1. First call: write(path, content, mode="overwrite") — create with initial section
+2. Subsequent calls: write(path, content, mode="append") — add remaining sections
+Each call should be ~100-150 lines to stay well within output limits.
+
+When to use `write` vs `edit` vs `patch`:
+- New file that doesn't exist yet → `write`
+- Replacing entire file content → `write` (after reading it first)
+- Adding content to end of file → `write` with mode="append"
+- Changing a few lines in an existing file → `edit`
+- Renaming a variable across a file → `edit` with replace_all
+- Replacing a large section by line numbers → `patch`

package/src/tool/prompt-loader.mjs

@@ -0,0 +1,18 @@
+import path from "node:path"
+import { readFile } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { renderTemplate } from "../util/template.mjs"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const PROMPT_DIR = path.join(__dirname, "prompt")
+
+const cache = new Map()
+
+export async function loadToolPrompt(name, vars = {}) {
+  if (!cache.has(name)) {
+    const file = path.join(PROMPT_DIR, name)
+    const text = (await readFile(file, "utf8")).trim()
+    cache.set(name, text)
+  }
+  return renderTemplate(cache.get(name), vars)
+}

package/src/tool/question-prompt.mjs

@@ -0,0 +1,86 @@
+import { stdin as input, stdout as output } from "node:process"
+import { createInterface } from "node:readline/promises"
+
+let customPromptHandler = null
+
+export function setQuestionPromptHandler(handler) {
+  customPromptHandler = typeof handler === "function" ? handler : null
+}
+
+export async function askQuestionInteractive({ questions }) {
+  if (!Array.isArray(questions) || questions.length === 0) {
+    return {}
+  }
+
+  // 1. TUI handler (registered by repl.mjs)
+  if (customPromptHandler) {
+    const answers = await customPromptHandler({ questions })
+    if (answers && typeof answers === "object") return answers
+  }
+
+  // 2. Non-TTY: return empty answers
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    return Object.fromEntries(questions.map((q) => [q.id, ""]))
+  }
+
+  // 3. TTY fallback: readline sequential Q&A
+  const rl = createInterface({ input, output })
+  const answers = {}
+  try {
+    for (const q of questions) {
+      console.log("")
+      console.log(`  ${q.text}`)
+      if (q.description) console.log(`  ${q.description}`)
+      const options = Array.isArray(q.options) ? q.options : []
+      if (options.length) {
+        for (let i = 0; i < options.length; i++) {
+          const opt = options[i]
+          console.log(`    ${i + 1}. ${opt.label}`)
+          if (opt.description) console.log(`       ${opt.description}`)
+        }
+        if (q.allowCustom !== false) {
+          console.log(`    ${options.length + 1}. Custom...`)
+        }
+      }
+      const raw = (await rl.question("  > ")).trim()
+      if (options.length) {
+        const idx = parseInt(raw, 10)
+        if (idx >= 1 && idx <= options.length) {
+          const chosen = options[idx - 1]
+          answers[q.id] = chosen.value || chosen.label
+        } else {
+          answers[q.id] = raw
+        }
+      } else {
+        answers[q.id] = raw
+      }
+    }
+  } finally {
+    rl.close()
+  }
+  return answers
+}
+
+export async function askPlanApproval({ plan, files = [] }) {
+  const fileList = files.length ? `\nFiles to modify:\n${files.map(f => `  - ${f}`).join("\n")}` : ""
+  const questions = [
+    {
+      id: "plan_approval",
+      text: `Plan Review`,
+      description: `${plan}${fileList}`,
+      options: [
+        { label: "Approve", value: "approve", description: "Proceed with this plan" },
+        { label: "Reject", value: "reject", description: "Reject and provide feedback" }
+      ],
+      multi: false,
+      allowCustom: true
+    }
+  ]
+  const answers = await askQuestionInteractive({ questions })
+  const answer = String(answers.plan_approval || "").trim().toLowerCase()
+  if (answer === "approve" || answer === "1") {
+    return { approved: true, feedback: "" }
+  }
+  const feedback = answer === "reject" || answer === "2" ? "" : answer
+  return { approved: false, feedback }
+}