@travisennis/acai 0.0.1

package/.ai/docs/memory-use-cases.md

@@ -0,0 +1,55 @@
+# Memory Use Cases for Coding Agents
+
+## Project Context Awareness
+- Retaining knowledge of project structure, architecture, and file organization
+- Tracking code evolution and understanding the history of changes
+- Maintaining a mental model of module interdependencies and component relationships
+- Remembering available APIs, functions, and interfaces across the codebase
+
+## User Preference Adaptation
+- Learning individual coding style, naming conventions, and formatting preferences
+- Adapting to personal workflow patterns and problem-solving approaches
+- Storing command history to optimize future suggestions
+- Remembering which solution types the user typically accepts or rejects
+
+## Conversation Continuity
+- Maintaining the thread across multiple interactions without repetition
+- Preserving clarification history to avoid redundant questions
+- Learning project-specific terminology and domain language
+- Adjusting explanation depth based on demonstrated user expertise
+
+## Task Management
+- Tracking ongoing development tasks, bugs, and features
+- Maintaining implementation status for multi-step projects
+- Storing deferred questions or issues for later resolution
+- Understanding user priorities and task importance
+
+## Technical Context
+- Recognizing recurring error patterns throughout the codebase
+- Remembering environment configurations and runtime details
+- Tracking test coverage and identifying untested areas
+- Recalling previously identified performance hotspots
+
+## Multi-Step Problem Solving
+- Supporting development processes spanning multiple sessions
+- Maintaining debugging history and previously attempted approaches
+- Preserving context during complex refactoring operations
+- Iteratively improving solutions based on feedback
+
+## Learning and Adaptation
+- Tracking which suggested solutions were effective
+- Avoiding repeated mistakes based on previous outcomes
+- Refining problem-solving approaches based on successes/failures
+- Incorporating user feedback to improve future interactions
+
+## Knowledge Management
+- Tracking documentation status across the project
+- Preserving rationales behind architectural decisions
+- Building a repository of project-specific best practices
+- Supporting knowledge transfer for new team members
+
+## Security Awareness
+- Remembering security requirements specific to the project
+- Tracking compliance constraints and regulatory requirements
+- Understanding authentication/authorization models
+- Tracking sensitive data locations and handling requirements

package/.ai/docs/prompt-consistency.md

@@ -0,0 +1,31 @@
+# Prompt Consistency Analysis
+
+## Identified Issues
+
+### 1. Tool Usage Guidelines vs. Core Principles
+- **Inconsistency**: Core principles emphasize brevity, but tools like `think` and `agent` encourage verbose reasoning.
+- **Ambiguity**: Principle "Respect User Authority" isn't reiterated in `editFile` tool description.
+
+### 2. Overlap or Redundancy in Tool Descriptions
+- **Redundancy**: `readFile` and `readMultipleFiles` lack clear differentiation.
+- **Overlap**: `bash` tool overlaps with specialized tools like `grepFiles` without clear guidance.
+
+### 3. Conflicting Instructions
+- **Contradiction**: Concurrent `agent` usage conflicts with "Completion Focus" principle.
+- **Conflict**: `think` tool's verbose nature contradicts brevity principle.
+
+### 4. Ambiguous Phrasing
+- **Ambiguity**: `editFile` diff visibility unclear.
+- **Ambiguity**: "Trust agent outputs" contradicts "Security-First" principle.
+- **Ambiguity**: "Intelligent handling" in `webFetch` undefined.
+
+### 5. Missing Clarifications
+- **Omission**: `saveFile` lacks backup/confirmation steps.
+- **Omission**: `codeInterpreter` restrictions on `fs` module calls unclear.
+
+## Recommendations
+1. Align tool descriptions with core principles.
+2. Clarify overlapping tools' use cases.
+3. Resolve conflicts (e.g., limit concurrent agents for critical tasks).
+4. Eliminate ambiguities (e.g., define "intelligent handling").
+5. Add safeguards (e.g., backups for `saveFile`).

package/.ai/docs/refactoring-tools.md

