From c0028f9518f49fa5585b2fba7ea6633d9ece9b05 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 08:44:27 +0000 Subject: [PATCH 1/3] Initial plan From 463634177dadb2056389a138fb6f1db24dc7a4de Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 08:47:03 +0000 Subject: [PATCH 2/3] Add AI Assistant Guide and update README Co-authored-by: kartikmodi <11896051+kartikmodi@users.noreply.github.com> --- README.md | 10 ++- docs/AI_ASSISTANT_GUIDE.md | 177 +++++++++++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 docs/AI_ASSISTANT_GUIDE.md diff --git a/README.md b/README.md index bc8e2ed..333ceb0 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,12 @@ Step Order - 2. Timeshift 3. zram 4. ansible bundle -5. timeshift \ No newline at end of file +5. timeshift + +## AI Assistant + +This repository supports AI-assisted development. See the [AI Assistant Guide](docs/AI_ASSISTANT_GUIDE.md) for: +- What the AI can help you with +- How to provide effective context +- Examples of common tasks +- Best practices for collaboration \ No newline at end of file diff --git a/docs/AI_ASSISTANT_GUIDE.md b/docs/AI_ASSISTANT_GUIDE.md new file mode 100644 index 0000000..0bbe09f --- /dev/null +++ b/docs/AI_ASSISTANT_GUIDE.md @@ -0,0 +1,177 @@ +# AI Assistant Guide + +This guide explains what the AI assistant can do for this dotfiles repository and how to provide effective context for tasks. + +## What I Can Do + +As an AI assistant for this repository, I can help you with: + +### 1. **Code and Configuration Changes** +- Modify Ansible playbooks and roles +- Update Nix configurations (flake.nix, home.nix) +- Edit shell scripts in the `bin/` directory +- Update inventory files and configuration + +### 2. **Documentation** +- Create and update documentation in the `docs/` folder +- Improve README files +- Write usage guides and tutorials +- Document setup procedures + +### 3. **Automation and Scripts** +- Create new Ansible roles for system configuration +- Write shell scripts for automation tasks +- Set up new development tools and environments +- Configure software installations + +### 4. **Repository Maintenance** +- Update dependencies in requirements.yml +- Organize and restructure files +- Add .gitignore rules +- Set up CI/CD workflows + +### 5. **Troubleshooting** +- Debug Ansible playbook issues +- Fix Nix configuration problems +- Resolve script errors +- Investigate setup failures + +## How to Provide Context + +To get the best results, provide clear context in these ways: + +### 1. **Be Specific About the Goal** +✅ Good: "Add a new Ansible role to install and configure Docker with docker-compose" +❌ Poor: "Fix Docker" + +### 2. **Describe the Current Problem** +If something isn't working, explain: +- What you tried to do +- What you expected to happen +- What actually happened +- Any error messages you received + +Example: +``` +I ran `ansible-playbook main.yml` and got an error about missing package 'docker-ce'. +I expected Docker to be installed but the task failed at the installation step. +Error: "Package docker-ce is not available" +``` + +### 3. **Specify Your Environment** +When relevant, mention: +- Operating system (Ubuntu, Debian, Arch, macOS, etc.) +- Architecture (x86_64, ARM64/Asahi, etc.) +- Existing configuration state + +### 4. **Include Relevant Files** +Point to specific files or sections: +- "Update the zsh configuration in roles/shell/tasks/main.yml" +- "Modify the neovim setup in home.nix" + +### 5. **Share Constraints or Preferences** +Let me know if you have: +- Preferred tools or methods +- Compatibility requirements +- Performance considerations +- Style preferences + +## Example Tasks + +Here are examples of well-defined tasks: + +### Example 1: New Software Installation +``` +Add Terraform to the Nix configuration in home.nix with version 1.6.0+. +Also create an Ansible role to configure Terraform with AWS credentials +from environment variables. +``` + +### Example 2: Documentation Update +``` +Create a guide in docs/usage-guide/ explaining how to set up PostgreSQL +using the existing Ansible roles. Include connection examples and common +troubleshooting steps. +``` + +### Example 3: Script Creation +``` +Create a shell script in bin/ that backs up my dotfiles to a specified +directory. It should create timestamped backups and keep only the last +5 backups. +``` + +### Example 4: Configuration Fix +``` +The bluetooth setup guide in docs/bluetooth.md references outdated commands. +Update it to work with PipeWire instead of PulseAudio on Ubuntu 22.04+. +``` + +### Example 5: Role Enhancement +``` +Enhance the existing vim/neovim role to include LSP configuration for +Python, JavaScript, and Go. Use modern plugin managers like lazy.nvim. +``` + +## Working with This Repository + +### Repository Structure +- `roles/` - Ansible roles for different tools and configurations +- `docs/` - Documentation and guides +- `bin/` - Utility scripts +- `home.nix` - Nix home-manager configuration +- `flake.nix` - Nix flake for reproducible environments +- `main.yml` - Main Ansible playbook +- `inventory.yml` - Ansible inventory + +### Common Workflows + +1. **Adding New Tool Configuration** + - Create new role in `roles/` + - Include role in `main.yml` + - Test with specific tags + - Document in `docs/` + +2. **Updating Nix Packages** + - Modify `home.nix` + - Test with `nix build` + - Update documentation if needed + +3. **Creating New Scripts** + - Add to `bin/` directory + - Make executable + - Document usage in comments or docs + +## Tips for Best Results + +1. **One task at a time**: Focus on a single clear objective +2. **Provide examples**: Show what success looks like +3. **Reference existing patterns**: Point to similar existing code/configs +4. **Test incrementally**: Ask for changes that can be tested in steps +5. **Review suggestions**: I can explain my changes if needed + +## What I Cannot Do + +- I cannot push directly to your repository (I work via Pull Requests) +- I cannot access external services or APIs during execution +- I cannot make changes to your live system (only to repository files) +- I cannot access private credentials or secrets + +## Getting Started + +To start working with me: + +1. **Describe your goal**: Tell me what you want to achieve +2. **Provide context**: Share relevant details about your setup +3. **Review my plan**: I'll outline what I'll do before making changes +4. **Iterate**: We can refine the approach based on your feedback + +## Questions? + +If you're unsure how to phrase a request, you can: +- Start with a high-level goal and I'll ask clarifying questions +- Show me an example from another project +- Describe the manual steps you would take +- Ask me to explore the repository first to understand the context + +Feel free to be conversational - I can help translate your ideas into specific, actionable tasks! From 7f294e87544da4a370031502ad31361d29f2e0be Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 08:47:49 +0000 Subject: [PATCH 3/3] Refine AI Assistant Guide limitations section Co-authored-by: kartikmodi <11896051+kartikmodi@users.noreply.github.com> --- docs/AI_ASSISTANT_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/AI_ASSISTANT_GUIDE.md b/docs/AI_ASSISTANT_GUIDE.md index 0bbe09f..a674ae9 100644 --- a/docs/AI_ASSISTANT_GUIDE.md +++ b/docs/AI_ASSISTANT_GUIDE.md @@ -152,10 +152,10 @@ Python, JavaScript, and Go. Use modern plugin managers like lazy.nvim. ## What I Cannot Do -- I cannot push directly to your repository (I work via Pull Requests) - I cannot access external services or APIs during execution - I cannot make changes to your live system (only to repository files) - I cannot access private credentials or secrets +- I cannot execute commands with destructive side effects outside the repository ## Getting Started