diff --git a/conductor/code_styleguides/markdown.md b/conductor/code_styleguides/markdown.md new file mode 100644 index 0000000..add8e94 --- /dev/null +++ b/conductor/code_styleguides/markdown.md @@ -0,0 +1,28 @@ +# Markdown Style Guide + +## General +- **Line Wrapping:** Wrap lines at 80-100 characters for readability, unless it breaks a link or code block. +- **Headers:** + - Use ATX-style headers (`#`, `##`, etc.). + - Leave one blank line before and after headers. +- **Lists:** + - Use hyphens (`-`) for unordered lists. + - Use numbers (`1.`, `2.`) for ordered lists. + - Indent nested lists by 2 or 4 spaces. + +## Code Blocks +- **Fenced Code Blocks:** Use triple backticks (```) for code blocks. +- **Language Tags:** Always specify the language for syntax highlighting (e.g., ```rust). + +## Links & Images +- **Reference Links:** Prefer inline links `[text](url)` for short links. +- **Images:** Provide descriptive alt text for accessibility: `![Alt text](url)`. + +## Emphasis +- **Bold:** Use double asterisks (`**text**`). +- **Italic:** Use single asterisks (`*text*`) or underscores (`_text_`). +- **Code:** Use single backticks (`` `text` ``) for inline code. + +## Structure +- **Table of Contents:** Include a TOC for long documents. +- **Sections:** Use logical hierarchy for sections and subsections. diff --git a/conductor/code_styleguides/rust.md b/conductor/code_styleguides/rust.md new file mode 100644 index 0000000..699b8a5 --- /dev/null +++ b/conductor/code_styleguides/rust.md @@ -0,0 +1,37 @@ +# Rust Style Guide + +## General +- **Formatting:** Always use `rustfmt` with default settings. +- **Linting:** Use `clippy` to catch common mistakes and improve code quality. Address all warnings. +- **Edition:** Use the latest stable edition (currently 2024). + +## Naming Conventions +- **Crates:** `snake_case` (e.g., `my_crate`) +- **Modules:** `snake_case` (e.g., `my_module`) +- **Types (Structs, Enums, Traits):** `UpperCamelCase` (e.g., `MyStruct`) +- **Functions & Methods:** `snake_case` (e.g., `my_function`) +- **Variables:** `snake_case` (e.g., `my_variable`) +- **Constants:** `SCREAMING_SNAKE_CASE` (e.g., `MAX_SIZE`) +- **Generics:** `UpperCamelCase`, usually single letters (e.g., `T`, `U`) or descriptive names (e.g., `Input`, `Output`). + +## Code Structure +- **Imports:** Group imports by crate. Use `std` first, then external crates, then internal modules. +- **Visibility:** Minimizing visibility is preferred. Use `pub(crate)` or `pub(super)` where appropriate. +- **Error Handling:** + - Prefer `Result` over `panic!`. + - Use the `?` operator for error propagation. + - Use `anyhow` for application-level error handling and `thiserror` for library-level errors. + +## Documentation +- **Public API:** Document all public items using `///` comments. +- **Module Level:** Include module-level documentation using `//!` at the top of the file. +- **Examples:** Include examples in documentation where helpful. + +## Testing +- **Unit Tests:** Place unit tests in a `tests` module within the same file, annotated with `#[cfg(test)]`. +- **Integration Tests:** Place integration tests in the `tests/` directory at the crate root. + +## Idioms +- **Pattern Matching:** Use pattern matching (`match`, `if let`) extensively. +- **Ownership & Borrowing:** Follow Rust's ownership rules strictly. Avoid `clone()` unless necessary. +- **Iterators:** Prefer iterators and combinators (`map`, `filter`, `fold`) over explicit loops. diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md new file mode 100644 index 0000000..eb5991d --- /dev/null +++ b/conductor/product-guidelines.md @@ -0,0 +1,22 @@ +# Product Guidelines + +## Prose Style +- **Professional & Direct:** Use a professional tone that is helpful but concise. +- **Clarity over Verbosity:** Explain complex actions briefly without being overly chatty. +- **Technical Accuracy:** Use precise terminology when referring to code or system operations. + +## Technical Excellence +- **Idiomatic Rust:** Follow standard Rust conventions (`rustfmt`, `clippy`). +- **Safety First:** Prioritize memory safety and robust error handling. Use `Result` and `Option` effectively. +- **Performance:** Ensure that file operations and LLM interactions are as efficient as possible. +- **Modularity:** Maintain high cohesion and low coupling between crates. + +## Security & Privacy +- **Minimal Privilege:** Only request permissions for necessary operations. +- **Secret Handling:** Never log or store API keys or sensitive data in plain text. +- **Transparency:** Clearly inform the user before executing potentially destructive commands. + +## UI/UX Design (CLI/TUI) +- **Unix Philosophy:** Support piping and non-interactive modes where applicable. +- **Visual Feedback:** Use progress indicators for long-running tasks. +- **Accessibility:** Ensure the TUI is readable and navigable with standard terminal settings. diff --git a/conductor/product.md b/conductor/product.md new file mode 100644 index 0000000..8c4656a --- /dev/null +++ b/conductor/product.md @@ -0,0 +1,21 @@ +# Product Guide + +## Initial Concept +A robust, modular, and high-performance AI coding assistant for the terminal, built in Rust. It aims to streamline software development workflows by integrating directly with the codebase and version control systems. + +## Target Audience +- **Software Developers:** The primary users who need assistance with coding tasks, refactoring, and understanding complex codebases. +- **DevOps Engineers:** For handling infrastructure-as-code and script automation via natural language. + +## Core Value Proposition +- **Performance & Safety:** Leverages Rust's memory safety and speed for a responsive CLI experience. +- **Model Agnostic:** Supports multiple LLM backends (Anthropic, OpenAI, Ollama) giving users flexibility. +- **Deep Integration:** Deeply integrates with the local development environment (filesystem, git, shell). +- **Extensibility:** A plugin architecture to extend functionality with custom commands and agents. + +## Key Features +- **Natural Language Interface:** Interact with the agent using plain English to perform complex tasks. +- **Codebase Awareness:** The agent can read and analyze the project structure and file contents to provide context-aware assistance. +- **Multi-LLM Support:** Configurable providers including Anthropic, OpenAI, and local models via Ollama. +- **Rich TUI:** A text-based user interface for a better user experience in the terminal. +- **Tool Ecosystem:** A suite of built-in tools for file manipulation, shell execution, and more. diff --git a/conductor/setup_state.json b/conductor/setup_state.json new file mode 100644 index 0000000..e23b6a6 --- /dev/null +++ b/conductor/setup_state.json @@ -0,0 +1 @@ +{"last_successful_step": "3.3_initial_track_generated"} \ No newline at end of file diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md new file mode 100644 index 0000000..24c3821 --- /dev/null +++ b/conductor/tech-stack.md @@ -0,0 +1,28 @@ +# Tech Stack + +## Core Technologies +- **Language:** Rust (Edition 2024, v1.91+) +- **Architecture:** Modular Workspace with specialized crates for UI, Core Agent, LLM Providers, Platform Services, and Tools. +- **Dependency Management:** Cargo (Rust's package manager). + +## Crates & Components +- **Frontends:** + - `crates/app/cli`: Command-line interface. + - `crates/app/ui`: Terminal User Interface (TUI). +- **Core Agent:** + - `crates/core/agent`: The primary orchestration engine for the AI agent. +- **LLM Providers:** + - `crates/llm/anthropic`: Integration with Anthropic's Claude models. + - `crates/llm/openai`: Integration with OpenAI's models. + - `crates/llm/ollama`: Integration with local models via Ollama. +- **Platform Services:** + - `crates/platform/auth`: Authentication logic. + - `crates/platform/config`: Configuration management. + - `crates/platform/credentials`: Secure credential storage and retrieval. + - `crates/platform/hooks`: Plugin hook system. + - `crates/platform/permissions`: Permission and safety system. + - `crates/platform/plugins`: Plugin management. +- **Functional Tools:** + - Specialized tools in `crates/tools/` for `bash` execution, `fs` (filesystem) operations, `web` search/fetch, `notebook` interaction, `plan` management, and more. +- **Integration:** + - `crates/integration/mcp-client`: Client for the Model Context Protocol (MCP). diff --git a/conductor/tracks.md b/conductor/tracks.md new file mode 100644 index 0000000..ad083c5 --- /dev/null +++ b/conductor/tracks.md @@ -0,0 +1,8 @@ +# Project Tracks + +This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. + +--- + +## [ ] Track: Establish a comprehensive test suite for the core agent logic and ensure basic documentation for all crates. +*Link: [./conductor/tracks/stabilize_core_20251226/](./conductor/tracks/stabilize_core_20251226/)* diff --git a/conductor/tracks/stabilize_core_20251226/metadata.json b/conductor/tracks/stabilize_core_20251226/metadata.json new file mode 100644 index 0000000..81bd133 --- /dev/null +++ b/conductor/tracks/stabilize_core_20251226/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "stabilize_core_20251226", + "type": "feature", + "status": "new", + "created_at": "2025-12-26T10:00:00Z", + "updated_at": "2025-12-26T10:00:00Z", + "description": "Establish a comprehensive test suite for the core agent logic and ensure basic documentation for all crates." +} diff --git a/conductor/tracks/stabilize_core_20251226/plan.md b/conductor/tracks/stabilize_core_20251226/plan.md new file mode 100644 index 0000000..6b9da37 --- /dev/null +++ b/conductor/tracks/stabilize_core_20251226/plan.md @@ -0,0 +1,17 @@ +# Plan: Core Stabilization & Documentation + +## Phase 1: Core Agent & Platform Testing + +- [ ] Task: Write unit tests for `crates/core/agent/src/lib.rs` +- [ ] Task: Write unit tests for `crates/platform/permissions/src/lib.rs` +- [ ] Task: Write unit tests for `crates/platform/config/src/lib.rs` +- [ ] Task: Conductor - User Manual Verification 'Core Agent & Platform Testing' (Protocol in workflow.md) + +## Phase 2: Documentation Audit & Standardization + +- [ ] Task: Create/Update README.md for all crates in `crates/app/` +- [ ] Task: Create/Update README.md for all crates in `crates/llm/` +- [ ] Task: Create/Update README.md for all crates in `crates/platform/` +- [ ] Task: Create/Update README.md for all crates in `crates/tools/` +- [ ] Task: Add doc-comments to all public functions in `crates/core/agent/` +- [ ] Task: Conductor - User Manual Verification 'Documentation Audit & Standardization' (Protocol in workflow.md) diff --git a/conductor/tracks/stabilize_core_20251226/spec.md b/conductor/tracks/stabilize_core_20251226/spec.md new file mode 100644 index 0000000..1fb7411 --- /dev/null +++ b/conductor/tracks/stabilize_core_20251226/spec.md @@ -0,0 +1,14 @@ +# Specification: Core Stabilization & Documentation + +## Goal +To increase the reliability and maintainability of the Owlen codebase by establishing a robust testing foundation and comprehensive documentation for all existing crates. + +## Scope +- **Crates Covered:** All crates in the workspace (`app/*`, `core/*`, `llm/*`, `platform/*`, `tools/*`, `integration/*`). +- **Testing:** Unit tests for core logic, focusing on the `core/agent` and `platform/*` crates. +- **Documentation:** `README.md` for each crate and doc-comments for all public APIs. + +## Deliverables +- Increased test coverage (targeting >80%) for core crates. +- Comprehensive API documentation. +- Standardized `README.md` files for all crates. diff --git a/conductor/workflow.md b/conductor/workflow.md new file mode 100644 index 0000000..a81bcf2 --- /dev/null +++ b/conductor/workflow.md @@ -0,0 +1,333 @@ +# Project Workflow + +## Guiding Principles + +1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md` +2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation +3. **Test-Driven Development:** Write unit tests before implementing functionality +4. **High Code Coverage:** Aim for >80% code coverage for all modules +5. **User Experience First:** Every decision should prioritize user experience +6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution. + +## Task Workflow + +All tasks follow a strict lifecycle: + +### Standard Task Workflow + +1. **Select Task:** Choose the next available task from `plan.md` in sequential order + +2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]` + +3. **Write Failing Tests (Red Phase):** + - Create a new test file for the feature or bug fix. + - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task. + - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests. + +4. **Implement to Pass Tests (Green Phase):** + - Write the minimum amount of application code necessary to make the failing tests pass. + - Run the test suite again and confirm that all tests now pass. This is the "Green" phase. + +5. **Refactor (Optional but Recommended):** + - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior. + - Rerun tests to ensure they still pass after refactoring. + +6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like: + ```bash + pytest --cov=app --cov-report=html + ``` + Target: >80% coverage for new code. The specific tools and commands will vary by language and framework. + +7. **Document Deviations:** If implementation differs from tech stack: + - **STOP** implementation + - Update `tech-stack.md` with new design + - Add dated note explaining the change + - Resume implementation + +8. **Commit Code Changes:** + - Stage all code changes related to the task. + - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`. + - Perform the commit. + +9. **Attach Task Summary with Git Notes:** + - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`). + - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change. + - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit. + ```bash + # The note content from the previous step is passed via the -m flag. + git notes add -m "" + ``` + +10. **Get and Record Task Commit SHA:** + - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash. + - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`. + +11. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`). + +### Phase Completion Verification and Checkpointing Protocol + +**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`. + +1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun. + +2. **Ensure Test Coverage for Phase Changes:** + - **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit. + - **Step 2.2: List Changed Files:** Execute `git diff --name-only HEAD` to get a precise list of all files modified during this phase. + - **Step 2.3: Verify and Create Tests:** For each file in the list: + - **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`). + - For each remaining code file, verify a corresponding test file exists. + - If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`). + +3. **Execute Automated Tests with Proactive Debugging:** + - Before execution, you **must** announce the exact shell command you will use to run the tests. + - **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`" + - Execute the announced command. + - If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance. + +4. **Propose a Detailed, Actionable Manual Verification Plan:** + - **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase. + - You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes. + - The plan you present to the user **must** follow this format: + + **For a Frontend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Start the development server with the command:** `npm run dev` + 2. **Open your browser to:** `http://localhost:3000` + 3. **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly. + ``` + + **For a Backend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Ensure the server is running.** + 2. **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'` + 3. **Confirm that you receive:** A JSON response with a status of `201 Created`. + ``` + +5. **Await Explicit User Feedback:** + - After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**" + - **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation. + +6. **Create Checkpoint Commit:** + - Stage all changes. If no changes occurred in this step, proceed with an empty commit. + - Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`). + +7. **Attach Auditable Verification Report using Git Notes:** + - **Step 8.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation. + - **Step 8.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit. + +8. **Get and Record Phase Checkpoint SHA:** + - **Step 7.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`). + - **Step 7.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: ]`. + - **Step 7.3: Write Plan:** Write the updated content back to `plan.md`. + +9. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '' as complete`. + +10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note. + +### Quality Gates + +Before marking any task complete, verify: + +- [ ] All tests pass +- [ ] Code coverage meets requirements (>80%) +- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`) +- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc) +- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types) +- [ ] No linting or static analysis errors (using the project's configured tools) +- [ ] Works correctly on mobile (if applicable) +- [ ] Documentation updated if needed +- [ ] No security vulnerabilities introduced + +## Development Commands + +**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.** + +### Setup +```bash +# Example: Commands to set up the development environment (e.g., install dependencies, configure database) +# e.g., for a Node.js project: npm install +# e.g., for a Go project: go mod tidy +``` + +### Daily Development +```bash +# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format) +# e.g., for a Node.js project: npm run dev, npm test, npm run lint +# e.g., for a Go project: go run main.go, go test ./..., go fmt ./... +``` + +### Before Committing +```bash +# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests) +# e.g., for a Node.js project: npm run check +# e.g., for a Go project: make check (if a Makefile exists) +``` + +## Testing Requirements + +### Unit Testing +- Every module must have corresponding tests. +- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach). +- Mock external dependencies. +- Test both success and failure cases. + +### Integration Testing +- Test complete user flows +- Verify database transactions +- Test authentication and authorization +- Check form submissions + +### Mobile Testing +- Test on actual iPhone when possible +- Use Safari developer tools +- Test touch interactions +- Verify responsive layouts +- Check performance on 3G/4G + +## Code Review Process + +### Self-Review Checklist +Before requesting review: + +1. **Functionality** + - Feature works as specified + - Edge cases handled + - Error messages are user-friendly + +2. **Code Quality** + - Follows style guide + - DRY principle applied + - Clear variable/function names + - Appropriate comments + +3. **Testing** + - Unit tests comprehensive + - Integration tests pass + - Coverage adequate (>80%) + +4. **Security** + - No hardcoded secrets + - Input validation present + - SQL injection prevented + - XSS protection in place + +5. **Performance** + - Database queries optimized + - Images optimized + - Caching implemented where needed + +6. **Mobile Experience** + - Touch targets adequate (44x44px) + - Text readable without zooming + - Performance acceptable on mobile + - Interactions feel native + +## Commit Guidelines + +### Message Format +``` +(): + +[optional body] + +[optional footer] +``` + +### Types +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation only +- `style`: Formatting, missing semicolons, etc. +- `refactor`: Code change that neither fixes a bug nor adds a feature +- `test`: Adding missing tests +- `chore`: Maintenance tasks + +### Examples +```bash +git commit -m "feat(auth): Add remember me functionality" +git commit -m "fix(posts): Correct excerpt generation for short posts" +git commit -m "test(comments): Add tests for emoji reaction limits" +git commit -m "style(mobile): Improve button touch targets" +``` + +## Definition of Done + +A task is complete when: + +1. All code implemented to specification +2. Unit tests written and passing +3. Code coverage meets project requirements +4. Documentation complete (if applicable) +5. Code passes all configured linting and static analysis checks +6. Works beautifully on mobile (if applicable) +7. Implementation notes added to `plan.md` +8. Changes committed with proper message +9. Git note with task summary attached to the commit + +## Emergency Procedures + +### Critical Bug in Production +1. Create hotfix branch from main +2. Write failing test for bug +3. Implement minimal fix +4. Test thoroughly including mobile +5. Deploy immediately +6. Document in plan.md + +### Data Loss +1. Stop all write operations +2. Restore from latest backup +3. Verify data integrity +4. Document incident +5. Update backup procedures + +### Security Breach +1. Rotate all secrets immediately +2. Review access logs +3. Patch vulnerability +4. Notify affected users (if any) +5. Document and update security procedures + +## Deployment Workflow + +### Pre-Deployment Checklist +- [ ] All tests passing +- [ ] Coverage >80% +- [ ] No linting errors +- [ ] Mobile testing complete +- [ ] Environment variables configured +- [ ] Database migrations ready +- [ ] Backup created + +### Deployment Steps +1. Merge feature branch to main +2. Tag release with version +3. Push to deployment service +4. Run database migrations +5. Verify deployment +6. Test critical paths +7. Monitor for errors + +### Post-Deployment +1. Monitor analytics +2. Check error logs +3. Gather user feedback +4. Plan next iteration + +## Continuous Improvement + +- Review workflow weekly +- Update based on pain points +- Document lessons learned +- Optimize for user happiness +- Keep things simple and maintainable