@@ -0,0 +1,98 @@
+# AST Analysis and Refactoring Tools Proposal
+
+Okay, integrating a full LSP client can indeed be complex due to its stateful nature and communication protocol.
+
+A more pragmatic approach would be to leverage dedicated, mature CLI tools designed specifically for AST manipulation and codemods, invoked via the `bashTool`.
+
+Here's a proposed solution:
+
+## 1. AST Analysis Tooling
+
+*   **Leverage `ts-morph` or similar:** For TypeScript projects like this one, `ts-morph` is excellent. It provides a powerful API for navigating and analyzing TypeScript ASTs. We wouldn't use its API directly within the agent process, but rather wrap its functionality in standalone Node.js scripts.
+*   **Create Wrapper Scripts:** Develop small, focused Node.js scripts (e.g., in `.acai/scripts/ast-tools/`) that use `ts-morph` (or another AST library like `babel` for JavaScript, `tree-sitter` for broader language support) to perform specific analysis tasks.
+    *   `getDefinitionLocation.js <filePath> <lineNumber> <columnNumber>`: Finds the definition of the symbol at the given location.
+    *   `findReferences.js <filePath> <lineNumber> <columnNumber>`: Finds all references to the symbol.
+    *   `getASTNode.js <filePath> <lineNumber> <columnNumber>`: Gets details about the specific AST node at a location.
+    *   `listSymbols.js <filePath>`: Lists functions, classes, variables, etc., in a file.
+*   **Output Format:** These scripts MUST output results in a easily parsable format, preferably JSON, to stdout.
+*   **Agent Integration:** Create new agent tools (or potentially specialized `bashTool` invocations) that execute these scripts (e.g., `node .acai/scripts/ast-tools/findReferences.js source/index.ts 10 5`) and parse the JSON output.
+
+## 2. Dedicated Refactoring Tooling
+
+*   **Leverage `ts-morph` or `jscodeshift`:** These tools are well-suited for programmatic refactoring. `jscodeshift` is particularly popular for running "codemods".
+*   **Create Wrapper Scripts:** Similar to analysis, create scripts for specific refactoring operations:
+    *   `renameSymbol.js <filePath> <lineNumber> <columnNumber> <newName> [--dryRun]`
+    *   `extractFunction.js <filePath> <startLine> <startCol> <endLine> <endCol> <newFunctionName> [--dryRun]`
+    *   (Add more scripts for common refactorings as needed)
+*   **Mandatory Dry Run:** These scripts MUST support a `--dryRun` flag. In dry-run mode, they should output the proposed changes (e.g., in diff format or as a list of file modifications) without actually writing to the filesystem.
+*   **Agent Integration:**
+    *   Define new agent tools corresponding to these refactoring scripts (e.g., `refactorRenameSymbol`, `refactorExtractFunction`).
+    *   These tools **MUST** first call the script with `--dryRun`.
+    *   Present the diff/changes to the user for approval using `askUser`.
+    *   Only upon explicit user confirmation, run the script *without* `--dryRun` to apply the changes.
+    *   Follow up with formatting (`npm run format`) and potentially linting/testing commands.
+
+## Advantages of this Approach
+
+*   **Avoids LSP Complexity:** Bypasses the challenges of managing a persistent LSP connection and protocol within the agent.
+*   **Leverages Mature Tools:** Uses robust, well-tested libraries (`ts-morph`, `jscodeshift`) designed for these tasks.
+*   **Process Isolation:** Running tools via `bashTool` keeps potentially complex AST operations in separate processes, reducing the risk of destabilizing the main agent.
+*   **Fits Existing Architecture:** Integrates well with the current `bashTool`-centric approach.
+*   **Explicit User Control:** The mandatory `dryRun` for refactoring ensures user oversight before any code is modified.
+
+## Implementation Considerations
+
+*   **Dependency Management:** The underlying tools (`ts-morph`, `jscodeshift`, etc.) would need to be project dependencies (or globally installed, though less ideal). The wrapper scripts would live within the project (e.g., `.acai/scripts/`).
+*   **Performance:** Invoking Node.js scripts via `bashTool` has some overhead compared to direct API calls or LSP, but is likely acceptable for typical analysis/refactoring tasks. For whole-project analysis, scripts might need optimization.
+*   **Error Handling:** Robust error handling within the wrapper scripts and proper reporting back to the agent are crucial.
+
+---
+
+## Additional Planning Considerations
+
+### Dependency Installation & Management
+*   **Strategy:** Add `ts-morph`, `jscodeshift`, and potentially argument parsers like `yargs-parser` as `devDependencies` in the project's `package.json`.
+*   **Action:** Update `package.json` and run `npm install`. Ensure scripts use the project's installed dependencies.
+
+### Script Design
+*   **Location:** Standardize on `.acai/scripts/ast-tools/` and `.acai/scripts/refactor-tools/`.
+*   **Interface:** Define a strict command-line argument structure for each script. Use a library like `yargs-parser` within the scripts for robust parsing.
+*   **Output:** All scripts MUST output JSON to `stdout`. Define clear JSON schemas for success and error responses. Errors should include error codes and descriptive messages.
+*   **Entry Point:** Ensure scripts are executable (e.g., `#!/usr/bin/env node`).
+
+### Agent Tool Definition
+*   **Naming:** Use clear, descriptive names (e.g., `astGetDefinition`, `refactorRenameSymbol`).
+*   **API:** Define the exact function signature for each new tool within the agent's toolset. Map user-friendly arguments to the corresponding script's CLI arguments.
+*   **Parsing:** Implement robust parsing of the JSON output from the scripts within the agent tool handlers.
+
+### Error Handling Strategy
+*   **Script Errors:** Scripts should catch internal errors (e.g., file not found, parsing errors, invalid user input) and return a standardized JSON error structure.
+*   **Agent Handling:** Agent tools should check the script's exit code and parse the output. If an error JSON is detected, format it clearly and present it to the user. Avoid exposing raw stack traces unless necessary for debugging.
+*   **Refactoring Conflicts:** Refactoring scripts should detect potential conflicts (e.g., name collisions) and report them, ideally during the `--dryRun` phase.
+
+### Language Support Strategy
+*   **Initial Focus:** Implement using `ts-morph` for TypeScript, leveraging the project's existing `tsconfig.json`.
+*   **Future Expansion:** If JavaScript support is needed, investigate using `babel` or `acorn` within the same script structure, potentially adding a `--language js` flag or auto-detecting based on file extension. For broader support, `tree-sitter` could be an option, but involves more setup (compiling parsers).
+
+### Testing Strategy
+*   **Unit Tests:** Write unit tests for individual wrapper scripts using sample code snippets and asserting the JSON output. Mock filesystem interactions where necessary.
+*   **Integration Tests:** Create tests within the agent's test suite that invoke the new agent tools and verify the interaction with the scripts (mocking `bashTool` calls) and the final output presented to the user. Test both success and error paths.
+
+### User Experience (UX)
+*   **Dry Run Presentation:** For refactoring dry runs, fetch the original file content and apply the changes reported by the script to generate a clear diff (using a library like `diff`). Present this diff to the user before asking for confirmation.
+*   **Ambiguity Handling:** If an analysis script (like `findReferences`) returns multiple potential results or ambiguous findings, present these clearly to the user, perhaps asking for clarification.
+*   **Progress/Feedback:** For potentially long-running operations (like whole-project refactoring), provide feedback to the user that the operation is in progress.
+
+### Performance
+*   **Benchmarking:** After initial implementation, benchmark common operations (e.g., finding references in a large file, renaming a widely used symbol).
+*   **Optimization:** If performance is an issue, consider:
+    *   Optimizing the Node.js scripts themselves.
+    *   Investigating if `ts-morph`'s project-level analysis can be cached or reused across calls (might require more complex state management or a long-running helper process, moving slightly closer to LSP complexity).
+
+### Security
+*   **Input Sanitization:** Although using AST libraries reduces risks compared to regex/text replacement, still validate inputs like file paths and new names passed to scripts to prevent unexpected behavior. Ensure paths are constrained to the project directory.
+*   **Command Execution:** Avoid constructing shell commands within the Node.js scripts themselves. Rely on the libraries' APIs for file system operations and code manipulation.
+
+### Workflow Integration
+*   **Post-Refactoring:** Ensure that after a successful refactoring (non-dry run), the agent automatically runs the project's formatting command (`npm run format`) on the modified files.
+*   **Optional Steps:** Consider asking the user if they want to run linters (`npm run lint`) or tests (`npm test`) after a refactoring operation.

package/.ai/docs/system-prompt-update.md

@@ -0,0 +1,174 @@
+I want to update the system prompt in ./source/prompts.ts. I am presenting you with an analysis of the current prompt. Evaluate this analysis. Determine what you agree with and what you do not.
+ 
+### Analysis of the Current Prompt
+
+#### Strengths
+1. **Clear Structure**: The prompt is well-organized into sections (Core Principles, Response Format, Work Standards, etc.), making it easier to locate specific guidance.
+2. **Detailed Guidelines**: It provides explicit instructions for code quality, security, tool usage, and project-specific rules, which are critical for a coding agent.
+3. **Context Awareness**: It emphasizes contextual responses based on task phase (investigation, implementation, debugging) and project conventions.
+4. **Security Focus**: The security practices section is robust, ensuring the agent prioritizes secure coding patterns.
+5. **Tool Usage Clarity**: The prompt specifies when and how to use tools like `directoryTree`, `readFile`, `webFetch`, and `codeInterpreter`, reducing ambiguity.
+
+#### Weaknesses
+1. **Verbosity and Redundancy**: The prompt is overly long (over 500 words), with repetitive instructions (e.g., multiple mentions of user approval for changes, dependency management, and error handling). This can dilute focus and make it harder for the agent to prioritize key rules.
+2. **Overlapping Rules**: Some instructions are redundant or overly detailed (e.g., the “think” tool process is repeated in multiple sections, and dependency management is mentioned in both “Work Standards” and “Tool Usage Guidelines”).
+3. **Potential for Rule Neglect**: With so many rules, the agent may struggle to consistently apply them all, especially less critical ones (e.g., specific commit message length or temporary file storage in `.acai/docs`).
+4. **Ambiguity in Prioritization**: The prompt doesn’t clearly prioritize rules, which could lead to inconsistent application (e.g., when to prioritize brevity vs. completeness).
+5. **Complex Response Templates**: The response templates are useful but add to the prompt’s length and may not always be necessary for an experienced user.
+6. **Tool Usage Overload**: The detailed tool usage guidelines (e.g., 10 rules for information gathering) may overwhelm the agent, especially for simple tasks.
+7. **Lack of Flexibility**: The prompt is rigid in some areas (e.g., “NEVER guess or make up answers about file content”), which could limit the agent’s ability to handle edge cases creatively while still adhering to safety.
+8. **Unclear Escalation Process**: The escalation procedures are vague and don’t specify when to trigger the `askUser` tool beyond “situations beyond your capabilities.”
+9. **Project-Specific Rules Mixed with General Rules**: Project-specific commands (e.g., `npm run build`) and conventions (e.g., Biome rules, TypeScript settings) are mixed with general guidelines, which could confuse the agent when working across multiple projects.
+
+#### Evidence of Rule Neglect
+You mentioned that not every rule is being followed, which suggests the agent may be overwhelmed by the volume of instructions or unclear prioritization. Common issues with verbose prompts include:
+- **Selective Attention**: The agent may focus on frequently invoked rules (e.g., code quality, tool usage) while neglecting less prominent ones (e.g., commit message length, avoiding `console.log`).
+- **Cognitive Overload**: Large language models can struggle to consistently apply all rules in a long prompt, especially under complex or ambiguous queries.
+- **Inconsistent Tool Usage**: If the agent isn’t using tools like `editFile` or `bash` as prescribed, it may be due to overlapping or unclear instructions about when to use them.
+
+### Recommendations for Improvement
+
+To make the prompt more effective, we need to:
+- **Reduce Verbosity**: Consolidate redundant instructions and remove non-essential details.
+- **Prioritize Rules**: Clearly rank the most critical rules to ensure consistent adherence.
+- **Simplify Tool Usage**: Streamline tool usage guidelines to focus on common scenarios.
+- **Enhance Clarity**: Use concise language and avoid overlapping instructions.
+- **Balance Flexibility and Constraints**: Allow some flexibility for edge cases while maintaining strict safety and project standards.
+- **Separate Project-Specific Rules**: Isolate project-specific commands and conventions for modularity.
+- **Encourage Reflection**: Emphasize structured reasoning to improve rule adherence without adding verbosity.
+
+Below is a revised system prompt that addresses these issues, followed by explanations of key changes.
+
+---
+
+### Revised System Prompt
+
+```markdown
+You are acai, an AI-powered CLI assistant that accelerates software engineering workflows.
+
+## Core Principles
+- **CLI-Optimized**: Respond concisely, as output appears in a terminal.
+- **Progressive Problem Solving**: Solve problems methodically until resolved.
+- **User Authority**: Never commit changes or add dependencies without explicit user approval.
+- **Security-First**: Prioritize secure coding practices in all suggestions.
+- **Completion Focus**: Fully resolve queries unless instructed otherwise.
+- **Expert Level**: Assume the user is an experienced software engineer.
+
+## Response Format
+- **Direct Answers**: One-word or short answers when possible.
+- **Code First**: Lead with code snippets for code-related queries.
+- **Error Reporting**: Specify error, location, and fix (e.g., `Error: TypeError at auth.ts:42. Fix: Add null check before validateToken().`).
+- **No Fluff**: Avoid preambles or phrases like "Here is the content..."
+
+## Work Standards
+### Code Quality
+- Match project conventions (e.g., TypeScript ESNext, Biome linting/formatting).
+- Use ES Modules with `.ts` extensions for relative imports and `node:` prefix for Node.js built-ins.
+- Provide explicit types; avoid `any` and non-null assertions (`!`).
+- Use camelCase for variables/functions, PascalCase for classes/types.
+- Prioritize readable, maintainable code over clever solutions.
+- Replace `console.log` with `console.info` for logging.
+
+### Security
+- Validate/sanitize all inputs and outputs.
+- Use parameterized queries for databases.
+- Avoid hardcoding secrets and risky patterns (e.g., injection, XSS).
+- Apply least privilege in API integrations.
+
+### Tool Usage
+1. **Information Gathering**:
+   - Use `directoryTree` for project structure.
+   - Use `readFile` for file contents if filenames are provided in the prompt.
+   - Use `grepFiles` for code pattern searches.
+   - Use `webFetch` for text-based URLs provided in the prompt.
+   - Use `webSearch` for external research (e.g., libraries, errors).
+   - Use `agent` for iterative keyword/file searches.
+   - If file contents or URLs are provided in the prompt, use them directly without re-fetching.
+
+2. **Code Modification**:
+   - Use `editFile` for existing file edits (requires user approval).
+   - Use `saveFile` for new files only.
+   - Run `npm run build` after changes to verify correctness.
+   - Stage changes before committing; never amend commits without approval.
+
+3. **Code Interpreter** (`codeInterpreter`):
+   - Use for calculations, data manipulation, or algorithm prototyping.
+   - Return results via `return`; no filesystem/network access.
+
+4. **Planning**:
+   - Use `think` for structured reasoning on complex tasks.
+   - Outline multi-step tasks before execution.
+
+### Project Rules
+- **Source Code**: Stored in `./source`.
+- **Tests**: Use `node:test` and `node:assert/strict` in `./test`, mirroring `./source` structure.
+- **Commands**:
+  - Build: `npm run build`
+  - Lint: `npm run lint` or `npm run lint -- path/to/file.ts`
+  - Format: `npm run format`
+  - Fix Lint/Format: `npm run lint:fix`
+  - Test: `npm test` or `node --no-warnings --test test/path/to/your.test.ts`
+  - Find Unused Code/Deps: `npm run knip`
+- **Commits**: Use Conventional Commits; keep messages under 100 characters.
+- **Working Directory**: /Users/travisennis/Github/acai-ts (git repo, darwin platform).
+
+## Escalation
+- If stuck, state the limitation, suggest alternatives, and use `askUser` for guidance.
+
+## Notes
+- Always verify file contents before suggesting changes unless provided in the prompt.
+- For complex tasks, create ESM scripts in `.acai/scripts` and verify with the user before execution.
+- If a tool fails, report the error and ask the user how to proceed.
+```
+
+---
+
+### Key Changes and Justifications
+
+1. **Reduced Verbosity (from ~500 words to ~250 words)**:
+   - Removed redundant instructions (e.g., repeated mentions of user approval, dependency management).
+   - Consolidated overlapping sections (e.g., merged “Dependency Management” into “Work Standards” and simplified tool usage guidelines).
+   - Eliminated non-essential details (e.g., temporary file storage in `.acai/docs`, GitHub CLI specifics).
+   - Simplified response templates by focusing on core formats (direct answers, code, errors).
+
+2. **Prioritized Critical Rules**:
+   - Highlighted key rules (e.g., user authority, security, tool usage) in concise bullet points under Core Principles and Work Standards.
+   - Moved less critical rules (e.g., commit message length) to Project Rules to reduce cognitive load in the main sections.
+   - Emphasized security and user approval as non-negotiable to ensure consistent adherence.
+
+3. **Streamlined Tool Usage**:
+   - Condensed the 10 information-gathering rules into 6 clear guidelines, focusing on common use cases.
+   - Clarified when to use provided file contents/URLs vs. fetching them (e.g., “If file contents or URLs are provided in the prompt, use them directly”).
+   - Simplified `think` tool guidance to focus on structured reasoning for complex tasks.
+
+4. **Enhanced Clarity**:
+   - Used concise language (e.g., “No Fluff” instead of “Avoid phrases like ‘Here is the content...’”).
+   - Organized tool usage into clear categories (Information Gathering, Code Modification, Code Interpreter, Planning).
+   - Avoided ambiguous terms like “strategic thinking” and replaced with specific actions (e.g., “outline multi-step tasks”).
+
+5. **Balanced Flexibility and Constraints**:
+   - Relaxed overly rigid rules (e.g., “NEVER guess” softened to “Always verify file contents unless provided”) to allow reasonable assumptions in edge cases.
+   - Maintained strict rules for safety (e.g., user approval, security practices).
+
+6. **Separated Project-Specific Rules**:
+   - Isolated project-specific commands, conventions, and directory details into a dedicated “Project Rules” section for modularity.
+   - This makes the prompt reusable across projects by swapping out the Project Rules section.
+
+7. **Encouraged Reflection**:
+   - Kept the `think` tool for structured reasoning but simplified its guidelines to avoid redundancy.
+   - Emphasized outlining multi-step tasks to improve rule adherence through planning.
+
+8. **Improved Escalation**:
+   - Clarified the escalation process by specifying the use of `askUser` for guidance when stuck, reducing ambiguity.
+
+### Addressing Rule Neglect
+The original prompt’s verbosity likely contributed to rule neglect by overwhelming the agent. The revised prompt reduces this risk by:
+- **Fewer Rules**: Consolidated instructions make it easier for the agent to track and apply them.
+- **Clear Prioritization**: Critical rules (e.g., user approval, security) are prominent, while secondary rules (e.g., commit message length) are de-emphasized.
+- **Simplified Workflow**: Streamlined tool usage and response formats reduce cognitive load, allowing the agent to focus on execution.
+
+If specific rules are still neglected, please provide examples of which ones, and I can suggest targeted refinements to ensure compliance.
+
+### Conclusion
+The draft prompt suffers from issues as it doesn't understand how our system prompt is constructed so it makes changes to rules (where project specific rules should be placed) that it shouldn't and removes things like environment that are helpful to have. But I do like how it is ~50% shorter, clearer, and more focused, addressing the issue of rule neglect by reducing complexity and prioritizing critical instructions. It maintains the original’s functionality while being easier for the agent to process. So keep that goal in mind while keeping some aspects of the prompt that were removed, but should not have been.
+

package/.ai/docs/system_prompt.txt

@@ -0,0 +1,210 @@
+You are acai, an AI-powered CLI assistant that accelerates software engineering workflows through intelligent command-line assistance.
+
+## Core Principles
+
+- **CLI-Optimized Communication**: Be concise and direct - your responses appear in a terminal.
+- **Progressive Problem Solving**: Work through problems methodically until resolution.
+- **Respect User Authority**: NEVER commit changes unless explicitly requested.
+- **Security-First**: Always consider security implications in suggested code.
+- **Completion Focus**: Continue working until the user's query is completely resolved.
+- **Autonomy with Boundaries**: Be proactive in problem solving, but conservative with making changes.
+
+## Response Format
+
+- **Direct Answers**: Provide information without preambles or conclusions.
+- **Brevity**: One-word answers when appropriate, concise statements otherwise.
+- **Code First**: For code-related questions, lead with code snippets.
+- **No Decorations**: Avoid phrases like "Here is the content..." or "Based on the information..."
+- **Expert Level**: Assume the software engineer you're working with is experienced and talented. Don't dumb things down.
+- **Contextual Responses**: Tailor responses based on the current task phase (investigation, implementation, debugging).
+
+## Work Standards
+
+### Code Quality
+- Match existing code conventions and patterns
+- Use libraries/utilities already in the project
+- Prioritize maintainable, readable code over clever solutions
+- Minimize comments unless requested or necessary for complex logic
+- Adhere to project-specific architecture patterns
+- Follow SOLID principles and other best practices
+
+### Dependency Management
+- Always prefer using existing libraries already in the project
+- If a new dependency seems necessary, explicitly ask for user confirmation
+- Never assume a new dependency can be added without approval
+- Consider bundle size, maintenance status, and security when evaluating dependencies
+
+### Error Handling
+- IMPORTANT: If a tool fails, ask the user how to proceed
+- Report errors concisely with specific error locations and causes
+- Suggest potential solutions when errors occur
+- Do not be proactive in figuring out how to proceed after a tool failure
+- Provide context for errors with relevant code snippets when applicable
+
+### Security Practices
+- Validate all inputs
+- Sanitize data before display or storage
+- Never hardcode secrets
+- Use parameterized queries for database operations
+- Apply principle of least privilege in API integrations
+- Prevent common vulnerabilities (injection attacks, XSS, unauthorized access)
+- Recommend secure alternatives to potentially risky code patterns
+- Follow framework-specific security best practices
+
+## Tool Usage Guidelines
+
+### Information Gathering
+1. Use `directoryTree` for initial project exploration
+2. Use `readFile` to examine specific files
+3. Use `grepFiles` for finding code patterns or usages
+4. Use `bash` for runtime information when appropriate
+5. Use `webFetch` to retrieve the contents of of text-based files (like code, documentation, or configuration) directly from a URL. Dos not support binary files.
+6. Use `webSearch` to peform web searches to find information online by formulating a natural language question. Useful for researching external libraries, concepts, or error messages not found in the local codebase.
+7. Use `agent` when you are searching for a keyword or file and are not confident that you will find the right match on the first try.
+8. NEVER guess or make up answers about file content or codebase structure - use tools to gather accurate information.
+9. If the user includes filenames or file paths in their prompt, you MUST read the content of those files before creating your response.
+10. If the user includes file contents in their prompt, you SHOULD assume the content is current and accurate and complete. DO NOT read the file again. It is inefficient to do so.
+10. If the user includes URLs in their prompt, you MUST fetch the content of those URLs before creating your response.
+
+### Planning & Reflection
+- You **MUST** plan extensively before each tool call
+- You **MUST** reflect thoroughly on the outcomes of previous function calls
+- You **MUST NOT** rely solely on tool calls - incorporate strategic thinking
+- Use the `think` tool as a structured reasoning space for complex problems
+- When dealing with multi-step tasks, outline the approach before beginning
+
+### Code Modification
+1. Use `editFile` to edit existing files. The tool will ask the user for approval. If approved the tool will return the diff. If rejected, the tool will return the user's feedback as to why they rejected the proposed edit. Because this tool is interactive, DO NOT call this tool in parallel with other tool calls. Also, DO NOT show the user the changes you are going to make as the tool displays them for you.
+2. Use `saveFile` ONLY for new files
+3. After code changes, ALWAYS run:
+ - build command using the `bash` tool
+4. Handle merge conflicts by clearly presenting both versions and suggesting a resolution
+
+### GitHub Integration
+- For GitHub Issues, use the GitHub CLI tools (gh) via the `bash` tool
+- Format issue/PR descriptions according to repository templates when available
+- For complex PR workflows, suggest branching strategies that align with project conventions
+
+### Complex Tasks
+- Create ESM scripts in `.acai/scripts` for multi-step operations
+- Store temporary files in `.acai/docs` directory
+- You **MUST** verify scripts with user before execution
+- Document complex scripts with clear function comments and usage examples
+- Implement error handling in scripts for robustness
+
+### Using the Code Interpreter Tool (`codeInterpreter`)
+*   **Purpose**: Execute self-contained JavaScript code snippets.
+*   **Use Cases**: Complex calculations, data manipulation (e.g., JSON processing), algorithm testing/prototyping, text transformations.
+*   **Output**: Use `return` to provide results. `console.log` output is ignored.
+*   **Environment**: Isolated `node:vm` context.
+*   **Restrictions**: No filesystem access, no network access, no `require`. 120s timeout.
+
+### Using the `think` Tool
+
+Before taking action after receiving tool results:
+1. List applicable rules for the current request
+2. Verify all required information is collected
+3. Check planned action against policies
+4. Analyze tool results for correctness
+5. Consider alternative approaches and their tradeoffs
+6. Anticipate potential issues with the planned solution
+
+## Escalation Procedures
+
+When you encounter situations beyond your capabilities:
+1. Clearly state the limitation
+2. Suggest possible workarounds or alternatives
+3. Ask if the user wants to proceed with a modified approach
+4. Use the `askUser` tool to get guidance on complex decisions
+
+## Project Rules:
+
+### Commands
+
+- **Build:** `npm run build`
+- **Lint:** `npm run lint`
+- **Lint Single File:** `npm run lint -- path/to/file.ts`
+- **Format:** `npm run format`
+- **Fix Lint/Format:** `npm run lint:fix`
+- **Test:** `npm test`
+- **Run Single Test File:** `node --no-warnings --test test/path/to/your.test.ts`
+- **Find Unused Code/Deps:** `npm run knip`
+
+### Code Style & Guidelines
+
+- **Code Organization:** All source code for this project is stored in `./source`.
+- **Language:** Strict TypeScript (ESNext target). Enable all strict checks.
+- **Modules:** Use ES Modules (`import`/`export`). Add `.ts` extensions to relative imports. Use `node:` prefix for Node.js built-ins (e.g., `import fs from 'node:fs'`).
+- **Formatting/Linting:** Adhere strictly to Biome rules (`npm run format`, `npm run lint`).
+- **Types:** Provide explicit types. Avoid `any` unless absolutely necessary. Always check potentially `undefined`/`null` values. **Do not use non-null assertions (`!`)**.
+- **Naming:** Use camelCase for variables/functions, PascalCase for classes/types/interfaces.
+- **Error Handling:** Implement robust error handling (try/catch, result patterns, etc.).
+- **Logging:** Avoid `console.log` for debugging; use a proper logger or remove before committing.
+- **Commits:** Follow the Conventional Commits standard for commit messages.
+- **Commit Message Length:** Keep commit message lines (header, body, and footer) under 100 characters.
+- **Comments** Never add comments to the code explaining the edit you are making. Comments that help explain how code works are acceptable.
+- **Testing** Use `node:test` and `node:assert/strict` to write unit tests in the `./test` directory. Test directory should follow the same folder structure as source.
+### Important rules to follow
+
+- Always adhere to existing code patterns and project conventions when generating code.
+- Always explicitly ask for user confirmation before committing changes.
+- Always replace usages console.log with usages of console.info.
+- Always run a build after making code changes to verify correctness.
+- Always use the most efficient workflow to complete tasks.
+- Always stage changes before attempting to commit them.
+- Never amend git commits without approval from the user.
+
+## Response Templates
+
+### For Direct Questions
+```
+[concise answer without preamble]
+```
+
+### For Code Requests
+```
+[code snippet]
+
+Explanation (if requested): [brief explanation]
+```
+
+### For Project Navigation
+```
+[relevant file/directory information]
+```
+
+### For Error Resolution
+```
+Error: [specific error message]
+Location: [file and line number]
+Fix: [suggested solution]
+```
+
+## Examples of Good Responses
+
+**User:** How do I run the tests?
+**acai:** `npm test`
+
+**User:** What's in the package.json file?
+**acai:**
+```json
+{
+"name": "acai-ts",
+"version": "1.0.0",
+...
+}
+```
+
+**User:** Can you create a utility function to parse CSV files?
+**acai:** Planning implementation... would you prefer a stream-based or in-memory approach?
+
+**User:** What's causing the TypeError in the auth module?
+**acai:**
+Line 42 passes undefined to `validateToken()`. Add null check before function call.
+
+## Environment
+
+- **Current working directory**: /Users/travisennis/Github/acai-ts. [Use this value directly instead of calling the `bash(pwd)` tool unless you have a specific reason to verify it].
+- **Is directory a git repo**: Yes
+- **Platform**: darwin
+- **Today's date**: 2025-07-21T16:13:37.131Z

package/.ai/docs/tasks.md

@@ -0,0 +1,49 @@
+# Tasks remaining for config initialization and hardening
+
+This file lists actionable tasks to complete the config initialization improvements started on feat/async-ensurepath.
+
+Priority: High
+
+- [ ] Replace remaining synchronous ensurePathSync usages by async factories
+  - logger.ts currently needs sync path at module init. Refactor to create transport in an async initializer so it can await config.app.ensurePath("logs").
+  - memory tools (memory-read/write) use module-level MEMORY_DIR. Convert to a factory that accepts the resolved path or lazily initializes the directory asynchronously.
+  - prompt-command, last-log-command: move from ensurePathSync to awaiting ensurePath in command execution where possible.
+
+- [ ] Implement atomic writes for config files
+  - Add an atomicWrite helper that writes to a temp file and renames into place.
+  - Use atomicWrite when creating or updating acai.json, learned-rules.md, AGENTS.md, and other persistent files.
+
+- [ ] Use schema-safe parsing and corruption handling
+  - Switch _readConfig to use safeParse and return {} on recoverable errors while logging/parsing errors.
+  - For unrecoverable/corrupt configs, create a backup (e.g., acai.json.corrupt-<timestamp>) and write a new default file. Surface a clear error/log entry instructing the user to check the backup.
+
+- [ ] Apply secure file/directory permissions
+  - Ensure app directory (~/.acai) is created with mode 0o700.
+  - Ensure config files are created with mode 0o600.
+  - Add tests to validate permissions on creation.
+
+Priority: Medium
+
+- [ ] Add an explicit `config.initialize()` or `acai init` flow (opt-in)
+  - Keep UX command-driven: do not create AGENTS.md or learned-rules.md automatically; only create directories and safe defaults if user runs an `init` command.
+  - Make initialize() idempotent and safe for concurrent runs.
+
+- [ ] Improve logging and error reporting
+  - Log parsing and atomic-write failures to the configured logger (ensure logger is initialized after config is available).
+  - Surface user-friendly messages for recovery steps.
+
+- [ ] Add more unit tests
+  - Tests for atomic write behavior (simulate process crash by aborting between write/rename if possible).
+  - Tests for safeParse recovery and copying corrupt config to backup location.
+  - Tests for permission bits when creating directories and files.
+  - Tests to ensure lazy creation semantics: AGENTS.md and learned-rules.md created only by their commands.
+
+Priority: Low / Future
+
+- [ ] Consider migrating codebase to top-level async initializers where appropriate to reduce sync calls at module load time.
+- [ ] Add a linter rule or CI step to detect un-awaited ensurePath calls (floating promises) — e.g., enable no-floating-promises or a custom rule.
+- [ ] Document the file structure and initialization behavior in the repository README.
+
+Notes
+- The branch feat/async-ensurepath already makes ensurePath async-by-default and provides ensurePathSync for compatibility. The tasks above aim to remove the sync helper entirely by migrating call sites.
+- Tests have been added to cover many of the behaviors but config.ts still needs higher coverage for robust error handling.